<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Survex 1.4.1 Manual</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"></HEAD
><BODY
CLASS="ARTICLE"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="ARTICLE"
><DIV
CLASS="TITLEPAGE"
><H1
CLASS="TITLE"
><A
NAME="AEN2"
><SPAN
CLASS="APPLICATION"
>Survex</SPAN
> 1.4.1 Manual</A
></H1
><DIV
CLASS="AUTHORGROUP"
><A
NAME="AEN5"
></A
><H3
CLASS="AUTHOR"
><A
NAME="AEN6"
>Olly Betts</A
></H3
><DIV
CLASS="AFFILIATION"
><DIV
CLASS="ADDRESS"
><P
CLASS="ADDRESS"
><CODE
CLASS="EMAIL"
>&#60;<A
HREF="mailto:olly@survex.com"
>olly@survex.com</A
>&#62;</CODE
></P
></DIV
></DIV
><H3
CLASS="AUTHOR"
><A
NAME="AEN15"
>Wookey</A
></H3
><DIV
CLASS="AFFILIATION"
><DIV
CLASS="ADDRESS"
><P
CLASS="ADDRESS"
><CODE
CLASS="EMAIL"
>&#60;<A
HREF="mailto:wookey@survex.com"
>wookey@survex.com</A
>&#62;</CODE
></P
></DIV
></DIV
></DIV
><P
CLASS="COPYRIGHT"
>Copyright &copy; 1998-2018 Olly Betts</P
><DIV
><DIV
CLASS="ABSTRACT"
><P
></P
><A
NAME="AEN25"
></A
><P
>    This is the manual for <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> - an open-source software package for
    cave surveyors.
   </P
><P
></P
></DIV
></DIV
><HR></DIV
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
>1. <A
HREF="#AEN28"
>Introduction</A
></DT
><DD
><DL
><DT
>1.1. <A
HREF="#AEN32"
>About <SPAN
CLASS="APPLICATION"
>Survex</SPAN
></A
></DT
><DT
>1.2. <A
HREF="#AEN53"
>About this Manual</A
></DT
><DD
><DL
><DT
>1.2.1. <A
HREF="#AEN62"
>Terminology</A
></DT
></DL
></DD
></DL
></DD
><DT
>2. <A
HREF="#AEN78"
>Getting Started</A
></DT
><DD
><DL
><DT
>2.1. <A
HREF="#AEN81"
>Obtaining <SPAN
CLASS="APPLICATION"
>Survex</SPAN
></A
></DT
><DT
>2.2. <A
HREF="#AEN89"
>Installing <SPAN
CLASS="APPLICATION"
>Survex</SPAN
></A
></DT
><DD
><DL
><DT
>2.2.1. <A
HREF="#AEN93"
>Linux</A
></DT
><DT
>2.2.2. <A
HREF="#AEN97"
>Other versions of UNIX</A
></DT
><DT
>2.2.3. <A
HREF="#AEN100"
>macOS</A
></DT
><DT
>2.2.4. <A
HREF="#AEN104"
>Microsoft Windows</A
></DT
></DL
></DD
><DT
>2.3. <A
HREF="#AEN202"
>Configuration</A
></DT
><DD
><DL
><DT
>2.3.1. <A
HREF="#AEN204"
>Selecting Your Preferred Language</A
></DT
></DL
></DD
><DT
>2.4. <A
HREF="#AEN296"
>Using <SPAN
CLASS="APPLICATION"
>Survex</SPAN
></A
></DT
></DL
></DD
><DT
>3. <A
HREF="#AEN327"
>Survex Programs</A
></DT
><DD
><DL
><DT
>3.1. <A
HREF="#AEN329"
>Standard Options</A
></DT
><DT
>3.2. <A
HREF="#AEN342"
>Short and Long Options</A
></DT
><DT
>3.3. <A
HREF="#AEN349"
>Filenames on the Command Line</A
></DT
><DT
>3.4. <A
HREF="#AEN358"
>Command Reference</A
></DT
><DD
><DL
><DT
><A
HREF="#CAVERN"
>cavern</A
>&nbsp;--&nbsp;process raw survey data</DT
><DT
><A
HREF="#AVEN"
>aven</A
>&nbsp;--&nbsp;sophisticated cave viewer for Unix and MS Windows</DT
><DT
><A
HREF="#DIFFPOS"
>diffpos</A
>&nbsp;--&nbsp;compare the contents of two <TT
CLASS="FILENAME"
>.3d</TT
> files</DT
><DT
><A
HREF="#EXTEND"
>extend</A
>&nbsp;--&nbsp;produce an extended elevation from a <TT
CLASS="FILENAME"
>.3d</TT
> file</DT
><DT
><A
HREF="#SORTERR"
>sorterr</A
>&nbsp;--&nbsp;re-sort .err file by various criteria</DT
><DT
><A
HREF="#SURVEXPORT"
>survexport</A
>&nbsp;--&nbsp;convert a processed survey data file (such as a <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> <TT
CLASS="FILENAME"
>.3d</TT
> file)
to another format.</DT
></DL
></DD
></DL
></DD
><DT
>4. <A
HREF="#AEN636"
><SPAN
CLASS="APPLICATION"
>Survex</SPAN
> data files</A
></DT
><DD
><DL
><DT
>4.1. <A
HREF="#AEN649"
>Readings</A
></DT
><DT
>4.2. <A
HREF="#AEN652"
>Survey Station Names</A
></DT
><DD
><DL
><DT
>4.2.1. <A
HREF="#AEN664"
>Anonymous Stations</A
></DT
></DL
></DD
><DT
>4.3. <A
HREF="#AEN683"
>Numeric fields</A
></DT
><DT
>4.4. <A
HREF="#AEN689"
>Accuracy</A
></DT
><DT
>4.5. <A
HREF="#AEN692"
>Cavern Commands</A
></DT
><DD
><DL
><DT
>4.5.1. <A
HREF="#AEN713"
>ALIAS</A
></DT
><DT
>4.5.2. <A
HREF="#AEN735"
>BEGIN</A
></DT
><DT
>4.5.3. <A
HREF="#AEN756"
>CALIBRATE</A
></DT
><DT
>4.5.4. <A
HREF="#AEN791"
>CASE</A
></DT
><DT
>4.5.5. <A
HREF="#AEN811"
>COPYRIGHT</A
></DT
><DT
>4.5.6. <A
HREF="#AEN835"
>CS</A
></DT
><DT
>4.5.7. <A
HREF="#AEN879"
>DATA</A
></DT
><DT
>4.5.8. <A
HREF="#AEN970"
>DATE</A
></DT
><DT
>4.5.9. <A
HREF="#AEN997"
>DECLINATION</A
></DT
><DT
>4.5.10. <A
HREF="#AEN1019"
>DEFAULT</A
></DT
><DT
>4.5.11. <A
HREF="#AEN1035"
>END</A
></DT
><DT
>4.5.12. <A
HREF="#AEN1054"
>ENTRANCE</A
></DT
><DT
>4.5.13. <A
HREF="#AEN1071"
>EQUATE</A
></DT
><DT
>4.5.14. <A
HREF="#AEN1091"
>EXPORT</A
></DT
><DT
>4.5.15. <A
HREF="#AEN1115"
>FIX</A
></DT
><DT
>4.5.16. <A
HREF="#AEN1142"
>FLAGS</A
></DT
><DT
>4.5.17. <A
HREF="#AEN1163"
>INCLUDE</A
></DT
><DT
>4.5.18. <A
HREF="#AEN1185"
>INFER</A
></DT
><DT
>4.5.19. <A
HREF="#AEN1200"
>INSTRUMENT</A
></DT
><DT
>4.5.20. <A
HREF="#AEN1224"
>PREFIX</A
></DT
><DT
>4.5.21. <A
HREF="#AEN1248"
>REF</A
></DT
><DT
>4.5.22. <A
HREF="#AEN1273"
>REQUIRE</A
></DT
><DT
>4.5.23. <A
HREF="#AEN1289"
>SD</A
></DT
><DT
>4.5.24. <A
HREF="#AEN1352"
>SET</A
></DT
><DT
>4.5.25. <A
HREF="#AEN1394"
>SOLVE</A
></DT
><DT
>4.5.26. <A
HREF="#AEN1410"
>TEAM</A
></DT
><DT
>4.5.27. <A
HREF="#AEN1434"
>TITLE</A
></DT
><DT
>4.5.28. <A
HREF="#AEN1450"
>TRUNCATE</A
></DT
><DT
>4.5.29. <A
HREF="#AEN1469"
>UNITS</A
></DT
></DL
></DD
></DL
></DD
><DT
>5. <A
HREF="#AEN1506"
>Contents of <TT
CLASS="FILENAME"
>.svx</TT
> files: How do I?</A
></DT
><DD
><DL
><DT
>5.1. <A
HREF="#AEN1530"
>Specify surface survey data</A
></DT
><DT
>5.2. <A
HREF="#AEN1537"
>Specify the ordering and type of data</A
></DT
><DT
>5.3. <A
HREF="#AEN1540"
>Deal with Plumbs or Legs Across Static Water</A
></DT
><DT
>5.4. <A
HREF="#AEN1547"
>Specify a BCRA grade</A
></DT
><DT
>5.5. <A
HREF="#AEN1552"
>Specify different accuracy for a leg</A
></DT
><DT
>5.6. <A
HREF="#AEN1556"
>Enter Repeated Readings</A
></DT
><DT
>5.7. <A
HREF="#AEN1559"
>Enter Radiolocation Data</A
></DT
><DT
>5.8. <A
HREF="#AEN1567"
>Enter Diving Data</A
></DT
><DT
>5.9. <A
HREF="#AEN1570"
>Enter Theodolite data</A
></DT
></DL
></DD
><DT
>6. <A
HREF="#AEN1574"
>General: How do I?</A
></DT
><DD
><DL
><DT
>6.1. <A
HREF="#AEN1576"
>Create a new survey</A
></DT
><DT
>6.2. <A
HREF="#AEN1583"
>Join surveys together</A
></DT
><DT
>6.3. <A
HREF="#AEN1586"
>Organise my surveys</A
></DT
><DD
><DL
><DT
>6.3.1. <A
HREF="#AEN1590"
>Fixed Points (Control Points)</A
></DT
><DT
>6.3.2. <A
HREF="#AEN1593"
>More than one survey per trip</A
></DT
></DL
></DD
><DT
>6.4. <A
HREF="#AEN1597"
>Add surface topography</A
></DT
><DT
>6.5. <A
HREF="#AEN1611"
>Overlay a grid</A
></DT
><DT
>6.6. <A
HREF="#AEN1615"
>Import data from other programs</A
></DT
><DD
><DL
><DT
>6.6.1. <A
HREF="#AEN1622"
>Changing Meanings of Characters</A
></DT
></DL
></DD
><DT
>6.7. <A
HREF="#AEN1630"
>Export data from <SPAN
CLASS="APPLICATION"
>Survex</SPAN
></A
></DT
><DT
>6.8. <A
HREF="#AEN1634"
>See errors and warnings that have gone off the screen</A
></DT
><DT
>6.9. <A
HREF="#AEN1641"
>Create an Extended Elevation</A
></DT
></DL
></DD
><DT
>7. <A
HREF="#AEN1645"
>Working with Larry Fish's Compass</A
></DT
><DT
>8. <A
HREF="#AEN1655"
>Mailing List</A
></DT
><DT
>9. <A
HREF="#AEN1664"
>Future Developments</A
></DT
></DL
></DIV
><DIV
CLASS="SECT1"
><H2
CLASS="SECT1"
><A
NAME="AEN28"
>1. Introduction</A
></H2
><P
>This section describes what <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> is, and outlines the scope of this
manual.</P
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN32"
>1.1. About <SPAN
CLASS="APPLICATION"
>Survex</SPAN
></A
></H3
><P
><SPAN
CLASS="APPLICATION"
>Survex</SPAN
> is a multi-platform open-source cave surveying
package.
Versions 1.2 and later run on UNIX, Microsoft Windows, and macOS.
We're investigating support for phones and tablets.</P
><P
>We are well aware that not everyone has access to super hardware
- often surveying projects are run on little or no budget and any
computers used are donated.  We aim to ensure that <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> is
feasible to use on low-spec machines.  Obviously it won't be as
responsive, but we intend it to be usable.
Please help us to achieve this by giving us some feedback
if you use <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> on a slow machine.</P
><P
><SPAN
CLASS="APPLICATION"
>Survex</SPAN
> is capable of processing extremely complex caves very
quickly and has a very effective, real-time cave viewer which allows
you to rotate, zoom, and pan the cave using mouse or keyboard. We have
tested it extensively using <ACRONYM
CLASS="ACRONYM"
>CUCC</ACRONYM
> and <ACRONYM
CLASS="ACRONYM"
>ARGE</ACRONYM
>'s surveys of the caves
under the Loser Plateau in Austria (over 25,000 survey legs, and over
140km of underground survey data). This can all be processed in around
10 seconds on a low-end netbook.
Survex is also used by many other survey projects around the world,
including the 
<A
HREF="http://www.oucc.org.uk/draenen/draenenmain.htm"
TARGET="_top"
>Ogof Draenen</A
> survey, the 
<A
HREF="http://www.easegill.org.uk/"
TARGET="_top"
>Easegill</A
> resurvey project,
the <ACRONYM
CLASS="ACRONYM"
>OFD</ACRONYM
> survey, the 
<A
HREF="http://www.oucc.org.uk/reports/surveys/surveys.htm"
TARGET="_top"
><ACRONYM
CLASS="ACRONYM"
>OUCC</ACRONYM
> Picos expeditions</A
>, and the 
<A
HREF="http://www.hongmeigui.net/"
TARGET="_top"
>Hong Meigui China
expeditions</A
>. </P
><P
><SPAN
CLASS="APPLICATION"
>Survex</SPAN
> is still actively being worked on.  Version 1.0 was
complete in some sense, but development continues - initially in reshaping
Survex into a more integrated GUI package.</P
><P
>We encourage feedback from users on important features or problems,
which will help to direct future development.  See the "Mailing List" section
of this manual for the best way to contact us.</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN53"
>1.2. About this Manual</A
></H3
><P
>If there's a part of this manual you find hard to understand, please do
let us know.  We already know Survex well, so it can be hard for us
to spot areas where the manual doesn't given enough information, or
doesn't explain things clearly enough to follow when you don't know what's
going on.  It's helpful is you can suggest a better wording, but don't worry
if you can't, just explain the problem as precisely as you can.</P
><P
>The master version of this manual is an <ACRONYM
CLASS="ACRONYM"
>SGML</ACRONYM
>
document written using the <A
HREF="http://www.docbook.org/"
TARGET="_top"
>docbook
<ACRONYM
CLASS="ACRONYM"
>DTD</ACRONYM
></A
>,
and automatically converted to a number of other formats.  If
you are going to send us <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>major</I
></SPAN
> changes, it's much easier
to include them if you work from this master.  You can get it
from the source archive (docs/manual.sgml) or from <A
HREF="https://survex.com/docs.html"
TARGET="_top"
>the Survex website</A
>.</P
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN62"
>1.2.1. Terminology</A
></H4
><P
>Throughout this document we use British terminology for
surveying.</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>station</DT
><DD
><P
>a point in the cave that you survey from and/or to</P
></DD
><DT
>leg</DT
><DD
><P
>a line joining two stations</P
></DD
><DT
>survey</DT
><DD
><P
>a group of legs surveyed on the same trip</P
></DD
></DL
></DIV
></DIV
></DIV
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN78"
>2. Getting Started</A
></H2
><P
>This section covers how to obtain the software, and how to unpack and
install it, and how to configure it.</P
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN81"
>2.1. Obtaining <SPAN
CLASS="APPLICATION"
>Survex</SPAN
></A
></H3
><P
>The latest version is available from the <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> website:
<A
HREF="https://survex.com/"
TARGET="_top"
>https://survex.com/</A
>.  It is also
freely redistributable, so you welcome to get a copy from someone else
who has already downloaded it.</P
><P
>If you want some sample data to experiment with, you can download some
from the Survex website too:
<A
HREF="https://survex.com/software/sample.tar.gz"
TARGET="_top"
>https://survex.com/software/sample.tar.gz</A
></P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN89"
>2.2. Installing <SPAN
CLASS="APPLICATION"
>Survex</SPAN
></A
></H3
><P
>The details of installation depend greatly on what platform you
are using, so there is a separate section below for each platform.</P
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN93"
>2.2.1. Linux</A
></H4
><P
>We supply pre-compiled versions for x86 Linux machines in RPM format
(suitable for Redhat, Mandrake, and some other distributions).
Survex Debian packages are available from Debian mirror sites in
the usual way.</P
><P
>You'll need root access to install these prebuilt packages.
If you don't have root access you will need to build from source
(see the next section).</P
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN97"
>2.2.2. Other versions of UNIX</A
></H4
><P
>For other UNIX versions you'll need to get the source code
and compile it on your system.  Unpack the sources and read
the file called INSTALL in the top level for details about building
from source.</P
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN100"
>2.2.3. macOS</A
></H4
><P
>The easiest way to install a recent release of Survex on macOS is by using
the Homebrew package manager. If you don't already use Homebrew, you'll
need to install it first.  See the
<A
HREF="https://survex.com/download.html?platform=macosx"
TARGET="_top"
>macOS
download page on the website</A
> for installation instructions.</P
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN104"
>2.2.4. Microsoft Windows</A
></H4
><P
>This version comes packaged with an installation wizard.  Just
run the downloaded package and it will lead you through the
installation process.  If you want the file associations to be
set up for all user, run the installer as administrator, or as a
user with administrator rights.</P
><P
>The survey viewer that's part of <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> is called
aven, and uses OpenGL for 3d rendering.</P
><P
>If you find that 3D rendering is sometimes very slow (e.g. one user reported
very slow performance when running full screen, while running in a window
was fine) then try installing the OpenGL driver supplied by the manufacturer
of your graphics card rather than the driver Microsoft supply.</P
><P
>The installer creates a Survex group in the Programs sub-menu of the
Start menu containing the following items:</P
><P
></P
><UL
><LI
><P
>Aven</P
></LI
><LI
><P
>Documentation</P
></LI
><LI
><P
>Uninstall Survex</P
></LI
></UL
><P
>Icons are installed for <TT
CLASS="FILENAME"
>.svx</TT
>, <TT
CLASS="FILENAME"
>.3d</TT
>, <TT
CLASS="FILENAME"
>.err</TT
>, and <TT
CLASS="FILENAME"
>.pos</TT
> files, and also for
Compass Plot files (<TT
CLASS="FILENAME"
>.plt</TT
> and <TT
CLASS="FILENAME"
>.plf</TT
>)
(which Survex can read). 
Double-clicking on a <TT
CLASS="FILENAME"
>.svx</TT
> file loads it for editing.  To process it to
produce a <TT
CLASS="FILENAME"
>.3d</TT
> file, right click and choose "Process" from
the menu - this runs aven to process the <TT
CLASS="FILENAME"
>.svx</TT
> file and
automatically load the resultant <TT
CLASS="FILENAME"
>.3d</TT
> file.
All the <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> file types can be right clicked on to give a menu of
possible actions.  </P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="FILENAME"
>.svx</TT
></DT
><DD
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Process</DT
><DD
><P
>  Process file with aven to produce <TT
CLASS="FILENAME"
>.3d</TT
> file (and <TT
CLASS="FILENAME"
>.err</TT
> file)
  </P
></DD
></DL
></DIV
></DD
><DT
><TT
CLASS="FILENAME"
>.3d</TT
></DT
><DD
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Open</DT
><DD
><P
>  Load file into Aven
  </P
></DD
><DT
>Print</DT
><DD
><P
>  Print the file via Aven
  </P
></DD
><DT
>Extend</DT
><DD
><P
>  Produce extended elevation
  </P
></DD
><DT
>Convert to DXF</DT
><DD
><P
>  This entry used to be provided to allow converting to a DXF file (suitable
  for importing into many CAD packages) but this functionality is now available
  from inside Aven with the ability to control what is exported, and this entry
  was dropped in 1.2.35.
  </P
></DD
><DT
>Convert for hand plotting</DT
><DD
><P
>  This entry used to be provided to allow converting to a <TT
CLASS="FILENAME"
>.pos</TT
> file
  listing all the stations and their coordinates, but this functionality is now
  available from inside Aven with the ability to control what is exported. and
  this entry was dropped in 1.2.35.
  </P
></DD
></DL
></DIV
></DD
><DT
><TT
CLASS="FILENAME"
>.err</TT
></DT
><DD
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Open</DT
><DD
><P
>  Load file into Notepad
  </P
></DD
><DT
>Sort by Error</DT
><DD
><P
>  Sort <TT
CLASS="FILENAME"
>.err</TT
> file by the error in each traverse
  </P
></DD
><DT
>Sort by Horizontal Error</DT
><DD
><P
>  Sort <TT
CLASS="FILENAME"
>.err</TT
> file by the horizontal error in each traverse
  </P
></DD
><DT
>Sort by Vertical Error</DT
><DD
><P
>  Sort <TT
CLASS="FILENAME"
>.err</TT
> file by the vertical error in each traverse
  </P
></DD
><DT
>Sort by Percentage Error</DT
><DD
><P
>  Sort <TT
CLASS="FILENAME"
>.err</TT
> file by the percentage error in each traverse
  </P
></DD
><DT
>Sort by Error per Leg</DT
><DD
><P
>  Sort <TT
CLASS="FILENAME"
>.err</TT
> file by the error per leg in each traverse
  </P
></DD
></DL
></DIV
></DD
></DL
></DIV
></DIV
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN202"
>2.3. Configuration</A
></H3
><DIV
CLASS="SECT3"
><H4
CLASS="SECT3"
><A
NAME="AEN204"
>2.3.1. Selecting Your Preferred Language</A
></H4
><P
>Survex has extensive internationalisation capabilities.  The
language used for messages from Survex and most of the library calls
it uses can be changed.  By default this is picked up from the
language the operating system is set to use (from "Regional Settings"
in Control Panel on Microsoft Windows, from the
<SPAN
CLASS="SYSTEMITEM"
>LANG</SPAN
> environment variable on UNIX
If no setting
is found, or <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> hasn't been translated into the
requested language, UK English is used.</P
><P
>However you may want to override the language manually -
for example if Survex isn't available in your native language
you'll want to choose the supported language you understand best.</P
><P
>To do this, you set the
<SPAN
CLASS="SYSTEMITEM"
>SURVEXLANG</SPAN
> environment variable.  Here's a list
of the codes currently supported:</P
><DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="AEN212"
></A
><TABLE
BORDER="1"
FRAME="border"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Code</TH
><TH
>Language</TH
></TR
></THEAD
><TBODY
><TR
><TD
>en</TD
><TD
>International English</TD
></TR
><TR
><TD
>en_US</TD
><TD
>US English</TD
></TR
><TR
><TD
>bg</TD
><TD
>Bulgarian</TD
></TR
><TR
><TD
>ca</TD
><TD
>Catalan</TD
></TR
><TR
><TD
>de</TD
><TD
>German</TD
></TR
><TR
><TD
>de_CH</TD
><TD
>Swiss German</TD
></TR
><TR
><TD
>el</TD
><TD
>Greek</TD
></TR
><TR
><TD
>es</TD
><TD
>Spanish</TD
></TR
><TR
><TD
>fr</TD
><TD
>French</TD
></TR
><TR
><TD
>hu</TD
><TD
>Hungarian</TD
></TR
><TR
><TD
>id</TD
><TD
>Indonesian</TD
></TR
><TR
><TD
>it</TD
><TD
>Italian</TD
></TR
><TR
><TD
>pl</TD
><TD
>Polish</TD
></TR
><TR
><TD
>pt</TD
><TD
>Portuguese</TD
></TR
><TR
><TD
>pt_BR</TD
><TD
>Brazillian Portuguese</TD
></TR
><TR
><TD
>ro</TD
><TD
>Romanian</TD
></TR
><TR
><TD
>ru</TD
><TD
>Russian</TD
></TR
><TR
><TD
>sk</TD
><TD
>Slovak</TD
></TR
><TR
><TD
>zh_CN</TD
><TD
>Chinese (Simplified)</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
><P
>Here are examples of how to set this environment variable to give
messages in French (language code fr):</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Microsoft Windows</DT
><DD
><P
>For MS Windows proceed as follows (this description was written from
MS Windows 2000, but it should be fairly similar in other versions): Open the
Start Menu, navigate to the Settings sub-menu, and
open Control Panel.  Open System (picture of a computer) and click on the
Advanced tab.  Choose `Environmental Variables', and create a new one: name
<SPAN
CLASS="SYSTEMITEM"
>SURVEXLANG</SPAN
>, value <SPAN
CLASS="SYSTEMITEM"
>fr</SPAN
>.
Click OK and the new value should be effective immediately.
   </P
></DD
><DT
>UNIX - csh/tcsh</DT
><DD
><P
><KBD
CLASS="USERINPUT"
>setenv SURVEXLANG fr</KBD
></P
></DD
><DT
>UNIX - sh/bash</DT
><DD
><P
><KBD
CLASS="USERINPUT"
>SURVEXLANG=fr ; export SURVEXLANG</KBD
></P
></DD
></DL
></DIV
><P
>If <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> isn't available in your language, you could
help out by providing a translation.  The initial translation is
likely to be about a day's work; after that translations for
new or changed messages are occasionally required.  Contact us for details
if you're interested.</P
></DIV
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN296"
>2.4. Using <SPAN
CLASS="APPLICATION"
>Survex</SPAN
></A
></H3
><P
>Most common tasks can now be accomplished through Aven - processing survey
data, viewing the processed data, printing, exporting to other formats,
and producing simple extended elevations.</P
><P
>A few tasks still require you to use the command line.  And some functionality
is available both via aven and from the command line, which allows it to be
scripted.</P
><P
>The command line programs that come with Survex are:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>extend</DT
><DD
><P
>	Produces extended elevations - this is probably the most useful of
	these command line tools.  Since version 1.2.27 you can produce simple
	extended elevations from Aven using the "Extended Elevation" function.
	However the command line tool allows you to specify a spec file to
	control how the survey is extended, which you can't currently do via
	Aven.
    </P
></DD
><DT
>diffpos</DT
><DD
><P
>	Compares the positions of stations in two .3d, .pos, etc files.
    </P
></DD
><DT
>sorterr</DT
><DD
><P
>	 Sorts a .err file by a specified field.
    </P
></DD
><DT
>survexport</DT
><DD
><P
>	Provides access to Aven's "Export" functionality from the command line,
	which can be useful in scripts.
    </P
></DD
><DT
>cavern</DT
><DD
><P
>	Processes survey data, but since version 1.2.3 you can process .svx
	files by simply opening them with Aven, so you no longer need to run
	cavern from the command line.  The main reason to run cavern directly
	is for use in scripts.
    </P
></DD
><DT
>dump3d</DT
><DD
><P
>	Dumps out a list of the items in a .3d file - it's mainly useful for
	debugging.
    </P
></DD
></DL
></DIV
></DIV
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN327"
>3. Survex Programs</A
></H2
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN329"
>3.1. Standard Options</A
></H3
><P
>All <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> programs respond to the following command line options:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>--help</DT
><DD
><P
>display option summary and exit</P
></DD
><DT
>--version</DT
><DD
><P
>output version information and exit</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN342"
>3.2. Short and Long Options</A
></H3
><P
>Options have two forms: short (a dash followed by a single letter e.g.
<B
CLASS="COMMAND"
>cavern -q</B
>) and long (two dashes followed by one or more words e.g.
<B
CLASS="COMMAND"
>cavern --quiet</B
>).  The long form is generally easier to
remember, while the short form is quicker to type.  Options are often
available in both forms.</P
><DIV
CLASS="NOTE"
><P
></P
><TABLE
CLASS="NOTE"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Command line options are case sensitive, so "-B" and "-b"
are different (this didn't used to be the case before Survex 0.90).  Case
sensitivity doubles the number of available short options (and is also the
norm on UNIX).</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN349"
>3.3. Filenames on the Command Line</A
></H3
><P
>Filenames with spaces can be processed (provided your operating system
supports them - UNIX does, and so do modern versions of Microsoft
Windows).  You need to enclose the filename in quotes like so:
<KBD
CLASS="USERINPUT"
>cavern "Spider Cave"</KBD
></P
><P
>A file specified on the command line of any of the <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> suite
of programs will be looked for as specified.  If it is not found, then the
file is looked for with the appropriate extension appended.  So
<KBD
CLASS="USERINPUT"
>cavern survey</KBD
> will look first for
<TT
CLASS="FILENAME"
>survey</TT
>, then for <TT
CLASS="FILENAME"
>survey.svx</TT
>.</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN358"
>3.4. Command Reference</A
></H3
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
><A
HREF="#CAVERN"
>cavern</A
>&nbsp;--&nbsp;process raw survey data</DT
><DT
><A
HREF="#AVEN"
>aven</A
>&nbsp;--&nbsp;sophisticated cave viewer for Unix and MS Windows</DT
><DT
><A
HREF="#DIFFPOS"
>diffpos</A
>&nbsp;--&nbsp;compare the contents of two <TT
CLASS="FILENAME"
>.3d</TT
> files</DT
><DT
><A
HREF="#EXTEND"
>extend</A
>&nbsp;--&nbsp;produce an extended elevation from a <TT
CLASS="FILENAME"
>.3d</TT
> file</DT
><DT
><A
HREF="#SORTERR"
>sorterr</A
>&nbsp;--&nbsp;re-sort .err file by various criteria</DT
><DT
><A
HREF="#SURVEXPORT"
>survexport</A
>&nbsp;--&nbsp;convert a processed survey data file (such as a <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> <TT
CLASS="FILENAME"
>.3d</TT
> file)
to another format.</DT
></DL
></DIV
><H1
><A
NAME="CAVERN"
></A
>cavern</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN364"
></A
><H2
>Name</H2
>cavern&nbsp;--&nbsp;process raw survey data</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN367"
></A
><H2
>Synopsis</H2
><P
><B
CLASS="COMMAND"
>cavern</B
>  [options] {survex data file...}</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN372"
></A
><H2
>Description</H2
><P
>Cavern is the <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> data processing engine.</P
><P
>If multiple survey data files are listed on the command line,
they are processed in order from left to right.  Settings are reset to
their defaults before processing each file.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN377"
></A
><H2
>Options</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>-o, --output=OUTPUT</DT
><DD
><P
>Sets location for output files.</P
></DD
><DT
>-q, --quiet</DT
><DD
><P
>Only show a brief summary (--quiet --quiet or -qq will display
warnings and errors only).</P
></DD
><DT
>-s, --no-auxiliary-files</DT
><DD
><P
>do not create .err file.</P
></DD
><DT
>-w, --warnings-are-errors</DT
><DD
><P
>turn warnings into errors.</P
></DD
><DT
>--log</DT
><DD
><P
>Send screen output to a .log file.</P
></DD
><DT
>-v, --3d-version</DT
><DD
><P
>Specify the 3d file format version to output.  By default the latest
version is written, but you can override this to produce a 3d file which can
be read by software which doesn't understand the latest 3d file format version.
Note that any information which the specified format version didn't support
will be omitted.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN404"
></A
><H2
>Output</H2
><P
>Cavern reads in text files containing the survey data
<TT
CLASS="FILENAME"
>.svx</TT
>) and outputs two files, with the extensions
<TT
CLASS="FILENAME"
>.3d</TT
> and <TT
CLASS="FILENAME"
>.err</TT
>.
By default these files are put in the current directory, 
with the same base filename as the first <TT
CLASS="FILENAME"
>.svx</TT
> file read,
but a different extension.
You can change the directory and/or base filename using the --output
command line option.
 </P
><P
>E.g. if you process the data file <TT
CLASS="FILENAME"
>entrance.svx</TT
>
with the command <KBD
CLASS="USERINPUT"
>cavern entrance</KBD
> then the files
<TT
CLASS="FILENAME"
>entrance.3d</TT
> and <TT
CLASS="FILENAME"
>entrance.err</TT
>
will be created.</P
><P
>Cavern also gives a range of statistics at the end of a successful run:</P
><P
></P
><UL
><LI
><P
>The highest and lowest stations and the height difference
between them</P
></LI
><LI
><P
>The total length of the survey (before and after
adjustment).  This total excludes survey legs flagged as SURFACE,
DUPLICATE, or SPLAY.</P
></LI
><LI
><P
>The number of stations and legs.  Note that a *EQUATE
is counted as a leg in this statistic.</P
></LI
><LI
><P
>The East-West and North-South ranges, and the North-most,
South-most, East-most, and West-most stations.</P
></LI
><LI
><P
>The number of each size of node in the network (where size
is number of connections to a station) i.e. a one node is the end of a
dead-end traverse, a two-node is a typical station in the middle of a
traverse, a three-node is a T-junction etc.</P
></LI
><LI
><P
>How long the processing took and how much CPU time was
used.</P
></LI
></UL
><DIV
CLASS="REFSECT2"
><A
NAME="AEN430"
></A
><H3
><TT
CLASS="FILENAME"
>.3d</TT
> - data describing the loop-closed centre line</H3
><P
>This file contains details of the stations and legs, and any
flags associated with them.</P
></DIV
><DIV
CLASS="REFSECT2"
><A
NAME="AEN434"
></A
><H3
><TT
CLASS="FILENAME"
>.err</TT
> - loop closure statistics (percentage errors, etc)</H3
><P
>This file contains statistics about each traverse in the survey
which is part of a loop. It includes various statistics for each
traverse, such as the percentage error per leg.
You should study this information to determine if any parts of the survey
are of lower quality or contain gross errors.&#13;</P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN438"
></A
><H2
>Error Messages</H2
><P
>There are a number of error messages that you may get when processing
data.  Most of these are self explanatory, and will be caused by such
problems as typing mistakes, or by your survey data not being attached
to fixed points (in this situation, <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> will
list some of the stations that are not connected).</P
><P
>Along with the error message, the filename and line number of the offending
line will be printed (or the filename for errors such as `file not
found').  The format of the filename and line number is that used by
gcc, so if your editor can parse errors from gcc, you should be able to
set it to allow you to jump to the file and line of each error.</P
><P
>Cavern will stop after more than 50 errors.  This usually indicates
something like the incorrect data order being specified.  Deluging
the user with error messages makes the actual problem less clear.</P
></DIV
><H1
><A
NAME="AVEN"
></A
>aven</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN448"
></A
><H2
>Name</H2
>aven&nbsp;--&nbsp;sophisticated cave viewer for Unix and MS Windows</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN451"
></A
><H2
>Synopsis</H2
><P
><B
CLASS="COMMAND"
>aven</B
>  [--survey=SURVEY] [--print] {.3d file}</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN457"
></A
><H2
>Description</H2
><P
>Aven displays processed cave surveys in a window and allows you to
manipulate the view.</P
><P
>Note that there is no perspective in the view. This means that
it is impossible to tell which way round a cave is rotating, or
whether you are viewing something from behind, or in front. So
if you think the direction of rotation in wrong, or changes as
you watch, this is just your brain being confused, not a bug!</P
><DIV
CLASS="REFSECT2"
><A
NAME="AEN461"
></A
><H3
>Mouse Control</H3
><P
>The best way to move the cave is with the mouse.  We suggest you
try each of these out after reading this section to get a feel
for how they work.</P
><P
>If you hold down the right button then the cave is dragged when you move the
mouse.</P
><P
>If you hold down the left button, then the cave is rotated if you move
left or right, and zoomed if you move up and down.
If you hold down <B
CLASS="KEYCAP"
>Ctrl</B
> while dragging with the left
mouse button, then the cave rotates and tilts at the same time instead.</P
><P
>If your mouse has a middle button then holding it down and moving the
mouse up and down tilts the cave.  Moving the mouse left and right has
no effect.</P
><P
>And if you have a scrollwheel, this can be used to zoom in/out.</P
><P
>By default the mouse moves the cave, but if you press <B
CLASS="KEYCAP"
>Ctrl-R</B
>,
then the mouse will move the viewpoint instead (i.e. everything will
go in the opposite direction). Apparently this feels more natural to some
people.</P
></DIV
><DIV
CLASS="REFSECT2"
><A
NAME="AEN471"
></A
><H3
>Keyboard Control</H3
><P
><B
CLASS="KEYCAP"
>P</B
> and <B
CLASS="KEYCAP"
>L</B
> select Plan and eLevation
respectively.  Changing between plan to elevation is animated to help
you see where you are and how things relate. This animation is
automatically disabled on slow machines to avoid user frustration.</P
><P
>Comma <B
CLASS="KEYCAP"
>'</B
>, and Slash <B
CLASS="KEYCAP"
>/</B
> tilt up
and down respectively. Tilt goes 180 degrees from plan view to a view
from directly below (upside down plan).</P
><P
><B
CLASS="KEYCAP"
>Space</B
> toggles automatic rotation about a vertical
axis on and off.  The speed of rotation for this, and animated transitions
between plan and elevation, is controlled by <B
CLASS="KEYCAP"
>Z</B
> and <B
CLASS="KEYCAP"
>X</B
>.</P
><P
>Crosses and/or labels can be displayed at survey stations.
<B
CLASS="KEYCAP"
>Ctrl-X</B
> toggles crosses and <B
CLASS="KEYCAP"
>Ctrl-N</B
> station names.
<B
CLASS="KEYCAP"
>Ctrl-L</B
> toggles the display of survey legs.</P
><P
><B
CLASS="KEYCAP"
>Delete</B
> is useful if you get lost - it resets the scale,
position, and rotation speed, so that the cave returns to the centre
of the screen. There are also keyboard controls to use instead of the
mouse - <B
CLASS="KEYCAP"
>Shift</B
> helps here as it accelerates all
movements:</P
><PRE
CLASS="SCREEN"
><B
CLASS="KEYCAP"
>Z</B
>, <B
CLASS="KEYCAP"
>X</B
> : Faster/Slower Rotation
<B
CLASS="KEYCAP"
>R</B
>: Reverse direction of rotation
<B
CLASS="KEYCAP"
>Enter</B
>, <B
CLASS="KEYCAP"
>Space</B
>: Start and stop auto-rotation
<B
CLASS="KEYCAP"
>Ctrl-Cursor Left</B
>, <B
CLASS="KEYCAP"
>Ctrl-Cursor Right</B
>: Rotate cave one step clockwise/anti-clockwise (also: <B
CLASS="KEYCAP"
>C</B
>, <B
CLASS="KEYCAP"
>V</B
>)
<B
CLASS="KEYCAP"
>Ctrl-Cursor Up</B
> , <B
CLASS="KEYCAP"
>Ctrl-Cursor Down</B
>: Higher/Lower Viewpoint (also: <B
CLASS="KEYCAP"
>'</B
> , <B
CLASS="KEYCAP"
>/</B
>)
<B
CLASS="KEYCAP"
>]</B
> , <B
CLASS="KEYCAP"
>[</B
>: Zoom in/Out
<B
CLASS="KEYCAP"
>U</B
>, <B
CLASS="KEYCAP"
>D</B
>: Set view to Up/Down
<B
CLASS="KEYCAP"
>N</B
>, <B
CLASS="KEYCAP"
>S</B
>, <B
CLASS="KEYCAP"
>E</B
>, <B
CLASS="KEYCAP"
>W</B
>: Set view to North, South, East, West
<B
CLASS="KEYCAP"
>Delete</B
>: Reset to default scale, rotation rate, etc
<B
CLASS="KEYCAP"
>P</B
>, <B
CLASS="KEYCAP"
>L</B
>: Plan, Elevation
<B
CLASS="KEYCAP"
>Cursor Left</B
>, <B
CLASS="KEYCAP"
>Cursor Right</B
>: Pan survey Left/Right (on screen)
<B
CLASS="KEYCAP"
>Cursor Up</B
>, <B
CLASS="KEYCAP"
>Cursor Down</B
>: Pan survey Up/Down (on screen)
<B
CLASS="KEYCAP"
>Ctrl-N</B
>: Toggle display of station names
<B
CLASS="KEYCAP"
>Ctrl-X</B
>: Toggle display of crosses at stations
<B
CLASS="KEYCAP"
>Ctrl-L</B
>: Toggle display of survey legs
<B
CLASS="KEYCAP"
>Ctrl-F</B
>: Toggle display of surface legs
<B
CLASS="KEYCAP"
>Ctrl-G</B
>: Toggle display of grid
<B
CLASS="KEYCAP"
>Ctrl-B</B
>: Toggle display of bounding box
<B
CLASS="KEYCAP"
>O</B
>: Toggle display of non-overlapping/all names
<B
CLASS="KEYCAP"
>Ctrl-R</B
>: reverse sense of controls
<B
CLASS="KEYCAP"
>Shift</B
>: accelerates all movement keys</PRE
><P
>A little experimentation should give a better understanding of how
this works.</P
><P
>There is an auto-resizing scale bar along the bottom of the screen
which varies in length as you zoom in or out.  
In the lower right corner is a compass pointer showing which way
is North, and a clino pointer showing the angle of tilt.
And in the upper right is a colour key showing the correspondence between
colour and depth (by default - you can also colour by date or by error).</P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN530"
></A
><H2
>Options</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>-p, --print</DT
><DD
><P
>Print the specified file and exit.</P
></DD
><DT
>-s, --survey=SURVEY</DT
><DD
><P
>Only load the sub-survey 'SURVEY'.</P
></DD
></DL
></DIV
></DIV
><H1
><A
NAME="DIFFPOS"
></A
>diffpos</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN545"
></A
><H2
>Name</H2
>diffpos&nbsp;--&nbsp;compare the contents of two <TT
CLASS="FILENAME"
>.3d</TT
> files</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN549"
></A
><H2
>Synopsis</H2
><P
><B
CLASS="COMMAND"
>diffpos</B
>  {.3d file} {.3d file} [threshold]</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN555"
></A
><H2
>Description</H2
><P
>Diffpos reports stations which
are in one file but not the other, and also stations which have moved
by more than a specified threshold distance in X, Y, or Z.  The
threshold distance is given in metres and defaults to 0.01m if not
specified.</P
><P
>For backward compatibility diffpos will also read the
<TT
CLASS="FILENAME"
>.pos</TT
> files produced by earlier versions of cavern, by
the (now removed) 3dtopos tool, by survexport, or by aven's export feature
(requires 1.2.19 or later).</P
></DIV
><H1
><A
NAME="EXTEND"
></A
>extend</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN564"
></A
><H2
>Name</H2
>extend&nbsp;--&nbsp;produce an extended elevation from a <TT
CLASS="FILENAME"
>.3d</TT
> file</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN568"
></A
><H2
>Synopsis</H2
><P
><B
CLASS="COMMAND"
>extend</B
>  [--survey=SURVEY] [--specfile=ESPEC_FILE] [--show-breaks] {INPUT_3D_FILE} [OUTPUT_3D_FILE]</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN576"
></A
><H2
>Description</H2
><DIV
CLASS="NOTE"
><P
></P
><TABLE
CLASS="NOTE"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>The <B
CLASS="COMMAND"
>extend</B
> program can also work on
<SPAN
CLASS="APPLICATION"
>Compass</SPAN
> <TT
CLASS="FILENAME"
>.plt</TT
> (as can
<B
CLASS="COMMAND"
>aven</B
> and any other <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> program which reads <TT
CLASS="FILENAME"
>.3d</TT
>
files).</P
></TD
></TR
></TABLE
></DIV
><P
>If no specfile is given, extend starts with the highest station marked
as an entrance which has at least one underground survey leg attached
to it.  If there are no such stations, the highest deadend station in
the survey (or the highest station if there are no deadends) is used.
Extend puts the first station on the left, then folds each leg out
individually to the right, breaking loops arbitrarily (usually at
junctions).</P
><P
>If the output filename is not specified, extend bases the output
filename on the input filename, but ending "_extend.3d".  For example,
<B
CLASS="COMMAND"
>extend deep_pit.3d</B
> produces an extended elevation
called <TT
CLASS="FILENAME"
>deep_pit_extend.3d</TT
>.</P
><P
>If you pass <CODE
CLASS="OPTION"
>--show-breaks</CODE
> then a leg flagged as
"surface survey" will be added between each point at which a loop has
been broken - this can be very useful for visualising the result in
aven.</P
><P
>This approach suffices for simple caves or sections of cave, but for more
complicated situations human intervention is required.  More complex
sections of cave can be handled with a specfile giving directions to
switch the direction of extension between left and right, to
explicitly specify the start station, or to break the extension at
particular stations or legs. </P
><P
>The specfile is in a format similar to cavern's data format:</P
><PRE
CLASS="PROGRAMLISTING"
>;This is a comment

; start the elevation at station entrance.a
*start entrance.a  ;this is a comment after a command

; start extending leftwards from station half-way-down.5
*eleft half-way-down.5

; change direction of extension at further-down.8
*eswap further-down.8

; extend right from further-down.junction, but only for
; the leg joining it to very-deep.1, other legs continuing
; as before
*eright further-down.junction  very-deep.1

; break the survey at station side-loop.4
*break side-loop.4

; break survey at station side-loop.junction but only
; for leg going to complex-loop.2
*break side-loop.junction complex-loop.2 </PRE
><P
>This approach requires some trial and error, but gives useful results
for many caves.  The most complex systems would benefit from an
interactive interface to select and view the breaks and switches of
direction.</P
></DIV
><H1
><A
NAME="SORTERR"
></A
>sorterr</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN600"
></A
><H2
>Name</H2
>sorterr&nbsp;--&nbsp;re-sort .err file by various criteria</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN603"
></A
><H2
>Synopsis</H2
><P
><B
CLASS="COMMAND"
>sorterr</B
>  [options] {.err file} [how many]</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN609"
></A
><H2
>Description</H2
><P
>Sorterr re-sorts a .err file by the specified criterion (or by the
error ratio by default).  Output is sent to stdout, or if --replace is
specified the input file is replaced with the sorted version. By
default all entries in the file are included - if a second parameter
is given then only the top entries after sorting are returned.</P
></DIV
><H1
><A
NAME="SURVEXPORT"
></A
>survexport</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN616"
></A
><H2
>Name</H2
>survexport&nbsp;--&nbsp;convert a processed survey data file (such as a <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> <TT
CLASS="FILENAME"
>.3d</TT
> file)
to another format.</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN621"
></A
><H2
>Synopsis</H2
><P
><B
CLASS="COMMAND"
>survexport</B
>  [options] {.3d file} [output file]</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN627"
></A
><H2
>Description</H2
><P
>The input formats supports are all those supported by Survex's "img"
library - Survex .3d, Survex .pos, Compass PLT and CMAP XYZ files.</P
><P
>Currently the output formats supported are
CSV, DXF, EPS (Encapsulated PostScript), GPX, HPGL for plotters, JSON, KML,
Survex POS files, Skencil, and SVG.
Also survexport can produce Compass .plt files, which are primarily intended
for importing into Carto, but can also be used with Compass itself.</P
><DIV
CLASS="REFSECT2"
><A
NAME="AEN631"
></A
><H3
>POS Format</H3
><P
>The POS format is a Survex-specific format containing a
list of stations with coordinates (ordered x,y,z [East, North,
Up]) and complete names.</P
><P
>The stations are sorted by name such that numbers occur in the correct order
(so ``2'' before ``10'').  Numbers with a prefix and/or suffix are sorted by the
number part first, so you'd get:</P
><PRE
CLASS="SCREEN"
>040.sv8
040.sv8a
040.sv8b
040.sv8c
040.sv9
040.sv10
040.sv11
40_entrance_tag
40b_entrance_tag</PRE
></DIV
></DIV
></DIV
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN636"
>4. <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> data files</A
></H2
><P
>Survey data is entered in the form of text files. You can use any
text editor you like for this, so long as it has the capability of
writing a plain ASCII text file. The data format is very flexible;
unlike some other cave surveying software, Survex does not require
survey legs to be rearranged to suit the computer, and the ordering 
of instrument readings on each line is fully specifiable.  So you can enter
your data much as it appears on the survey notes, which is important
in reducing the opportunities for transcription errors.</P
><P
>Also all the special characters are user-definable - for example,
the separators can be spaces and tabs, or commas (e.g. when exporting from a
spreadsheet), etc; the decimal point can be a slash (for clarity), a comma
(as used in continental Europe), or anything else you care to choose.
This flexibility
means that it should be possible to read in data from almost any sort of
survey data file without much work.</P
><P
><SPAN
CLASS="APPLICATION"
>Survex</SPAN
> places no restrictions on you in terms of the ordering
of survey legs. You can enter or process data in any order and <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> will
read it all in before determining how it is connected. You can also use the
hierarchical naming so that you do not need to worry about using the same
station name twice.</P
><P
>The usual arrangement is to have one file which lists all the others
that are included (e.g., <TT
CLASS="FILENAME"
>161.svx</TT
>). Then
<B
CLASS="COMMAND"
>cavern 161</B
> will process all your data. To just process a
section use the filename for that section, e.g. <B
CLASS="COMMAND"
>cavern dtime</B
>
will process the dreamtime file/section of Kaninchenh&ouml;hle.  To
help you out, if all legs in a survey are connected to one another
but the survey has no fixed points, cavern
will 'invent' a fixed point and print a warning message to this
effect.</P
><P
>It is up to you what data you put in which files.  You
can have one file per trip, or per area of the cave, or just one
file for the whole cave if you like.
On a large survey project it makes sense to group related surveys in the
same file or directory.</P
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN649"
>4.1. Readings</A
></H3
><P
>Blank lines (i.e. lines consisting solely of BLANK characters)
are ignored. The last line in the file need not be terminated by
an end of line character. All fields on a line must be separated
by at least one BLANK character. An OMIT character
(default '-') indicates that a field is unused. If the field is
not optional, then an error is given.</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN652"
>4.2. Survey Station Names</A
></H3
><P
><SPAN
CLASS="APPLICATION"
>Survex</SPAN
> has a powerful system for naming stations.  It
uses a hierarchy of survey names, similar to the nested folders
your computer stores files in.
So point 6 in the entrance survey of Kaninchenh&ouml;hle
(cave number 161) is referred to as: 161.entrance.6</P
><P
>This seems a natural way to refer to station names.  It also
means that it is very easy to include more levels, for example if you
want to plot all the caves in the area you just list them all in
another file, specifying a new prefix.  So to group 3 nearby caves
on the Loser Plateau you would use a file like
this:</P
><PRE
CLASS="PROGRAMLISTING"
>*begin Loser
*include 161
*include 2YrGest
*include 145
*end Loser</PRE
><P
>The entrance series point mentioned above would now be referred
to as: Loser.161.entrance.6</P
><P
>You do not have to use this system at all, and can just give all
stations unique identifiers if you like:</P
><P
>1, 2, 3, 4, 5, ... 1381, 1382</P
><P
>or</P
><P
>AA06, AA07, P34, ZZ6, etc.</P
><P
>Station and survey names may contain any alphanumeric characters and
additionally any characters in NAMES (default `_' and `-'). Alphabetic
characters may be forced to upper or lower case by using the *case
command. Station names may be any length - if you want to only treat
the first few characters as significant you can get cavern to truncate
the names using the *truncate command.</P
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN664"
>4.2.1. Anonymous Stations</A
></H4
><P
>Survex supports the concept of anonymous survey stations.  That is
survey stations without a name.  Each time an anonymous station name is
used it represents a different point.  Currently three types of anonymous
station are supported, referred to by one, two or three separator characters
- with the default separator of '.', that means '.', '..', and '...' are
anonymous stations.  Their meanings are:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Single separator ('.' by default)</DT
><DD
><P
>An anonymous non-wall point at the end of an implicit splay.</P
></DD
><DT
>Double separator ('..' by default)</DT
><DD
><P
>An anonymous wall point at the end of an implicit splay.</P
></DD
><DT
>Triple separator ('...' by default)</DT
><DD
><P
>an anonymous point with no implicit flags on the leg (intended for cases like
a disto leg along a continuing passage).</P
></DD
></DL
></DIV
><P
>You can map '-' to '..' (for compatibility with data from pocket topo) using
the command:</P
><PRE
CLASS="PROGRAMLISTING"
>*alias station - ..</PRE
><P
>Support for anonymous stations and for '*alias station - ..' was added in
Survex 1.2.7.</P
></DIV
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN683"
>4.3. Numeric fields</A
></H3
><P
>[&lt;MINUS&gt;|&lt;PLUS&gt;] &lt;integer part&gt; [ &lt;DECIMAL&gt;
[ &lt;decimal fraction&gt; ] ]</P
><P
>or [&lt;MINUS&gt;|&lt;PLUS&gt;] &lt;DECIMAL&gt; &lt;dec fraction&gt;</P
><P
>i.e. optional PLUS or MINUS sign in front, with
optional DECIMAL character (default '.'), which may be
embedded, leading or trailing. No spaces are allowed between the
various elements.</P
><P
>All of these are valid examples: +47, 23, -22, +4.5, 1.3, -0.7, +.15, .4,
-.05</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN689"
>4.4. Accuracy</A
></H3
><P
>Accuracy assessments may be provided or defaulted for any survey
leg. These determine the distribution of loop closure errors over the
legs in the loop. See *SD for more information.</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN692"
>4.5. Cavern Commands</A
></H3
><P
>Commands in <TT
CLASS="FILENAME"
>.svx</TT
> files are introduced by an asterisk
(by default - this can be changed using the <B
CLASS="COMMAND"
>set</B
> command).</P
><P
>The commands are documented in a common format:</P
><P
></P
><UL
><LI
><P
>Command Name</P
></LI
><LI
><P
>Syntax</P
></LI
><LI
><P
>Example</P
></LI
><LI
><P
>Validity</P
></LI
><LI
><P
>Description</P
></LI
><LI
><P
>Caveats</P
></LI
><LI
><P
>See Also</P
></LI
></UL
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN713"
>4.5.1. ALIAS</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*alias station &lt;alias&gt; [&lt;target&gt;]</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*begin parsons_nose
*alias station - ..
1 2 12.21 073 -12
2 -  4.33 011 +02
2 -  1.64 180 +03
2 3  6.77 098 -04
*end parsons_nose</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>*alias allows you to map a station name which appears in
the survey data to a different name internally.  At present, you can only
create an alias of '-' to '..', which is intended to support the pocket topo
style notation of '-' being a splay to an anonymous point on the cave wall.
And you can unalias '-' with '*alias station -'.</P
><P
>Aliases are scoped by *begin/*end blocks - when a *end is reached, the aliases
in force at the corresponding begin are restored.</P
><P
>*alias was added in Survex 1.2.7.</P
></DD
><DT
>See Also</DT
><DD
><P
>*begin, *end</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN735"
>4.5.2. BEGIN</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*begin [&lt;survey&gt;]</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*begin littlebit
1 2 10.23 106 -02
2 3  1.56 092 +10
*end littlebit</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>; length of leg across shaft estimated
*begin
*sd tape 2 metres
9 10 6.   031 -07
*end</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>*begin stores the current values of the current settings
such as instrument calibration, data format, and so on.
These stored values are restored after the corresponding *end.
If a survey name is given, this is used inside the *begin/*end block,
and the corresponding *end should have the same survey name.
*begin/*end blocks may be nested to indefinite depth.</P
></DD
><DT
>See Also</DT
><DD
><P
>*end, *prefix</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN756"
>4.5.3. CALIBRATE</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*calibrate &lt;quantity list&gt; &lt;zero error&gt; [&lt;scale&gt;]</P
><P
>*calibrate &lt;quantity list&gt; &lt;zero error&gt; &lt;units&gt; [&lt;scale&gt;]</P
><P
>*calibrate default</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*calibrate tape +0.3</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>*calibrate is used to specify instrument calibrations, via a zero error
and a scale factor.  By default, the zero error is 0.0 and the scale
factor 1.0 for all quantities.</P
><P
>&lt;quantity&gt; is one of TAPE|COMPASS|CLINO|COUNTER|DEPTH|DECLINATION|X|Y|Z</P
><P
>Several quantities can be given in &lt;quantity list&gt; - the specified
calibration will be applied to each of them.</P
><P
>You need to be careful about the sign of the ZeroError.  Survex follows
the convention used with scientific instruments - the ZeroError is what
the instrument reads when measuring a reading which should be zero.  So
for example, if your tape measure has the end missing, and you are using the
30cm mark to take all measurements from, then a zero distance would be measured
as 30cm and you would correct this with:</P
><PRE
CLASS="PROGRAMLISTING"
>*CALIBRATE tape +0.3</PRE
><P
>If you tape was too long, starting at -20cm (it does happen!)
then you can correct it with:</P
><PRE
CLASS="PROGRAMLISTING"
>*CALIBRATE tape -0.2</PRE
><P
>Note: ZeroError is irrelevant for Topofil counters and depth
gauges since pairs of readings are subtracted.</P
><P
>In the first form in the synopsis above, the zero error is measured by the
instrument itself (e.g. reading off the number where a truncated tape now ends)
and any scale factor specified applies to it, like so:</P
><P
>Value = ( Reading - ZeroError ) * Scale    (Scale defaults to 1.0)</P
><P
>In the second form above (supported since Survex 1.2.21), the zero error has
been measured externally (e.g. measuring how much too long your tape is with
a ruler) - the units of the zero error are explicitly specified and any scale
factor isn't applied to it:</P
><P
>Value = ( Reading * Scale ) - ZeroError    (Scale defaults to 1.0)</P
><P
>If the scale factor is 1.0, then the two forms are equivalent, though they
still allow you to differentiate between how the zero error has been determined.</P
><P
>With older Survex versions, you would specify the magnetic declination
(difference between True North and Magnetic North) by using *calibrate
declination to set an explicit value (with no scale factor allowed).  Since
Survex 1.2.22, it's recommended to instead use the new *declination command
instead - see the documentation of that command for more details.</P
></DD
><DT
>See Also</DT
><DD
><P
>*declination, *units</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN791"
>4.5.4. CASE</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*case preserve|toupper|tolower</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*begin bobsbit
; Bob insists on using case sensitive station names
*case preserve
1 2   10.23 106 -02
2 2a   1.56 092 +10
2 2A   3.12 034 +02
2 3    8.64 239 -01
*end bobsbit</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>*case determines how the case of letters in survey names is
handled.  By default all names are forced to lower case (which gives a case
insensitive match, but you can tell cavern to force to upper case, or leave
the case as is (in which case '2a' and '2A' will be regarded as different).</P
></DD
><DT
>See Also</DT
><DD
><P
>*truncate</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN811"
>4.5.5. COPYRIGHT</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*copyright &lt;date&gt; &lt;text&gt;</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*begin littlebit
*copyright 1983 CUCC
1 2 10.23 106 -02
2 3  1.56 092 +10
*end littlebit</PRE
></P
></DD
><DT
>Validity</DT
><DD
><P
>valid at the start of a *begin/*end block.</P
></DD
><DT
>Description</DT
><DD
><P
>*copyright allows the copyright information to be
stored in a way that can be automatically collated.</P
></DD
><DT
>See Also</DT
><DD
><P
>*begin</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN835"
>4.5.6. CS</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*cs [out] &lt;coordinate system&gt;</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*cs UTM60S
*fix beehive 313800 5427953 20</PRE
></P
><P
><PRE
CLASS="PROGRAMLISTING"
>; Output in the coordinate system used in the Totes Gebirge in Austria
*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"</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>*cs allows the coordinate systems used for fixed points and for
processed survey data to be specified.</P
><P
>*cs was added in Survex 1.2.14, but handling of fixed points specified with
latitude and longitude didn't work until 1.2.21.  And *fix with standard
deviations specified also didn't work until 1.2.21.</P
><P
>The currently supported coordinate systems are:</P
><P
>CUSTOM followed by a PROJ string (like in the example above).</P
><P
>EPSG: followed by a positive integer code.  EPSG codes cover most
coordinate systems in use, and PROJ supports many of these.  The website
<A
HREF="https://epsg.io/"
TARGET="_top"
>https://epsg.io/</A
> is a useful resource for
finding the EPSG code you want.  Supported since Survex 1.2.15.</P
><P
>ESRI: followed by a positive integer code.  ESRI codes are used by
ArcGIS to specify coordinate systems (in a similar way to EPSG codes), and PROJ
supports many of them.  Supported since Survex 1.2.15.</P
><P
>EUR79Z30 for UTM zone 30, EUR79 datum.  Supported since Survex 1.2.15.</P
><P
>IJTSK for the modified version of the Czechoslovak S-JTSK system where
the axes point East and North.  Supported since Survex 1.2.15.</P
><P
>IJTSK03 for a variant of IJTSK.  Supported since Survex 1.2.15.</P
><P
>JTSK for the Czechoslovak S-JTSK system.  The axes on this point West
and South, so it's not supported as an output coordinate system.
Supported since Survex 1.2.16.</P
><P
>JTSK03 for a variant of JTSK.  Supported since Survex 1.2.16.</P
><P
>LONG-LAT for longitude/latitude.  The WGS84 datum is assumed.
NB <B
CLASS="COMMAND"
>*fix</B
> expects the coordinates in the order x,y,z which
means longitude (i.e. E/W), then latitude (i.e. N/S), then altitude.
Supported since Survex 1.2.15.</P
><P
>OSGB: followed by a two letter code for the UK Ordnance Survey National
Grid.  The first letter should be 'H', 'N', 'O', 'S' or 'T'; the second any
letter except 'I'.  Supported since Survex 1.2.15.</P
><P
>S-MERC for the "Web Mercator" spherical mercator projection, used by
online map sites like OpenStreetMap, Google maps, Bing maps, etc.  Supported
since Survex 1.2.15.</P
><P
>UTM followed by a zone number (1-60), optionally followed by "N" or "S"
(default is North).  The WGS84 datum is assumed.</P
><P
>By default, Survex works in an unspecified coordinate system (and this was the
only option before *cs was added).  However, it's useful for coordinate system
which the processed survey data is in to be specified if you want to use the
processed data in ways which required knowing the coordinate system (such as
exporting a list of entrances for use in a GPS).  You can now do this by using
"*cs out".</P
><P
>It is also useful to be able to take coordinates for fixed points in whatever
coordinate system you receive them in and put them directly into Survex, rather
than having to convert with an external tool.  For example, you may have your
GPS set to show coordinates in UTM with the WGS84 datum, even though you want
the processed data to be in some local coordinate system.  And someone else
may provide GPS coordinates in yet another coordinate system.  You just need
to set the appropriate coordinate system with "*cs" before each group of "*fix"
commands in a particular coordinate system.</P
><P
>If you're going to make use of "*cs", then the coordinate system must be
specified for everything, so a coordinate system must be in effect for all
"*fix" commands, and you must set the output coordinate system before any
points are fixed.</P
><P
>Also, if "*cs" is in use, then you can't omit the coordinates in a "*fix"
command, and a fixed point won't be invented if none exists.</P
><P
>If you use "*cs out" more than once, the second and subsequent commands are
silently ignored - this makes it possible to combine two datasets with
different "*cs out" settings without having to modify either of them.</P
><P
>Something to be aware of with "*cs" is that altitudes are currently assumed to
be "height above the ellipsoid", whereas GPS units typically give you "height
above sea level", or more accurately "height above a particular geoid".  This
is something we're looking at how best to address, but you shouldn't need to
worry about it if your fixed points are in the same coordinate system as your
output, or if they all use the same ellipsoid.  For a more detailed discussion
of this, please see: http://expo.survex.com/handbook/survey/coord.htm</P
></DD
><DT
>See Also</DT
><DD
><P
>*fix</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN879"
>4.5.7. DATA</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*data &lt;style&gt; &lt;ordering&gt;</P
><P
>*data</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*data normal from to compass tape clino</PRE
></P
><P
><PRE
CLASS="PROGRAMLISTING"
>*data normal station ignoreall newline compass tape clino</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>&lt;style&gt; = DEFAULT|NORMAL|DIVING|CARTESIAN|TOPOFIL|CYLPOLAR|NOSURVEY|PASSAGE</P
><P
>&lt;ordering&gt; = ordered list of instruments - which are valid depends on the
style.</P
><P
>In Survex 1.0.2 and later, TOPOFIL is simply a synonym for NORMAL, left in to
allow older data to be processed without modification.  Use the name NORMAL
by preference.</P
><P
>There are two variants of each style - interleaved and non-interleaved.
Non-interleaved is "one line per leg", interleaved has a line for the data
shared between two legs (e.g. STATION=FROM/TO, DEPTH=FROMDEPTH/TODEPTH,
COUNT=FROMCOUNT/TOCOUNT).  Note that not all readings that can be shared
have to be, for example here the to/from station name is shared but the
depth gauge readings aren't:

<PRE
CLASS="PROGRAMLISTING"
>*data diving station newline fromdepth compass tape todepth</PRE
>

In addition, interleaved data can have a DIRECTION reading, which can be "F"
for a foresight or "B" for a backsight (meaning the direction of the leg is
reversed).</P
><P
>In interleaved data, a blank line (one which contains only characters which
are set as BLANK) ends the current traverse so can be used to handle
branches in the survey, e.g.:
<PRE
CLASS="PROGRAMLISTING"
>*data normal station newline tape compass clino

1
    9.34   087   -05
2
    ; single leg up unexplored side passage
    4.30   002	  +06
3

2
    ; and back to the main package
    6.29   093	  -02
4</PRE
></P
><P
>In data styles which include a TAPE reading (i.e. NORMAL, DIVING, and CYLPOLAR
data styles), TAPE may be replaced by FROMCOUNT/TOCOUNT (or COUNT in
interleaved data) to allow processing of surveys performed with a Topofil
instead of a tape.</P
><P
>In Survex 1.2.44 and later, you can use <B
CLASS="COMMAND"
>*data</B
> without any
arguments to keep the currently set data style, but resetting any state.  This
is useful when you're entering passage tubes with branches - see the description
of the "PASSAGE" style below.  (This feature was originally added in 1.2.31,
but was buggy until 1.2.44 - any data up to the next <B
CLASS="COMMAND"
>*data</B
>
gets quietly ignored).</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>DEFAULT</DT
><DD
><P
>Select the default data style and ordering (NORMAL style, ordering: from to tape compass clino).</P
></DD
><DT
>NORMAL</DT
><DD
><P
>The usual tape/compass/clino centreline survey.
For non-interleaved data the allowed readings are:
FROM TO TAPE COMPASS CLINO BACKCOMPASS BACKCLINO;
for interleaved data the allowed readings are:
STATION DIRECTION TAPE COMPASS CLINO BACKCOMPASS BACKCLINO.
The CLINO/BACKCLINO reading is not required - if it's not given, the vertical
standard deviation is taken to be proportional to the tape measurement.
Alternatively, individual clino readings can be given as OMIT (default "-")
which allows for data where only some clino readings are missing.
E.g.:

<PRE
CLASS="PROGRAMLISTING"
>*data normal from to compass clino tape
1 2 172 -03 12.61</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*data normal station newline direction tape compass clino
1
 F 12.61 172 -03
2</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*data normal from to compass clino fromcount tocount
1 2 172 -03 11532 11873</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*data normal station count newline direction compass clino
1 11532
 F 172 -03
2 11873</PRE
>
 </P
></DD
><DT
>DIVING</DT
><DD
><P
>An underwater survey where the vertical information is from a diver's depth
gauge.  This style can also be also used for an above-water survey where the
altitude is measured with an altimeter.  DEPTH is defined as the altitude (Z)
so increases upwards by default.  So for a diver's depth gauge, you'll need to
use *CALIBRATE with a negative scale factor (e.g. *calibrate depth 0 -1).</P
><P
>For non-interleaved data the allowed readings are:
FROM TO TAPE COMPASS CLINO BACKCOMPASS BACKCLINO FROMDEPTH TODEPTH DEPTHCHANGE (the vertical
can be given as readings at each station, (FROMDEPTH/TODEPTH) or as a change
along the leg (DEPTHCHANGE)).</P
><P
>Survex 1.2.20 and later allow an optional CLINO and/or BACKCLINO reading
in DIVING style.  At present these extra readings are checked for syntactic
validity, but are otherwise ignored.  The intention is that a future version
will check them against the other readings to flag up likely blunders, and
average with the slope data from the depth gauge and tape reading.</P
><P
>For interleaved data the allowed readings are:
STATION DIRECTION TAPE COMPASS BACKCOMPASS DEPTH DEPTHCHANGE.
(the vertical change can be given as a reading at the station (DEPTH) or as a change along the leg (DEPTHCHANGE)).

<PRE
CLASS="PROGRAMLISTING"
>*data diving from to tape compass fromdepth todepth
1 2 14.7 250 -20.7 -22.4</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*data diving station depth newline tape compass
1 -20.7
 14.7 250
2 -22.4</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*data diving from to tape compass depthchange
1 2 14.7 250 -1.7</PRE
></P
></DD
><DT
>CARTESIAN</DT
><DD
><P
>Cartesian data style allows you to specify the (x,y,z) changes between
stations.  It's useful for digitising surveys where the original survey
data has been lost and all that's available is a drawn up version.

<PRE
CLASS="PROGRAMLISTING"
>*data cartesian from to northing easting altitude
1 2 16.1 20.4 8.7</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*data cartesian station newline northing easting altitude
1
 16.1 20.4 8.7
2</PRE
>&#13;</P
><DIV
CLASS="NOTE"
><P
></P
><TABLE
CLASS="NOTE"
WIDTH="90%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Cartesian data are relative to <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>true</I
></SPAN
> North not
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>magnetic</I
></SPAN
> North (i.e. they are unaffected by
<B
CLASS="COMMAND"
>*calibrate declination</B
>).</P
></TD
></TR
></TABLE
></DIV
></DD
><DT
>CYLPOLAR</DT
><DD
><P
>A CYLPOLAR style survey is very similar to a diving survey, except that the tape
is always measured horizontally rather than along the slope of the leg.

<PRE
CLASS="PROGRAMLISTING"
>*data cylpolar from to tape compass fromdepth todepth
1 2 9.45 311 -13.3 -19.0</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*data cylpolar station depth newline tape compass
1 -13.3
 9.45 311
2 -19.0</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*data cylpolar from to tape compass depthchange
1 2 9.45 311 -5.7</PRE
></P
></DD
><DT
>NOSURVEY</DT
><DD
><P
>A NOSURVEY survey doesn't have any measurements - it merely indicates that
there is line of sight between the pairs of stations.

<PRE
CLASS="PROGRAMLISTING"
>*data nosurvey from to
1 7
5 7
9 11</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*data nosurvey station
1
7
5

*data nosurvey station
9
11</PRE
></P
></DD
><DT
>PASSAGE</DT
><DD
><P
>This survey style defines a 3D "tube" modelling a passage in the cave.
The tube uses the survey stations listed in the order listed.  It's
permitted to use survey stations which aren't directly linked by
the centre-line survey.  This can be useful - sometimes the centreline
will step sideways or up/down to allow a better sight for the next
leg and you can ignore the extra station.  You can also define tubes
along unsurveyed passages, akin to "nosurvey" legs in the centreline
data.</P
><P
>This means that you need to split off side passages into seperate
tubes, and hence separate sections of passage data, starting with
a new *data command.</P
><P
>Simple example of how to use this data style (note the use of ignoreall
to allow a free-form text description to be given):

<PRE
CLASS="PROGRAMLISTING"
>*data passage station left right up down ignoreall
1  0.1 2.3 8.0 1.4  Sticking out point on left wall
2  0.0 1.9 9.0 0.5  Point on left wall
3  1.0 0.7 9.0 0.8  Highest point of boulder</PRE
>

Each <B
CLASS="COMMAND"
>*data passage</B
> data block describes a single continuous
tube - to break a tube or to enter a side passage you need to have a second
block.  With Survex 1.2.30 and older, you had to repeat the entire
<B
CLASS="COMMAND"
>*data passage</B
> line to start a new tube, but in Survex 1.2.31
and later, you can just use <B
CLASS="COMMAND"
>*data</B
> without any arguments.</P
><P
>For example here the main passage is 1-2-3 and a side passage is 2-4:

<PRE
CLASS="PROGRAMLISTING"
>*data passage station left right up down ignoreall
1  0.1 2.3 8.0 1.4  Sticking out point on left wall
2  0.0 1.9 9.0 0.5  Point on left wall opposite side passage
3  1.0 0.7 9.0 0.8  Highest point of boulder
; If you're happy to require Survex 1.2.31 or later, you can just use
; "*data" here instead.
*data passage station left right up down ignoreall
2  0.3 0.2 9.0 0.5
4  0.0 0.5 6.5 1.5  Fossil on left wall</PRE
></P
></DD
></DL
></DIV
><P
>IGNORE skips a field (it may be used any number of times),
and IGNOREALL may be used last to ignore the rest of the data line.</P
><P
>LENGTH is a synonym for TAPE; BEARING for COMPASS; GRADIENT for CLINO; COUNT for COUNTER.</P
><P
>The units of each quantity may be set with the UNITS command.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN970"
>4.5.8. DATE</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*date &lt;year&gt;[.&lt;month&gt;[.&lt;day&gt;]][-&lt;year&gt;[.&lt;month&gt;[.&lt;day&gt;]]]</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*date 2001</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*date 2000.10</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*date 1987.07.27</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*date 1985.08.12-1985.08.13</PRE
></P
></DD
><DT
>Validity</DT
><DD
><P
>valid at the start of a *begin/*end block.</P
></DD
><DT
>Description</DT
><DD
><P
>*date specifies the date that the survey was done.  A range of dates
can be specified (useful for overnight or multi-day surveying trips).</P
></DD
><DT
>See Also</DT
><DD
><P
>*begin, *instrument, *team</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN997"
>4.5.9. DECLINATION</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*declination auto &lt;x&gt; &lt;y&gt; &lt;z&gt;</P
><P
>*declination &lt;declination&gt; &lt;units&gt;</P
></DD
><DT
>Description</DT
><DD
><P
>The *declination command is the modern way to specify magnetic declinations in
Survex.  Prior to 1.2.22, *calibrate declination was used instead.  If you
use a mixture of *calibrate declination and *declination, they interact in
the natural way - whichever was set most recently is used for each compass
reading (taking into account survey scope).  We don't generally recommend
mixing the two, but it's useful to understand how they interact if you want to
combine datasets using the old and new commands, and perhaps if you have a
large existing dataset and want to migrate it without having to change
everything at once.</P
><P
>Magnetic declination is the difference between Magnetic North and True North.
It varies both with location and over time.  Compass bearings are measured
relative to Magnetic North - adding the magnetic declination gives bearings
relative to True North.</P
><P
>If you have specified the output coordinate system (using *cs out) then you can
use *declination auto (and we recommend that you do).  This is supported since
Survex 1.2.21 and automatically calculates magnetic declinations based on the
IGRF (International Geomagnetic Reference Field) model for the specified date
of each survey and at the specified representative location (given in the
current input coordinate system, as set with *cs).  Survex 1.2.27 and
later also automatically correct for grid convergence (the difference between
Grid North and True North) when *declination auto is in use, based on the same
specified representative location.  A revised version of the IGRF model is
usually issued every 5 years - Survex 1.2.43 updated to using version 13 in
early 2020.</P
><P
>You might wonder why Survex needs a representative location instead of
calculating the magnetic declination and grid convergence for the actual
position of each survey station.  The reason is that we need to adjust the
compass bearings before we can solve the network to find survey station
locations.  Both magnetic declination and grid convergence don't generally vary
significantly over the area of a typical cave system - if you are mapping a
very large cave system, or caves over a wide area, or are working close to a
magnetic pole or where the output coordinate system is rather distorted, then
you can specify *declination auto several times with different locations - the
one currently in effect is used for each survey leg.</P
><P
>Generally it's best to specify a suitable output coordinate system, and use
*declination auto so Survex corrects for magnetic declination and grid
convergence for you.  Then Aven knows how to translate coordinates to allow
export to formats such as GPX and KML, and to overlay terrain data.</P
><P
>If you don't specify an output coordinate system, but fix one or more points
then Survex works implicitly in the coordinate system your fixed points were
specified in.  This mode of operation is provided for compatibility with
datasets from before support for explicit coordinate systems was added to
Survex - it's much better to specify the output coordinate system as above.
But if you have a survey of a cave which isn't connected to any known fixed
points then you'll need to handle it this way, either fixing an entrance
to some arbitrary coordinates (probably (0,0,0)) or letting Survex pick a
station as the origin.  If the survey was all done in a short enough period
of time that the magnetic declination won't have changed significantly, you
can just ignore it and Grid North in the implicit coordinate system will be
Magnetic North at the time of the survey.  If you want to correct for magnetic
declination, you can't use *declination auto because the IGRF model needs the
real world coordinates, but you can specify literal declination values for each
survey using *declination &lt;declination&gt; &lt;units&gt;.  Then Grid North
in the implicit coordinate system is True North.</P
><P
>Note that the value specified uses the conventional sign for magnetic
declination, unlike the old *calibrate declination which needed a value with
the opposite sign (because *calibrate specifies a zero error), so take care
when updating old data, or if you're used to the semantics of *calibrate
declination.</P
></DD
><DT
>See Also</DT
><DD
><P
>*calibrate</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1019"
>4.5.10. DEFAULT</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*default &lt;settings list&gt;|all</P
></DD
><DT
>Description</DT
><DD
><P
>The valid settings are CALIBRATE, DATA, and UNITS.</P
><P
>*default restores defaults for given settings.  This command is deprecated -
you should instead use: *calibrate default, *data default, *units default.</P
></DD
><DT
>See Also</DT
><DD
><P
>*calibrate, *data, *units</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1035"
>4.5.11. END</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*end [&lt;survey&gt;]</P
></DD
><DT
>Validity</DT
><DD
><P
>valid for closing a block started by *begin in the same file.</P
></DD
><DT
>Description</DT
><DD
><P
>Closes a block started by *begin.</P
></DD
><DT
>See Also</DT
><DD
><P
>*begin</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1054"
>4.5.12. ENTRANCE</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*entrance &lt;station&gt;</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*entrance P163</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>*entrance sets the <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>entrance</I
></SPAN
> flag for a station.
This information is used by aven to allow entrances to be highlighted.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1071"
>4.5.13. EQUATE</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*equate &lt;station&gt; &lt;station&gt;...</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*equate chosspot.1 triassic.27</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>*equate specifies that the station names in the list refer to the
same physical survey station. An error is given if there is only one station
listed.</P
></DD
><DT
>See Also</DT
><DD
><P
>*infer equates</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1091"
>4.5.14. EXPORT</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*export &lt;station&gt;...</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*export 1 6 17</PRE
></P
></DD
><DT
>Validity</DT
><DD
><P
>valid at the start of a *begin/*end block.</P
></DD
><DT
>Description</DT
><DD
><P
>*export marks the stations named as referable to from the enclosing
survey.  To be able to refer to a station from a survey several levels
above, it must be exported from each enclosing survey.</P
></DD
><DT
>See Also</DT
><DD
><P
>*begin, *infer exports</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1115"
>4.5.15. FIX</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*fix &lt;station&gt; [reference]
 [ &lt;x&gt; &lt;y&gt; &lt;z&gt;
   [ &lt;x std err&gt; &lt;y std err&gt; &lt;z std err&gt;
     [ &lt;cov(x,y)&gt; &lt;cov(y,z)&gt; &lt;cov(z,x)&gt; ] ] ]</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*fix entrance.0 32768 86723 1760</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*fix KT114_96 reference 36670.37 83317.43 1903.97</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>*fix fixes the position of &lt;station&gt; at the given coordinates.
If you haven't specified the coordinate system with "*cs", you can
omit the position and it will default to (0,0,0).  The standard errors default
to zero (fix station exactly).  cavern will give an error if you attempt to fix
the same survey station twice at different coordinates, or a warning if you fix
it twice with matching coordinates.</P
><P
>You can also specify just one standard error (in which case it is assumed
equal in X, Y, and Z) or two (in which case the first is taken as the
standard error in X and Y, and the second as the standard error in Z).</P
><P
>If you have covariances for the fix, you can also specify these - the
order is cov(x,y) cov(y,z) cov(z,x). </P
><P
>If you've specified a coordinate system (see <B
CLASS="COMMAND"
>*cs</B
>) then
that determines the meaning of X, Y and Z (if you want to specify the
units for altitude, note that using a PROJ string containing
<B
CLASS="COMMAND"
>+vunits</B
> allows this - e.g. <B
CLASS="COMMAND"
>+vunits=us-ft</B
>
for US survey feet).  If you don't specify a coordinate system, then the
coordinates must be in metres.  The standard deviations must always be
in metres (and the covariances in metres squared).</P
><P
>You can fix as many stations as you like - just use a *fix command for each
one.  Cavern will check that all stations are connected to
at least one fixed point so that co-ordinates can be calculated for all
stations.</P
><P
>By default cavern will warn about stations which have been FIX-ed but
not used otherwise, as this might be due to a typo in the station
name.  This is unhelpful if you want to include a standard file of benchmarks,
some of which won't be used.  In this sort of situation, specify "REFERENCE"
after the station name in the FIX command to suppress this warning for a
particular station.</P
><DIV
CLASS="NOTE"
><P
></P
><TABLE
CLASS="NOTE"
WIDTH="90%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>X is Easting, Y is Northing, and Z is altitude.  This convention was chosen
since on a map, the horizontal (X) axis is usually East, and the vertical
axis (Y) North.  The choice of altitude (rather than depth) for Z is taken
from surface maps, and makes for less confusion when dealing with cave
systems with more than one entrance.  It also gives a right-handed
set of axes.</P
></TD
></TR
></TABLE
></DIV
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1142"
>4.5.16. FLAGS</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*flags &lt;flags&gt;</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*flags duplicate not surface</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>*flags updates the current flag settings.
Flags not mentioned retain their previous state.  Valid flags
are DUPLICATE, SPLAY, and SURFACE, and a flag may be preceded with NOT to
turn it off.</P
><P
>Survey legs marked SURFACE are hidden from plots by default, and not
included in cave survey length calculations.  Survey legs marked as
DUPLICATE or SPLAY are also not included in cave survey length
calculations; legs marked SPLAY are ignored by the extend program.
DUPLICATE is intended for the case when if you have two different
surveys along the same section of passage (for example to tie two
surveys into a permanent survey station); SPLAY is intended for 
cases such as radial legs in a large chamber.</P
></DD
><DT
>See Also</DT
><DD
><P
>*begin</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1163"
>4.5.17. INCLUDE</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*include &lt;filename&gt;</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*include mission</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*include "the pits"</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>*include processes &lt;filename&gt; as if it were inserted at this
place in the current file. (i.e. The current settings are carried
into &lt;filename&gt;, and any alterations to settings in &lt;filename&gt;
will be carried back again).  There's one exception to this (for
obscure historical reasons) which is that the survey prefix is
restored upon return to the original file.  Since *begin and *end
nesting cannot cross files, this can only make a difference if you
use the deprecated *prefix command.</P
><P
>If &lt;filename&gt; contains spaces, it must be enclosed in quotes.</P
><P
>An included file which does not have a complete path
is resolved relative to the directory which the parent file is in
(just as relative HTML links do).  Cavern will try adding a <TT
CLASS="FILENAME"
>.svx</TT
>
extension, and will also try translating "\" to "/".
And as a last
resort, it will try a lower case version of the filename (so if you
use Unix and someone sends you a DOS/Windows dataset with mismatched
case, unzip it with "unzip -L" and UNIX cavern will process it).</P
><P
>The depth to which you can nest
include files may be limited by the operating system
you use.  Usually the limit is fairly high (&#62;30), but if you want to be able to
process your dataset with <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> on any supported platform, it
would be prudent not to go overboard with nested include files.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1185"
>4.5.18. INFER</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*infer plumbs on|off</P
><P
>*infer equates on|off</P
><P
>*infer exports on|off</P
></DD
><DT
>Description</DT
><DD
><P
>"*infer plumbs on" tells cavern to interpret gradients of +/- 90
degrees as UP/DOWN (so it
will not apply the clino correction to them). This is useful when
the data has not been converted to have UP and DOWN in it.</P
><P
>"*infer equates on" tells cavern to interpret a leg with
a tape reading of zero as a *equate.  this prevents tape corrections
being applied to them.</P
><P
>"*infer exports on" is necessary when you have a dataset which is
partly annotated with *export.  It tells cavern not to complain about
missing *export commands in part of the dataset.  Also stations which
were used to join surveys are marked as exported in the 3d file.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1200"
>4.5.19. INSTRUMENT</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*instrument &lt;instrument&gt; &lt;identifier&gt;</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*instrument compass "CUCC 2"
*instrument clino "CUCC 2"
*instrument tape "CUCC Fisco Ranger open reel"</PRE
></P
></DD
><DT
>Validity</DT
><DD
><P
>valid at the start of a *begin/*end block.</P
></DD
><DT
>Description</DT
><DD
><P
>*instrument specifies the particular instruments used to perform a
survey.</P
></DD
><DT
>See Also</DT
><DD
><P
>*begin, *date, *team</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1224"
>4.5.20. PREFIX</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*prefix &lt;survey&gt;</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*prefix flapjack</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>*prefix sets the current survey.</P
></DD
><DT
>Caveats</DT
><DD
><P
>*prefix is deprecated - you should use *begin and *end
instead.</P
></DD
><DT
>See Also</DT
><DD
><P
>*begin, *end</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1248"
>4.5.21. REF</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*ref &lt;string&gt;</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*ref "survey folder 2007#12"</PRE
></P
></DD
><DT
>Validity</DT
><DD
><P
>valid at the start of a *begin/*end block.</P
></DD
><DT
>Description</DT
><DD
><P
>*ref allows you to specify a reference.  If the reference contains spaces, you
must enclose it in double quotes.  Survex doesn't try to interpret the
reference in any way, so it's up to you how you use it - for example it could
specify where the original survey notes can be found.</P
><P
>*ref was added in Survex 1.2.23.</P
></DD
><DT
>See Also</DT
><DD
><P
>*begin, *date, *instrument, *team</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1273"
>4.5.22. REQUIRE</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*require &lt;version&gt;</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*require 0.98</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>*require checks that the version of cavern in use is at least
&lt;version&gt; and stops with an error if not.
So if your dataset requires a feature
introduced in a particular version, you can add a *require command and
users will know what version they need to upgrade to, rather than
getting an error message and having to guess what the real problem is.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1289"
>4.5.23. SD</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*sd &lt;quantity list&gt; &lt;standard deviation&gt;</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*sd tape 0.15 metres</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>*sd sets the standard deviation of a measurement.</P
><P
>&lt;quantity&gt; is one of (each group gives alternative names for the same
quantity):</P
><P
></P
><UL
><LI
><P
>TAPE, LENGTH</P
></LI
><LI
><P
>BACKTAPE, BACKLENGTH (added in Survex 1.2.25)</P
></LI
><LI
><P
>COMPASS, BEARING</P
></LI
><LI
><P
>BACKCOMPASS, BACKBEARING</P
></LI
><LI
><P
>CLINO, GRADIENT</P
></LI
><LI
><P
>BACKCLINO, BACKGRADIENT</P
></LI
><LI
><P
>COUNTER, COUNT</P
></LI
><LI
><P
>DEPTH</P
></LI
><LI
><P
>DECLINATION</P
></LI
><LI
><P
>DX, EASTING</P
></LI
><LI
><P
>DY, NORTHING</P
></LI
><LI
><P
>DZ, ALTITUDE</P
></LI
><LI
><P
>LEFT</P
></LI
><LI
><P
>RIGHT</P
></LI
><LI
><P
>UP, CEILING</P
></LI
><LI
><P
>DOWN, FLOOR</P
></LI
><LI
><P
>LEVEL</P
></LI
><LI
><P
>PLUMB</P
></LI
><LI
><P
>POSITION</P
></LI
></UL
><P
>&lt;standard deviation&gt; must include units and thus is typically
"0.05 metres", or "0.02 degrees". See *units below for full list
of valid units.</P
><P
>To utilise this command fully you need to understand what a
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>standard deviation</I
></SPAN
> is.
It gives a value to the 'spread' of the errors
in a measurement. Assuming that these are normally distributed
we can say that 95.44% of the actual lengths will fall within two
standard deviations of the measured length. i.e. a tape SD of
0.25 metres means that the actual length of a tape measurement
is within + or - 0.5 metres of the recorded value 95.44% of the time.
So if the measurement is 7.34m then the actual length is very
likely to be between 6.84m and 7.84m. This example corresponds
to BCRA grade 3. Note that this is just one interpretation of
the BCRA standard, taking the permitted error values as 2SD 95.44%
confidence limits. If you want to take the readings as being some
other limit (e.g. 1SD = 68.26%) then you will need to change the BCRA3
and BCRA5 files accordingly. This issue is explored in more
detail in various surveying articles.</P
></DD
><DT
>See Also</DT
><DD
><P
>*units</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1352"
>4.5.24. SET</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*set &lt;item&gt; &lt;character list&gt;</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*set blank x09x20
*set decimal ,</PRE
>

Note that you need to eliminate comma from being a blank before setting it as
a decimal - otherwise the comma in "*set decimal ," is parsed as a blank, and
you set decimal to not have any characters representing it.</P
></DD
><DT
>Description</DT
><DD
><P
>*set sets the specified &lt;item&gt; to the character or characters
given in &lt;character list&gt;. The example sets the decimal
separator to be a comma.</P
><P
>xAB means the character with hex value AB. Eg x20 is a space.</P
><P
>The complete list of items that can be set, the defaults (in
brackets), and the meaning of the item, is:</P
><P
></P
><UL
><LI
><P
>BLANK (x09x20,) Separates fields</P
></LI
><LI
><P
>COMMENT (;) Introduces comments</P
></LI
><LI
><P
>DECIMAL (.) Decimal point character </P
></LI
><LI
><P
>EOL (x0Ax0D) End of line character</P
></LI
><LI
><P
>KEYWORD (*) Introduces keywords</P
></LI
><LI
><P
>MINUS (-) Indicates negative number</P
></LI
><LI
><P
>NAMES (_-) Non-alphanumeric chars permitted in station
names (letters and numbers are always permitted).</P
></LI
><LI
><P
>OMIT (-) Contents of field omitted (e.g. in plumbed legs)</P
></LI
><LI
><P
>PLUS (+) Indicates positive number </P
></LI
><LI
><P
>ROOT (\) Prefix in force at start of current file (use of ROOT is deprecated)</P
></LI
><LI
><P
>SEPARATOR (.) Level separator in prefix hierarchy</P
></LI
></UL
><P
>The special characters may not be alphanumeric.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1394"
>4.5.25. SOLVE</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*solve</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*include 1997data
*solve
*include 1998data</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>Distributes misclosures around any loops in the survey and fixes
the positions of all existing stations.  This command is intended
for situations where you have some new surveys adding extensions
to an already drawn-up survey which you wish to avoid completely
redrawing. You can read in the old data, use *SOLVE to fix it, and then
read in the new data.  Then old stations will be in the same
positions as they are in the existing drawn up survey, even if new loops
have been formed by the extensions.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1410"
>4.5.26. TEAM</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*team &lt;person&gt; [&lt;role&gt;...]</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*team "Nick Proctor" compass clino tape
*team "Anthony Day" notes pictures tape</PRE
></P
></DD
><DT
>Validity</DT
><DD
><P
>valid at the start of a *begin/*end block.</P
></DD
><DT
>Description</DT
><DD
><P
>*team specifies the people involved in a survey and optionally what role or
roles they filled during that trip.  Unless the person is only identified by
one name you need to put double quotes around their name.</P
></DD
><DT
>See Also</DT
><DD
><P
>*begin, *date, *instrument</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1434"
>4.5.27. TITLE</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*title &lt;title&gt;</P
></DD
><DT
>Example</DT
><DD
><PRE
CLASS="PROGRAMLISTING"
>*title Dreamtime</PRE
><PRE
CLASS="PROGRAMLISTING"
>*title "Mission Impossible"</PRE
></DD
><DT
>Description</DT
><DD
><P
>*title allows you to set the descriptive title for a survey.
If the title contains spaces, you need to enclose it in quotes ("").
If there is no *title command, the title defaults to the survey name
given in the *begin command.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1450"
>4.5.28. TRUNCATE</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*truncate &lt;length&gt;|off</P
></DD
><DT
>Description</DT
><DD
><P
>Station names may be of any length in <SPAN
CLASS="APPLICATION"
>Survex</SPAN
>, but some
other (mostly older) cave surveying software only regard the first few
characters of a name as significant (e.g. "entran" and "entrance"
might be treated as the same).  To facilitate using data imported from
such a package <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> allows you to truncate names to whatever
length you want (but by default truncation is off).</P
><P
>Figures for the number of characters which are significant in various
software packages: Compass currently has a limit of 12,
CMAP has a limit of 6,
Smaps 4 had a limit of 8,
Surveyor87/8 used 8.
<SPAN
CLASS="APPLICATION"
>Survex</SPAN
> itself used 8 per prefix
level up to version 0.41, and 12 per prefix level up to 0.73 (more recent
versions removed this rather archaic restriction).</P
></DD
><DT
>See Also</DT
><DD
><P
>*case</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1469"
>4.5.29. UNITS</A
></H4
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Syntax</DT
><DD
><P
>*units &lt;quantity list&gt; [&lt;factor&gt;] &lt;unit&gt;</P
><P
>*units default</P
></DD
><DT
>Example</DT
><DD
><P
><PRE
CLASS="PROGRAMLISTING"
>*units tape metres</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*units compass backcompass clino backclino grads</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*units dx dy dz 1000 metres ; data given as kilometres</PRE
>

<PRE
CLASS="PROGRAMLISTING"
>*units left right up down feet</PRE
></P
></DD
><DT
>Description</DT
><DD
><P
>&lt;quantity&gt; is one of the following (grouped entries are just alternative names for the same thing):
TAPE/LENGTH, BACKTAPE/BACKLENGTH (added in Survex 1.2.25), COMPASS/BEARING, BACKCOMPASS/BACKBEARING, CLINO/GRADIENT, BACKCLINO/BACKGRADIENT, COUNTER/COUNT, DEPTH, DECLINATION, DX/EASTING, DY/NORTHING, DZ/ALTITUDE, LEFT, RIGHT, UP/CEILING, DOWN/FLOOR</P
><P
>Changes current units of all the quantities listed to [&lt;factor&gt;]
&lt;unit&gt;. Note that quantities can be expressed either as
the instrument (e.g. COMPASS) or the measurement (e.g. BEARING).</P
><P
>&lt;factor&gt; allows you to easy specify situations such as measuring
distance with a diving line knotted every 10cm (*units distance 0.1 metres).
If &lt;factor&gt; is omitted it defaults to 1.0.  If specified, it must be
non-zero.</P
><P
>Valid units for listed quantities are:</P
><P
>TAPE/LENGTH, BACKTAPE/BACKLENGTH, COUNTER/COUNT, DEPTH, DX/EASTING, DY/NORTHING, DZ/ALTITUDE
in YARDS|FEET|METRIC|METRES|METERS (default: METRES)</P
><P
>CLINO/GRADIENT, BACKCLINO/BACKGRADIENT
in DEGS|DEGREES|GRADS|MINUTES|PERCENT|PERCENTAGE (default: DEGREES)</P
><P
>COMPASS/BEARING, BACKCOMPASS/BACKBEARING, DECLINATION
in DEGS|DEGREES|GRADS|MINUTES|QUADS|QUADRANTS (default: DEGREES)</P
><P
>(360 degrees = 400 grads)</P
><P
>QUADRANTS are a style of bearing used predominantly in land survey, and occasionally
in survey with handheld instruments. All bearings are N or S, a numeric from 0 to
90, followed by E or W. For example S34E to refer to 146 degrees, or 34 degrees in
the SE quadrant. In this format, exact cardinal directions may be simply alphabetic.
E.g. N is equivalent to N0E and E is equivalent to N90E. This unit was added in Survex
1.2.44.</P
><P
>Survex has long support MILS as an alias for GRADS.  However, this seems to
be a bogus definition of a "mil" which is unique to Survex (except that Therion
has since copied it) - there are several different definitions of a "mil" but
they vary from 6000 to 6400 in a full circle, not 400.  Because of this we
deprecated MILS in Survex 1.2.38 - you can still process data which uses them
but you'll now get a warning, and we recommend you update your data.</P
><P
>For example, if your data uses

<PRE
CLASS="PROGRAMLISTING"
>*units compass mils</PRE
>

then you need to determine what the intended units actually are.  If there
are 400 in a full circle, then instead use this (which will work with older
Survex versions too):

<PRE
CLASS="PROGRAMLISTING"
>*units compass grads</PRE
>

If the units are actually mils, you can specify that in terms of degrees.
For example, for NATO mils (6400 in a full circle) you can use this (which
also works with older Survex versions):

<PRE
CLASS="PROGRAMLISTING"
>*units compass 0.05625 degrees</PRE
></P
></DD
><DT
>See Also</DT
><DD
><P
>*calibrate</P
></DD
></DL
></DIV
></DIV
></DIV
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN1506"
>5. Contents of <TT
CLASS="FILENAME"
>.svx</TT
> files: How do I?</A
></H2
><P
>Here is some example <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> data (a very small cave numbered 1623/163):</P
><PRE
CLASS="PROGRAMLISTING"
>2 1 26.60 222  17.5
2 3 10.85 014   7
2 4  7.89 254 -11
4 5  2.98  - DOWN
5 6  9.29 271 -28.5</PRE
><P
>You can vary the data ordering.  The default is:</P
><P
>from-station to-station tape compass clino</P
><P
>This data demonstrates a number of useful features of <SPAN
CLASS="APPLICATION"
>Survex</SPAN
>:</P
><P
>Legs can be measured either way round, which allows the use of
techniques like "leap-frogging" (which is where legs
alternate forwards and backwards).</P
><P
>Also notice that there is a spur in the survey (2 to 3).  You
do not need to specify this specially.</P
><P
><SPAN
CLASS="APPLICATION"
>Survex</SPAN
> places few restrictions on station naming (see "Survey
Station Names" in the previous section), so you can number the stations
as they were in the original survey notes.  Although not apparent from
this example, there is no requirement for each leg to connect to an
existing station.  <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> can accept data in any order, and will
check for connectedness once all the data has been read in.</P
><P
>Each survey is also likely to have other information associated
with it, such as instrument calibrations, etc.  This has been
omitted from this example to keep things simple.</P
><P
>Most caves will take more than just one survey trip to map.  Commonly
the numbering in each survey will begin at 1, so we need to be
able to tell apart stations with the same number in different
surveys.</P
><P
>To accomplish this, <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> has a very flexible system of hierarchical
prefixes.  All you need do is give each survey a unique name or
number, and enter the data like so:</P
><PRE
CLASS="PROGRAMLISTING"
>*begin 163
*export 1
2 1 26.60 222  17.5
2 3 10.85 014   7
2 4  7.89 254 -11
4 5  2.98  - DOWN
5 6  9.29 271 -28.5
*end 163</PRE
><P
><SPAN
CLASS="APPLICATION"
>Survex</SPAN
> will name the stations by attaching the current prefix.
In this case, the stations will be named 163.1, 163.2, etc.</P
><P
>We have a convention with the CUCC Austria data that the entrance survey
station of a cave is named P&lt;cave number&gt;, P163 in this case. We
can accomplish this like so:</P
><PRE
CLASS="PROGRAMLISTING"
>*equate P163 163.1
*entrance P163
*begin 163
*export 1
2 1 26.60 222  17.5
2 3 10.85 014   7
2 4  7.89 254 -11
4 5  2.98  - DOWN
5 6  9.29 271 -28.5
*end 163</PRE
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1530"
>5.1. Specify surface survey data</A
></H3
><P
>Say you have 2 underground surveys and 2 surface ones with 2 fixed reference
points.  You want to mark the surface surveys so that their length isn't
included in length statistics, and so that Aven knows to display them
differently.  To do this you mark surface data with the "surface" flag
- this is set with "*flags surface" like so:</P
><PRE
CLASS="PROGRAMLISTING"
>; fixed reference points
*fix fix_a 12345 56789 1234
*fix fix_b 23456 67890 1111                                                     
                                                                                
; surface data (enclosed in *begin ... *end to stop the *flags command
; from "leaking" out)
*begin
*flags surface
*include surface1
*include surface2
*end                                                                            
                                                                                
; underground data
*include cave1
*include cave2</PRE
><P
>You might also have a survey which starts on the surface and heads into a
cave.  This can be easily handled too - here's an example which goes in
one entrance, through the cave, and out of another entrance:</P
><PRE
CLASS="PROGRAMLISTING"
>*begin BtoC
*title "161b to 161c"
*date 1990.08.06 ; trip 1990-161c-3 in 1990 logbook

*begin
*flags surface
02    01      3.09   249    -08.5
02    03      4.13   252.5  -26
*end

04    03      6.00   020    +37
04    05      3.07   329    -31
06    05      2.67   203    -40.5
06    07      2.20   014    +04
07    08      2.98   032    +04
08    09      2.73   063.5  +21
09    10     12.35   059    +15

*begin
*flags surface
11    10      4.20   221.5  -11.5
11    12      5.05   215    +03.5
11    13      6.14   205    +12.5
13    14     15.40   221    -14
*end

*end BtoC</PRE
><P
>Note that to avoid needless complication, Survex regards each leg as
being either "surface" or "not surface" - if a leg spans the boundary you'll
have to call it one or the other.  It's good surveying practice to
deliberately put a station at the surface/underground interface
(typically the highest closed contour or drip line) so this generally
isn't an onerous restriction.</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1537"
>5.2. Specify the ordering and type of data</A
></H3
><P
>The *DATA command is used to specify the data style, and the
order in which the readings are given.</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1540"
>5.3. Deal with Plumbs or Legs Across Static Water</A
></H3
><P
>Plumbed legs should be given using 'UP' or 'DOWN' in place of the
clino reading and a dash (or a different specified 'OMIT' character)
in place of the compass reading.  This distinguishes
them from legs measured with a compass and clino.  Here's an example:</P
><PRE
CLASS="PROGRAMLISTING"
>1 2 21.54 - UP
3 2 7.36 017 +17
3 4 1.62 091 +08
5 4 10.38 - DOWN</PRE
><P
>U/D or +V/-V may be used instead of UP/DOWN; the check is not case
sensitive.</P
><P
>Legs surveyed across the surface of a static body of water where no
clino reading is taken (since the surface of the water can be assumed
to be flat) can be indicated by using LEVEL in place of a clino reading.
This prevents the clino correction being applied.  Here's an example:</P
><PRE
CLASS="PROGRAMLISTING"
>1 2 11.37 190 -12
3 2  7.36 017 LEVEL
3 4  1.62 091 LEVEL</PRE
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1547"
>5.4. Specify a BCRA grade</A
></H3
><P
>The *SD command can be used to specify the standard deviations of the
various measurements (tape, compass, clino, etc).  Examples files are
supplied which define BCRA Grade 3 and BCRA Grade 5 using a number of *sd
commands. You can use these by simply including them at the relevant point,
as follows:</P
><PRE
CLASS="PROGRAMLISTING"
>*begin somewhere
; This survey is only grade 3
*include grade3
2 1 26.60 222  17.5
2 3 10.85 014   7
; etc
*end somewhere</PRE
><P
>The default values for the standard deviations are those for
BCRA grade 5. Note that it is good practice to keep the *include
Grade3 within *Begin and *End commands otherwise it will apply
to following survey data, which may not be what you intended.</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1552"
>5.5. Specify different accuracy for a leg</A
></H3
><P
>For example, suppose the tape on the plumbed leg in this survey
is suspected of being less accurate than the rest of the survey because
the length was obtained by measuring the length of the rope used to rig
the pitch.  We can set a higher sd for this one measurement and use a
*begin/*end block to make sure this setting only applies to the one
leg:</P
><PRE
CLASS="PROGRAMLISTING"
>2 1 26.60 222  17.5
2 3 10.85 014   7
2 4  7.89 254 -11
*begin
; tape measurement was taken from the rope length
*sd tape 0.5 metres
4 5  34.50 - DOWN
*end
5 6  9.29 271 -28.5</PRE
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1556"
>5.6. Enter Repeated Readings</A
></H3
><P
>If your survey data contains multiple versions of each leg (for example,
pockettopo produces such data), then provided these are adjacent to one another
Survex 1.2.17 and later will automatically average these and treat them as a
single leg.</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1559"
>5.7. Enter Radiolocation Data</A
></H3
><P
>This is done by using the *SD command to specify the appropriate
errors for the radiolocation `survey leg' so that the loop closure
algorithm knows how to distribute errors if it forms part of a loop.</P
><P
>The best approach for a radiolocation where the underground station
is vertically below the surface station is to represent it as a
plumbed leg, giving suitable SDs for the length and plumb angle. The
horizontal positioning of this is generally quite accurate, but the
vertical positioning may be much less well known. E.g: we have a
radiolocation of about 50m depth +/- 20m and horizontal accuracy of
+/- 8m. Over 50m the +/-8m is equivalent to an angle of 9 degrees, so
that is the expected plumb error. 20m is the expected error in the
length. To get the equivalent SD we assume that 99.74% of readings will
be within 3 standard deviations of the error value. Thus we divide the
expected errors by 3 to get the SD we should specify:</P
><PRE
CLASS="PROGRAMLISTING"
>*begin
*sd length 6.67 metres
*sd plumb 3 degrees
surface underground 50 - down
*end</PRE
><P
>We wrap the radiolocation leg in a *begin/*end block to make
sure that the special *sd settings only apply to this one leg.</P
><P
>For more information on the expected errors from radiolocations
see Compass Points Issue 10, available online at
<A
HREF="http://www.chaos.org.uk/survex/cp/CP10/CPoint10.htm"
TARGET="_top"
>http://www.chaos.org.uk/survex/cp/CP10/CPoint10.htm</A
></P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1567"
>5.8. Enter Diving Data</A
></H3
><P
>Surveys made underwater using a diver's depth gauge can be
processed - use the *Data command to specify that the following data
is of this type.</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1570"
>5.9. Enter Theodolite data</A
></H3
><P
>Theodolite data with turned angles is not yet explicitly catered
for, so for now you will need to convert it into equivalent legs in
another style - normal or cylpolar are likely to be the best choices.</P
><P
>If there is no vertical info in your theodolite data then you should
use the cylpolar style and use *sd command to specify very low
accuracy (high SD) in the depth so that the points will move in the
vertical plane as required if the end points are fixed or the survey
is part of a loop.</P
></DIV
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN1574"
>6. General: How do I?</A
></H2
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1576"
>6.1. Create a new survey</A
></H3
><P
>You simply create a text file containing the relevant survey data,
using a text editor, and save it with a suitable name with a <TT
CLASS="FILENAME"
>.svx</TT
>
extension. The
easiest way is to look at some of the example data and use that
as a template. Nearly all surveys will need a bit of basic info
as well as the survey data itself: e.g. the date (*date), comments
about where, what cave, a name for the survey (using *begin and *end),
instrument error corrections etc. Here is a typical survey file:</P
><P
>All the lines starting with ';' are comments, which are ignored
by <SPAN
CLASS="APPLICATION"
>Survex</SPAN
>. You can also see the use of 'DOWN' for plumbs, and
*calibrate tape for dealing with a tape length error (in this case
the end of the tape had fallen off so measurements were made from the
20cm point).</P
><PRE
CLASS="PROGRAMLISTING"
>*equate chaos.1 triassic.pt3.8
*equate chaos.2 triassic.pt3.9

*begin chaos
*title "Bottomless Pit of Eternal Chaos to Redemption pitch"
*date 1996.07.11
*team "Nick Proctor" compass clino tape
*team "Anthony Day" notes pictures tape
*instrument compass "CUCC 2"
*instrument clino "CUCC 2"
;Calibration: Cairn-Rock 071 072 071,  -22 -22 -22
;       Rock-Cairn 252 251 252,  +21 +21 +21
;Calibration at 161d entrance from cairn nr entrance to
;prominent rock edge lower down. This is different from
;calibration used for thighs survey of 5 July 1996

*export 1 2

;Tape is 20cm too short
*calibrate tape +0.2

1 2 9.48 208 +08
2 3 9.30 179 -23
3 4 2.17 057 +09
5 4 10.13 263 +78
5 6 2.10 171 -73
7 6 7.93 291 +75
*begin
*calibrate tape 0
8 7 35.64 262 +86 ;true length measured for this leg
*end
8 9 24.90 - DOWN
10 9 8.61 031 -43
10 11 2.53 008 -34
11 12 2.70 286 -20
13 12 5.36 135 +23
14 13 1.52 119 -12
15 14 2.00 036 +13
16 15 2.10 103 +12
17 16 1.40 068 -07
17 18 1.53 285 -42
19 18 5.20 057 -36
19 20 2.41 161 -67
20 21 27.47 - DOWN
21 22 9.30 192 -29
*end chaos</PRE
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1583"
>6.2. Join surveys together</A
></H3
><P
>Once you have more than one survey you need to specify how they
link together. To do this use *export to make the stations to be
joined accessible in the enclosing survey, then *equate in the
enclosing survey to join them together.</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1586"
>6.3. Organise my surveys</A
></H3
><P
>This is actually a large subject. There are many ways you can
organise your data using <SPAN
CLASS="APPLICATION"
>Survex</SPAN
>. Take a look at the example dataset
for some ideas of ways to go about it.</P
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1590"
>6.3.1. Fixed Points (Control Points)</A
></H4
><P
>The *fix command is used to specify fixed points (also know as control
points).  See the description of this command in the "Cavern Commands"
section of this manual.</P
></DIV
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1593"
>6.3.2. More than one survey per trip</A
></H4
><P
>Suppose you have two separate bits of surveying which were done on the
same trip.  So the calibration details, etc. are the same for both.  But you
want to give a different survey name to the two sections.  This is easily
achieved like so:</P
><PRE
CLASS="PROGRAMLISTING"
>*begin
*calibrate compass 1.0
*calibrate clino 0.5
*begin altroute
; first survey
*end altroute
*begin faraway
; second survey
*end faraway
*end</PRE
></DIV
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1597"
>6.4. Add surface topography</A
></H3
><P
>Survex 1.2.18 added support for loading terrain data and rendering it as
a transparent surface.  Currently the main documentation for this is maintained
as a <A
HREF="https://trac.survex.com/wiki/TerrainData"
TARGET="_top"
>wiki page</A
>
as this allows us to update it between releases.</P
><P
>We recommend using this new code in preference, but previously the simplest
approach was to generate a <TT
CLASS="FILENAME"
>.svx</TT
> file with the surface mesh
in and display it with the survey data.</P
><P
>It is possible to generate
a mesh or contours overlaying your area by various means.  NASA have made
1 arc-second (approximately 30m) terrain data available for the USA for
some years, with only 3 arc-second data available for other countries.
However, starting in 2014 they're gradually making 1 arc-second data
available for more countries.</P
><P
>If you want a better resolution that this, reading heights from the
contours on a map is one approach.  It's laborious, but feasible for
a small area.</P
><P
>Details of several methods are given in the BCRA Cave Surveying
Group magazine Compass Points issue 11, available online at
<A
HREF="http://www.chaos.org.uk/survex/cp/CP11/CPoint11.htm#Art_5"
TARGET="_top"
>http://www.chaos.org.uk/survex/cp/CP11/CPoint11.htm#Art_5</A
></P
><P
>If you're using another program to generate a <TT
CLASS="FILENAME"
>.svx</TT
> file for the surface
mesh, it's best to use the NOSURVEY data style.
Simply fix all the grid intersections at the correct
coordinates and height, and put legs between them using the NOSURVEY style.
Here's a grid of 4 squares and 9 intersections:</P
><PRE
CLASS="PROGRAMLISTING"
>*fix 00 000 000 1070
*fix 01 000 100 1089
*fix 02 000 200 1093

*fix 10 100 000 1062
*fix 11 100 100 1080
*fix 12 100 200 1089

*fix 20 200 000 1050
*fix 21 200 100 1065
*fix 22 200 200 1077

*data nosurvey station

00
01
02

10
11
12

20
21
22

00
10
20

01
11
21

02
12
22</PRE
><P
>This is far simpler than trying to create fake tape/compass/clino legs of
the right length for each line in the mesh.  It's also very fast to process
with cavern.</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1611"
>6.5. Overlay a grid</A
></H3
><P
>Aven is able to display a grid, but this functionality isn't currently
available in printouts.
You can achieve a similar effect for now by creating a <TT
CLASS="FILENAME"
>.svx</TT
> file
where the survey legs form a grid.</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1615"
>6.6. Import data from other programs</A
></H3
><P
><SPAN
CLASS="APPLICATION"
>Survex</SPAN
> supports a number of features to help with importing
existing data. You can specify the ordering of items on a line using *Data
(see <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> Keywords above), and you can specify the characters used
to mean different things using *Set (see <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> Keywords above).</P
><P
>The Ignore and Ignoreall options to the *Data command are often
particularly useful, e.g. if you have a dataset with LRUD info or comments
on the ends of lines.</P
><DIV
CLASS="SECT3"
><HR><H4
CLASS="SECT3"
><A
NAME="AEN1622"
>6.6.1. Changing Meanings of Characters</A
></H4
><P
>e.g. if you have some data with station names containing the 
characters '?' and '+' (which are not permitted in a name by default)
then the command:</P
><PRE
CLASS="PROGRAMLISTING"
>*SET NAMES ?+</PRE
><P
>specifies that question marks and plus signs are permitted in station names.
A-Z, a-z, and 0-9 are always permitted. '_' and '-' are also permitted by
default, but aren't in this example.</P
><P
>If your data uses a comma ',' instead of a decimal point, then
you use</P
><PRE
CLASS="PROGRAMLISTING"
>*SET DECIMAL ,</PRE
><P
>to specify that ',' is now the decimal separator instead of '.'.</P
></DIV
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1630"
>6.7. Export data from <SPAN
CLASS="APPLICATION"
>Survex</SPAN
></A
></H3
><P
>See Rosetta Stal in the Related Tools section of the Survex web
site.  This is a utility written by Taco van Ieperen and Gary Petrie.
Note though that this only supports a subset of the svx format,
and only work on Microsoft Windows.  The Survex support is limited
and doesn't understand the more recently added commands.</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1634"
>6.8. See errors and warnings that have gone off the screen</A
></H3
><P
>When you run <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> it will process the specified survey data
files in order, reporting any warnings and errors.  If there are no
errors, the output files are written and various statistics about the
survey are displayed. If there are a lot of warnings or errors, they can
scroll off the screen and it's not always possible to scroll back to
read them.</P
><P
>The easiest way to see all the text is to use <B
CLASS="COMMAND"
>cavern
--log</B
> to redirect output to a <TT
CLASS="FILENAME"
>.log</TT
> file,
which you can then inspect with a text editor.</P
></DIV
><DIV
CLASS="SECT2"
><HR><H3
CLASS="SECT2"
><A
NAME="AEN1641"
>6.9. Create an Extended Elevation</A
></H3
><P
>Use the Extend program. This takes <TT
CLASS="FILENAME"
>.3d</TT
> files and
'flattens' them.  See 'Extend' for details.</P
></DIV
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN1645"
>7. Working with Larry Fish's Compass</A
></H2
><P
>Survex can read Compass survey data - both raw data (.DAT and .MAK
files) and processed survey data (.PLT and .PLF files).  You can even
use <B
CLASS="COMMAND"
>*include compassfile.dat</B
> in a <TT
CLASS="FILENAME"
>.svx</TT
> file and
it'll work!</P
><P
>One point to note (this tripped us up!): station names in DAT files are
case sensitive and so Survex reads DAT files with the equivalent of
<B
CLASS="COMMAND"
>*case preserve</B
>.  The default in SVX files is
<B
CLASS="COMMAND"
>*case lower</B
>.  So this won't work:

<PRE
CLASS="PROGRAMLISTING"
>*fix CE1 0 0 0
*include datfilewhichusesCE1.dat</PRE
>

Because the CE1 in the *fix is actually interpreted as ce1.  This is
what you have to do:

<PRE
CLASS="PROGRAMLISTING"
>*begin
*case preserve
*fix CE1 0 0 0
*include datfilewhichusesCE1.dat
*end</PRE
></P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN1655"
>8. Mailing List</A
></H2
><P
>The best way to contact the authors and other Survex users is the
Survex mailing list - for details visit:
<A
HREF="https://survex.com/maillist.html"
TARGET="_top"
>https://survex.com/maillist.html</A
></P
><P
>We'd be delighted to hear how you get on with <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> and
welcome comments and suggestions for improvements.</P
><P
>And we'd love you to contribute your skills to help make <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> even
better.  Point out areas of the documentation which could be made clearer, or
sections which are missing entirely.  Download test releases, try them out, and
let us know if you find problems or have suggestions for improvements.
If there's no translation to your language, you could provide one.
Or if you're a developer, <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>"Say it with code"</I
></SPAN
>.  There's
plenty to do, so feel free to join in.</P
></DIV
><DIV
CLASS="SECT1"
><HR><H2
CLASS="SECT1"
><A
NAME="AEN1664"
>9. Future Developments</A
></H2
><P
>Now that <SPAN
CLASS="APPLICATION"
>Survex</SPAN
> has reached version 1.0, we are continuing progress
towards version 2, in a series of steps, evolving out of 
Survex 1.0.  The GUI framework is being based on aven, with
the printer drivers and other utility programs being pulled in
and integrated into the menus.</P
><P
>Aven is built on <SPAN
CLASS="APPLICATION"
>wxWidgets</SPAN
>, which means that it can easily support
Unix, Microsoft Windows, and macOS.</P
><P
>More information on our plans is on the <A
HREF="https://survex.com/"
TARGET="_top"
>web site</A
>.</P
></DIV
></DIV
></BODY
></HTML
>
