Survex data files

*begin [<survey>]

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

*calibrate is used to specify instrument calibrations.

<quantity> is one of TAPE|COMPASS|CLINO|COUNTER|DEPTH|DECLINATION|X|Y|Z

Several quantities can be given in <quantity list>

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

You need to be careful about the sign of the ZeroError. The value of ZeroError is what the the instrument would read 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.

The magnetic deviation varies from year to year and it is often desirable to keep the compass zero error and the magnetic deviation separate. cavern calculates the true bearing as follows:

(magnetic bearing) = ((reading)-(compass zero err)) * (compass scale factor)

(true bearing) = ((bearing)-(declination zero err))

The scale factor for DECLINATION must be 1.0, otherwise an error is given.

The default is all quantities calibrated to scale factor 1.0, zero error 0.0

*units

*case preserve|toupper|tolower

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

*copyright <date> <text>

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

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

*begin

*data <style> <ordering>

<style> = DEFAULT|NORMAL|DIVING|CARTESIAN|TOPOFIL|CYLPOLAR|NOSURVEY

<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 interleavable readings have to be interleaved - for example:

*data diving station newline fromdepth compass tape todepth

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

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.

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

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

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

*begin, *instrument, *team

*default <settings list>|all

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.

*calibrate, *data, *units

*end [<survey>]

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

Closes a block started by *begin.

*begin

*entrance <station>

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

*equate <station> <station>...

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

*infer equates

*export <station>...

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

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

*begin, *infer exports

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

*fix fixes the position of <station> at the given coordinates. If the position is omitted it defaults 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).

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

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.

*flags <flags>

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

*begin

*include <filename>

*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 "/" (or other appropriate tricks on RISC OS). 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.

*infer plumbs on|off

*infer equates on|off

*infer exports on|off

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

*instrument <instrument> <identifier>

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

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

*begin, *date, *team

*prefix <survey>

*prefix sets the current survey.

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

*begin, *end

*require <version>

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

*sd <quantity list> <standard deviation>

*sd sets the standard deviation of a measurement.

<quantity> is one of TAPE|COMPASS|CLINO|COUNTER|DEPTH|DECLINATION|DX|DY|DZ

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

*units

*set <item> <character list>

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

*solve

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.

*team <person> <role>...

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

*team specifies the people involved in a survey and what role they filled during that trip.

*begin, *date, *instrument

*title <title>

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

*truncate <length>|off

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

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

*units default

<quantity> is one of TAPE|LENGTH|COMPASS|BEARING|CLINO|GRADIENT|COUNTER|DEPTH|DECLINATION|X|Y|Z

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, COUNTER, COUNT, DEPTH, dX, dY, dZ in YARDS|FEET|METRIC|METRES|METERS

CLINO, BACKCLINO, GRADIENT, BACKGRADIENT in DEG|DEGREES|GRADS|MILS|PERCENT|PERCENTAGE

COMPASS, BACKCOMPASS, BEARING, BACKBEARING, DECLINATION in DEG|DEGREES|GRADS|MILS|MINUTES

(360 degrees = 400 grads (also known as Mils))

Defaults are: Metres, Degrees, Degrees respectively.

*calibrate