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.
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.
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.
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:
An anonymous non-wall point at the end of an implicit splay.
An anonymous wall point at the end of an implicit splay.
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.
[<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
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.
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
*alias station <alias> [<target>]
*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 |
*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.
*begin, *end
*begin [<survey>]
*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 |
*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.
*end, *prefix
*calibrate <quantity list> <zero error> [<scale>]
*calibrate <quantity list> <zero error> <units> [<scale>]
*calibrate default
*calibrate tape +0.3 |
*calibrate is used to specify instrument calibrations, via a zero error and a scale factor. By default, the zero error is 0.0 and the scale factor 1.0 for all quantities.
<quantity> is one of TAPE|COMPASS|CLINO|COUNTER|DEPTH|DECLINATION|X|Y|Z
Several quantities can be given in <quantity list> - the specified calibration will be applied to each of them.
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.
*declination, *units
*case preserve|toupper|tolower
*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 |
*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).
*truncate
*copyright <date> <text>
*begin littlebit *copyright 1983 CUCC 1 2 10.23 106 -02 2 3 1.56 092 +10 *end littlebit |
valid at the start of a *begin/*end block.
*copyright allows the copyright information to be stored in a way that can be automatically collated.
*begin
*cs [out] <coordinate system>
*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=-5200000 +ellps=bessel +towgs84=577.326,90.129,463.919,5.137,1.474,5.297,2.4232" |
*cs allows the coordinate systems used for fixed points and for processed survey data to be specified.
*cs was added in Survex 1.2.14, but handling of fixed points specified with latitude and longitude didn't work until 1.2.21. And *fix with standard deviations specified also didn't work until 1.2.21.
The currently supported coordinate systems are:
CUSTOM followed by a PROJ4 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. 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.