source: git/doc/manual.sgml @ 2868e97

RELEASE/1.2debug-cidebug-ci-sanitisersstereowalls-data
Last change on this file since 2868e97 was 2868e97, checked in by Olly Betts <olly@…>, 9 years ago
  • .gitignore,configure.ac,desc-svxedit.txt,doc/,lib/,src/Makefile.am,

src/svxedit.rc: Remove lingering traces of svxedit.

  • Property mode set to 100644
File size: 99.2 KB
Line 
1<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
2<!ENTITY man.aven SYSTEM "aven.sgml">
3<!ENTITY man.3dtopos SYSTEM "3dtopos.sgml">
4<!ENTITY man.cad3d SYSTEM "cad3d.sgml">
5<!ENTITY man.cavern SYSTEM "cavern.sgml">
6<!ENTITY man.diffpos SYSTEM "diffpos.sgml">
7<!ENTITY man.extend SYSTEM "extend.sgml">
8<!ENTITY man.sorterr SYSTEM "sorterr.sgml">
9]>
10
11<!--
12FIXME:
13
143dfile title:
15defaults to a list of the leafnames of the <filename>.svx</filename> files specified on the
16command line (with any paths and extensions removed).
17.
18e.g.: cavern entrance.svx \data\2ndpart.svx
19.
20would give a surveytitle of 'entrance 2ndpart'.
21.
22but this may change...
23
24FIXME todo:
25mark-up of Windows Windows NT etc?
26section on "design philosophy"
27
28level sump fudge:
29
30*begin
31*data cartesian from to dx dy dz
32*sd dx dy 100 metres
33*sd dz 0.001 metres
34; upstream - downstream
35nuiping.gowiththeflow.129 dachao.upstream.105 0 0 0 ; last number is drop in height across the sump
36*end
37
38``Quick start'' section
39
40- install (by OS): unpacking, configuration (language, where support files live)
41
42- lead people through entering and processing
43a sample survey.  Take examples from surveying books and real surveys.
44
45
46<Para>The other really important commands apart from *BEGIN, *END, and
47*INCLUDE are *EQUATE and *FIX.
48</Para>
49
50<Para>*EQUATE is used to join surveys together, e.g.
51</Para>
52
53<programlisting>*equate entrance.6 adrian.1</programlisting>
54
55<Para>
56indicates that station 6 of the entrance survey was used as
57the station 1 of the Adrian's Route survey.
58</Para>
59
60<Para>*FIX is for fixing control points - for example:
61</Para>
62
63<programlisting>
64*fix 161.entrance.1    0  0  1780</programlisting>
65
66<Para>fixes the 1st point of the 'entrance' survey at the coordinates
670 (east-west), 0 (north-south), 1780 (altitude).
68</Para>
69
70
71<term>node</term>
72<listitem><para>when talking about the survey network, we talk about an
73<emphasis>n</emphasis>-node to describe the number of connections to
74a station.  So a 1-node is a station with only 1 leg to or from it
75- i.e. The end of a passage or survey. A
762-node is a typical station along a passage with a survey leg coming
77into it, and one going out.  A 3-node is a station with three legs
78joining it, e.g. at a T-junction. And so on.
79</para>
80
81-->
82
83<article Status="draft" id="index">
84 <articleinfo>
85  <Title><Application>Survex</Application> <!--VERSION-->1.2.19 Manual</Title>
86  <AuthorGroup>
87   <Author>
88    <FirstName>Olly</FirstName>
89    <SurName>Betts</SurName>
90    <AuthorBlurb><Para>
91      Olly Betts wrote most of <Application>Survex</Application>.
92    </Para></AuthorBlurb>
93    <Affiliation>
94     <Address><Email>olly@survex.com</Email></Address>
95    </Affiliation>
96   </Author>
97   <Author>
98    <SurName>Wookey</SurName>
99    <AuthorBlurb><Para>
100      Wookey is a small furry creature.
101    </Para></AuthorBlurb>
102    <Affiliation>
103     <Address><Email>wookey@survex.com</Email></Address>
104    </Affiliation>
105   </Author>
106  </AuthorGroup>
107  <copyright>
108   <year>1998-2015</year>
109   <holder role="mailto:olly@survex.com">Olly Betts</holder>
110  </copyright>
111  <Abstract>
112   <Para>
113    This is the manual for <Application>Survex</Application> - an open-source software package for
114    cave surveyors.
115   </Para>
116  </Abstract>
117 </articleinfo>
118
119<Sect1><Title>Introduction</Title>
120<?dbhtml filename="intro.htm">
121
122<Para>
123This section describes what <Application>Survex</Application> is, and outlines the scope of this
124manual.
125</Para>
126
127<Sect2><Title>About <Application>Survex</Application></Title>
128
129<Para><Application>Survex</Application> is a multi-platform open-source cave surveying
130package.
131Version 1.2
132currently runs on UNIX, Microsoft Windows 95/NT and
133successors, and Mac OS X.
134We're investigating support for various
135palmtop devices.
136Version 1.0 has fewer features, but also runs on DOS and RISC OS machines.
137</Para>
138
139<Para>We are well aware that not everyone has access to super hardware
140- often surveying projects are run on little or no budget and any
141computers used are donated.  We aim to ensure that <Application>Survex</Application> is
142feasible to use on low-spec machines.  Obviously it won't be as
143responsive, but we intend it to be usable.
144Please help us to achieve this by giving us some feedback
145if you use <Application>Survex</Application> on a slow machine.</Para>
146
147<Para><Application>Survex</Application> is capable of processing extremely complex caves very
148quickly and has a very effective, real-time cave viewer which allows
149you to rotate, zoom, and pan the cave using mouse or keyboard. We have
150tested it extensively using <Acronym>CUCC</Acronym> and <Acronym>ARGE</Acronym>'s surveys of the caves
151under the Loser Plateau in Austria (over 22,000 survey legs, and over
152120km of underground survey data). This can all be processed in around
15310 seconds on a low-end netbook.
154Survex is also used by many other survey projects around the world,
155including the
156<ulink url="http://www.oucc.org.uk/draenen/draenenmain.htm"
157>Ogof Draenen</ulink> survey, the
158<ulink url="http://www.easegill.org.uk/">Easegill</ulink> resurvey project,
159the <Acronym>OFD</Acronym> survey, the
160<!-- url="http://milos2.zoo.ox.ac.uk/~oucc/reports/surveys/surveys.htm" -->
161<ulink url="http://www.oucc.org.uk/reports/surveys/surveys.htm"
162><Acronym>OUCC</Acronym> Picos expeditions</ulink>, and the
163<ulink url="http://www.hongmeigui.net/">Hong Meigui China
164expeditions</ulink>. <!-- FIXME more? --></Para>
165
166<Para><Application>Survex</Application> is still actively being worked on.  Version 1.0 was
167complete in some sense, but development continues - initially in reshaping
168Survex into a more integrated GUI package.</Para>
169
170<Para>We encourage feedback from users on important features or problems,
171which will help to direct future development.  See the "Mailing List" section
172of this manual for the best way to contact us.</Para>
173
174</Sect2>
175
176<!--
177<Para>Because <Application>Survex</Application> is still being actively developed, this document
178has an unfortunate tendency to lag slightly behind the capabilities of the
179software. The latest version is now available on the web at <ulink
180url="http://survex.com/">http://survex.com/</ulink> - check there for latest info.
181</Para>
182-->
183
184<!--
185<Sect2><Title>Other Documentation</Title>
186
187<variablelist>
188<varlistentry>
189<term>NEWS or NEWS.txt</term>
190<listitem><Para>a list of changes of interest to
191<Application>Survex</Application> users, broken down by version number.  Consult this file
192when upgrading to find out what has changed since the version you were
193using previously.
194</Para></listitem>
195</varlistentry>
196
197<varlistentry>
198<term>ChangeLog or CHANGES.txt</term>
199<listitem><Para>a much more detailed list of changes, aimed at developers
200rather than end users.
201</Para></listitem>
202</varlistentry>
203
204<varlistentry>
205<term>BUGS or BUGS.txt</term>
206<listitem><Para>a list of known bugs.
207</Para></listitem>
208</varlistentry>
209
210<varlistentry>
211<term>TODO or TODO.txt</term>
212<listitem><Para>planned changes and enhancements.
213</Para></listitem>
214</varlistentry>
215
216FIXME: merge INSTALL* into here, then process separately and textify
217to produce INSTALL*
218
219<varlistentry>
220<term>INSTALL or INSTALL.txt</term>
221<listitem><Para>instructions for installing <Application>Survex</Application>.  The
222Microsoft Windows version comes packaged up with an installation wizard,
223so this file doesn't exist there (you just run the package and follow
224the on-screen instructions).
225</Para></listitem>
226</varlistentry>
227</variablelist>
228
229</Sect2>
230-->
231
232<Sect2><Title>About this Manual</Title>
233
234<Para>
235If there's a part of this manual you find hard to understand, please do
236let us know.  We already know Survex well, so it can be hard for us
237to spot areas where the manual doesn't given enough information, or
238doesn't explain things clearly enough to follow when you don't know what's
239going on.  It's helpful is you can suggest a better wording, but don't worry
240if you can't, just explain the problem as precisely as you can.
241</Para>
242
243<Para>
244The master version of this manual is an <acronym>SGML</acronym>
245document written using the <ulink url="http://www.docbook.org/">docbook
246<acronym>DTD</acronym></ulink>,
247and automatically converted to a number of other formats.  If
248you are going to send us <emphasis>major</emphasis> changes, it's much easier
249to include them if you work from this master.  You can get it
250from the source archive (docs/manual.sgml) or from <ulink
251url="http://survex.com/docs.html">the Survex website</ulink>.
252</Para>
253
254<Sect3><Title>Terminology</Title>
255
256<Para>Throughout this document we use British terminology for
257surveying.</Para>
258
259<variablelist>
260<varlistentry>
261<term>station</term>
262<listitem><para>a point in the cave that you survey from and/or to
263</para></listitem></varlistentry>
264
265<varlistentry>
266<term>leg</term>
267<listitem><para>a line joining two stations
268</para></listitem></varlistentry>
269
270<varlistentry>
271<term>survey</term>
272<listitem><para>a group of legs surveyed on the same trip
273</para></listitem></varlistentry>
274
275</variablelist>
276
277</Sect3>
278
279</Sect2>
280
281<!-- FIXME: Further sources of info: website, mailing lists, other docs -->
282
283</Sect1>
284
285<Sect1><Title>Getting Started</Title>
286<?dbhtml filename="getstart.htm">
287
288<Para>This section covers how to obtain the software, and how to unpack and
289install it, and how to configure it.</Para>
290
291<Sect2><Title>Obtaining <Application>Survex</Application></Title>
292
293<Para>The latest version is available from the <Application>Survex</Application> website:
294<ulink url="http://survex.com/">http://survex.com/</ulink>.  It is also
295freely redistributable, so you welcome to get a copy from someone else
296who has already downloaded it.</Para>
297
298<Para>If you want some sample data to experiment with, you can download some
299from the Survex website too:
300<ulink url="http://survex.com/software/sample.tar.gz">http://survex.com/software/sample.tar.gz</ulink></Para>
301
302</Sect2>
303
304<Sect2><Title>Installing <Application>Survex</Application></Title>
305
306<Para>The details of installation depend greatly on what platform you
307are using, so there is a separate section below for each platform.</Para>
308
309<Sect3><Title>Linux</Title>
310
311<Para>
312We supply pre-compiled versions for x86 Linux machines in RPM format
313(suitable for Redhat, Mandrake, and some other distributions).
314Survex Debian packages are available from Debian mirror sites in
315the usual way.
316</Para>
317
318<Para>
319You'll need root access to install these prebuilt packages.
320If you don't have root access you will need to build from source
321(see the next section).
322</Para>
323
324<!-- FIXME Add Gnome file association note for Linux/Unix
325<Para>On Microsoft Windows, <Application>Survex</Application> installs with
326suitable file associations so that you can drive it from the GUI.
327On UNIX you need to drive <Application>Survex</Application> from a command-line
328prompt (or set some a filemanager or graphics shell).
329</Para>
330-->
331
332</Sect3>
333
334<Sect3><Title>Other versions of UNIX</Title>
335
336<Para>For other UNIX versions you'll need to get the source code
337and compile it on your system.  Unpack the sources and read
338the file called INSTALL in the top level for details about building
339from source.
340</Para>
341
342</Sect3>
343
344<Sect3><Title>Microsoft Windows 95/NT and successors</Title>
345
346<Para>
347This version comes packaged with an installation wizard.  Just
348run the downloaded package and it will lead you through the
349installation process.  If installing on MS Windows NT, 2000, XP, or newer
350we recommend you run the installer as administrator (or as a
351user with administrator rights) so that the file associations
352can be set up for all users.
353</Para>
354
355<Para>
356The survey viewer that's part of <Application>Survex</Application> is called aven, and uses OpenGL
357for 3d rendering.
358OpenGL comes as standard as of Windows 98, and was included in the
359OSR2 update to Windows 95.  It's also possible that you've installed
360OpenGL with another application already (especially a 3D game like Quake).
361If you can view a survey in aven, all is well.  Otherwise you can
362<ulink url="http://support.microsoft.com/default.aspx?scid=kb;EN-US;q154877
363">download OpenGL drivers from Microsoft's website</ulink> (or here's
364a <ulink url="http://download.microsoft.com/download/win95upg/info/1/W95/EN-US/Opengl95.exe">direct link to the file you actually need</ulink>).
365</Para>
366
367<Para>
368If you find that 3D rendering is sometimes very slow (e.g. one user reported
369very slow performance when running full screen, while running in a window
370was fine) then try installing the OpenGL driver supplied by the manufacturer
371of your graphics card rather than the driver Microsoft supply.
372</Para>
373
374<Para>
375The installer creates a Survex group in the Programs sub-menu of the
376Start menu containing the following items:
377</Para>
378
379<ItemizedList>
380
381<ListItem><Para>Aven</Para></ListItem>
382
383<ListItem><Para>Documentation</Para></ListItem>
384
385<ListItem><Para>Uninstall Survex</Para></ListItem>
386
387</ItemizedList>
388
389<Para>
390Icons are installed for <filename>.svx</filename>, <filename>.3d</filename>, <filename>.err</filename>, and <filename>.pos</filename> files, and also for
391Compass Plot files (<filename>.plt</filename> and <filename>.plf</filename>)
392(which Survex can read). <!-- FIXME XYZ -->
393Double-clicking on a <filename>.svx</filename> file loads it for editing.  To process it to
394produce a <filename>.3d</filename> file, right click and choose "Process" from the menu.
395Double-clicking the resultant <filename>.3d</filename> file views it in aven.
396All the <Application>Survex</Application> file types can be right clicked on to give a menu of
397possible actions. 
398</Para>
399
400<VariableList>
401<VarListEntry><Term><filename>.svx</filename></Term>
402<ListItem>
403  <VariableList>
404  <VarListEntry><Term>Process</Term>
405  <ListItem><Para>
406  Process file with cavern to produce <filename>.3d</filename> file (and <filename>.err</filename> file)
407  </Para></ListItem>
408  </VarListEntry>
409  </VariableList>
410</ListItem>
411</VarListEntry>
412   
413<VarListEntry><Term><filename>.3d</filename></Term>
414<ListItem>
415  <VariableList>
416  <VarListEntry><Term>Open</Term>
417  <ListItem><Para>
418  Load file into Aven
419  </Para></ListItem>
420  </VarListEntry>
421  <VarListEntry><Term>Print</Term>
422  <ListItem><Para>
423  Send to the printer
424  </Para></ListItem>
425  </VarListEntry>
426  <VarListEntry><Term>Extend</Term>
427  <ListItem><Para>
428  Produce extended elevation
429  </Para></ListItem>
430  </VarListEntry>
431  <VarListEntry><Term>Convert to DXF</Term>
432  <ListItem><Para>
433  Convert to a DXF file (suitable for importing into many CAD packages)
434  </Para></ListItem>
435  </VarListEntry>
436  <VarListEntry><Term>Convert for hand plotting</Term>
437  <ListItem><Para>
438  Produce a <filename>.pos</filename> file listing all the stations and their coordinates
439  </Para></ListItem>
440  </VarListEntry>
441  </VariableList>
442</ListItem>
443</VarListEntry>
444
445<VarListEntry><Term><filename>.err</filename></Term>
446<ListItem>
447  <VariableList>
448  <VarListEntry><Term>Open</Term>
449  <ListItem><Para>
450  Load file into Notepad
451  </Para></ListItem>
452  </VarListEntry>
453  <VarListEntry><Term>Sort by Error</Term>
454  <ListItem><Para>
455  Sort <filename>.err</filename> file by the error in each traverse
456  </Para></ListItem>
457  </VarListEntry>
458  <VarListEntry><Term>Sort by Horizontal Error</Term>
459  <ListItem><Para>
460  Sort <filename>.err</filename> file by the horizontal error in each traverse
461  </Para></ListItem>
462  </VarListEntry>
463  <VarListEntry><Term>Sort by Vertical Error</Term>
464  <ListItem><Para>
465  Sort <filename>.err</filename> file by the vertical error in each traverse
466  </Para></ListItem>
467  </VarListEntry>
468  <VarListEntry><Term>Sort by Percentage Error</Term>
469  <ListItem><Para>
470  Sort <filename>.err</filename> file by the percentage error in each traverse
471  </Para></ListItem>
472  </VarListEntry>
473  <VarListEntry><Term>Sort by Error per Leg</Term>
474  <ListItem><Para>
475  Sort <filename>.err</filename> file by the error per leg in each traverse
476  </Para></ListItem>
477  </VarListEntry>
478  </VariableList>
479</ListItem>
480</VarListEntry>
481</VariableList>
482
483</Sect3>
484
485</Sect2>
486
487<Sect2><Title>Configuration</Title>
488
489<Sect3><Title>Selecting Your Preferred Language</Title>
490
491<Para>Survex has extensive internationalisation capabilities.  The
492language used for messages from Survex and most of the library calls
493it uses can be changed.  By default this is picked up from the
494language the operating system is set to use (from "Regional Settings"
495in Control Panel on Microsoft Windows, from the
496<systemitem>LANG</systemitem> environment variable on UNIX
497If no setting
498is found, or <Application>Survex</Application> hasn't been translated into the
499requested language, UK English is used.</Para>
500
501<Para>
502However you may want to override the language manually -
503for example if Survex isn't available in your native language
504you'll want to choose the supported language you understand best.
505</Para>
506
507<Para>
508To do this, you set the
509<systemitem>SURVEXLANG</systemitem> environment variable.  Here's a list
510of the codes currently supported:</Para>
511
512<informaltable frame="all">
513<tgroup cols="2">
514<thead>
515<row><entry>Code</entry><entry>Language</entry></row>
516</thead>
517<tbody>
518<row><entry>en</entry><entry>International English</entry></row>
519<row><entry>en_US</entry><entry>US English</entry></row>
520<row><entry>bg</entry><entry>Bulgarian</entry></row>
521<row><entry>ca</entry><entry>Catalan</entry></row>
522<row><entry>de</entry><entry>German</entry></row>
523<row><entry>de_CH</entry><entry>Swiss German</entry></row>
524<row><entry>el</entry><entry>Greek</entry></row>
525<row><entry>es</entry><entry>Spanish</entry></row>
526<row><entry>fr</entry><entry>French</entry></row>
527<row><entry>hu</entry><entry>Hungarian</entry></row>
528<row><entry>id</entry><entry>Indonesian</entry></row>
529<row><entry>it</entry><entry>Italian</entry></row>
530<row><entry>pl</entry><entry>Polish</entry></row>
531<row><entry>pt</entry><entry>Portuguese</entry></row>
532<row><entry>pt_BR</entry><entry>Brazillian Portuguese</entry></row>
533<row><entry>ro</entry><entry>Romanian</entry></row>
534<row><entry>ru</entry><entry>Russian</entry></row>
535<row><entry>sk</entry><entry>Slovak</entry></row>
536<row><entry>zh_CN</entry><entry>Chinese (Simplified)</entry></row>
537</tbody>
538</tgroup>
539</informaltable>
540
541<Para>Here are examples of how to set this environment variable to give
542messages in French (language code fr):</Para>
543
544<VariableList>
545 <VarListEntry><Term>Microsoft Windows</Term>
546   <ListItem><Para>
547For MS Windows 95 and 98 (and probably ME), you'll need to add a line
548containing <command>SET SURVEXLANG=fr</command> to your
549<filename>AUTOEXEC.BAT</filename> script.  You need to
550reboot for the change to take effect.
551</Para>
552
553<Para>For MS Windows NT4, 2000, and XP, you should proceed as follows
554(this description is written from MS Windows 2000 - it should be similar on
555NT4 and XP): Open the Start Menu, navigate to the Settings sub-menu, and
556open Control Panel.  Open System (picture of a computer) and click on the
557Advanced tab.  Choose `Environmental Variables', and create a new one: name
558<systemitem>SURVEXLANG</systemitem>, value <systemitem>fr</systemitem>.
559Click OK and the new value should be effective immediately.
560   </Para></ListItem>
561 </VarListEntry>
562 <VarListEntry><Term>UNIX - csh/tcsh</Term>
563   <ListItem><Para><userinput>setenv SURVEXLANG fr</userinput></Para></ListItem>
564 </VarListEntry>
565 <VarListEntry><Term>UNIX - sh/bash</Term>
566   <ListItem><Para><userinput>SURVEXLANG=fr ; export SURVEXLANG</userinput></Para></ListItem>
567 </VarListEntry>
568</VariableList>
569
570<Para>If <Application>Survex</Application> isn't available in your language, you could
571help out by providing a translation.  The initial translation is
572likely to be about a day's work; after that translations for
573new or changed messages are occasionally required.  Contact us for details
574if you're interested.</Para>
575
576</Sect3>
577
578</Sect2>
579
580</Sect1>
581
582<!-- FIXME
583
584type in .svx file
585
586run cavern (through aven)
587
588run aven
589
590how to print/export etc
591
592-->
593
594<!-- FIXME perhaps move this after data files section? -->
595<Sect1><Title>Survex Programs</Title>
596<?dbhtml filename="cmdline.htm">
597
598<Sect2><Title>Standard Options</Title>
599
600<Para>All <Application>Survex</Application> programs respond to the following command line options:
601</Para>
602
603<VariableList>
604
605<VarListEntry><Term>--help</Term><listitem><Para>
606display option summary and exit
607</Para></listitem></VarListEntry>
608
609<VarListEntry><Term>--version</Term><listitem><Para>
610output version information and exit
611</Para></listitem></VarListEntry>
612
613</VariableList>
614
615</Sect2>
616
617<Sect2><Title>Short and Long Options</Title>
618
619<Para>
620Options have two forms: short (a dash followed by a single letter e.g.
621<command>cavern -p</command>) and long (two dashes followed by one or more words e.g.
622<command>cavern --percentage</command>).  The long form is generally easier to
623remember, while the short form is quicker to type.  Options are often
624available in both forms.
625</Para>
626
627<Note><Para>Command line options are case sensitive, so "-B" and "-b"
628are different (this didn't used to be the case before Survex 0.90).  Case
629sensitivity doubles the number of available short options (and is also the
630norm on UNIX).
631</Para></Note>
632</Sect2>
633
634<Sect2><Title>Filenames on the Command Line</Title>
635
636<Para>Filenames with spaces can be processed (provided your operating system
637supports them - UNIX does, and so do recent versions of Microsoft
638Windows).  You need to enclose the filename in quotes like so:
639<userinput>cavern "Spider Cave"</userinput>
640</Para>
641
642<Para>A file specified on the command line of any of the <Application>Survex</Application> suite
643of programs will be looked for as specified.  If it is not found, then the
644file is looked for with the appropriate extension appended.  So
645<userinput>cavern survey</userinput> will look first for
646<filename>survey</filename>, then for <filename>survey.svx</filename>.
647</Para>
648
649</Sect2>
650
651<Sect2><title>Command Reference</title>
652
653<refentry id="cavern">
654<?dbhtml filename="cavern.htm">
655&man.cavern;
656</refentry>
657<refentry id="aven">
658<?dbhtml filename="aven.htm">
659&man.aven;
660</refentry>
661<refentry id="x3dtopos">
662<?dbhtml filename="3dtopos.htm">
663&man.3dtopos;
664</refentry>
665<refentry id="cad3d">
666<?dbhtml filename="cad3d.htm">
667&man.cad3d;
668</refentry>
669<refentry id="diffpos">
670<?dbhtml filename="diffpos.htm">
671&man.diffpos;
672</refentry>
673<refentry id="extend">
674<?dbhtml filename="extend.htm">
675&man.extend;
676</refentry>
677<refentry id="sorterr">
678<?dbhtml filename="sorterr.htm">
679&man.sorterr;
680</refentry>
681
682</Sect2>
683
684</Sect1>
685
686<Sect1><Title><Application>Survex</Application> data files</Title>
687<?dbhtml filename="datafile.htm">
688
689<Para>Survey data is entered in the form of text files. You can use any
690text editor you like for this, so long as it has the capability of
691writing a plain ASCII text file. The data format is very flexible;
692unlike some other cave surveying software, Survex does not require
693survey legs to be rearranged to suit the computer, and the ordering
694of instrument readings on each line is fully specifiable.  So you can enter
695your data much as it appears on the survey notes, which is important
696in reducing the opportunities for transcription errors.
697</Para>
698
699<Para>
700Also all the special characters are user-definable - for example,
701the separators can be spaces and tabs, or commas (e.g. when exporting from a
702spreadsheet), etc; the decimal point can be a slash (for clarity), a comma
703(as used in continental Europe), or anything else you care to choose.
704This flexibility
705means that it should be possible to read in data from almost any sort of
706survey data file without much work.
707</Para>
708
709<Para><Application>Survex</Application> places no restrictions on you in terms of the ordering
710of survey legs. You can enter or process data in any order and <Application>Survex</Application> will
711read it all in before determining how it is connected. You can also use the
712hierarchical naming so that you do not need to worry about using the same
713station name twice.
714</Para>
715
716<!-- FIXME don't encourage separate processing -->
717<Para>The usual arrangement is to have one file which lists all the others
718that are included (e.g., <filename>161.svx</filename>). Then
719<command>cavern 161</command> will process all your data. To just process a
720section use the filename for that section, e.g. <command>cavern dtime</command>
721will process the dreamtime file/section of Kaninchenh&ouml;hle.  To
722help you out, if all legs in a survey are connected to one another
723but the survey has no fixed points, cavern
724will 'invent' a fixed point and print a warning message to this
725effect.
726</Para>
727
728<Para>
729It is up to you what data you put in which files.  You
730can have one file per trip, or per area of the cave, or just one
731file for the whole cave if you like.
732On a large survey project it makes sense to group related surveys in the
733same file or directory.
734</Para>
735<!-- FIXME: wook sez:
736
737 Point out in documentation that file structure and survey structure don't
738 have to be the same.  And in particular that folder/directory names can be
739 different.
740
741Which is partly covered above, though the last bit isn't...
742-->
743
744<!-- FIXME "Anatomy of a Survey" section -->
745<Sect2><Title>Readings</Title>
746
747<Para>Blank lines (i.e. lines consisting solely of BLANK characters)
748are ignored. The last line in the file need not be terminated by
749an end of line character. All fields on a line must be separated
750by at least one BLANK character. An OMIT character
751(default '-') indicates that a field is unused. If the field is
752not optional, then an error is given.
753</Para>
754
755</Sect2>
756
757<Sect2><Title>Survey Station Names</Title>
758
759<Para><Application>Survex</Application> has a powerful system for naming stations.  It
760uses a hierarchy of survey names, similar to the nested folders
761your computer stores files in.
762So point 6 in the entrance survey of Kaninchenh&ouml;hle
763(cave number 161) is referred to as: 161.entrance.6
764</Para>
765
766<Para>This seems a natural way to refer to station names.  It also
767means that it is very easy to include more levels, for example if you
768want to plot all the caves in the area you just list them all in
769another file, specifying a new prefix.  So to group 3 nearby caves
770on the Loser Plateau you would use a file like
771this:
772</Para>
773
774<programlisting>
775*begin Loser
776*include 161
777*include 2YrGest
778*include 145
779*end Loser</programlisting>
780
781<Para>
782The entrance series point mentioned above would now be referred
783to as: Loser.161.entrance.6
784</Para>
785
786<!--
787<Para>This may seem a tad complex but is really very natural once you
788get the hang of it.
789</Para>
790-->
791<Para>You do not have to use this system at all, and can just give all
792stations unique identifiers if you like:
793</Para>
794
795<Para>1, 2, 3, 4, 5, ... 1381, 1382
796</Para>
797
798<Para>or
799</Para>
800
801<Para>AA06, AA07, P34, ZZ6, etc.
802</Para>
803
804<!-- FIXME:
805<Para>However you'll loose the ability to handle subsurveys if you do.
806</Para>
807-->
808
809<Para>Station and survey names may contain any alphanumeric characters and
810additionally any characters in NAMES (default `_' and `-'). Alphabetic
811characters may be forced to upper or lower case by using the *case
812command. Station names may be any length - if you want to only treat
813the first few characters as significant you can get cavern to truncate
814the names using the *truncate command.
815</Para>
816
817</Sect2>
818
819<Sect2><Title>Numeric fields</Title>
820
821<Para>[&lt;MINUS&gt;|&lt;PLUS&gt;] &lt;integer part&gt; [ &lt;DECIMAL&gt;
822[ &lt;decimal fraction&gt; ] ]
823</Para>
824
825<Para>
826or [&lt;MINUS&gt;|&lt;PLUS&gt;] &lt;DECIMAL&gt; &lt;dec fraction&gt;
827</Para>
828
829<Para><!-- FIXME: put informal description first -->
830i.e. optional PLUS or MINUS sign in front, with
831optional DECIMAL character (default '.'), which may be
832embedded, leading or trailing. No spaces are allowed between the
833various elements.
834</Para>
835
836<Para>
837All of these are valid examples: +47, 23, -22, +4.5, 1.3, -0.7, +.15, .4,
838-.05
839</Para>
840
841</Sect2>
842
843<Sect2><Title>Accuracy</Title>
844
845<Para>Accuracy assessments may be provided or defaulted for any survey
846leg. These determine the distribution of loop closure errors over the
847legs in the loop. See *SD for more information.
848</Para>
849
850</Sect2>
851
852<!--
853<Sect2><Title>Survey Coordinate Range</Title>
854
855<Para>
856If we store distances to nearest 10um (0.01mm) in 4 bytes, this
857gives a range of ~20 km. This method is currently not used, but
858has several advantages (data storage space [double uses 8 bytes
859- with my C compiler], speed (unless your FP chip works in parallel
860with your CPU [e.g. the new Acorn FPU for the ARM], and numerical
861accuracy [compared to using floats at least]) and so may be adopted
862in future). Nearest 0.1mm gives -200 km, which is enough for most
863people, but may mean rounding errors become significant.
864</Para>
865
866<Para>
867I will have to do some sums...
868</Para>
869
870</Sect2>
871
872-->
873
874<Sect2><Title>Cavern Commands</Title>
875
876<Para>Commands in <filename>.svx</filename> files are introduced by an asterisk
877(by default - this can be changed using the <command>set</command> command).
878</Para>
879
880<Para>The commands are documented in a common format:
881</Para>
882
883<!-- FIXME: make this a RefGroup (or whatever that's called) of RefEntry-s? -->
884<itemizedlist>
885<listitem><para>Command Name</para></listitem>
886<listitem><para>Syntax</para></listitem>
887<listitem><para>Example</para></listitem>
888<listitem><para>Validity</para></listitem>
889<!-- FIXME
890anywhere, in a block, at start of a block, after a begin (for *end)
891-->
892<listitem><para>Description</para></listitem>
893<listitem><para>Caveats</para></listitem>
894<listitem><para>See Also</para></listitem>
895<!-- FIXME
896"Usefulness" - or status maybe?
897deprecated, esoteric (*set), useful, vital
898-->
899</itemizedlist>
900
901<Sect3><Title>ALIAS</Title>
902
903<VariableList>
904
905<VarListEntry><Term>Syntax</Term>
906
907<listitem><Para>*alias station &lt;alias&gt; [&lt;target&gt;]</Para></listitem>
908
909</VarListEntry>
910
911<VarListEntry><Term>Example</Term>
912
913<listitem>
914<Para>
915<programlisting>
916*begin parsons_nose
917*alias station - ..
9181 2 12.21 073 -12
9192 -  4.33 011 +02
9202 -  1.64 180 +03
9212 3  6.77 098 -04
922*end parsons_nose</programlisting>
923</Para>
924</listitem>
925
926</VarListEntry>
927
928<VarListEntry><Term>Description</Term>
929
930<listitem><Para>*alias allows you to map a station name which appears in
931the survey data to a different name internally.  At present, you can only
932create an alias of '-' to '..', which is intended to support the pocket topo
933style notation of '-' being a splay to an anonymous point on the cave wall.
934And you can unalias '-' with '*alias station -'.
935</Para>
936
937<Para>
938Aliases are scoped by *begin/*end blocks - when a *end is reached, the aliases
939in force at the corresponding begin are restored.
940</Para>
941
942<Para>
943*alias was added in Survex 1.2.7.
944</Para></listitem>
945
946</VarListEntry>
947
948<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
949
950<VarListEntry><Term>See Also</Term>
951
952<listitem><Para>*begin, *end</Para></listitem>
953
954</VarListEntry>
955
956</VariableList>
957
958</Sect3>
959
960<Sect3><Title>BEGIN</Title>
961
962<VariableList>
963
964<VarListEntry><Term>Syntax</Term>
965
966<listitem><Para>*begin [&lt;survey&gt;]</Para></listitem>
967
968</VarListEntry>
969
970<VarListEntry><Term>Example</Term>
971
972<listitem>
973<Para>
974<programlisting>
975*begin littlebit
9761 2 10.23 106 -02
9772 3  1.56 092 +10
978*end littlebit</programlisting>
979
980<programlisting>
981; length of leg across shaft estimated
982*begin
983*sd tape 2 metres
9849 10 6.   031 -07
985*end</programlisting>
986</Para>
987</listitem>
988
989</VarListEntry>
990
991<VarListEntry><Term>Description</Term>
992
993<listitem><Para>*begin stores the current values of the current settings
994such as instrument calibration, data format, and so on.
995These stored values are restored after the corresponding *end.
996If a survey name is given, this is used inside the *begin/*end block,
997and the corresponding *end should have the same survey name.
998*begin/*end blocks may be nested to indefinite depth.
999</Para></listitem>
1000
1001</VarListEntry>
1002
1003<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1004
1005<VarListEntry><Term>See Also</Term>
1006
1007<listitem><Para>*end, *prefix</Para></listitem>
1008
1009</VarListEntry>
1010
1011</VariableList>
1012
1013</Sect3>
1014
1015<Sect3><Title>CALIBRATE</Title>
1016
1017<VariableList>
1018
1019<VarListEntry><Term>Syntax</Term>
1020
1021<listitem>
1022<Para>*calibrate &lt;quantity list&gt; &lt;zero error&gt; [&lt;scale&gt;]
1023</Para>
1024<Para>*calibrate default
1025</Para>
1026</listitem>
1027
1028</VarListEntry>
1029
1030<VarListEntry><Term>Example</Term>
1031
1032<listitem>
1033<Para>
1034<programlisting>
1035*calibrate tape +0.3
1036</programlisting>
1037</Para>
1038</listitem>
1039
1040</VarListEntry>
1041
1042<VarListEntry><Term>Description</Term>
1043
1044<listitem>
1045
1046<Para>
1047*calibrate is used to specify instrument calibrations.
1048</Para>
1049
1050<Para>
1051&lt;quantity&gt; is one of TAPE|COMPASS|CLINO|COUNTER|DEPTH|DECLINATION|X|Y|Z
1052</Para>
1053
1054<Para>
1055Several quantities can be given in &lt;quantity list&gt;
1056</Para>
1057
1058<Para>
1059Value = ( Reading - ZeroError ) * Scale    (Scale defaults to 1.0)
1060</Para>
1061
1062<Para>
1063You need to be careful about the sign of the ZeroError. The value of
1064ZeroError is what the the instrument would read when measuring a
1065reading which should be zero.  So for example, if your tape measure
1066has the end missing, and you are using the 30cm mark to take all
1067measurements from, then a zero distance would be measured as 30cm and
1068you would correct this with:
1069</Para>
1070
1071<programlisting>*CALIBRATE tape +0.3</programlisting>
1072
1073<Para>If you tape was too long, starting at -20cm (it does happen!)
1074then you can correct it with:
1075</Para>
1076
1077<programlisting>*CALIBRATE tape -0.2</programlisting>
1078
1079<Para>Note: ZeroError is irrelevant for Topofil counters and depth
1080gauges since pairs of readings are subtracted.
1081</Para>
1082
1083<Para>
1084The magnetic deviation varies from year to year and it is often
1085desirable to keep the compass zero error and the magnetic deviation
1086separate. cavern calculates the true bearing as follows:
1087</Para>
1088
1089<Para>
1090(magnetic bearing) = ((reading)-(compass zero err)) * (compass
1091scale factor)
1092</Para>
1093
1094<Para>
1095(true bearing) = ((bearing)-(declination zero err))
1096</Para>
1097
1098<Para>
1099The scale factor for DECLINATION must be 1.0, otherwise an error
1100is given. <!-- FIXME: practical example for declination -->
1101</Para>
1102
1103<Para>
1104The default is all quantities calibrated to scale factor 1.0,
1105zero error 0.0
1106</Para>
1107
1108</listitem>
1109
1110</VarListEntry>
1111
1112<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1113
1114<VarListEntry><Term>See Also</Term>
1115
1116<listitem><Para>*units</Para></listitem>
1117
1118</VarListEntry>
1119
1120</VariableList>
1121
1122</Sect3>
1123
1124<Sect3><Title>CASE</Title>
1125
1126<VariableList>
1127
1128<VarListEntry><Term>Syntax</Term>
1129
1130<listitem><para>*case preserve|toupper|tolower</para></listitem>
1131
1132</VarListEntry>
1133
1134<VarListEntry><Term>Example</Term>
1135
1136<listitem>
1137<Para>
1138<programlisting>
1139*begin bobsbit
1140; Bob insists on using case sensitive station names
1141*case preserve
11421 2   10.23 106 -02
11432 2a   1.56 092 +10
11442 2A   3.12 034 +02
11452 3    8.64 239 -01
1146*end bobsbit</programlisting>
1147</Para>
1148</listitem>
1149
1150</VarListEntry>
1151
1152<VarListEntry><Term>Description</Term>
1153
1154<listitem><Para>*case determines how the case of letters in survey names is
1155handled.  By default all names are forced to lower case (which gives a case
1156insensitive match, but you can tell cavern to force to upper case, or leave
1157the case as is (in which case '2a' and '2A' will be regarded as different).
1158</Para></listitem>
1159
1160</VarListEntry>
1161
1162<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1163
1164<!-- <VarListEntry><Term>See Also</Term>
1165
1166<listitem><Para>*end, *prefix</Para></listitem>
1167
1168</VarListEntry>
1169-->
1170
1171</VariableList>
1172
1173<!-- FIXME - work this text in here or elsewhere
1174
1175What I mean (though failed to express very well) is that a dataset without
1176this information isn't the same dataset (in general anyway).  For example:
1177
1178A1 a2 10.32 140 -05
1179a2 a3  4.91 041 -01
1180a1 a3  7.01 206  02
1181
1182is either a traverse of 3 legs or a (probably badly misclosed) loop.  If
1183these names are on the original survey notes, the surveyors ought to say
1184whether "A1" is the same as "a1" (although the usual case for using this
1185feature is probably for importing data from elsewhere).  Similarly for
1186truncation.  Whether a clino of +/-90 degrees (or +/-100 grad, etc) is
1187interpreted as a plumb is something that should have been noted in the cave
1188(unless it's implicit because it's standard practice for a survey project).
1189
1190It's a similar issue to calibration data in many ways.  You can argue it's
1191not part of "the survey", but without it the survey won't be the same shape,
1192and it's not useful to process the same survey with different settings for
1193compass calibration or name case sensitivity.
1194
1195>Clearly that is unhelpfully strict, but it is
1196>important to be semantically clear about what is 'data' and what is 'commands
1197>or meta-data' which describe what to do with/how to interpret that data.
1198
1199Think of the lines starting with a "*" as "command or meta-data".
1200
1201>The most-correct solution to this is (I believe) Martin Heller's idea about
1202>including 'rules' in the datastream, but that's too big a subject for right
1203>now.
1204>
1205>The reason '-C' was made into a command-line option, was that it made very
1206>little sense to change it part way though a dataset. What exactly happens if
1207>you suddenly tell cavern to become case-sensitive halfway through a run?
1208
1209-C has always had 3 settings - "leave case alone", "force to lower", and
1210"force to upper".  It doesn't really mean "case sensitivity" but rather
1211something like "case processing".  So you can usefully change it during a
1212run.  So if my dataset treats "NoTableChamber" (so named because it was
1213lacking in furniture) as different from "NotableChamber" (which was notable
1214for other reasons) I can process it with a dataset from someone else which
1215needs to be treated as case insensitive like so:
1216
1217*begin my_cave
1218*include my_dataset
1219*end my_cave
1220
1221*equate my_cave.NoTableChamber.14 your_cave.linkpassage.13
1222
1223*begin your_cave
1224*case tolower
1225*include your_dataset
1226*end your_cave
1227
1228You may be thinking of -U<n>, which used to mean "only compare the first n
1229characters of station names", but that doesn't allow arbitrary datasets to
1230be processed together.
1231
1232So we changed it to mean "truncate station names to n characters", and
1233allowed it to be changed at any point, rather than being set once for the
1234whole run.
1235
1236-->
1237
1238</Sect3>
1239
1240<Sect3><Title>COPYRIGHT</Title>
1241
1242<VariableList>
1243
1244<VarListEntry><Term>Syntax</Term>
1245
1246<listitem><Para>*copyright &lt;date&gt; &lt;text&gt;</Para></listitem>
1247
1248</VarListEntry>
1249
1250<VarListEntry><Term>Example</Term>
1251
1252<listitem>
1253<Para>
1254<programlisting>
1255*begin littlebit
1256*copyright 1983 CUCC
12571 2 10.23 106 -02
12582 3  1.56 092 +10
1259*end littlebit</programlisting>
1260</Para>
1261</listitem>
1262
1263</VarListEntry>
1264
1265<VarListEntry><Term>Validity</Term>
1266
1267<listitem><Para>valid at the start of a *begin/*end block.
1268</Para></listitem>
1269
1270</VarListEntry>
1271
1272<VarListEntry><Term>Description</Term>
1273
1274<listitem><Para>*copyright allow the copyright information to be
1275stored in a way that can be automatically collated.
1276</Para></listitem>
1277
1278</VarListEntry>
1279
1280<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1281
1282<VarListEntry><Term>See Also</Term>
1283
1284<listitem><Para>*begin</Para></listitem>
1285
1286</VarListEntry>
1287
1288</VariableList>
1289
1290</Sect3>
1291
1292<Sect3><Title>CS</Title>
1293
1294<VariableList>
1295
1296<VarListEntry><Term>Syntax</Term>
1297
1298<listitem><Para>*cs [out] &lt;coordinate system&gt;</Para></listitem>
1299
1300</VarListEntry>
1301
1302<VarListEntry><Term>Example</Term>
1303
1304<listitem>
1305<Para>
1306<programlisting>
1307*cs UTM60S
1308*fix beehive 313800 5427953 20</programlisting>
1309</Para>
1310
1311<Para>
1312<programlisting>
1313; Output in the coordinate system used in the Totes Gebirge in Austria
1314*cs out custom "+proj=tmerc +lat_0=0 +lon_0=13d20 +k=1 +x_0=0 +y_0=-5200000 +ellps=bessel +towgs84=577.326,90.129,463.919,5.137,1.474,5.297,2.4232"</programlisting>
1315</Para>
1316</listitem>
1317
1318</VarListEntry>
1319
1320<VarListEntry><Term>Description</Term>
1321
1322<listitem><Para>*cs allows the coordinate systems used for fixed points and for
1323processed survey data to be specified.
1324</Para>
1325
1326<Para>
1327*cs was added in Survex 1.2.14.  The currently supported coordinate systems
1328are:
1329</Para>
1330
1331<Para>CUSTOM followed by a PROJ4 string (like in the example above).</Para>
1332
1333<Para>EPSG: followed by a positive integer code.  EPSG codes cover most
1334coordinate systems in use, and PROJ supports many of these.  The website
1335<ulink url="http://epsg.io/">http://epsg.io/</ulink> is a useful resource for
1336finding the EPSG code you want.  Supported since Survex 1.2.15.</Para>
1337
1338<Para>ESRI: followed by a positive integer code.  ESRI codes are used by
1339ArcGIS to specify coordinate systems (in a similar way to EPSG codes), and PROJ
1340supports many of them.  Supported since Survex 1.2.15.</Para>
1341
1342<Para>EUR79Z30 for UTM zone 30, EUR79 datum.  Supported since Survex 1.2.15.
1343</Para>
1344
1345<Para>IJTSK for the modified version of the Czechoslovak S-JTSK system where
1346the axes point East and North.  Supported since Survex 1.2.15.</Para>
1347
1348<Para>IJTSK03 for a variant of IJTSK.  Supported since Survex 1.2.15.</Para>
1349
1350<Para>JTSK for the Czechoslovak S-JTSK system.  The axes on this point West
1351and South, so it's not support as an output coordinate system.
1352Supported since Survex 1.2.16.</Para>
1353
1354<Para>JTSK03 for a variant of JTSK.  Supported since Survex 1.2.16.</Para>
1355
1356<Para>LONG-LAT for longitude/latitude.  The WGS84 datum is assumed.  Supported
1357since Survex 1.2.15.</Para>
1358
1359<Para>OSGB: followed by a two letter code for the UK Ordnance Survey National
1360Grid.  The first letter should be 'H', 'N', 'O', 'S' or 'T'; the second any
1361letter except 'I'.  Supported since Survex 1.2.15.</Para>
1362
1363<Para>S-MERC for the "Web Mercator" spherical mercator projection, used by
1364online map sites like OpenStreetMap, Google maps, Bing maps, etc.  Supported
1365since Survex 1.2.15.
1366</Para>
1367
1368<Para>UTM followed by a zone number (1-60), optionally followed by "N" or "S"
1369(default is North).  The WGS84 datum is assumed.</Para>
1370
1371<Para>
1372By default, Survex works in an unspecified coordinate system (and this was the
1373only option before *cs was added).  However, it's useful for coordinate system
1374which the processed survey data is in to be specified if you want to use the
1375processed data in ways which required knowing the coordinate system (such as
1376exporting a list of entrances for use in a GPS).  You can now do this by using
1377"*cs out".
1378</Para>
1379
1380<Para>
1381It is also useful to be able to take coordinates for fixed points in whatever
1382coordinate system you receive them in and put them directly into Survex, rather
1383than having to convert with an external tool.  For example, you may have your
1384GPS set to show coordinates in UTM with the WGS84 datum, even though you want
1385the processed data to be in some local coordinate system.  And someone else
1386may provide GPS coordinates in yet another coordinate system.  You just need
1387to set the appropriate coordinate system with "*cs" before each group of "*fix"
1388commands in a particular coordinate system.
1389</Para>
1390
1391<Para>
1392If you're going to make use of "*cs", then the coordinate system must be
1393specified for everything, so a coordinate system must be in effect for all
1394"*fix" commands, and you must set the output coordinate system before any
1395points are fixed.
1396</Para>
1397
1398<Para>
1399Also, if "*cs" is in use, then you can't omit the coordinates in a "*fix"
1400command, and a fixed point won't be invented if none exists.
1401</Para>
1402
1403<Para>
1404If you use "*cs out" more than once, the second and subsequent commands are
1405silently ignored - this makes it possible to combine two datasets with
1406different "*cs out" settings without having to modify either of them.
1407</Para>
1408
1409<Para>
1410Something to be aware of with "*cs" is that altitudes are currently assumed to
1411be "height above the ellipsoid", whereas GPS units typically give you "height
1412above sea level", or more accurately "height above a particular geoid".  This
1413is something we're looking at how best to address, but you shouldn't need to
1414worry about it if your fixed points are in the same coordinate system as your
1415output, or if they all use the same ellipsoid.  For a more detailed discussion
1416of this, please see: http://expo.survex.com/handbook/survey/coord.htm
1417</Para>
1418</listitem>
1419
1420</VarListEntry>
1421
1422<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1423
1424<VarListEntry><Term>See Also</Term>
1425
1426<listitem><Para>*fix</Para></listitem>
1427
1428</VarListEntry>
1429
1430</VariableList>
1431
1432</Sect3>
1433<Sect3><Title>DATA</Title>
1434
1435<VariableList>
1436
1437<VarListEntry><Term>Syntax</Term>
1438
1439<listitem><Para>*data &lt;style&gt; &lt;ordering&gt;</Para></listitem>
1440<!-- BACKCOMPASS BACKCLINO -->
1441</VarListEntry>
1442
1443<VarListEntry><Term>Example</Term>
1444
1445<listitem>
1446<Para>
1447<programlisting>
1448*data normal from to compass tape clino</programlisting>
1449</Para>
1450
1451<Para>
1452<programlisting>
1453*data normal station ignoreall newline compass tape clino</programlisting>
1454</Para>
1455</listitem>
1456
1457</VarListEntry>
1458
1459<VarListEntry><Term>Description</Term>
1460
1461<listitem><Para>
1462&lt;style&gt; = DEFAULT|NORMAL|DIVING|CARTESIAN|TOPOFIL|CYLPOLAR|NOSURVEY|PASSAGE
1463</Para>
1464
1465<Para>
1466&lt;ordering&gt; = ordered list of instruments - which are valid depends on the
1467style.
1468</Para>
1469
1470<Para>
1471In Survex 1.0.2 and later, TOPOFIL is simply a synonym for NORMAL, left in to
1472allow older data to be processed without modification.  Use the name NORMAL
1473by preference.
1474</Para>
1475
1476<Para>
1477There are two variants of each style - interleaved and non-interleaved.
1478Non-interleaved is "one line per leg", interleaved has a line for the data
1479shared between two legs (e.g. STATION=FROM/TO, DEPTH=FROMDEPTH/TODEPTH,
1480COUNT=FROMCOUNT/TOCOUNT).  Note that not all interleavable readings have to
1481be interleaved - for example:
1482
1483<programlisting>
1484*data diving station newline fromdepth compass tape todepth</programlisting>
1485
1486In addition, interleaved data can have a DIRECTION reading, which can be "F"
1487for a foresight or "B" for a backsight.
1488</Para>
1489
1490<Para>
1491In NORMAL, DIVING, and CYLPOLAR data styles, TAPE may be replaced by
1492FROMCOUNT/TOCOUNT (or COUNT in interleaved data) to allow processing of surveys
1493performed with a Topofil instead of a tape.
1494</Para>
1495
1496<VariableList>
1497
1498<VarListEntry><Term>DEFAULT</Term>
1499<listitem><Para>Select the default data style and ordering (NORMAL style, ordering: from to tape compass clino).</Para></listitem>
1500</VarListEntry>
1501
1502<VarListEntry><Term>NORMAL</Term>
1503<listitem><Para>The usual tape/compass/clino centreline survey.
1504For non-interleaved data the allowed readings are:
1505FROM TO TAPE COMPASS CLINO BACKCOMPASS BACKCLINO;
1506for interleaved data the allowed readings are:
1507STATION DIRECTION TAPE COMPASS CLINO BACKCOMPASS BACKCLINO.
1508The CLINO/BACKCLINO reading is not required - if it's not given, the vertical
1509standard deviation is taken to be proportional to the tape measurement.
1510Alternatively, individual clino readings can be given as OMIT (default "-")
1511which allows for data where only some clino readings are missing.
1512E.g.:
1513
1514<programlisting>
1515*data normal from to compass clino tape
15161 2 172 -03 12.61</programlisting>
1517
1518<programlisting>
1519*data normal station newline direction tape compass clino
15201
1521 F 12.61 172 -03
15222</programlisting>
1523
1524<programlisting>
1525*data normal from to compass clino fromcount tocount
15261 2 172 -03 11532 11873</programlisting>
1527
1528<programlisting>
1529*data normal station count newline direction compass clino
15301 11532
1531 F 172 -03
15322 11873</programlisting>
1533 
1534</Para></listitem>
1535</VarListEntry>
1536
1537<VarListEntry><Term>DIVING</Term>
1538<listitem><Para>
1539An underwater survey where the vertical information is from a diver's depth
1540gauge.  This style can also be also used for an above-water survey where the
1541altitude is measured with an altimeter.  DEPTH is defined as the altitude (Z)
1542so increases upwards by default.  So for a diver's depth gauge, you'll need to
1543use *CALIBRATE with a negative scale factor (e.g. *calibrate depth 0 -1).
1544</Para>
1545
1546<Para>For non-interleaved data the allowed readings are:
1547FROM TO TAPE COMPASS BACKCOMPASS FROMDEPTH TODEPTH DEPTHCHANGE (the vertical
1548can be given as readings at each station, (FROMDEPTH/TODEPTH) or as a change
1549along the leg (DEPTHCHANGE)).</Para>
1550
1551<Para>For interleaved data the allowed readings are:
1552STATION DIRECTION TAPE COMPASS BACKCOMPASS DEPTH DEPTHCHANGE.
1553(the vertical change can be given as a reading at the station (DEPTH) or as a change along the leg (DEPTHCHANGE)).
1554
1555<programlisting>
1556*data diving from to tape compass fromdepth todepth
15571 2 14.7 250 -20.7 -22.4</programlisting>
1558
1559<programlisting>
1560*data diving station depth newline tape compass
15611 -20.7
1562 14.7 250
15632 -22.4</programlisting>
1564
1565<programlisting>
1566*data diving from to tape compass depthchange
15671 2 14.7 250 -1.7</programlisting>
1568</Para>
1569</listitem>
1570</VarListEntry>
1571
1572<VarListEntry><Term>CARTESIAN</Term>
1573<listitem><Para>
1574Cartesian data style allows you to specify the (x,y,z) changes between
1575stations.  It's useful for digitising surveys where the original survey
1576data has been lost and all that's available is a drawn up version.
1577
1578<programlisting>
1579*data cartesian from to northing easting altitude
15801 2 16.1 20.4 8.7</programlisting>
1581
1582<programlisting>
1583*data cartesian station newline northing easting altitude
15841
1585 16.1 20.4 8.7
15862</programlisting>
1587
1588<!--FIXME: dx dy dz-->
1589</Para>
1590
1591<Note><Para>
1592Cartesian data are relative to <emphasis>true</emphasis> North not
1593<emphasis>magnetic</emphasis> North (i.e. they are unaffected by
1594<command>*calibrate declination</command>).
1595</Para></Note>
1596</listitem>
1597</VarListEntry>
1598
1599<VarListEntry><Term>CYLPOLAR</Term>
1600<listitem><Para>
1601A CYLPOLAR style survey is very similar to a diving survey, except that the tape
1602is always measured horizontally rather than along the slope of the leg.
1603
1604<programlisting>
1605*data cypolar from to tape compass fromdepth todepth
16061 2 9.45 311 -13.3 -19.0</programlisting>
1607
1608<programlisting>
1609*data cylpolar station depth newline tape compass
16101 -13.3
1611 9.45 311
16122 -19.0</programlisting>
1613
1614<programlisting>
1615*data cylpolar from to tape compass depthchange
16161 2 9.45 311 -5.7</programlisting>
1617</Para></listitem>
1618</VarListEntry>
1619
1620<VarListEntry><Term>NOSURVEY</Term>
1621<listitem><Para>
1622A NOSURVEY survey doesn't have any measurements - it merely indicates that
1623there is line of sight between the pairs of stations.
1624
1625<programlisting>
1626*data nosurvey from to
16271 7
16285 7
16299 11</programlisting>
1630
1631<programlisting>
1632*data nosurvey station
16331
16347
16355
1636
1637*data nosurvey station
16389
163911</programlisting>
1640</Para></listitem>
1641</VarListEntry>
1642
1643<VarListEntry><Term>PASSAGE</Term>
1644<listitem><Para>
1645This survey style defines a 3D "tube" modelling a passage in the cave.
1646The tube uses the survey stations listed in the order listed.  It's
1647permitted to use survey stations which aren't directly linked by
1648the centre-line survey.  This can be useful - sometimes the centreline
1649will step sideways or up/down to allow a better sight for the next
1650leg and you can ignore the extra station.  You can also define tubes
1651along unsurveyed passages, akin to "nosurvey" legs in the centreline
1652data.</Para>
1653
1654<Para>This means that you need to split off side passages into seperate
1655tubes, and hence separate sections of passage data, starting with
1656a new *data command.</Para>
1657
1658<Para>
1659Simple example of how to use this data style (note the use of ignoreall
1660to allow a free-form text description to be given):
1661
1662<programlisting>
1663*data passage station left right up down ignoreall
16641  0.1 2.3 8.0 1.4  Sticking out point on left wall
16652  0.0 1.9 9.0 0.5  Point on left wall
16663  1.0 0.7 9.0 0.8  Highest point of boulder
1667</programlisting>
1668</Para>
1669</listitem>
1670</VarListEntry>
1671</VariableList>
1672
1673<Para>
1674IGNORE skips a field (it may be used any number of times),
1675and IGNOREALL may be used last to ignore the rest of the data line.
1676</Para>
1677
1678<Para>
1679LENGTH is a synonym for TAPE; BEARING for COMPASS; GRADIENT for CLINO; COUNT for COUNTER.<!--FIXME : others?-->
1680</Para>
1681
1682<Para>
1683The units of each quantity may be set with the UNITS command.
1684</Para>
1685
1686<!-- FIXME: plumbed diving legs -->
1687
1688<!--FIXME:
1689<Para>
1690Uses for CYLPOLAR:
1691Perhaps a Grade 3 survey, or when surveying with a level and stick (?)
1692[note - UBSS use it for the old County Clare data]
1693</Para>
1694-->
1695
1696</listitem>
1697
1698</VarListEntry>
1699
1700</VariableList>
1701
1702</Sect3>
1703
1704<Sect3><Title>DATE</Title>
1705<VariableList>
1706
1707<VarListEntry><Term>Syntax</Term>
1708
1709<listitem><Para>*date &lt;year&gt;[.&lt;month&gt;[.&lt;day&gt;]][-&lt;year&gt;[.&lt;month&gt;[.&lt;day&gt;]]]</Para></listitem>
1710
1711</VarListEntry>
1712
1713<VarListEntry><Term>Example</Term>
1714
1715<listitem>
1716<Para>
1717<programlisting>
1718*date 2001</programlisting>
1719
1720<programlisting>
1721*date 2000.10</programlisting>
1722
1723<programlisting>
1724*date 1987.07.27</programlisting>
1725
1726<programlisting>
1727*date 1985.08.12-1985.08.13</programlisting>
1728</Para>
1729</listitem>
1730
1731</VarListEntry>
1732
1733<VarListEntry><Term>Validity</Term>
1734
1735<listitem><Para>valid at the start of a *begin/*end block.
1736</Para></listitem>
1737
1738</VarListEntry>
1739
1740<VarListEntry><Term>Description</Term>
1741
1742<listitem><Para>
1743*date specifies the date that the survey was done.  A range of dates
1744can be specified (useful for overnight or multi-day surveying trips).
1745</Para></listitem>
1746
1747</VarListEntry>
1748
1749<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1750
1751<VarListEntry><Term>See Also</Term>
1752
1753<listitem><Para>*begin, *instrument, *team</Para></listitem>
1754
1755</VarListEntry>
1756
1757</VariableList>
1758
1759</Sect3>
1760
1761<Sect3><Title>DEFAULT</Title>
1762
1763<VariableList>
1764
1765<VarListEntry><Term>Syntax</Term>
1766
1767<listitem><Para>*default &lt;settings list&gt;|all</Para></listitem>
1768
1769</VarListEntry>
1770
1771<VarListEntry><Term>Description</Term>
1772
1773<listitem><Para>
1774The valid settings are CALIBRATE, DATA, and UNITS.
1775</Para>
1776
1777<Para>
1778*default restores defaults for given settings.  This command is deprecated -
1779you should instead use: *calibrate default, *data default, *units default.
1780</Para></listitem>
1781
1782</VarListEntry>
1783
1784<VarListEntry><Term>See Also</Term>
1785
1786<listitem><Para>*calibrate, *data, *units</Para></listitem>
1787
1788</VarListEntry>
1789
1790</VariableList>
1791
1792</Sect3>
1793
1794<Sect3><Title>END</Title>
1795
1796<VariableList>
1797
1798<VarListEntry><Term>Syntax</Term>
1799
1800<listitem><Para>*end [&lt;survey&gt;]</Para></listitem>
1801
1802</VarListEntry>
1803
1804<VarListEntry><Term>Validity</Term>
1805
1806<listitem><Para>valid for closing a block started by *begin in the same file.
1807</Para></listitem>
1808
1809</VarListEntry>
1810
1811<VarListEntry><Term>Description</Term>
1812
1813<listitem><Para>
1814Closes a block started by *begin.
1815</Para></listitem>
1816
1817</VarListEntry>
1818
1819<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1820
1821<VarListEntry><Term>See Also</Term>
1822
1823<listitem><Para>*begin</Para></listitem>
1824
1825</VarListEntry>
1826
1827</VariableList>
1828
1829</Sect3>
1830
1831<Sect3><Title>ENTRANCE</Title>
1832
1833<VariableList>
1834
1835<VarListEntry><Term>Syntax</Term>
1836
1837<listitem><Para>*entrance &lt;station&gt;</Para></listitem>
1838
1839</VarListEntry>
1840
1841<VarListEntry><Term>Example</Term>
1842
1843<listitem>
1844<Para>
1845<programlisting>
1846*entrance P163</programlisting>
1847</Para>
1848</listitem>
1849
1850</VarListEntry>
1851
1852<VarListEntry><Term>Description</Term>
1853
1854<listitem><Para>
1855*entrance sets the <emphasis>entrance</emphasis> flag for a station.
1856This information is used by aven to allow entrances to be highlighted.
1857</Para>
1858
1859<!-- FIXME:
1860(could be inferred from surface/ug join, but better to specify because
1861of caves with no surf svy (or no underground survey)
1862and also situations in which multiple surveys leave through an entrance)
1863-->
1864</listitem>
1865
1866</VarListEntry>
1867
1868<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1869
1870<!-- <VarListEntry><Term>See Also</Term>
1871
1872<listitem><Para></Para></listitem>
1873
1874</VarListEntry>
1875-->
1876
1877</VariableList>
1878
1879</Sect3>
1880
1881<Sect3><Title>EQUATE</Title>
1882
1883<VariableList>
1884
1885<VarListEntry><Term>Syntax</Term>
1886
1887<listitem><Para>*equate &lt;station&gt; &lt;station&gt;...</Para></listitem>
1888
1889</VarListEntry>
1890
1891<VarListEntry><Term>Example</Term>
1892
1893<listitem>
1894<Para>
1895<programlisting>
1896*equate chosspot.1 triassic.27</programlisting>
1897</Para>
1898</listitem>
1899
1900</VarListEntry>
1901
1902<VarListEntry><Term>Description</Term>
1903
1904<listitem><Para>
1905*equate specifies that the station names in the list refer to the
1906same physical survey station. An error is given if there is only one station
1907listed.
1908</Para>
1909
1910<!-- FIXME:
1911<Para>
1912I think this is preferable to using:
1913</Para>
1914
1915<programlisting> a b 0.00   0   0</programlisting>
1916
1917<Para>
1918as EQUATE does not add in an extra position error. It is also clearer than
1919substituting in the original name wherever passages are linked. If you
1920disagree, you can always use one of the other methods!
1921</Para>
1922-->
1923</listitem>
1924
1925</VarListEntry>
1926
1927<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1928
1929<VarListEntry><Term>See Also</Term>
1930
1931<listitem><Para>*infer equates</Para></listitem>
1932
1933</VarListEntry>
1934
1935</VariableList>
1936
1937</Sect3>
1938
1939<Sect3><Title>EXPORT</Title>
1940
1941<VariableList>
1942
1943<VarListEntry><Term>Syntax</Term>
1944
1945<listitem><Para>*export &lt;station&gt;...</Para></listitem>
1946
1947</VarListEntry>
1948
1949<VarListEntry><Term>Example</Term>
1950
1951<!-- FIXME better example -->
1952<listitem>
1953<Para>
1954<programlisting>
1955*export 1 6 17</programlisting>
1956</Para>
1957</listitem>
1958
1959</VarListEntry>
1960
1961<VarListEntry><Term>Validity</Term>
1962
1963<listitem><Para>valid at the start of a *begin/*end block.
1964</Para></listitem>
1965
1966</VarListEntry>
1967
1968<VarListEntry><Term>Description</Term>
1969
1970<listitem><Para>
1971*export marks the stations named as referable to from the enclosing
1972survey.  To be able to refer to a station from a survey several levels
1973above, it must be exported from each enclosing survey.
1974</Para>
1975
1976<!-- FIXME:
1977<Para>
1978I think this is preferable to using:
1979</Para>
1980
1981<programlisting> a b 0.00   0   0</programlisting>
1982
1983<Para>
1984as EQUATE does not add in an extra position error. It is also clearer than
1985substituting in the original name wherever passages are linked. If you
1986disagree, you can always use one of the other methods!
1987</Para>
1988-->
1989</listitem>
1990
1991</VarListEntry>
1992
1993<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
1994
1995<VarListEntry><Term>See Also</Term>
1996
1997<listitem><Para>*begin, *infer exports</Para></listitem>
1998
1999</VarListEntry>
2000
2001</VariableList>
2002
2003</Sect3>
2004
2005<Sect3><Title>FIX</Title>
2006
2007<VariableList>
2008
2009<VarListEntry><Term>Syntax</Term>
2010
2011<listitem><Para>*fix &lt;station&gt; [reference]
2012 [ &lt;x&gt; &lt;y&gt; &lt;z&gt;
2013   [ &lt;x std err&gt; &lt;y std err&gt; &lt;z std err&gt;
2014     [ &lt;cov(x,y)&gt; &lt;cov(y,z)&gt; &lt;cov(z,x)&gt; ] ] ]
2015</Para></listitem>
2016
2017</VarListEntry>
2018
2019<VarListEntry><Term>Example</Term>
2020
2021<listitem>
2022<Para>
2023<programlisting>
2024*fix entrance.0 32768 86723 1760</programlisting>
2025
2026<programlisting>
2027*fix KT114_96 reference 36670.37 83317.43 1903.97</programlisting>
2028</Para>
2029</listitem>
2030
2031</VarListEntry>
2032
2033<VarListEntry><Term>Description</Term>
2034
2035<listitem>
2036<Para>
2037*fix fixes the position of &lt;station&gt; at the given coordinates.
2038If you haven't specified the coordinate system with "*cs", you can
2039omit the position and it will default to (0,0,0).  The standard errors default
2040to zero (fix station exactly).  cavern will give an error if you attempt to fix
2041the same survey station twice at different coordinates, or a warning if you fix
2042it twice with matching coordinates.
2043</Para>
2044
2045<Para>
2046You can also specify just one standard error (in which case it is assumed
2047equal in X, Y, and Z) or two (in which case the first is taken as the
2048standard error in X and Y, and the second as the standard error in Z).
2049</Para>
2050
2051<Para>
2052If you have covariances for the fix, you can also specify these - the
2053order is cov(x,y) cov(y,z) cov(z,x).
2054</Para>
2055
2056<Para>
2057You can fix as many stations as you like - just use a *fix command for each
2058one.  Cavern will check that all stations are connected to
2059at least one fixed point so that co-ordinates can be calculated for all
2060stations.
2061</Para>
2062
2063<Para>
2064By default cavern will warn about stations which have been FIX-ed but
2065not used otherwise.  This is unhelpful if you want to include a
2066standard file of benchmarks, some of which won't be used.
2067In this sort of situation, specify "REFERENCE" after the station name
2068in the FIX command to suppress this warning for a particular station.
2069</Para>
2070
2071<Note><Para>
2072X is Easting, Y is Northing, and Z is altitude.  This convention was chosen
2073since on a map, the horizontal (X) axis is usually East, and the vertical
2074axis (Y) North.  The choice of altitude (rather than depth) for Z is taken
2075from surface maps, and makes for less confusion when dealing with cave
2076systems with more than one entrance.  It also gives a right-handed
2077set of axes.
2078</Para></Note>
2079
2080</listitem>
2081</VarListEntry>
2082
2083<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2084
2085<!-- <VarListEntry><Term>See Also</Term>
2086
2087<listitem><Para></Para></listitem>
2088
2089</VarListEntry>
2090-->
2091
2092</VariableList>
2093
2094</Sect3>
2095
2096<!--
2097<Sect3><Title></Title>
2098
2099<VariableList>
2100
2101<VarListEntry><Term>Syntax</Term>
2102
2103<listitem><Para>*</Para></listitem>
2104
2105</VarListEntry>
2106
2107<VarListEntry><Term>Example</Term>
2108
2109<listitem>
2110<Para>
2111<programlisting>
2112*</programlisting>
2113</Para>
2114</listitem>
2115
2116</VarListEntry>
2117
2118<VarListEntry><Term>Description</Term>
2119
2120<listitem><Para>
2121</Para></listitem>
2122
2123</VarListEntry>
2124
2125<VarListEntry><Term>Caveats </Term> </VarListEntry>
2126
2127<VarListEntry><Term>See Also</Term>
2128
2129<listitem><Para></Para></listitem>
2130
2131</VarListEntry>
2132
2133</VariableList>
2134
2135</Sect3>
2136-->
2137
2138<Sect3><Title>FLAGS</Title>
2139
2140<VariableList>
2141
2142<VarListEntry><Term>Syntax</Term>
2143
2144<listitem><Para>*flags &lt;flags&gt;</Para></listitem>
2145
2146</VarListEntry>
2147
2148<VarListEntry><Term>Example</Term>
2149
2150<listitem>
2151<Para>
2152<programlisting>
2153*flags duplicate not surface</programlisting>
2154</Para>
2155</listitem>
2156
2157</VarListEntry>
2158
2159<VarListEntry><Term>Description</Term>
2160
2161<listitem><Para>
2162*flags updates the current flag settings.
2163Flags not mentioned retain their previous state.  Valid flags
2164are DUPLICATE, SPLAY, and SURFACE, and a flag may be preceded with NOT to
2165turn it off.
2166</Para>
2167
2168<Para>
2169Survey legs marked SURFACE are hidden from plots by default, and not
2170included in cave survey length calculations.  Survey legs marked as
2171DUPLICATE or SPLAY are also not included in cave survey length
2172calculations; legs marked SPLAY are ignored by the extend program.
2173DUPLICATE is intended for the case when if you have two different
2174surveys along the same section of passage (for example to tie two
2175surveys into a permanent survey station); SPLAY is intended for
2176cases such as radial legs in a large chamber.
2177</Para>
2178</listitem>
2179
2180</VarListEntry>
2181
2182<VarListEntry><Term>See Also</Term>
2183
2184<listitem><Para>*begin</Para></listitem>
2185
2186</VarListEntry>
2187
2188</VariableList>
2189
2190</Sect3>
2191
2192<Sect3><Title>INCLUDE</Title>
2193
2194<VariableList>
2195
2196<VarListEntry><Term>Syntax</Term>
2197
2198<listitem><Para>*include &lt;filename&gt;</Para></listitem>
2199
2200</VarListEntry>
2201
2202<VarListEntry><Term>Example</Term>
2203
2204<listitem>
2205<Para>
2206<programlisting>
2207*include mission</programlisting>
2208
2209<programlisting>
2210*include "the pits"</programlisting>
2211</Para>
2212</listitem>
2213
2214</VarListEntry>
2215
2216<VarListEntry><Term>Description</Term>
2217
2218<listitem><Para>
2219*include processes &lt;filename&gt; as if it were inserted at this
2220place in the current file. (i.e. The current settings are carried
2221into &lt;filename&gt;, and any alterations to settings in &lt;filename&gt;
2222will be carried back again).  There's one exception to this (for
2223obscure historical reasons) which is that the survey prefix is
2224restored upon return to the original file.  Since *begin and *end
2225nesting cannot cross files, this can only make a difference if you
2226use the deprecated *prefix command.
2227</Para>
2228
2229<Para>If &lt;filename&gt; contains spaces, it must be enclosed in quotes.
2230</Para>
2231
2232<Para>An included file which does not have a complete path
2233is resolved relative to the directory which the parent file is in
2234(just as relative HTML links do).  Cavern will try adding a <filename>.svx</filename>
2235extension, and will also try translating "\" to "/".
2236And as a last
2237resort, it will try a lower case version of the filename (so if you
2238use Unix and someone sends you a DOS/Windows dataset with mismatched
2239case, unzip it with "unzip -L" and UNIX cavern will process it).
2240</Para>
2241
2242<Para>
2243The depth to which you can nest
2244include files may be limited by the operating system
2245you use.  Usually the limit is fairly high (>30), but if you want to be able to
2246process your dataset with <Application>Survex</Application> on any supported platform, it
2247would be prudent not to go overboard with nested include files.
2248</Para>
2249</listitem>
2250</VarListEntry>
2251
2252</VariableList>
2253
2254</Sect3>
2255
2256<Sect3><Title>INFER</Title>
2257
2258<VariableList>
2259
2260<VarListEntry><Term>Syntax</Term>
2261
2262<listitem>
2263<Para>*infer plumbs on|off</Para>
2264
2265<Para>*infer equates on|off</Para>
2266
2267<Para>*infer exports on|off</Para>
2268</listitem>
2269
2270</VarListEntry>
2271
2272<!--
2273<VarListEntry><Term>Example</Term>
2274
2275<listitem>
2276<programlisting>
2277</programlisting>
2278
2279</listitem>
2280
2281</VarListEntry>
2282-->
2283
2284<VarListEntry><Term>Description</Term>
2285
2286<listitem>
2287<Para>"*infer plumbs on" tells cavern to interpret gradients of +/- 90
2288degrees as UP/DOWN (so it
2289will not apply the clino correction to them). This is useful when
2290the data has not been converted to have UP and DOWN in it.
2291</Para>
2292
2293<para>"*infer equates on" tells cavern to interpret a leg with
2294a tape reading of zero as a *equate.  this prevents tape corrections
2295being applied to them.
2296</para>
2297
2298<para>"*infer exports on" is necessary when you have a dataset which is
2299partly annotated with *export.  It tells cavern not to complain about
2300missing *export commands in part of the dataset.  Also stations which
2301were used to join surveys are marked as exported in the 3d file.
2302</para>
2303</listitem>
2304
2305</VarListEntry>
2306
2307<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2308
2309<!--
2310<VarListEntry><Term>See Also</Term>
2311
2312<listitem><Para>*end, *prefix</Para></listitem>
2313
2314</VarListEntry>
2315-->
2316
2317</VariableList>
2318
2319</Sect3>
2320
2321<Sect3><Title>INSTRUMENT</Title>
2322
2323<VariableList>
2324
2325<VarListEntry><Term>Syntax</Term>
2326
2327<listitem><Para>*instrument &lt;instrument&gt; &lt;identifier&gt;</Para></listitem>
2328
2329</VarListEntry>
2330
2331<VarListEntry><Term>Example</Term>
2332
2333<listitem>
2334<Para>
2335<programlisting>
2336*instrument compass "CUCC 2"
2337*instrument clino "CUCC 2"
2338*instrument tape "CUCC Fisco Ranger open reel"</programlisting>
2339</Para>
2340</listitem>
2341
2342</VarListEntry>
2343
2344<VarListEntry><Term>Validity</Term>
2345
2346<listitem><Para>valid at the start of a *begin/*end block.
2347</Para></listitem>
2348
2349</VarListEntry>
2350
2351<VarListEntry><Term>Description</Term>
2352
2353<listitem><Para>
2354*instrument specifies the particular instruments used to perform a
2355survey.
2356</Para></listitem>
2357
2358</VarListEntry>
2359
2360<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2361
2362<VarListEntry><Term>See Also</Term>
2363
2364<listitem><Para>*begin, *date, *team</Para></listitem>
2365
2366</VarListEntry>
2367
2368</VariableList>
2369
2370</Sect3>
2371
2372<Sect3><Title>PREFIX</Title>
2373
2374<VariableList>
2375
2376<VarListEntry><Term>Syntax</Term>
2377
2378<listitem><Para>*prefix &lt;survey&gt;</Para></listitem>
2379
2380</VarListEntry>
2381
2382<VarListEntry><Term>Example</Term>
2383
2384<listitem>
2385<Para>
2386<programlisting>
2387*prefix flapjack</programlisting>
2388</Para>
2389</listitem>
2390
2391</VarListEntry>
2392
2393<VarListEntry><Term>Description</Term>
2394
2395<listitem><Para>
2396*prefix sets the current survey.
2397</Para></listitem>
2398
2399</VarListEntry>
2400
2401<VarListEntry><Term>Caveats </Term>
2402
2403<listitem><Para>*prefix is deprecated - you should use *begin and *end
2404instead.</Para></listitem>
2405
2406</VarListEntry>
2407
2408<VarListEntry><Term>See Also</Term>
2409
2410<listitem><Para>*begin, *end</Para></listitem>
2411
2412</VarListEntry>
2413
2414</VariableList>
2415
2416</Sect3>
2417
2418<Sect3><Title>REQUIRE</Title>
2419
2420<VariableList>
2421
2422<VarListEntry><Term>Syntax</Term>
2423
2424<listitem><Para>*require &lt;version&gt;</Para></listitem>
2425
2426</VarListEntry>
2427
2428<VarListEntry><Term>Example</Term>
2429
2430<listitem>
2431<Para>
2432<programlisting>
2433*require 0.98</programlisting>
2434</Para>
2435</listitem>
2436
2437</VarListEntry>
2438
2439<VarListEntry><Term>Description</Term>
2440
2441<listitem><Para>
2442*require checks that the version of cavern in use is at least
2443&lt;version&gt; and stops with an error if not.
2444So if your dataset requires a feature
2445introduced in a particular version, you can add a *require command and
2446users will know what version they need to upgrade to, rather than
2447getting an error message and having to guess what the real problem is.
2448</Para></listitem>
2449
2450</VarListEntry>
2451
2452</VariableList>
2453
2454</Sect3>
2455
2456<Sect3><Title>SD</Title>
2457
2458<VariableList>
2459
2460<VarListEntry><Term>Syntax</Term>
2461
2462<listitem><Para>*sd &lt;quantity list&gt; &lt;standard deviation&gt;
2463</Para></listitem>
2464
2465</VarListEntry>
2466
2467<VarListEntry><Term>Example</Term>
2468
2469<listitem>
2470<Para>
2471<programlisting>
2472*sd tape 0.15 metres</programlisting>
2473</Para>
2474</listitem>
2475
2476</VarListEntry>
2477
2478<VarListEntry><Term>Description</Term>
2479
2480<listitem><Para>
2481*sd sets the standard deviation of a measurement.
2482</Para>
2483
2484<Para>
2485&lt;quantity&gt; is one of (each group gives alternative names for the same
2486quantity):
2487</Para>
2488
2489<ItemizedList>
2490    <listitem><para>TAPE, LENGTH</para></listitem>
2491    <listitem><para>COMPASS, BEARING</para></listitem>
2492    <listitem><para>BACKCOMPASS, BACKBEARING</para></listitem>
2493    <listitem><para>CLINO, GRADIENT</para></listitem>
2494    <listitem><para>BACKCLINO, BACKGRADIENT</para></listitem>
2495    <listitem><para>COUNTER, COUNT</para></listitem>
2496    <listitem><para>DEPTH</para></listitem>
2497    <listitem><para>DECLINATION</para></listitem>
2498    <listitem><para>DX, EASTING</para></listitem>
2499    <listitem><para>DY, NORTHING</para></listitem>
2500    <listitem><para>DZ, ALTITUDE</para></listitem>
2501    <listitem><para>LEFT</para></listitem>
2502    <listitem><para>RIGHT</para></listitem>
2503    <listitem><para>UP, CEILING</para></listitem>
2504    <listitem><para>DOWN, FLOOR</para></listitem>
2505    <listitem><para>LEVEL</para></listitem>
2506    <listitem><para>PLUMB</para></listitem>
2507    <listitem><para>POSITION</para></listitem>
2508</ItemizedList>
2509
2510<Para>
2511&lt;standard deviation&gt; must include units and thus is typically
2512"0.05 metres", or "0.02 degrees". See *units below for full list
2513of valid units.
2514</Para>
2515
2516<!-- FIXME mention central limit theorem -->
2517<Para>
2518To utilise this command fully you need to understand what a
2519<emphasis>standard deviation</emphasis> is.
2520It gives a value to the 'spread' of the errors
2521in a measurement. Assuming that these are normally distributed
2522we can say that 95.44% of the actual lengths will fall within two
2523standard deviations of the measured length. i.e. a tape SD of
25240.25 metres means that the actual length of a tape measurement
2525is within + or - 0.5 metres of the recorded value 95.44% of the time.
2526So if the measurement is 7.34m then the actual length is very
2527likely to be between 6.84m and 7.84m. This example corresponds
2528to BCRA grade 3. Note that this is just one interpretation of
2529the BCRA standard, taking the permitted error values as 2SD 95.44%
2530confidence limits. If you want to take the readings as being some
2531other limit (e.g. 1SD = 68.26%) then you will need to change the BCRA3
2532and BCRA5 files accordingly. This issue is explored in more
2533detail in various surveying articles.
2534<!--
25352.565 sd 99%
25362.5   sd 98.76%
25372     sd 95.44%
25381     sd 68.26%
2539.97   sd 66.67%
25401.15  sd 75%
2541-->
2542</Para></listitem>
2543
2544</VarListEntry>
2545
2546<VarListEntry><Term>See Also</Term>
2547
2548<listitem><Para>*units</Para></listitem>
2549
2550</VarListEntry>
2551
2552</VariableList>
2553
2554</Sect3>
2555
2556<Sect3><Title>SET</Title>
2557
2558<VariableList>
2559
2560<VarListEntry><Term>Syntax</Term>
2561
2562<listitem><Para>*set &lt;item&gt; &lt;character list&gt;</Para></listitem>
2563
2564</VarListEntry>
2565
2566<VarListEntry><Term>Example</Term>
2567
2568<listitem>
2569<Para>
2570<programlisting>
2571*set blank x09x20
2572*set decimal ,</programlisting>
2573
2574Note that you need to eliminate comma from being a blank before setting it as
2575a decimal - otherwise the comma in "*set decimal ," is parsed as a blank, and
2576you set decimal to not have any characters representing it.
2577</Para>
2578</listitem>
2579
2580</VarListEntry>
2581
2582<VarListEntry><Term>Description</Term>
2583
2584<listitem><Para>
2585*set sets the specified &lt;item&gt; to the character or characters
2586given in &lt;character list&gt;. The example sets the decimal
2587separator to be a comma.
2588</Para>
2589
2590<Para>
2591xAB means the character with hex value AB. Eg x20 is a space.
2592</Para>
2593
2594<Para>
2595The complete list of items that can be set, the defaults (in
2596brackets), and the meaning of the item, is:
2597</Para>
2598
2599<ItemizedList>
2600
2601<ListItem><Para>
2602BLANK (x09x20,) Separates fields
2603</Para></ListItem>
2604
2605<ListItem><Para>
2606COMMENT (;) Introduces comments
2607</Para></ListItem>
2608
2609<ListItem><Para>
2610DECIMAL (.) Decimal point character
2611</Para></ListItem>
2612
2613<ListItem><Para>
2614EOL (x0Ax0D) End of line character
2615</Para></ListItem>
2616
2617<ListItem><Para>
2618KEYWORD (*) Introduces keywords
2619</Para></ListItem>
2620
2621<ListItem><Para>
2622MINUS (-) Indicates negative number
2623</Para></ListItem>
2624
2625<ListItem><Para>
2626NAMES (_-) Non-alphanumeric chars permitted in station
2627names (letters and numbers are always permitted).
2628</Para></ListItem>
2629
2630<ListItem><Para>
2631OMIT (-) Contents of field omitted (e.g. in plumbed legs)
2632</Para></ListItem>
2633
2634<ListItem><Para>
2635PLUS (+) Indicates positive number
2636</Para></ListItem>
2637
2638<ListItem><Para>
2639ROOT (\) Prefix in force at start of current file (use of ROOT is deprecated)
2640</Para></ListItem>
2641
2642<ListItem><Para>
2643SEPARATOR (.) Level separator in prefix hierarchy
2644</Para></ListItem>
2645
2646<!-- FIXME OPEN ({) and CLOSE (}) -->
2647</ItemizedList>
2648
2649<Para>
2650The special characters may not be alphanumeric.
2651</Para>
2652
2653</listitem>
2654
2655</VarListEntry>
2656
2657</VariableList>
2658
2659</Sect3>
2660
2661<Sect3><Title>SOLVE</Title>
2662
2663<VariableList>
2664
2665<VarListEntry><Term>Syntax</Term>
2666
2667<listitem><Para>*solve</Para></listitem>
2668
2669</VarListEntry>
2670
2671<VarListEntry><Term>Example</Term>
2672
2673<listitem>
2674<Para>
2675<programlisting>
2676*include 1997data
2677*solve
2678*include 1998data
2679</programlisting>
2680</Para>
2681</listitem>
2682
2683</VarListEntry>
2684
2685<VarListEntry><Term>Description</Term>
2686
2687<listitem><Para>
2688Distributes misclosures around any loops in the survey and fixes
2689the positions of all existing stations.  This command is intended
2690for situations where you have some new surveys adding extensions
2691to an already drawn-up survey which you wish to avoid completely
2692redrawing. You can read in the old data, use *SOLVE to fix it, and then
2693read in the new data.  Then old stations will be in the same
2694positions as they are in the existing drawn up survey, even if new loops
2695have been formed by the extensions.
2696</Para></listitem>
2697
2698</VarListEntry>
2699
2700</VariableList>
2701
2702</Sect3>
2703
2704<Sect3><Title>TEAM</Title>
2705
2706<VariableList>
2707
2708<VarListEntry><Term>Syntax</Term>
2709
2710<listitem><Para>*team &lt;person&gt; &lt;role&gt;...</Para></listitem>
2711
2712</VarListEntry>
2713
2714<VarListEntry><Term>Example</Term>
2715
2716<listitem>
2717<Para>
2718<programlisting>
2719*team "Nick Proctor" compass clino tape
2720*team "Anthony Day" notes pictures tape
2721</programlisting>
2722</Para>
2723</listitem>
2724
2725</VarListEntry>
2726
2727<VarListEntry><Term>Validity</Term>
2728
2729<listitem><Para>valid at the start of a *begin/*end block.
2730</Para></listitem>
2731<!-- FIXME valid roles are? -->
2732
2733</VarListEntry>
2734
2735<VarListEntry><Term>Description</Term>
2736
2737<listitem><Para>
2738*team specifies the people involved in a survey and what role they
2739filled during that trip.
2740</Para></listitem>
2741
2742</VarListEntry>
2743
2744<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2745
2746<VarListEntry><Term>See Also</Term>
2747
2748<listitem><Para>*begin, *date, *instrument</Para></listitem>
2749
2750</VarListEntry>
2751
2752</VariableList>
2753
2754</Sect3>
2755
2756<Sect3><Title>TITLE</Title>
2757
2758<VariableList>
2759
2760<VarListEntry><Term>Syntax</Term>
2761
2762<listitem><Para>*title &lt;title&gt;</Para></listitem>
2763
2764</VarListEntry>
2765
2766<VarListEntry><Term>Example</Term>
2767
2768<listitem>
2769<programlisting>
2770*title Dreamtime</programlisting>
2771
2772<programlisting>
2773*title "Mission Impossible"</programlisting>
2774</listitem>
2775
2776</VarListEntry>
2777
2778<VarListEntry><Term>Description</Term>
2779
2780<listitem><Para>*title allows you to set the descriptive title for a survey.
2781If the title contains spaces, you need to enclose it in quotes ("").
2782If there is no *title command, the title defaults to the survey name
2783given in the *begin command.
2784</Para>
2785</listitem>
2786
2787</VarListEntry>
2788
2789<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2790
2791<!--
2792<VarListEntry><Term>See Also</Term>
2793
2794<listitem><Para>*end, *prefix</Para></listitem>
2795
2796</VarListEntry>
2797-->
2798
2799</VariableList>
2800
2801</Sect3>
2802
2803<Sect3><Title>TRUNCATE</Title>
2804
2805<VariableList>
2806
2807<VarListEntry><Term>Syntax</Term>
2808
2809<listitem><Para>*truncate &lt;length&gt;|off</Para></listitem>
2810
2811</VarListEntry>
2812
2813<!-- FIXME:
2814<VarListEntry><Term>Example</Term>
2815
2816<listitem>
2817<programlisting>
2818</programlisting>
2819
2820</listitem>
2821
2822</VarListEntry>
2823-->
2824
2825<VarListEntry><Term>Description</Term>
2826
2827<listitem><Para>Station names may be of any length in <Application>Survex</Application>, but some
2828other (mostly older) cave surveying software only regard the first few
2829characters of a name as significant (e.g. "entran" and "entrance"
2830might be treated as the same).  To facilitate using data imported from
2831such a package <Application>Survex</Application> allows you to truncate names to whatever
2832length you want (but by default truncation is off).
2833</Para>
2834
2835<Para>Figures for the number of characters which are significant in various
2836software packages: Compass currently has a limit of 12,
2837CMAP has a limit of 6,
2838Smaps 4 had a limit of 8,
2839<!-- FIXME any limits for other software, winkarst for example? -->
2840Surveyor87/8 used 8.
2841<Application>Survex</Application> itself used 8 per prefix
2842level up to version 0.41, and 12 per prefix level up to 0.73 (more recent
2843versions removed this rather archaic restriction).
2844</Para>
2845</listitem>
2846
2847</VarListEntry>
2848
2849<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2850
2851<!--
2852<VarListEntry><Term>See Also</Term>
2853
2854<listitem><Para>*end, *prefix</Para></listitem>
2855
2856</VarListEntry>
2857-->
2858
2859</VariableList>
2860
2861</Sect3>
2862
2863<Sect3><Title>UNITS</Title>
2864
2865<VariableList>
2866
2867<VarListEntry><Term>Syntax</Term>
2868
2869<listitem><Para>
2870*units &lt;quantity list&gt; [&lt;factor&gt;] &lt;unit&gt;
2871</Para>
2872<Para>
2873*units default
2874</Para></listitem>
2875
2876</VarListEntry>
2877
2878<VarListEntry><Term>Example</Term>
2879
2880<listitem>
2881<Para>
2882<programlisting>
2883*units tape metres</programlisting>
2884
2885<programlisting>
2886*units compass backcompass clino backclino grads</programlisting>
2887
2888<programlisting>
2889*units dx dy dz 1000 metres ; data given as kilometres</programlisting>
2890
2891<programlisting>
2892*units left right up down feet</programlisting>
2893</Para>
2894</listitem>
2895
2896</VarListEntry>
2897
2898<VarListEntry><Term>Description</Term>
2899
2900<listitem><Para>
2901&lt;quantity&gt; is one of the following (grouped entries are just alternative names for the same thing):
2902TAPE/LENGTH, COMPASS/BEARING, BACKCOMPASS/BACKBEARING, CLINO/GRADIENT, BACKCLINO/BACKGRADIENT, COUNTER/COUNT, DEPTH, DECLINATION, DX/EASTING, DY/NORTHING, DZ/ALTITUDE, LEFT, RIGHT, UP/CEILING, DOWN/FLOOR
2903</Para>
2904
2905<Para>Changes current units of all the quantities listed to [&lt;factor&gt;]
2906&lt;unit&gt;. Note that quantities can be expressed either as
2907the instrument (e.g. COMPASS) or the measurement (e.g. BEARING).
2908</Para>
2909
2910<Para>&lt;factor&gt; allows you to easy specify situations such as measuring
2911distance with a diving line knotted every 10cm (*units distance 0.1 metres).
2912If &lt;factor&gt; is omitted it defaults to 1.0.  If specified, it must be
2913non-zero.
2914</Para>
2915
2916<Para>Valid units for listed quantities are:
2917</Para>
2918
2919<Para>TAPE/LENGTH, COUNTER/COUNT, DEPTH, DX/EASTING, DY/NORTHING, DZ/ALTITUDE
2920in YARDS|FEET|METRIC|METRES|METERS (default: METRES)
2921</Para>
2922
2923<Para>CLINO/GRADIENT, BACKCLINO/BACKGRADIENT
2924in DEG|DEGREES|GRADS|MILS|PERCENT|PERCENTAGE (default: DEGREES)
2925</Para>
2926
2927<Para>COMPASS/BEARING, BACKCOMPASS/BACKBEARING, DECLINATION
2928in DEG|DEGREES|GRADS|MILS|MINUTES (default: DEGREES)
2929</Para>
2930
2931<Para>(360 degrees = 400 grads (also known as Mils))
2932</Para>
2933</listitem>
2934
2935</VarListEntry>
2936
2937<!-- <VarListEntry><Term>Caveats </Term> </VarListEntry> -->
2938
2939<VarListEntry><Term>See Also</Term>
2940
2941<listitem><Para>*calibrate</Para></listitem>
2942
2943</VarListEntry>
2944
2945</VariableList>
2946
2947</Sect3>
2948
2949</Sect2>
2950
2951</Sect1>
2952
2953<!-- FIXME rename to "Cookbook"? -->
2954<Sect1><Title>Contents of <filename>.svx</filename> files: How do I?</Title>
2955<?dbhtml filename="svxhowto.htm">
2956
2957<Para>
2958Here is some example <Application>Survex</Application> data (a very small cave numbered 1623/163):
2959</Para>
2960
2961<programlisting>
29622 1 26.60 222  17.5
29632 3 10.85 014   7
29642 4  7.89 254 -11
29654 5  2.98  - DOWN
29665 6  9.29 271 -28.5</programlisting>
2967
2968<Para>
2969You can vary the data ordering.  The default is:
2970</Para>
2971
2972<Para>
2973from-station to-station tape compass clino
2974</Para>
2975
2976<Para>
2977This data demonstrates a number of useful features of <Application>Survex</Application>:
2978</Para>
2979
2980<Para>
2981Legs can be measured either way round, which allows the use of
2982techniques like "leap-frogging" (which is where legs
2983alternate forwards and backwards).
2984</Para>
2985
2986<Para>
2987Also notice that there is a spur in the survey (2 to 3).  You
2988do not need to specify this specially.
2989</Para>
2990
2991<Para>
2992<Application>Survex</Application> places few restrictions on station naming (see "Survey
2993Station Names" in the previous section), so you can number the stations
2994as they were in the original survey notes.  Although not apparent from
2995this example, there is no requirement for each leg to connect to an
2996existing station.  <Application>Survex</Application> can accept data in any order, and will
2997check for connectedness once all the data has been read in.
2998</Para>
2999
3000<Para>
3001Each survey is also likely to have other information associated
3002with it, such as instrument calibrations, etc.  This has been
3003omitted from this example to keep things simple.
3004</Para>
3005
3006<Para>
3007Most caves will take more than just one survey trip to map.  Commonly
3008the numbering in each survey will begin at 1, so we need to be
3009able to tell apart stations with the same number in different
3010surveys.
3011</Para>
3012
3013<Para>
3014To accomplish this, <Application>Survex</Application> has a very flexible system of hierarchical
3015prefixes.  All you need do is give each survey a unique name or
3016number, and enter the data like so:
3017</Para>
3018
3019<programlisting>
3020*begin 163
3021*export 1
30222 1 26.60 222  17.5
30232 3 10.85 014   7
30242 4  7.89 254 -11
30254 5  2.98  - DOWN
30265 6  9.29 271 -28.5
3027*end 163</programlisting>
3028
3029<Para><Application>Survex</Application> will name the stations by attaching the current prefix.
3030In this case, the stations will be named 163.1, 163.2, etc.
3031</Para>
3032
3033<Para>We have a convention with the CUCC Austria data that the entrance survey
3034station of a cave is named P&lt;cave number&gt;, P163 in this case. We
3035can accomplish this like so:
3036</Para>
3037
3038<programlisting>
3039*equate P163 163.1
3040*entrance P163
3041*begin 163
3042*export 1
30432 1 26.60 222  17.5
30442 3 10.85 014   7
30452 4  7.89 254 -11
30464 5  2.98  - DOWN
30475 6  9.29 271 -28.5
3048*end 163</programlisting>
3049
3050<Sect2><Title>Specify surface survey data</Title>
3051
3052<Para>
3053Say you have 2 underground surveys and 2 surface ones with 2 fixed reference
3054points.  You want to mark the surface surveys so that their length isn't
3055included in length statistics, and so that Aven knows to display them
3056differently.  To do this you mark surface data with the "surface" flag
3057- this is set with "*flags surface" like so:
3058</Para>
3059
3060<programlisting>
3061; fixed reference points
3062*fix fix_a 12345 56789 1234
3063*fix fix_b 23456 67890 1111                                                     
3064                                                                               
3065; surface data (enclosed in *begin ... *end to stop the *flags command
3066; from "leaking" out)
3067*begin
3068*flags surface
3069*include surface1
3070*include surface2
3071*end                                                                           
3072                                                                               
3073; underground data
3074*include cave1
3075*include cave2</programlisting>
3076
3077<Para>
3078You might also have a survey which starts on the surface and heads into a
3079cave.  This can be easily handled too - here's an example which goes in
3080one entrance, through the cave, and out of another entrance:
3081</Para>
3082
3083<programlisting>
3084*begin BtoC
3085*title "161b to 161c"
3086*date 1990.08.06 ; trip 1990-161c-3 in 1990 logbook
3087
3088*begin
3089*flags surface
309002    01      3.09   249    -08.5
309102    03      4.13   252.5  -26
3092*end
3093
309404    03      6.00   020    +37
309504    05      3.07   329    -31
309606    05      2.67   203    -40.5
309706    07      2.20   014    +04
309807    08      2.98   032    +04
309908    09      2.73   063.5  +21
310009    10     12.35   059    +15
3101
3102*begin
3103*flags surface
310411    10      4.20   221.5  -11.5
310511    12      5.05   215    +03.5
310611    13      6.14   205    +12.5
310713    14     15.40   221    -14
3108*end
3109
3110*end BtoC</programlisting>
3111
3112<Para>
3113Note that to avoid needless complication, Survex regards each leg as
3114being either "surface" or "not surface" - if a leg spans the boundary you'll
3115have to call it one or the other.  It's good surveying practice to
3116deliberately put a station at the surface/underground interface
3117(typically the highest closed contour or drip line) so this generally
3118isn't an onerous restriction.
3119</Para>
3120
3121</Sect2>
3122
3123<Sect2><Title>Specify the ordering and type of data</Title>
3124
3125<Para>The *DATA command is used to specify the data style, and the
3126order in which the readings are given.</Para>
3127
3128</Sect2>
3129
3130<Sect2><Title>Deal with Plumbs or Legs Across Static Water</Title>
3131
3132<!-- FIXME
3133<Para>
3134They can be given
3135as +90, or -90, but as they are not usually measured with the
3136clino, but with a plumb of some sort, then it is useful to distinguish
3137them in this way so that any clino adjustment is not applied to
3138these values.
3139</Para>
3140
3141FIXME: paste in section from mail to list
3142
3143<Para>
3144Note that a similar effect can be achieved by using the "*infer plumbs" command
3145to stop clino corrections being applied to -90 and +90 clino readings.
3146</Para>
3147-->
3148
3149<Para>
3150Plumbed legs should be given using 'UP' or 'DOWN' in place of the
3151clino reading and a dash (or a different specified 'OMIT' character)
3152in place of the compass reading.  This distinguishes
3153them from legs measured with a compass and clino.  Here's an example:
3154</Para>
3155
3156<programlisting>
31571 2 21.54 - UP
31583 2 7.36 017 +17
31593 4 1.62 091 +08
31605 4 10.38 - DOWN</programlisting>
3161
3162<Para>
3163U/D or +V/-V may be used instead of UP/DOWN; the check is not case
3164sensitive.
3165</Para>
3166
3167<Para>
3168Legs surveyed across the surface of a static body of water where no
3169clino reading is taken (since the surface of the water can be assumed
3170to be flat) can be indicated by using LEVEL in place of a clino reading.
3171This prevents the clino correction being applied.  Here's an example:
3172</Para>
3173
3174<programlisting>
31751 2 11.37 190 -12
31763 2  7.36 017 LEVEL
31773 4  1.62 091 LEVEL</programlisting>
3178
3179</Sect2>
3180
3181<Sect2><Title>Specify a BCRA grade</Title>
3182
3183<Para>The *SD command can be used to specify the standard deviations of the
3184various measurements (tape, compass, clino, etc).  Examples files are
3185supplied which define BCRA Grade 3 and BCRA Grade 5 using a number of *sd
3186commands. You can use these by simply including them at the relevant point,
3187as follows:
3188</Para>
3189
3190<programlisting>
3191*begin somewhere
3192; This survey is only grade 3
3193*include grade3
31942 1 26.60 222  17.5
31952 3 10.85 014   7
3196; etc
3197*end somewhere</programlisting>
3198
3199<Para>The default values for the standard deviations are those for
3200BCRA grade 5. Note that it is good practice to keep the *include
3201Grade3 within *Begin and *End commands otherwise it will apply
3202to following survey data, which may not be what you intended.
3203</Para>
3204
3205</Sect2>
3206
3207<Sect2><Title>Specify different accuracy for a leg</Title>
3208
3209<Para>For example, suppose the tape on the plumbed leg in this survey
3210is suspected of being less accurate than the rest of the survey because
3211the length was obtained by measuring the length of the rope used to rig
3212the pitch.  We can set a higher sd for this one measurement and use a
3213*begin/*end block to make sure this setting only applies to the one
3214leg:
3215</Para>
3216
3217<programlisting>
32182 1 26.60 222  17.5
32192 3 10.85 014   7
32202 4  7.89 254 -11
3221*begin
3222; tape measurement was taken from the rope length
3223*sd tape 0.5 metres
32244 5  34.50 - DOWN
3225*end
32265 6  9.29 271 -28.5</programlisting>
3227
3228<!-- FIXME also *calibrate and *instrument? Except rope is measure with the
3229tape... -->
3230</Sect2>
3231
3232<Sect2><Title>Enter Repeated Readings</Title>
3233
3234<Para>If your survey data contains multiple versions of each leg (for example,
3235pockettopo produces such data), then provided these are adjacent to one another
3236Survex 1.2.17 and later will automatically average these and treat them as a
3237single leg.
3238</Para>
3239
3240</Sect2>
3241
3242<Sect2><Title>Enter Radiolocation Data</Title>
3243
3244<!-- FIXME comments from David Gibson here -->
3245<Para>This is done by using the *SD command to specify the appropriate
3246errors for the radiolocation `survey leg' so that the loop closure
3247algorithm knows how to distribute errors if it forms part of a loop.
3248</Para>
3249
3250<Para>The best approach for a radiolocation where the underground station
3251is vertically below the surface station is to represent it as a
3252plumbed leg, giving suitable SDs for the length and plumb angle. The
3253horizontal positioning of this is generally quite accurate, but the
3254vertical positioning may be much less well known. E.g: we have a
3255radiolocation of about 50m depth +/- 20m and horizontal accuracy of
3256+/- 8m. Over 50m the +/-8m is equivalent to an angle of 9 degrees, so
3257that is the expected plumb error. 20m is the expected error in the
3258length. To get the equivalent SD we assume that 99.74% of readings will
3259be within 3 standard deviations of the error value. Thus we divide the
3260expected errors by 3 to get the SD we should specify:
3261</Para> <!-- 3 SD? or same as BCRA3.SVX, etc -->
3262
3263<programlisting>
3264*begin
3265*sd length 6.67 metres
3266*sd plumb 3 degrees
3267surface underground 50 - down
3268*end</programlisting>
3269
3270<Para>
3271We wrap the radiolocation leg in a *begin/*end block to make
3272sure that the special *sd settings only apply to this one leg.
3273</Para>
3274
3275<Para>For more information on the expected errors from radiolocations
3276see Compass Points Issue 10, available online at
3277<ulink url="http://www.chaos.org.uk/survex/cp/CP10/CPoint10.htm">http://www.chaos.org.uk/survex/cp/CP10/CPoint10.htm</ulink>
3278</Para>
3279
3280</Sect2>
3281
3282<Sect2><Title>Enter Diving Data</Title>
3283
3284<Para>Surveys made underwater using a diver's depth gauge can be
3285processed - use the *Data command to specify that the following data
3286is of this type.
3287</Para>
3288
3289</Sect2>
3290
3291<Sect2><Title>Enter Theodolite data</Title>
3292
3293<Para>
3294Theodolite data with turned angles is not yet explicitly catered
3295for, so for now you will need to convert it into equivalent legs in
3296another style - normal or cylpolar are likely to be the best choices.
3297</Para>
3298
3299<Para>
3300If there is no vertical info in your theodolite data then you should
3301use the cylpolar style and use *sd command to specify very low
3302accuracy (high SD) in the depth so that the points will move in the
3303vertical plane as required if the end points are fixed or the survey
3304is part of a loop.
3305</Para>
3306
3307</Sect2>
3308
3309</Sect1>
3310
3311<Sect1><Title>General: How do I?</Title>
3312<?dbhtml filename="genhowto.htm">
3313
3314<Sect2><Title>Create a new survey</Title>
3315
3316<Para>You simply create a text file containing the relevant survey data,
3317using a text editor, and save it with a suitable name with a <filename>.svx</filename>
3318extension. The
3319easiest way is to look at some of the example data and use that
3320as a template. Nearly all surveys will need a bit of basic info
3321as well as the survey data itself: e.g. the date (*date), comments
3322about where, what cave, a name for the survey (using *begin and *end),
3323instrument error corrections etc. Here is a typical survey file:
3324</Para>
3325
3326<Para>All the lines starting with ';' are comments, which are ignored
3327by <Application>Survex</Application>. You can also see the use of 'DOWN' for plumbs, and
3328*calibrate tape for dealing with a tape length error (in this case
3329the end of the tape had fallen off so measurements were made from the
333020cm point).</Para>
3331
3332<programlisting>
3333*equate chaos.1 triassic.pt3.8
3334*equate chaos.2 triassic.pt3.9
3335
3336*begin chaos
3337*title "Bottomless Pit of Eternal Chaos to Redemption pitch"
3338*date 1996.07.11
3339*team "Nick Proctor" compass clino tape
3340*team "Anthony Day" notes pictures tape
3341*instrument compass "CUCC 2"
3342*instrument clino "CUCC 2"
3343;Calibration: Cairn-Rock 071 072 071,  -22 -22 -22
3344;       Rock-Cairn 252 251 252,  +21 +21 +21
3345;Calibration at 161d entrance from cairn nr entrance to
3346;prominent rock edge lower down. This is different from
3347;calibration used for thighs survey of 5 July 1996
3348
3349*export 1 2
3350
3351;Tape is 20cm too short
3352*calibrate tape +0.2
3353
33541 2 9.48 208 +08
33552 3 9.30 179 -23
33563 4 2.17 057 +09
33575 4 10.13 263 +78
33585 6 2.10 171 -73
33597 6 7.93 291 +75
3360*begin
3361*calibrate tape 0
33628 7 35.64 262 +86 ;true length measured for this leg
3363*end
33648 9 24.90 - DOWN
336510 9 8.61 031 -43
336610 11 2.53 008 -34
336711 12 2.70 286 -20
336813 12 5.36 135 +23
336914 13 1.52 119 -12
337015 14 2.00 036 +13
337116 15 2.10 103 +12
337217 16 1.40 068 -07
337317 18 1.53 285 -42
337419 18 5.20 057 -36
337519 20 2.41 161 -67
337620 21 27.47 - DOWN
337721 22 9.30 192 -29
3378*end chaos</programlisting>
3379
3380</Sect2>
3381
3382<Sect2><Title>Join surveys together</Title>
3383
3384<Para>Once you have more than one survey you need to specify how they
3385link together. To do this use *export to make the stations to be
3386joined accessible in the enclosing survey, then *equate in the
3387enclosing survey to join them together.
3388<!-- FIXME example -->
3389</Para>
3390
3391</Sect2>
3392
3393<Sect2><Title>Organise my surveys</Title>
3394
3395<Para>This is actually a large subject. There are many ways you can
3396organise your data using <Application>Survex</Application>. Take a look at the example dataset
3397for some ideas of ways to go about it.
3398</Para>
3399
3400<Sect3><Title>Fixed Points (Control Points)</Title>
3401
3402<Para>The *fix command is used to specify fixed points (also know as control
3403points).  See the description of this command in the "Cavern Commands"
3404section of this manual.
3405</Para>
3406
3407</Sect3>
3408
3409<Sect3><Title>More than one survey per trip</Title>
3410
3411<Para>Suppose you have two separate bits of surveying which were done on the
3412same trip.  So the calibration details, etc. are the same for both.  But you
3413want to give a different survey name to the two sections.  This is easily
3414achieved like so:
3415</Para>
3416
3417<programlisting>
3418*begin
3419*calibrate compass 1.0
3420*calibrate clino 0.5
3421*begin altroute
3422; first survey
3423*end altroute
3424*begin faraway
3425; second survey
3426*end faraway
3427*end</programlisting>
3428
3429</Sect3>
3430
3431</Sect2>
3432
3433<Sect2><Title>Add surface topography</Title>
3434
3435<Para>Survex 1.2.18 added support for loading terrain data and rendering it as
3436a transparent surface.
3437</Para>
3438
3439<Para>
3440We recommend using this new code in preference, but previously the simplest
3441approach was to generate a <filename>.svx</filename> file with the surface mesh
3442in and display it with the survey data.
3443</Para>
3444
3445<Para>
3446It is possible to generate
3447a mesh or contours overlaying your area by various means.  NASA have made
34481 arc-second (approximately 30m) terrain data available for the USA for
3449some years, with only 3 arc-second data available for other countries.
3450However, starting in 2014 they're gradually making 1 arc-second data
3451available for more countries.
3452</Para>
3453
3454<Para>
3455If you want a better resolution that this, reading heights from the
3456contours on a map is one approach.  It's laborious, but feasible for
3457a small area.
3458</Para>
3459
3460<Para>
3461Details of several methods are given in the BCRA Cave Surveying
3462Group magazine Compass Points issue 11, available online at
3463<ulink url="http://www.chaos.org.uk/survex/cp/CP11/CPoint11.htm#Art_5">http://www.chaos.org.uk/survex/cp/CP11/CPoint11.htm#Art_5</ulink>
3464</Para>
3465
3466<Para>If you're using another program to generate a <filename>.svx</filename> file for the surface
3467mesh, it's best to use the NOSURVEY data style.
3468Simply fix all the grid intersections at the correct
3469coordinates and height, and put legs between them using the NOSURVEY style.
3470Here's a grid of 4 squares and 9 intersections:
3471</Para>
3472
3473<programlisting>
3474*fix 00 000 000 1070
3475*fix 01 000 100 1089
3476*fix 02 000 200 1093
3477
3478*fix 10 100 000 1062
3479*fix 11 100 100 1080
3480*fix 12 100 200 1089
3481
3482*fix 20 200 000 1050
3483*fix 21 200 100 1065
3484*fix 22 200 200 1077
3485
3486*data nosurvey station
3487
348800
348901
349002
3491
349210
349311
349412
3495
349620
349721
349822
3499
350000
350110
350220
3503
350401
350511
350621
3507
350802
350912
351022</programlisting>
3511
3512<Para>
3513This is far simpler than trying to create fake tape/compass/clino legs of
3514the right length for each line in the mesh.  It's also very fast to process
3515with cavern.
3516</Para>
3517
3518<Para>SpeleoGen can also help with this process if you want
3519final output in DXF form.  See the 'Related Tools' section of the
3520Survex website for download links.
3521</Para>
3522
3523</Sect2>
3524
3525<Sect2><Title>Overlay a grid</Title>
3526
3527<Para>Aven is able to display a grid, but this functionality isn't currently
3528available in printouts.
3529You can achieve a similar effect for now by creating a <filename>.svx</filename> file
3530where the survey legs form a grid.
3531</Para>
3532
3533</Sect2>
3534
3535<Sect2><Title>Import data from other programs</Title>
3536
3537<Para><Application>Survex</Application> supports a number of features to help with importing
3538existing data. You can specify the ordering of items on a line using *Data
3539(see <Application>Survex</Application> Keywords above), and you can specify the characters used
3540to mean different things using *Set (see <Application>Survex</Application> Keywords above).
3541</Para>
3542
3543<Para>The Ignore and Ignoreall options to the *Data command are often
3544particularly useful, e.g. if you have a dataset with LRUD info or comments
3545on the ends of lines.
3546</Para>
3547
3548<Sect3><Title>Changing Meanings of Characters</Title>
3549
3550<Para>e.g. if you have some data with station names containing the
3551characters '?' and '+' (which are not permitted in a name by default)
3552then the command:
3553</Para>
3554
3555<programlisting>
3556*SET NAMES ?+</programlisting>
3557
3558<Para>
3559specifies that question marks and plus signs are permitted in station names.
3560A-Z, a-z, and 0-9 are always permitted. '_' and '-' are also permitted by
3561default, but aren't in this example.
3562</Para>
3563
3564<Para>If your data uses a comma ',' instead of a decimal point, then
3565you use
3566</Para>
3567
3568<programlisting>
3569*SET DECIMAL ,</programlisting>
3570
3571<Para>to specify that ',' is now the decimal separator instead of '.'.
3572</Para>
3573
3574<!-- FIXME
3575<Para>Note that there are plenty of ways you can use this facility to
3576completely confuse the software, as it may not be able to work out what is
3577going on, or it may simply be ambiguous. It can cope with some ambiguity (e.g.
3578the '-' character is used both for 'MINUS' and for 'OMIT'), but there are
3579limits. If you have a dataset that you can not make <Application>Survex</Application>
3580understand, then send it to us, and we will see what can be done.
3581</Para>
3582-->
3583
3584</Sect3>
3585
3586<!--
3587 Nobody seems to have the CfH convertor...
3588 but it's probably no longer useful anyway
3589
3590<Sect3><Title>Other Converters</Title>
3591
3592<Para>We have an Excel 5 macro for converting The Lotus 123 spreadsheets
3593used by the German survey software Cad F&uuml;r H&ouml;hlen into
3594<Application>Survex</Application> data files. Other converters may also come to be available.
3595These will normally be available via the
3596<ulink url="http://survex.com/"><Application>Survex</Application> Web pages</ulink>.
3597</Para>
3598
3599</Sect3>
3600-->
3601
3602</Sect2>
3603
3604<Sect2><Title>Export data from <Application>Survex</Application></Title>
3605
3606<Para>See Rosetta Stal in the Related Tools section of the Survex web
3607site.  This is a utility written by Taco van Ieperen and Gary Petrie.
3608Note though that this only supports a subset of the svx format,
3609and only work on Microsoft Windows.  The Survex support is limited
3610and doesn't understand the more recently added commands.</Para>
3611
3612</Sect2>
3613
3614<Sect2><Title>See errors and warnings that have gone off the screen</Title>
3615
3616<Para>When you run <Application>Survex</Application> it will process the specified survey data
3617files in order, reporting any warnings and errors.  If there are no
3618errors, the output files are written and various statistics about the
3619survey are displayed. If there are a lot of warnings or errors, they can
3620scroll off the screen and it's not always possible to scroll back to
3621read them.
3622</Para>
3623
3624<Para>The easiest way to see all the text is to use <command>cavern
3625--log</command> to redirect output to a <filename>.log</filename> file,
3626which you can then inspect with a text editor.
3627</Para>
3628
3629<!-- <command>cavern cavename &gt; tmpfile</command> -->
3630
3631</Sect2>
3632
3633<Sect2><Title>Create an Extended Elevation</Title>
3634
3635<Para>Use the Extend program. This takes <filename>.3d</filename> files and
3636'flattens' them.  See 'Extend' for details.
3637</Para>
3638
3639</Sect2>
3640
3641</Sect1>
3642
3643<!--
3644<Sect1><Title>Appendices</Title>
3645<?dbhtml filename="appendix.htm">
3646
3647<Para>Files provided
3648</Para>
3649
3650<Para>Command specification
3651</Para>
3652
3653</Sect1>
3654-->
3655<Sect1><Title>Working with Larry Fish's Compass</Title>
3656<?dbhtml filename="compass.htm">
3657
3658<Para>
3659Survex can read Compass survey data - both raw data (.DAT and .MAK
3660files) and processed survey data (.PLT and .PLF files).  You can even
3661use <command>*include compassfile.dat</command> in a <filename>.svx</filename> file and
3662it'll work!
3663</Para>
3664
3665<Para>
3666One point to note (this tripped us up!): station names in DAT files are
3667case sensitive and so Survex reads DAT files with the equivalent of
3668<command>*case preserve</command>.  The default in SVX files is
3669<command>*case lower</command>.  So this won't work:
3670
3671<programlisting>
3672*fix CE1 0 0 0
3673*include datfilewhichusesCE1.dat</programlisting>
3674
3675Because the CE1 in the *fix is actually interpreted as ce1.  This is
3676what you have to do:
3677
3678<programlisting>
3679*begin
3680*case preserve
3681*fix CE1 0 0 0
3682*include datfilewhichusesCE1.dat
3683*end</programlisting>
3684</Para>
3685
3686</Sect1>
3687
3688<Sect1><Title>Mailing List</Title>
3689<?dbhtml filename="maillist.htm">
3690
3691<Para>The best way to contact the authors and other Survex users is the
3692Survex mailing list - for details visit:
3693<ulink url="http://survex.com/maillist.html">http://survex.com/maillist.html</ulink>
3694</Para>
3695
3696<Para>We'd be delighted to hear how you get on with <Application>Survex</Application> and
3697welcome comments and suggestions for improvements.</Para>
3698
3699<Para>
3700And we'd love you to contribute your skills to help make <Application>Survex</Application> even
3701better.  Point out areas of the documentation which could be made clearer, or
3702sections which are missing entirely.  Download test releases, try them out, and
3703let us know if you find problems or have suggestions for improvements.
3704If there's no translation to your language, you could provide one.
3705Or if your a developer, <emphasis>"Say it with code"</emphasis>.  There's
3706plenty to do, so feel free to join in.
3707</Para>
3708
3709</Sect1>
3710
3711<Sect1><Title>Future Developments</Title>
3712<?dbhtml filename="future.htm">
3713
3714<Para>
3715Now that <Application>Survex</Application> has reached version 1.0, we are continuing progress
3716towards version 2, in a series of steps, evolving out of
3717Survex 1.0.  The GUI framework is being based on aven, with
3718the printer drivers and other utility programs being pulled in
3719and integrated into the menus.</Para>
3720
3721<Para>Aven is built on <Application>wxWidgets</Application>, which means that it can easily support
3722Unix, Microsoft Windows, and Mac OS X.</Para>
3723
3724<Para>More information on our plans is on the <ulink
3725url="http://survex.com/">web site</ulink>.
3726</Para>
3727
3728</Sect1>
3729
3730</article>
Note: See TracBrowser for help on using the repository browser.