# Survex Programs

This section describes command-line use of Survex. Our aim is to make all functionality available without needing to use the command line (though we aren’t quite there currently - the main thing lacking is more complex use of `extend`). We also aim to give access from the command line to any functionality which it is useful to be able to use from scripts, so that users who do like to use the command line can take full advantage of it.

## Standard Options

All Survex programs support to the following command line options:

`--help`

  display option summary and exit

`--version`

  output version information and exit

Tools which take a processed survey data file to read also provide a way to specify the prefix of a sub-survey to restrict reading to:

`-s`, `--survey=`SURVEY

  Only load the sub-survey SURVEY.

## 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, but more obscure or potentially dangerous options may only have a long form.

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

## 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 the command above will look first for `Spider Cave`, then for `Spider Cave.svx`.

## Command Reference

### aven

#### SYNOPSIS

> `aven` [–survey=SURVEY] [–print] SURVEY_FILE

#### DESCRIPTION

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

If `SURVEY_FILE` is an unprocessed survey data format which `cavern` can process, then `aven` will run `cavern` on it, and if successful, display the processed data. If there are any warnings and errors, it will show a log window with the output with clickable links to open the affected file at the problematic line.

`SURVEY_FILE` can also be processed survey data - a Survex `.3d` file, a Compass `.plt` file or a CMAP `.sht` file. It can also be a Survex `.pos` file or a CMP `.una` or `.adj` file, but for these only stations are shown, not any legs (for `.pos` this is because the format only records station positions). (All Survex programs which read `.3d` files can also transparently handle these formats.)

##### On-Screen Indicators

There is an auto-resizing scale bar along the bottom of the screen which varies in length as you zoom in or out. You can left-button drag on this to zoom, and right click gives a menu to select units or hide the scale bar (to get it back go to the Control->Indicators menu from the menu bar).

In the lower right corner is a compass indicator showing which way is North. You can drag this to rotate the view; if while dragging you move the mouse outside the compass the view snaps to 45° positions: N/NE/E/SE/S/SW/W/NW. Right click gives menu to change the view to N/S/E/W, select units, or hide the compass (to get it back go to the Control->Indicators menu from the menu bar).

Just to the left of the compass is clino indicator showing the angle of tilt. You can drag this to tilt the view; if while dragging you move the mouse outside the clino the view snaps to 90° positions: plan/elevation/inverted plan. Right click gives menu to change the view to plan/elevation, select units, or hide the clino (to get it back go to the Control->Indicators menu from the menu bar).

In the upper right is a colour key showing the correspondence between colour and depth (by default - you can also colour by other criteria). Right click gives a menu to choose what to colour by, select units, or hide the colour key (to get it back go to the Control->Indicators menu from the menu bar).

##### Mouse Control

Using the mouse to move the cave will probably feel most natural. 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 view is panned when you move the mouse - it effectively feels like you are dragging the cave around.

If you hold down the left button, then the view is rotated as you move left or right, and zoomed as you move up and down. If you hold down `Ctrl` while dragging with the left mouse button, then moving up and down instead tilts the view. Tilt goes 180 degrees from plan view through elevation view to a view from directly below (upside down plan) - aven deliberately doesn’t allow going beyond horizontal into an inverted view.

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

As with mouse controls, a little experimentation should give a better understanding of how these work.

All keyboard shortcuts have a corresponding menu items which should show the keyboard shortcut - this provides a way within the application to see the keyboard shortcut for a particular action.

`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

`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. You can force skipping the animation by pressing the key again during it, so a double press will always take you there quickly.

`Space` toggles on and off automatic rotation about a vertical axis through the current centre point (which is moved by panning the view or by selecting a station or survey). `R` toggles the direction of auto-rotation. The speed of auto-rotation can be 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 and `Ctrl-F` of surface survey legs.

`Ctrl-G` toggles display of an auto-sizing grid.

`Ctrl-B` toggles display of a bounding box.

`O` toggles display of non-overlapping/all names. For a large survey turning on overlapping names will make update rather slow.

Holding down `Shift` accelerates all the following movement keys:

The cursor keys pan the survey view (like dragging with the right mouse button).

`Ctrl` plus cursor keys rotate and tilt (like the mouse left button with `Ctrl` held down). `C`/`V` do the same as `Ctrl` plus cursor left/right, while Apostrophe `'`, and Slash `/` do the same as `Ctrl` plus cursor up/down.

`[` and `]` zoom out and in respectively.

#### OPTIONS

`-p`, `--print`

  Load the specified file, open the print dialog to allow printing, then exit.

`-s`, `--survey=`SURVEY

  Only load the sub-survey SURVEY.

`--help`

  display short help and exit

`--version`

  output version information and exit

### cavern

#### SYNOPSIS

> `cavern` [OPTIONS] SURVEY_DATA_FILE…

#### DESCRIPTION

`cavern` is the Survex data processing engine.

`cavern` is a command line tool, but if you’re not a fan of working from the command line you can open unprocessed survey data files with `aven` and it will run `cavern` for you, and if successful, display the processed data. If there are any warnings and errors, `aven` will show a log window with the output with clickable links to open the affected file at the problematic line.

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.

Each SURVEY_DATA_FILE must be unprocessed survey data in a format which Survex supports, either native format (`.svx`) or Compass format (`.mak`, `.dat` or `.clp`), or Walls format (`.wpj` or `.srv`).

Support for Compass `.clp` was added in Survex 1.4.6; support for Walls was added in Survex 1.4.9.

#### 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=`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.

`--help`

  display short help and exit

`--version`

  output version information and exit

#### OUTPUT

If there were no errors during processing, cavern produces two output files, with the extensions `.3d` and `.err` (unless `--no-auxiliary-files` is specified in which case only the `.3d` file is produced).

These two files are always created with their respective extensions. By default they are created in the current directory, with the same base filename as the first SURVEY_DATA_FILE listed on the command line.

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

You can change the directory and/or base filename using the `--output` command line option. If you specify a directory then output files will go there instead of the current directory, but still use the basename of the first SURVEY_DATA_FILE. If you specify a filename which is not a directory (note that it doesn’t need to actually exist as a file) then the directory this file is in is used, and also the basename of the filename is used instead of the basename of the first SURVEY_DATA_FILE.

Details of the output files:

`.3d`

  This is a binary file format containing the adjusted survey data and associated meta data.

`.err`

  This is a text file which contains statistics about each traverse in the survey which is part of a loop. It includes various statistics for each traverse:

  Original length

    This is the measured length of the traverse (for a “normal” or “diving” survey this is the sum of the tape readings after applying calibration corrections).

  Number of legs

    The number of survey legs in the traverse

  Moved

    How much one end of the traverse moved by relative to the other after loop closure

  Moved per leg

    Moved / Number of legs

  Percentage error

    (Moved / Original length) as a percentage. This seems to be a popular measure of how good or bad a misclosure is, but it’s a problematic one because a longer traverse will naturally tend to have a lower percentage error so you can’t just compare values between traverses. We recommend using the E, H and V values instead.

  Error (E)

    This isn’t labelled in the .err file but is the value on a line by itself. In `aven` it’s the value used by Colour by Error. It is Moved divided by the standard deviation for the traverse based on the standard errors specified for the instruments. This tells us how plausible it is that the misclosure is just due to random errors. It is a number of standard deviations, so the 68-95-99.7 rule applies - e.g. approximately 99.7% of traverses should have a value of 3.0 or less (assuming the specified instrument standard deviations are realistic).

  Horizontal Error (H)

    This is like E but only considers the horizontal component. In `aven` it’s the value used by Colour by Horizontal Error. You can identify suspect traverses by looking at E and then compare H and V to see what sort of blunder might explain the misclosure. For example, if H is small but V is large it could be a clino reading or plumb with an incorrect sign, or a tape blunder on a plumbed leg; if H is large but V is small it could be a compass blunder, or a tape blunder of a nearly-flat leg.

  Vertical Error (V)

    This is like E but only considers the vertical component. In `aven` it’s the value used by Colour by Vertical Error.

  This information is now also present in the `.3d` file so you can view the survey coloured by these errors, but the `.err` file can still be useful as you can sort it using `sorterr` to get a ranked list of the sections of survey with the worst misclosure errors.

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

- The highest and lowest stations and the height difference between them

- The East-West and North-South ranges, and the Northernmost, Southernmost, Easternmost, and Westernmost stations.

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

If you successfully processed your data by loading it into `aven` then you can see this log output by using `File->Show Log` (also available as an icon in the toolbar).

##### Error Messages

There are many different error messages that you can get when processing data. Along with the error message, a location is reported. For an error like “file not found” this only reports the filename, but usually it will give the filename and line number of the offending line, and in many cases also an offset or span within the line.

The format of the location data follows that used by the GCC compiler so if your text editor can parse errors from GCC then you should be able to set it to allow you to jump to the file and line of each error.

One common cause of errors and warnings are typing mistakes. Another is your survey data not being all attached to fixed points (which is a warning since Survex 1.4.10, but was an error prior to this; in this situation, Survex will list at least one station in each piece of survey data which is not connected).

We try to make error and warning messages self-explanatory, but welcome feedback on cases where you get a message which seems unclear.

Generally you want to look at the first reported error first as there can be a cascade effect where one error triggers another. Cavern will stop after more than 50 errors. This usually indicates something like the incorrect data order being specified and deluging the user with error messages in such cases usually makes the actual problem less clear.

### diffpos

#### SYNOPSIS

> `diffpos` FILE1 FILE2 [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. THRESHOLD is a distance in metres and defaults to 0.01m if not specified.

Note that the input files can be any format the “img” library can read (and can be different formats), so it works with Survex `.3d` and `.pos` files, Compass `.plt` and `.plf` files, CMAP `.sht`, `.adj` and `.una` files.

#### OPTIONS

`--help`

  display short help and exit

`--version`

  output version information and exit

### dump3d

#### SYNOPSIS

> `dump3d` [–survey=SURVEY] [–rewind] [–show-dates] [–legs] INPUT_FILE

#### DESCRIPTION

Dump out the entries in a processed survey data file - useful for debugging, and also provides a textual format which is fairly easy to parse if you want to write a simple script to pull out information from such files.

Don’t be mislead by the “3d” in this tool’s name - it can be used to dump a file in any format the “img” library can read, so it works with Survex `.3d` and `.pos` files, Compass `.plt` and `.plf` files, CMAP `.sht`, `.adj` and `.una` files.

If you’re parsing the output in a script, you may want to use option `-legs` so you get a `LEG` item for each leg with from and to coordinates instead of each traverse being a `MOVE` item followed by a series of `LINE` items.

The `--show-dates` option uses `.` as the separator between date components by default (e.g. `2024.12.01`), but (since Survex 1.4.13) you can specify a different separator. If this separator is `.` then `-` is used between two dates which form a range, otherwise a space is used. For convenience, `-D` is provided as a short-cut for `--show-dates=-` which outputs dates in the ISO date format.

(The `--rewind` option is only provided to allow debugging and testing the `img_rewind()` function.)

#### OPTIONS

`-s`, `--survey=`SURVEY

  only load the sub-survey with this prefix

`-r`, `--rewind`

  rewind file and read it a second time

`-d`, `--show-dates[=SEPARATOR]`

  show survey date information (if present)

`-D`

  equivalent to –show-dates=-

`-l`, `--legs`

  convert MOVE and LINE into LEG

`--help`

  display short help and exit

`--version`

  output version information and exit

### extend

#### SYNOPSIS

> `extend` [–survey=SURVEY] [–specfile=ESPEC_FILE] [–show-breaks] INPUT_FILE [OUTPUT_3D_FILE]

#### DESCRIPTION

`INPUT_FILE` can be a Survex `.3d` file, a Compass `.plt` file or a CMAP `.sht` file (all Survex programs which read `.3d` files can also transparently handle these formats).

If no `--specfile` option (or short option `-p`) 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 replacing the extension with `_extend.3d`. For example, `extend deep_pit.3d` produces an extended elevation called `deep_pit_extend.3d`.

The `--survey=`SURVEY option (short option `-s`) restricts processing to the survey SURVEY including any sub-surveys.

If you pass `--show-breaks` (short option `-b`) 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

#### 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` (short option `-r`) 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 `HOW_MANY` entries after sorting are returned.

#### OPTIONS

`-h`, `--horizontal`

  sort by horizontal error factor

`-v`, `--vertical`

  sort by vertical error factor

`-p`, `--percentage`

  sort by percentage error

`-l`, `--per-leg`

  sort by error per leg

`-r`, `--replace`

  replace .err file with re-sorted version

`--help`

  display short help and exit

`--version`

  output version information and exit

### survexport

#### SYNOPSIS

> `survexport` [OPTIONS] INPUT_FILE [OUTPUT_FILE]

#### 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, and SVG.

Also survexport can produce Compass .plt files, which were primarily intended for importing into Carto; the principal author of Carto has sadly died and it seems Carto is no longer actively developed, but we’ve left this support in place in case it is useful - the generated files can be used with Compass itself for example, though they are rather crudely structured.

##### 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. In old versions of Survex it was produced by the (now removed) `3dtopos` tool. Since Survex 1.2.19 it can be generated by `survexport` or by `aven`’s export feature.

The header line is translated to the user’s language, but always starts with `(` and ends with `)`.

While not a requirement of the format, in `.pos` files created by Survex 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 prefix as a string, then the number part as above, then by the suffix as a string, 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 Format

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 currently configurable.

#### 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=`GRID

  generate grid with spacing `GRID` metres (default `100`)

`-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

`--pos`

  produce Survex POS output

`--svg`

  produce SVG output

`--help`

  display short help and exit

`--version`

  output version information and exit