Survex 1.4.4 Manual

Olly Betts

   <olly@survex.com>

Wookey

   <wookey@survex.com>

   Copyright © 1998-2018 Olly Betts

   This is the manual for Survex - an open-source software package
   for cave surveyors.
     __________________________________________________________

   Table of Contents
   1. Introduction

        1.1. About Survex
        1.2. About this Manual

              1.2.1. Terminology

   2. Getting Started

        2.1. Obtaining Survex
        2.2. Installing Survex

              2.2.1. Linux
              2.2.2. Other versions of UNIX
              2.2.3. macOS
              2.2.4. Microsoft Windows

        2.3. Configuration

              2.3.1. Selecting Your Preferred Language

        2.4. Using Survex

   3. Survex Programs

        3.1. Standard Options
        3.2. Short and Long Options
        3.3. Filenames on the Command Line
        3.4. Command Reference

              cavern -- process raw survey data
              aven -- sophisticated cave viewer for Unix and MS
                      Windows

              diffpos -- compare the contents of two .3d files
              extend -- produce an extended elevation from a .3d
                      file

              sorterr -- re-sort .err file by various criteria
              survexport -- convert a processed survey data file
                      (such as a Survex .3d file) to another
                      format.

   4. Survex data files

        4.1. Readings
        4.2. Survey Station Names

              4.2.1. Anonymous Stations

        4.3. Numeric fields
        4.4. Accuracy
        4.5. Cavern Commands

              4.5.1. ALIAS
              4.5.2. BEGIN
              4.5.3. CALIBRATE
              4.5.4. CASE
              4.5.5. COPYRIGHT
              4.5.6. CS
              4.5.7. DATA
              4.5.8. DATE
              4.5.9. DECLINATION
              4.5.10. DEFAULT
              4.5.11. END
              4.5.12. ENTRANCE
              4.5.13. EQUATE
              4.5.14. EXPORT
              4.5.15. FIX
              4.5.16. FLAGS
              4.5.17. INCLUDE
              4.5.18. INFER
              4.5.19. INSTRUMENT
              4.5.20. PREFIX
              4.5.21. REF
              4.5.22. REQUIRE
              4.5.23. SD
              4.5.24. SET
              4.5.25. SOLVE
              4.5.26. TEAM
              4.5.27. TITLE
              4.5.28. TRUNCATE
              4.5.29. UNITS

   5. Contents of .svx files: How do I?

        5.1. Specify surface survey data
        5.2. Specify the ordering and type of data
        5.3. Deal with Plumbs or Legs Across Static Water
        5.4. Specify a BCRA grade
        5.5. Specify different accuracy for a leg
        5.6. Enter Repeated Readings
        5.7. Enter Radiolocation Data
        5.8. Enter Diving Data
        5.9. Enter Theodolite data

   6. General: How do I?

        6.1. Create a new survey
        6.2. Join surveys together
        6.3. Organise my surveys

              6.3.1. Fixed Points (Control Points)
              6.3.2. More than one survey per trip

        6.4. Add surface topography
        6.5. Overlay a grid
        6.6. Import data from other programs

              6.6.1. Changing Meanings of Characters

        6.7. Export data from Survex
        6.8. See errors and warnings that have gone off the screen
        6.9. Create an Extended Elevation

   7. Working with Larry Fish's Compass
   8. Mailing List
   9. Future Developments

1. Introduction

   This section describes what Survex is, and outlines the scope
   of this manual.
     __________________________________________________________

1.1. About Survex

   Survex 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.

   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 Survex 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 Survex on a slow machine.

   Survex 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 CUCC and ARGE'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 Ogof Draenen survey, the
   Easegill resurvey project, the OFD survey, the OUCC Picos
   expeditions, and the Hong Meigui China expeditions.

   Survex 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.

   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.
     __________________________________________________________

1.2. About this Manual

   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.

   The master version of this manual is an SGML document written
   using the docbook DTD, and automatically converted to a number
   of other formats. If you are going to send us major 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 the Survex website.
     __________________________________________________________

1.2.1. Terminology

   Throughout this document we use British terminology for
   surveying.

   station
          a point in the cave that you survey from and/or to

   leg
          a line joining two stations

   survey
          a group of legs surveyed on the same trip
     __________________________________________________________

2. Getting Started

   This section covers how to obtain the software, and how to
   unpack and install it, and how to configure it.
     __________________________________________________________

2.1. Obtaining Survex

   The latest version is available from the Survex website:
   https://survex.com/. It is also freely redistributable, so you
   welcome to get a copy from someone else who has already
   downloaded it.

   If you want some sample data to experiment with, you can
   download some from the Survex website too:
   https://survex.com/software/sample.tar.gz
     __________________________________________________________

2.2. Installing Survex

   The details of installation depend greatly on what platform you
   are using, so there is a separate section below for each
   platform.
     __________________________________________________________

2.2.1. Linux

   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.

   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).
     __________________________________________________________

2.2.2. Other versions of UNIX

   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.
     __________________________________________________________

2.2.3. macOS

   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 macOS
   download page on the website for installation instructions.
     __________________________________________________________

2.2.4. Microsoft Windows

   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.

   The survey viewer that's part of Survex is called aven, and
   uses OpenGL for 3d rendering.

   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.

   The installer creates a Survex group in the Programs sub-menu
   of the Start menu containing the following items:

     * Aven
     * Documentation
     * Uninstall Survex

   Icons are installed for .svx, .3d, .err, and .pos files, and
   also for Compass Plot files (.plt and .plf) (which Survex can
   read). Double-clicking on a .svx file loads it for editing. To
   process it to produce a .3d file, right click and choose
   "Process" from the menu - this runs aven to process the .svx
   file and automatically load the resultant .3d file. All the
   Survex file types can be right clicked on to give a menu of
   possible actions.

   .svx

        Process
                Process file with aven to produce .3d file (and
                .err file)

   .3d

        Open
                Load file into Aven

        Print
                Print the file via Aven

        Extend
                Produce extended elevation

        Convert to DXF
                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.

        Convert for hand plotting
                This entry used to be provided to allow converting
                to a .pos 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.

   .err

        Open
                Load file into Notepad

        Sort by Error
                Sort .err file by the error in each traverse

        Sort by Horizontal Error
                Sort .err file by the horizontal error in each
                traverse

        Sort by Vertical Error
                Sort .err file by the vertical error in each
                traverse

        Sort by Percentage Error
                Sort .err file by the percentage error in each
                traverse

        Sort by Error per Leg
                Sort .err file by the error per leg in each
                traverse
     __________________________________________________________

2.3. Configuration

2.3.1. Selecting Your Preferred Language

   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 LANG
   environment variable on UNIX If no setting is found, or Survex
   hasn't been translated into the requested language, UK English
   is used.

   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.

   To do this, you set the SURVEXLANG environment variable. Here's
   a list of the codes currently supported:

   Code        Language
   en    International English
   en_US US English
   bg    Bulgarian
   ca    Catalan
   de    German
   de_CH Swiss German
   el    Greek
   es    Spanish
   fr    French
   hu    Hungarian
   id    Indonesian
   it    Italian
   pl    Polish
   pt    Portuguese
   pt_BR Brazillian Portuguese
   ro    Romanian
   ru    Russian
   sk    Slovak
   zh_CN Chinese (Simplified)

   Here are examples of how to set this environment variable to
   give messages in French (language code fr):

   Microsoft Windows
          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 SURVEXLANG, value fr. Click OK
          and the new value should be effective immediately.

   UNIX - csh/tcsh
          setenv SURVEXLANG fr

   UNIX - sh/bash
          SURVEXLANG=fr ; export SURVEXLANG

   If Survex 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.
     __________________________________________________________

2.4. Using Survex

   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.

   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.

   The command line programs that come with Survex are:

   extend
          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.

   diffpos
          Compares the positions of stations in two .3d, .pos, etc
          files.

   sorterr
          Sorts a .err file by a specified field.

   survexport
          Provides access to Aven's "Export" functionality from
          the command line, which can be useful in scripts.

   cavern
          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.

   dump3d
          Dumps out a list of the items in a .3d file - it's
          mainly useful for debugging.
     __________________________________________________________

3. Survex Programs
     __________________________________________________________

3.1. Standard Options

   All Survex programs respond to the following command line
   options:

   --help
          display option summary and exit

   --version
          output version information and exit
     __________________________________________________________

3.2. Short and Long Options

   Options have two forms: short (a dash followed by a single
   letter e.g. cavern -q) and long (two dashes followed by one or
   more words e.g. cavern --quiet). The long form is generally
   easier to remember, while the short form is quicker to type.
   Options are often available in both forms.

   Note

   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).
     __________________________________________________________

3.3. Filenames on the Command Line

   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: cavern "Spider Cave"

   A file specified on the command line of any of the Survex 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 cavern survey will look first for
   survey, then for survey.svx.
     __________________________________________________________

3.4. Command Reference

   Table of Contents
   cavern -- process raw survey data
   aven -- sophisticated cave viewer for Unix and MS Windows
   diffpos -- compare the contents of two .3d files
   extend -- produce an extended elevation from a .3d file
   sorterr -- re-sort .err file by various criteria
   survexport -- convert a processed survey data file (such as a
          Survex .3d file) to another format.

cavern

Name

   cavern -- process raw survey data

Synopsis

   cavern [options] {survex data file...}

Description

   Cavern is the Survex data processing engine.

   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.

Options

   -o, --output=OUTPUT
          Sets location for output files.

   -q, --quiet
          Only show a brief summary (--quiet --quiet or -qq will
          display warnings and errors only).

   -s, --no-auxiliary-files
          do not create .err file.

   -w, --warnings-are-errors
          turn warnings into errors.

   --log
          Send screen output to a .log file.

   -v, --3d-version
          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.

Output

   Cavern reads in text files containing the survey data .svx) and
   outputs two files, with the extensions .3d and .err. By default
   these files are put in the current directory, with the same
   base filename as the first .svx file read, but a different
   extension. You can change the directory and/or base filename
   using the --output command line option.

   E.g. if you process the data file entrance.svx with the command
   cavern entrance then the files entrance.3d and entrance.err
   will be created.

   Cavern also gives a range of statistics at the end of a
   successful run:

     * The highest and lowest stations and the height difference
       between them
     * The total length of the survey (before and after
       adjustment). This total excludes survey legs flagged as
       SURFACE, DUPLICATE, or SPLAY.
     * The number of stations and legs. Note that a *EQUATE is
       counted as a leg in this statistic.
     * The East-West and North-South ranges, and the North-most,
       South-most, East-most, and West-most stations.
     * 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.
     * How long the processing took and how much CPU time was
       used.

.3d - data describing the loop-closed centre line

   This file contains details of the stations and legs, and any
   flags associated with them.

.err - loop closure statistics (percentage errors, etc)

   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.

Error Messages

   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, Survex will list some of the stations that are not
   connected).

   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.

   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.

aven

Name

   aven -- sophisticated cave viewer for Unix and MS Windows

Synopsis

   aven [--survey=SURVEY] [--print] {.3d file}

Description

   Aven displays processed cave surveys in a window and allows you
   to manipulate the view.

   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!

Mouse Control

   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.

   If you hold down the right button then the cave is dragged when
   you move the mouse.

   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 Ctrl while dragging with the left mouse button,
   then the cave rotates and tilts at the same time instead.

   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.

   And if you have a scrollwheel, this can be used to zoom in/out.

   By default the mouse moves the cave, but if you press Ctrl-R,
   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.

Keyboard Control

   P and L 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.

   Comma ', and Slash / tilt up and down respectively. Tilt goes
   180 degrees from plan view to a view from directly below
   (upside down plan).

   Space 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 Z and X.

   Crosses and/or labels can be displayed at survey stations.
   Ctrl-X toggles crosses and Ctrl-N station names. Ctrl-L toggles
   the display of survey legs.

   Delete 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 - Shift helps here as it accelerates all
   movements:
Z, X : Faster/Slower Rotation
R: Reverse direction of rotation
Enter, Space: Start and stop auto-rotation
Ctrl-Cursor Left, Ctrl-Cursor Right: Rotate cave one step clockwise/anti
-clockwise (also: C, V)
Ctrl-Cursor Up , Ctrl-Cursor Down: Higher/Lower Viewpoint (also: ' , /)
] , [: Zoom in/Out
U, D: Set view to Up/Down
N, S, E, W: Set view to North, South, East, West
Delete: Reset to default scale, rotation rate, etc
P, L: Plan, Elevation
Cursor Left, Cursor Right: Pan survey Left/Right (on screen)
Cursor Up, Cursor Down: Pan survey Up/Down (on screen)
Ctrl-N: Toggle display of station names
Ctrl-X: Toggle display of crosses at stations
Ctrl-L: Toggle display of survey legs
Ctrl-F: Toggle display of surface legs
Ctrl-G: Toggle display of grid
Ctrl-B: Toggle display of bounding box
O: Toggle display of non-overlapping/all names
Ctrl-R: reverse sense of controls
Shift: accelerates all movement keys

   A little experimentation should give a better understanding of
   how this works.

   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).

Options

   -p, --print
          Print the specified file and exit.

   -s, --survey=SURVEY
          Only load the sub-survey 'SURVEY'.

diffpos

Name

   diffpos -- compare the contents of two .3d files

Synopsis

   diffpos {.3d file} {.3d file} [threshold]

Description

   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.

   For backward compatibility diffpos will also read the .pos
   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).

extend

Name

   extend -- produce an extended elevation from a .3d file

Synopsis

   extend [--survey=SURVEY] [--specfile=ESPEC_FILE]
   [--show-breaks] {INPUT_3D_FILE} [OUTPUT_3D_FILE]

Description

   Note

   The extend program can also work on Compass .plt (as can aven
   and any other Survex program which reads .3d files).

   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).

   If the output filename is not specified, extend bases the
   output filename on the input filename, but ending "_extend.3d".
   For example, extend deep_pit.3d produces an extended elevation
   called deep_pit_extend.3d.

   If you pass --show-breaks 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.

   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.

   The specfile is in a format similar to cavern's data format:
;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

   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.

sorterr

Name

   sorterr -- re-sort .err file by various criteria

Synopsis

   sorterr [options] {.err file} [how many]

Description

   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.

survexport

Name

   survexport -- convert a processed survey data file (such as a
   Survex .3d file) to another format.

Synopsis

   survexport [options] {.3d file} [output file]

Options

   -s, --survey=SURVEY only load the sub-survey with this prefix

   --scale=SCALE scale (50, 0.02, 1:50 and 2:100 all mean 1:50)

   --bearing=BEARING bearing (90, 90d, 100g all mean 90°)

   --tilt=TILT tilt (45, 45d, 50g, 100% all mean 45°)

   --plan plan view (equivalent to --tilt=-90)

   --elevation elevation view (equivalent to --tilt=0)

   --legs underground survey legs

   --surface-legs surface survey legs

   --splays splay legs

   --crosses station markers

   --station-names station labels

   --entrances entrances

   --fixes fixed points

   --exports exported stations

   --cross-sections cross-sections

   --walls walls

   --passages passages

   --origin-in-centre origin in centre

   --full-coordinates full coordinates

   --clamp-to-ground clamp to ground

   --defaults include items exported by default

   -g, --grid[=GRID] generate grid (default 100m)

   -t, --text-height=TEXT-HEIGHT station labels text height
   (default 0.6)

   -m, --marker-size=MARKER-SIZE station marker size (default 0.8)

   --csv produce CSV output

   --dxf produce DXF output

   --eps produce EPS output

   --gpx produce GPX output

   --hpgl produce HPGL output

   --json produce JSON output

   --kml produce KML output

   --plt produce Compass PLT output for Carto

   --skencil produce Skencil output

   --pos produce Survex POS output

   --svg produce SVG output

   --help display short help and exit

   --version output version information and exit

Description

   The input formats supports are all those supported by Survex's
   "img" library - Survex .3d, Survex .pos, Compass PLT and CMAP
   XYZ files.

   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.

POS Format

   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.

   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:
040.sv8
040.sv8a
040.sv8b
040.sv8c
040.sv9
040.sv10
040.sv11
40_entrance_tag
40b_entrance_tag

DXF Export

   DXF export separates Splays, Surface legs, Surface points,
   survey legs, and survey stations onto separate layers. Splays
   will export dotted, and surface legs dashed. This is not
   configurable.
     __________________________________________________________

4. Survex data files

   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.

   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.

   Survex places no restrictions on you in terms of the ordering
   of survey legs. You can enter or process data in any order and
   Survex 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.

   The usual arrangement is to have one file which lists all the
   others that are included (e.g., 161.svx). Then cavern 161 will
   process all your data. To just process a section use the
   filename for that section, e.g. cavern dtime will process the
   dreamtime file/section of Kaninchenhö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.

   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.
     __________________________________________________________

4.1. Readings

   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.
     __________________________________________________________

4.2. Survey Station Names

   Survex 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öhle (cave number 161) is referred to as:
   161.entrance.6

   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:
*begin Loser
*include 161
*include 2YrGest
*include 145
*end Loser

   The entrance series point mentioned above would now be referred
   to as: Loser.161.entrance.6

   You do not have to use this system at all, and can just give
   all stations unique identifiers if you like:

   1, 2, 3, 4, 5, ... 1381, 1382

   or

   AA06, AA07, P34, ZZ6, etc.

   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.
     __________________________________________________________

4.2.1. Anonymous Stations

   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:

   Single separator ('.' by default)
          An anonymous non-wall point at the end of an implicit
          splay.

   Double separator ('..' by default)
          An anonymous wall point at the end of an implicit splay.

   Triple separator ('...' by default)
          an anonymous point with no implicit flags on the leg
          (intended for cases like a disto leg along a continuing
          passage).

   You can map '-' to '..' (for compatibility with data from
   pocket topo) using the command:
*alias station - ..

   Support for anonymous stations and for '*alias station - ..'
   was added in Survex 1.2.7.
     __________________________________________________________

4.3. Numeric fields

   [<MINUS>|<PLUS>] <integer part> [ <DECIMAL> [ <decimal
   fraction> ] ]

   or [<MINUS>|<PLUS>] <DECIMAL> <dec fraction>

   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.

   All of these are valid examples: +47, 23, -22, +4.5, 1.3, -0.7,
   +.15, .4, -.05
     __________________________________________________________

4.4. Accuracy

   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.
     __________________________________________________________

4.5. Cavern Commands

   Commands in .svx files are introduced by an asterisk (by
   default - this can be changed using the set command).

   The commands are documented in a common format:

     * Command Name
     * Syntax
     * Example
     * Validity
     * Description
     * Caveats
     * See Also
     __________________________________________________________

4.5.1. ALIAS

   Syntax
          *alias station <alias> [<target>]

   Example

*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

   Description
          *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 -'.

          Aliases are scoped by *begin/*end blocks - when a *end
          is reached, the aliases in force at the corresponding
          begin are restored.

          *alias was added in Survex 1.2.7.

   See Also
          *begin, *end
     __________________________________________________________

4.5.2. BEGIN

   Syntax
          *begin [<survey>]

   Example

*begin littlebit
1 2 10.23 106 -02
2 3  1.56 092 +10
*end littlebit

; length of leg across shaft estimated
*begin
*sd tape 2 metres
9 10 6.   031 -07
*end

   Description
          *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.

   See Also
          *end, *prefix
     __________________________________________________________

4.5.3. CALIBRATE

   Syntax
          *calibrate <quantity list> <zero error> [<scale>]

          *calibrate <quantity list> <zero error> <units>
          [<scale>]

          *calibrate default

   Example

*calibrate tape +0.3

   Description
          *calibrate is used to specify instrument calibrations,
          via a zero error and an optional scale factor (which
          defaults to 1.0 if not specified). Without an explicit
          calibration the zero error is 0.0 and the scale factor
          is 1.0.

          <quantity list> is one or more of:

            Quantity     Aliases
          LENGTH       TAPE
          BEARING      COMPASS
          GRADIENT     CLINO
          BACKLENGTH   BACKTAPE
          BACKBEARING  BACKCOMPASS
          BACKGRADIENT BACKCLINO
          COUNT        COUNTER
          LEFT
          RIGHT
          UP           CEILING
          DOWN         FLOOR
          DEPTH
          DECLINATION
          EASTING      DX
          NORTHING     DY
          ALTITUDE     DZ
          DECLINATION

          The specified calibration is applied to each quantity in
          the list, which is handy if you use the same instrument
          to measure several things, for example:

*calibrate left right up down +0.1

          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:

*CALIBRATE tape +0.3

          If you tape was too long, starting at -20cm (it does
          happen!) then you can correct it with:

*CALIBRATE tape -0.2

          Note: ZeroError is irrelevant for Topofil counters and
          depth gauges since pairs of readings are subtracted.

          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:

          Value = ( Reading - ZeroError ) * Scale (Scale defaults
          to 1.0)

          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:

          Value = ( Reading * Scale ) - ZeroError (Scale defaults
          to 1.0)

          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.

          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.

   See Also
          *declination, *units
     __________________________________________________________

4.5.4. CASE

   Syntax
          *case preserve|toupper|tolower

   Example

*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

   Description
          *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).

   See Also
          *truncate
     __________________________________________________________

4.5.5. COPYRIGHT

   Syntax
          *copyright <date> <text>

   Example

*begin littlebit
*copyright 1983 CUCC
1 2 10.23 106 -02
2 3  1.56 092 +10
*end littlebit

   Validity
          valid at the start of a *begin/*end block.

   Description
          *copyright allows the copyright information to be stored
          in a way that can be automatically collated.

   See Also
          *begin
     __________________________________________________________

4.5.6. CS

   Syntax
          *cs [out] <coordinate system>

   Example

*cs UTM60S
*fix beehive 313800 5427953 20

; 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=-5200
000 +ellps=bessel +towgs84=577.326,90.129,463.919,5.137,1.474,5.297,2.42
32"

   Description
          *cs allows the coordinate systems used for fixed points
          and for processed survey data to be specified.

          The "input" coordinate system is set with *cs and you
          can change it between fixed points if you have some
          fixed points in different coordinate systems to others.

          The "output" coordinate system is set with *cs out and
          is what the survey data is processed in and the
          coordinate system used for resultant .3d file. The
          output coordinate system must be in metres with axis
          order (East, North, Up), so for example *cs out long-lat
          isn't valid.

          *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. Also *fix with standard deviations
          specified also didn't work until 1.2.21.

          The currently supported coordinate systems are:

          CUSTOM followed by a PROJ string (like in the example
          above).

          EPSG: followed by a positive integer code. EPSG codes
          cover most coordinate systems in use, and PROJ supports
          many of these. The website https://epsg.io/ is a useful
          resource for finding the EPSG code you want. For
          example, EPSG:4167 is NZGD2000. Supported since Survex
          1.2.15.

          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.

          EUR79Z30 for UTM zone 30, EUR79 datum. Supported since
          Survex 1.2.15.

          IJTSK for the modified version of the Czechoslovak
          S-JTSK system where the axes point East and North.
          Supported since Survex 1.2.15.

          IJTSK03 for a variant of IJTSK. Supported since Survex
          1.2.15.

          JTSK for the Czechoslovak S-JTSK system. Its axes point
          West and South, so it's not supported as an output
          coordinate system. Supported since Survex 1.2.16.

          JTSK03 for a variant of JTSK. Supported since Survex
          1.2.16.

          LONG-LAT for longitude/latitude. The WGS84 datum is
          assumed. NB *fix 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.

          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'.
          For example, OSGB:SD. Supported since Survex 1.2.15.

          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.

          UTM followed by a zone number (1-60), optionally
          followed by "N" or "S" (default is North). The WGS84
          datum is assumed.

          By default, Survex works in an unspecified coordinate
          system (and this was the only option before *cs was
          added). However, it's useful for the 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".

          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.

          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.

          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.

          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.

          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

   See Also
          *fix
     __________________________________________________________

4.5.7. DATA

   Syntax
          *data <style> <ordering>

          *data

   Example

*data normal from to compass tape clino

*data normal station ignoreall newline compass tape clino

   Description
          <style> =
          DEFAULT|NORMAL|DIVING|CARTESIAN|TOPOFIL|CYLPOLAR|NOSURVE
          Y|PASSAGE

          <ordering> = ordered list of instruments - which are
          valid depends on the style.

          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.

          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:

*data diving station newline fromdepth compass tape todepth

          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).

          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.:

*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

          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.

          In Survex 1.2.44 and later, you can use *data 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 *data gets quietly ignored).

        DEFAULT
                Select the default data style and ordering (NORMAL
                style, ordering: from to tape compass clino).

        NORMAL
                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.:

*data normal from to compass clino tape
1 2 172 -03 12.61

*data normal station newline direction tape compass clino
1
 F 12.61 172 -03
2

*data normal from to compass clino fromcount tocount
1 2 172 -03 11532 11873

*data normal station count newline direction compass clino
1 11532
 F 172 -03
2 11873

        DIVING
                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).

                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)).

                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.

                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)).

*data diving from to tape compass fromdepth todepth
1 2 14.7 250 -20.7 -22.4

*data diving station depth newline tape compass
1 -20.7
 14.7 250
2 -22.4

*data diving from to tape compass depthchange
1 2 14.7 250 -1.7

        CARTESIAN
                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.

*data cartesian from to northing easting altitude
1 2 16.1 20.4 8.7

*data cartesian station newline northing easting altitude
1
 16.1 20.4 8.7
2

                Note

   Cartesian data are relative to true North not magnetic North
   (i.e. they are unaffected by *calibrate declination).

        CYLPOLAR
                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.

*data cylpolar from to tape compass fromdepth todepth
1 2 9.45 311 -13.3 -19.0

*data cylpolar station depth newline tape compass
1 -13.3
 9.45 311
2 -19.0

*data cylpolar from to tape compass depthchange
1 2 9.45 311 -5.7

        NOSURVEY
                A NOSURVEY survey doesn't have any measurements -
                it merely indicates that there is line of sight
                between the pairs of stations.

*data nosurvey from to
1 7
5 7
9 11

*data nosurvey station
1
7
5

*data nosurvey station
9
11

        PASSAGE
                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.

                This means that you need to split off side
                passages into separate tubes, and hence separate
                sections of passage data, starting with a new
                *data command.

                Simple example of how to use this data style (note
                the use of ignoreall to allow a free-form text
                description to be given):

*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

                Each *data passage 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 *data passage line to start a new tube, but
                in Survex 1.2.31 and later, you can just use *data
                without any arguments.

                For example here the main passage is 1-2-3 and a
                side passage is 2-4:

*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

          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.

          LENGTH is a synonym for TAPE; BEARING for COMPASS;
          GRADIENT for CLINO; COUNT for COUNTER.

          The units of each quantity may be set with the UNITS
          command.
     __________________________________________________________

4.5.8. DATE

   Syntax
          *date
          <year>[.<month>[.<day>]][-<year>[.<month>[.<day>]]]

   Example

*date 2001

*date 2000.10

*date 1987.07.27

*date 1985.08.12-1985.08.13

   Validity
          valid at the start of a *begin/*end block.

   Description
          *date specifies the date that the survey was done. A
          range of dates can be specified (useful for overnight or
          multi-day surveying trips).

   See Also
          *begin, *instrument, *team
     __________________________________________________________

4.5.9. DECLINATION

   Syntax
          *declination auto <x> <y> <z>

          *declination <declination> <units>

   Description
          The *declination command is the modern way to specify
          magnetic declinations in Survex. Magnetic declination is
          the difference between Magnetic North and True North. It
          varies over time as the Earth's magnetic field moves,
          and also with location. Compass bearings are measured
          relative to Magnetic North - adding the magnetic
          declination gives bearings relative to True North.

          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.

          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.

          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. A revised version of
          the IGRF model is usually issued every 5 years, and
          calculates values using a model based on observations
          for years before it is issued, and on predictions for 5
          years after it is issued. Survex 1.2.43 updated to using
          version 13 in early 2020.

          The IGRF model takes a date and a location as inputs.
          Survex uses the specified date of the survey, and uses
          the "x y z" coordinates specified in the *declination
          auto command as the location in the current input
          coordinate system (as set by *cs). Most users can just
          specify a single representative location somewhere in
          the area of the cave. If you're not sure what to use
          pick some coordinates roughly in the middle of the
          bounding box of the cave - it doesn't need to be a fixed
          point or a known refindable location, though it can be
          if you prefer.

          For each *declination auto command cavern will (since
          Survex 1.4.2) report the range of calculated declination
          values and the dates at which the ends of the range were
          obtained, and also the grid convergence (which doesn't
          vary with time). This appears in the log - if you
          processed the data with aven you can view this by using
          "File->View Log". It looks like this:

/home/ol/1623.svx:20: info: Declination: -0.4° @ 1977-07-02 / 3.8° @ 201
8-07-21, grid convergence: -0.9°
 *declination auto 36670.37 83317.43 1903.97

          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
          representative locations for different areas of the cave
          system - the one currently in effect is used for each
          survey leg.

          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.

          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.

          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
          <declination> <units>. Then Grid North in the implicit
          coordinate system is True North.

   See Also
          *calibrate
     __________________________________________________________

4.5.10. DEFAULT

   Syntax
          *default <settings list>|all

   Description
          The valid settings are CALIBRATE, DATA, and UNITS.

          *default restores defaults for given settings. This
          command is deprecated - you should instead use:
          *calibrate default, *data default, *units default.

   See Also
          *calibrate, *data, *units
     __________________________________________________________

4.5.11. END

   Syntax
          *end [<survey>]

   Validity
          valid for closing a block started by *begin in the same
          file.

   Description
          Closes a block started by *begin.

   See Also
          *begin
     __________________________________________________________

4.5.12. ENTRANCE

   Syntax
          *entrance <station>

   Example

*entrance P163

   Description
          *entrance sets the entrance flag for a station. This
          information is used by aven to allow entrances to be
          highlighted.
     __________________________________________________________

4.5.13. EQUATE

   Syntax
          *equate <station> <station>...

   Example

*equate chosspot.1 triassic.27

   Description
          *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.

   See Also
          *infer equates
     __________________________________________________________

4.5.14. EXPORT

   Syntax
          *export <station>...

   Example

*export 1 6 17

   Validity
          valid at the start of a *begin/*end block.

   Description
          *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.

   See Also
          *begin, *infer exports
     __________________________________________________________

4.5.15. FIX

   Syntax
          *fix <station> [reference] [ <x> <y> <z> [ <x std err>
          <y std err> <z std err> [ <cov(x,y)> <cov(y,z)>
          <cov(z,x)> ] ] ]

   Example

*fix entrance.0 32768 86723 1760

*fix KT114_96 reference 36670.37 83317.43 1903.97

   Description
          *fix fixes the position of <station> 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.

          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).

          If you have covariances for the fix, you can also
          specify these - the order is cov(x,y) cov(y,z) cov(z,x).

          If you've specified a coordinate system (see *cs) 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 +vunits allows this - e.g.
          +vunits=us-ft 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).

          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.

          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.

   Note

   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.
     __________________________________________________________

4.5.16. FLAGS

   Syntax
          *flags <flags>

   Example

*flags duplicate not surface

   Description
          *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.

          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.

   See Also
          *begin
     __________________________________________________________

4.5.17. INCLUDE

   Syntax
          *include <filename>

   Example

*include mission

*include "the pits"

   Description
          *include processes <filename> as if it were inserted at
          this place in the current file. (i.e. The current
          settings are carried into <filename>, and any
          alterations to settings in <filename> 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.

          If <filename> contains spaces, it must be enclosed in
          quotes.

          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 .svx 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).

          The depth to which you can nest include files may be
          limited by the operating system you use. Usually the
          limit is fairly high (>30), but if you want to be able
          to process your dataset with Survex on any supported
          platform, it would be prudent not to go overboard with
          nested include files.
     __________________________________________________________

4.5.18. INFER

   Syntax
          *infer plumbs on|off

          *infer equates on|off

          *infer exports on|off

   Description
          "*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.

          "*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.

          "*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.
     __________________________________________________________

4.5.19. INSTRUMENT

   Syntax
          *instrument <instrument> <identifier>

   Example

*instrument compass "CUCC 2"
*instrument clino "CUCC 2"
*instrument tape "CUCC Fisco Ranger open reel"

   Validity
          valid at the start of a *begin/*end block.

   Description
          *instrument specifies the particular instruments used to
          perform a survey.

   See Also
          *begin, *date, *team
     __________________________________________________________

4.5.20. PREFIX

   Syntax
          *prefix <survey>

   Example

*prefix flapjack

   Description
          *prefix sets the current survey.

   Caveats
          *prefix is deprecated - you should use *begin and *end
          instead.

   See Also
          *begin, *end
     __________________________________________________________

4.5.21. REF

   Syntax
          *ref <string>

   Example

*ref "survey folder 2007#12"

   Validity
          valid at the start of a *begin/*end block.

   Description
          *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.

          *ref was added in Survex 1.2.23.

   See Also
          *begin, *date, *instrument, *team
     __________________________________________________________

4.5.22. REQUIRE

   Syntax
          *require <version>

   Example

*require 0.98

   Description
          *require checks that the version of cavern in use is at
          least <version> 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.
     __________________________________________________________

4.5.23. SD

   Syntax
          *sd <quantity list> <standard deviation>

   Example

*sd tape 0.15 metres

   Description
          *sd sets the standard deviation of a measurement.

          <quantity> is one of (each group gives alternative names
          for the same quantity):

          + 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
          + LEVEL
          + PLUMB
          + POSITION

          <standard deviation> must include units and thus is
          typically "0.05 metres", or "0.02 degrees". See *units
          below for full list of valid units.

          To utilise this command fully you need to understand
          what a standard deviation 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.

   See Also
          *units
     __________________________________________________________

4.5.24. SET

   Syntax
          *set <item> <character list>

   Example

*set blank x09x20
*set decimal ,

          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.

   Description
          *set sets the specified <item> to the character or
          characters given in <character list>. The example sets
          the decimal separator to be a comma.

          xAB means the character with hex value AB. Eg x20 is a
          space.

          The complete list of items that can be set, the defaults
          (in brackets), and the meaning of the item, is:

          + BLANK (x09x20,) Separates fields
          + COMMENT (;) Introduces comments
          + DECIMAL (.) Decimal point character
          + EOL (x0Ax0D) End of line character
          + KEYWORD (*) Introduces keywords
          + MINUS (-) Indicates negative number
          + NAMES (_-) Non-alphanumeric chars permitted in station
            names (letters and numbers are always permitted).
          + OMIT (-) Contents of field omitted (e.g. in plumbed
            legs)
          + PLUS (+) Indicates positive number
          + ROOT (\) Prefix in force at start of current file (use
            of ROOT is deprecated)
          + SEPARATOR (.) Level separator in prefix hierarchy

          The special characters may not be alphanumeric.
     __________________________________________________________

4.5.25. SOLVE

   Syntax
          *solve

   Example

*include 1997data
*solve
*include 1998data

   Description
          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.
     __________________________________________________________

4.5.26. TEAM

   Syntax
          *team <person> [<role>...]

   Example

*team "Nick Proctor" compass clino tape
*team "Anthony Day" notes pictures tape

   Validity
          valid at the start of a *begin/*end block.

   Description
          *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.

   See Also
          *begin, *date, *instrument
     __________________________________________________________

4.5.27. TITLE

   Syntax
          *title <title>

   Example

*title Dreamtime

*title "Mission Impossible"

   Description
          *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.
     __________________________________________________________

4.5.28. TRUNCATE

   Syntax
          *truncate <length>|off

   Description
          Station names may be of any length in Survex, 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
          Survex allows you to truncate names to whatever length
          you want (but by default truncation is off).

          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. Survex
          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).

   See Also
          *case
     __________________________________________________________

4.5.29. UNITS

   Syntax
          *units <quantity list> [<factor>] <unit>

          *units default

   Example

*units tape metres

*units compass backcompass clino backclino grads

*units dx dy dz 1000 metres ; data given as kilometres

*units left right up down feet

   Description
          <quantity> 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

          Changes current units of all the quantities listed to
          [<factor>] <unit>. Note that quantities can be expressed
          either as the instrument (e.g. COMPASS) or the
          measurement (e.g. BEARING).

          <factor> allows you to easy specify situations such as
          measuring distance with a diving line knotted every 10cm
          (*units distance 0.1 metres). If <factor> is omitted it
          defaults to 1.0. If specified, it must be non-zero.

          Valid units for listed quantities are:

          TAPE/LENGTH, BACKTAPE/BACKLENGTH, COUNTER/COUNT, DEPTH,
          DX/EASTING, DY/NORTHING, DZ/ALTITUDE in
          YARDS|FEET|METRIC|METRES|METERS (default: METRES)

          CLINO/GRADIENT, BACKCLINO/BACKGRADIENT in
          DEGS|DEGREES|GRADS|MINUTES|PERCENT|PERCENTAGE (default:
          DEGREES)

          COMPASS/BEARING, BACKCOMPASS/BACKBEARING, DECLINATION in
          DEGS|DEGREES|GRADS|MINUTES|QUADS|QUADRANTS (default:
          DEGREES)

          (360 degrees = 400 grads)

          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.

          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.

          For example, if your data uses

*units compass mils

          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):

*units compass grads

          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):

*units compass 0.05625 degrees

   See Also
          *calibrate
     __________________________________________________________

5. Contents of .svx files: How do I?

   Here is some example Survex data (a very small cave numbered
   1623/163):
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

   You can vary the data ordering. The default is:

   from-station to-station tape compass clino

   This data demonstrates a number of useful features of Survex:

   Legs can be measured either way round, which allows the use of
   techniques like "leap-frogging" (which is where legs alternate
   forwards and backwards).

   Also notice that there is a spur in the survey (2 to 3). You do
   not need to specify this specially.

   Survex 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. Survex can accept
   data in any order, and will check for connectedness once all
   the data has been read in.

   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.

   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.

   To accomplish this, Survex 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:
*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

   Survex will name the stations by attaching the current prefix.
   In this case, the stations will be named 163.1, 163.2, etc.

   We have a convention with the CUCC Austria data that the
   entrance survey station of a cave is named P<cave number>, P163
   in this case. We can accomplish this like so:
*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
     __________________________________________________________

5.1. Specify surface survey data

   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:
; 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

   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:
*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

   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.
     __________________________________________________________

5.2. Specify the ordering and type of data

   The *DATA command is used to specify the data style, and the
   order in which the readings are given.
     __________________________________________________________

5.3. Deal with Plumbs or Legs Across Static Water

   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:
1 2 21.54 - UP
3 2 7.36 017 +17
3 4 1.62 091 +08
5 4 10.38 - DOWN

   U/D or +V/-V may be used instead of UP/DOWN; the check is not
   case sensitive.

   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:
1 2 11.37 190 -12
3 2  7.36 017 LEVEL
3 4  1.62 091 LEVEL
     __________________________________________________________

5.4. Specify a BCRA grade

   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:
*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

   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.
     __________________________________________________________

5.5. Specify different accuracy for a leg

   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:
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
     __________________________________________________________

5.6. Enter Repeated Readings

   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.
     __________________________________________________________

5.7. Enter Radiolocation Data

   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.

   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:
*begin
*sd length 6.67 metres
*sd plumb 3 degrees
surface underground 50 - down
*end

   We wrap the radiolocation leg in a *begin/*end block to make
   sure that the special *sd settings only apply to this one leg.

   For more information on the expected errors from radiolocations
   see Compass Points Issue 10, available online at
   http://www.chaos.org.uk/survex/cp/CP10/CPoint10.htm
     __________________________________________________________

5.8. Enter Diving Data

   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.
     __________________________________________________________

5.9. Enter Theodolite data

   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.

   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.
     __________________________________________________________

6. General: How do I?
     __________________________________________________________

6.1. Create a new survey

   You simply create a text file containing the relevant survey
   data, using a text editor, and save it with a suitable name
   with a .svx 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:

   All the lines starting with ';' are comments, which are ignored
   by Survex. 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).
*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
     __________________________________________________________

6.2. Join surveys together

   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.
     __________________________________________________________

6.3. Organise my surveys

   This is actually a large subject. There are many ways you can
   organise your data using Survex. Take a look at the example
   dataset for some ideas of ways to go about it.
     __________________________________________________________

6.3.1. Fixed Points (Control Points)

   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.
     __________________________________________________________

6.3.2. More than one survey per trip

   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:
*begin
*calibrate compass 1.0
*calibrate clino 0.5
*begin altroute
; first survey
*end altroute
*begin faraway
; second survey
*end faraway
*end
     __________________________________________________________

6.4. Add surface topography

   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 wiki page as this
   allows us to update it between releases.

   We recommend using this new code in preference, but previously
   the simplest approach was to generate a .svx file with the
   surface mesh in and display it with the survey data.

   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.

   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.

   Details of several methods are given in the BCRA Cave Surveying
   Group magazine Compass Points issue 11, available online at
   http://www.chaos.org.uk/survex/cp/CP11/CPoint11.htm#Art_5

   If you're using another program to generate a .svx 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:
*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

   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.
     __________________________________________________________

6.5. Overlay a grid

   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 .svx file where the survey legs
   form a grid.
     __________________________________________________________

6.6. Import data from other programs

   Survex supports a number of features to help with importing
   existing data. You can specify the ordering of items on a line
   using *Data (see Survex Keywords above), and you can specify
   the characters used to mean different things using *Set (see
   Survex Keywords above).

   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.
     __________________________________________________________

6.6.1. Changing Meanings of Characters

   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:
*SET NAMES ?+

   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.

   If your data uses a comma ',' instead of a decimal point, then
   you use
*SET DECIMAL ,

   to specify that ',' is now the decimal separator instead of
   '.'.
     __________________________________________________________

6.7. Export data from Survex

   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.
     __________________________________________________________

6.8. See errors and warnings that have gone off the screen

   When you run Survex 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.

   The easiest way to see all the text is to use cavern --log to
   redirect output to a .log file, which you can then inspect with
   a text editor.
     __________________________________________________________

6.9. Create an Extended Elevation

   Use the Extend program. This takes .3d files and 'flattens'
   them. See 'Extend' for details.
     __________________________________________________________

7. Working with Larry Fish's Compass

   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 *include compassfile.dat in a .svx file and
   it'll work!

   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 *case preserve. The default in SVX files is *case
   lower. So this won't work:
*fix CE1 0 0 0
*include datfilewhichusesCE1.dat

   Because the CE1 in the *fix is actually interpreted as ce1.
   This is what you have to do:
*begin
*case preserve
*fix CE1 0 0 0
*include datfilewhichusesCE1.dat
*end
     __________________________________________________________

8. Mailing List

   The best way to contact the authors and other Survex users is
   the Survex mailing list - for details visit:
   https://survex.com/maillist.html

   We'd be delighted to hear how you get on with Survex and
   welcome comments and suggestions for improvements.

   And we'd love you to contribute your skills to help make Survex
   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, "Say it with code". There's plenty to do,
   so feel free to join in.
     __________________________________________________________

9. Future Developments

   Now that Survex 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.

   Aven is built on wxWidgets, which means that it can easily
   support Unix, Microsoft Windows, and macOS.

   More information on our plans is on the web site.
