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:

sv8
sv8a
sv8b
sv8c
sv9
sv10
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