General: How do I?

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
*calibrate tape 0
8 7 35.64 262 +86 ;true length measured for this leg
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

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.

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.

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.

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:

*calibrate compass 1.0
*calibrate clino 0.5
*begin altroute
; first survey
*end altroute
*begin faraway
; second survey
*end faraway

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

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







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.

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.

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.

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:


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


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

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.

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.

Create an Extended Elevation

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