Olly Betts wrote most of &survexsuite;.

&ollyemail;

Wookey is a small furry creature.

&wookeyemail;

1998-2015 Olly Betts This is the manual for &survexsuite; - an open-source software package for cave surveyors. This section describes what &survexsuite; is, and outlines the scope of this manual. &survexsuite; is a multi-platform open-source cave surveying package. Version 1.2 currently runs on &unix;, Microsoft Windows 95/NT and successors, and Mac OS X. We're investigating support for various palmtop devices. Version 1.0 has fewer features, but also runs on &msdos; and &riscos; machines. We are well aware that not everyone has access to super hardware - often surveying projects are run on little or no budget and any computers used are donated. We aim to ensure that &survexsuite; is feasible to use on low-spec machines. Obviously it won't be as responsive, but we intend it to be usable. Please help us to achieve this by giving us some feedback if you use &survexsuite; on a slow machine. &survexsuite; is capable of processing extremely complex caves very quickly and has a very effective, real-time cave viewer which allows you to rotate, zoom, and pan the cave using mouse or keyboard. We have tested it extensively using &cucc; and &arge;'s surveys of the caves under the Loser Plateau in Austria (over 22,000 survey legs, and over 120km of underground survey data). This can all be processed in around 10 seconds on a low-end netbook. Survex is also used by many other survey projects around the world, including the Ogof Draenen survey, the Easegill resurvey project, the , and the Hong Meigui China expeditions. &survexsuite; is still actively being worked on. Version 1.0 was complete in some sense, but development continues - initially in reshaping Survex into a more integrated GUI package. We encourage feedback from users on important features or problems, which will help to direct future development. Contact addresses are at the end of this manual. If there's a part of this manual you find hard to understand, please do let us know. We already know Survex well, so it can be hard for us to spot areas where the manual doesn't given enough information, or doesn't explain things clearly enough to follow when you don't know what's going on. It's helpful is you can suggest a better wording, but don't worry if you can't, just explain the problem as precisely as you can. The master version of this manual is an SGML document written using the docbook DTD, and automatically converted to a number of other formats. If you are going to send us major changes, it's much easier to include them if you work from this master. You can get it from the source archive (docs/manual.sgml) or from the Survex website. Throughout this document we use British terminology for surveying. station a point in the cave that you survey from and/or to leg a line joining two stations survey a group of legs surveyed on the same trip This section covers how to obtain the software, and how to unpack and install it, and how to configure it. The latest version is available from the &survexsuite; website: &survexwebsite;. If you do not have internet access or would prefer to get a copy by post, we are also happy to send out up-to-date copies on a floppy on receipt of a stamped, self-addressed envelope. See the end of this document for addresses. There's also a CD containing versions of &survexsuite; for every supported platform. You can download an image for this from the website, or we'll send you a copy on a CD-R if you send us money to cover the costs. The details of installation depend greatly on what platform you are using, so there is a separate section below for each platform. We supply pre-compiled versions for x86 &linux; machines in RPM format (suitable for Redhat, Mandrake, and some other distributions). Survex Debian packages are available from Debian mirror sites in the usual way. You'll need root access to install these prebuilt packages. If you don't have root access you will need to build from source (see the next section). For other &unix; versions you'll need to get the source code and compile it on your system. Unpack the sources and read the file called INSTALL in the top level for details about building from source. This version comes packaged with an installation wizard. Just run the downloaded package and it will lead you through the installation process. If installing on MS Windows NT, 2000, XP, or newer we recommend you run the installer as administrator (or as a user with administrator rights) so that the file associations can be set up for all users. The survey viewer that's part of &survexsuite; is called aven, and uses OpenGL for 3d rendering. OpenGL comes as standard as of Windows 98, and was included in the OSR2 update to Windows 95. It's also possible that you've installed OpenGL with another application already (especially a 3D game like Quake). If you can view a survey in aven, all is well. Otherwise you can download OpenGL drivers from Microsoft's website (or here's a direct link to the file you actually need). If you find that 3D rendering is sometimes very slow (e.g. one user reported very slow performance when running full screen, while running in a window was fine) then try installing the OpenGL driver supplied by the manufacturer of your graphics card rather than the driver Microsoft supply. The installer creates a Survex group in the Programs sub-menu of the Start menu containing the following items: Aven Documentation Uninstall Survex Icons are installed for &svx;, &x3d;, &err;, and &pos; files, and also for Compass Plot files (.plt and .plf) (which Survex can read). Double-clicking on a &svx; file loads it for editing. To process it to produce a &x3d; file, right click and choose "Process" from the menu. Double-clicking the resultant &x3d; file views it in aven. All the &survexsuite; file types can be right clicked on to give a menu of possible actions. &svx; Open Load file into SvxEdit Process Process file with cavern to produce &x3d; file (and &err; file) &x3d; Open Load file into Aven Print Send to the printer Extend Produce extended elevation Convert to DXF Convert to a DXF file (suitable for importing into many CAD packages) Convert for hand plotting Produce a &pos; file listing all the stations and their coordinates &err; Open Load file into Notepad Sort by Error Sort &err; file by the error in each traverse Sort by Horizontal Error Sort &err; file by the horizontal error in each traverse Sort by Vertical Error Sort &err; file by the vertical error in each traverse Sort by Percentage Error Sort &err; file by the percentage error in each traverse Sort by Error per Leg Sort &err; file by the error per leg in each traverse Survex has extensive internationalisation capabilities. The language used for messages from Survex and most of the library calls it uses can be changed. By default this is picked up from the language the operating system is set to use (from "Regional Settings" in Control Panel on Microsoft Windows, from the LANG environment variable on &unix; If no setting is found, or &survexsuite; hasn't been translated into the requested language, UK English is used. However you may want to override the language manually - for example if Survex isn't available in your native language you'll want to choose the supported language you understand best. To do this, you set the SURVEXLANG environment variable. Here's a list of the codes currently supported: Here are examples of how to set this environment variable to give messages in French (language code fr): Microsoft Windows For MS Windows 95 and 98 (and probably ME), you'll need to add a line containing SET SURVEXLANG=fr to your AUTOEXEC.BAT script. You need to reboot for the change to take effect. For MS Windows NT4, 2000, and XP, you should proceed as follows (this description is written from MS Windows 2000 - it should be similar on NT4 and XP): Open the Start Menu, navigate to the Settings sub-menu, and open Control Panel. Open System (picture of a computer) and click on the Advanced tab. Choose `Environmental Variables', and create a new one: name SURVEXLANG, value fr. Click OK and the new value should be effective immediately. &unix; - csh/tcsh setenv SURVEXLANG fr &unix; - sh/bash SURVEXLANG=fr ; export SURVEXLANG If &survexsuite; isn't available in your language, you could help out by providing a translation. The initial translation is likely to be about a day's work; after that translations for new or changed messages are occasionally required. Contact us for details if you're interested. Printing is now built into aven. The print.ini configuration file still exists, but is only useful if you want to configure the colours used if you have a colour printer. &man.print.ini; All &survexsuite; programs respond to the following command line options: --help display option summary and exit --version output version information and exit Options have two forms: short (a dash followed by a single letter e.g. 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;). Filenames with spaces can be processed (provided your operating system supports them - &unix; does, and so do recent 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 &survexsuite; 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 cavern survey will look first for survey, then for survey.svx. &man.cavern; &man.svxedit; &man.aven; &man.3dtopos; &man.cad3d; &man.diffpos; &man.extend; &man.sorterr; 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. &survexsuite; places no restrictions on you in terms of the ordering of survey legs. You can enter or process data in any order and &survexsuite; 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., 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. &survexsuite; 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. [<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 The commands are documented in a common format: Command Name Syntax Example Validity Description Caveats See Also Syntax *alias station <alias> [<target>] Example *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 Description *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. See Also *begin, *end Syntax *begin [<survey>] Example *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 Description *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. See Also *end, *prefix Syntax *calibrate <quantity list> <zero error> [<scale>] *calibrate default Example *calibrate tape +0.3 Description *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 See Also *units Syntax *case preserve|toupper|tolower Example *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 Description *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). Syntax *copyright <date> <text> Example *begin littlebit *copyright 1983 CUCC 1 2 10.23 106 -02 2 3 1.56 092 +10 *end littlebit Validity valid at the start of a *begin/*end block. Description *copyright allow the copyright information to be stored in a way that can be automatically collated. See Also *begin Syntax *cs [out] <coordinate system> Example *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" Description *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. 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 http://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. JTSK for the Czechoslovak S-JTSK system. The axes on this point West and South, so it's not support as an output coordinate system. Supported since Survex 1.2.16. JTSK03 for a variant of JTSK. Supported since Survex 1.2.16. LONG-LAT for longitude/latitude. The WGS84 datum is assumed. Supported since Survex 1.2.15. OSGB: followed by a two letter code for the UK Ordnance Survey National Grid. The first letter should be 'H', 'N', 'O', 'S' or 'T'; the second any letter except 'I'. Supported since Survex 1.2.15. S-MERC for the "Web Mercator" spherical mercator projection, used by online map sites like OpenStreetMap, Google maps, Bing maps, etc. Supported since Survex 1.2.15. UTM followed by a zone number (1-60), optionally followed by "N" or "S" (default is North). The WGS84 datum is assumed. By default, Survex works in an unspecified coordinate system (and this was the only option before *cs was added). However, it's useful for coordinate system which the processed survey data is in to be specified if you want to use the processed data in ways which required knowing the coordinate system (such as exporting a list of entrances for use in a GPS). You can now do this by using "*cs out". It is also useful to be able to take coordinates for fixed points in whatever coordinate system you receive them in and put them directly into Survex, rather than having to convert with an external tool. For example, you may have your GPS set to show coordinates in UTM with the WGS84 datum, even though you want the processed data to be in some local coordinate system. And someone else may provide GPS coordinates in yet another coordinate system. You just need to set the appropriate coordinate system with "*cs" before each group of "*fix" commands in a particular coordinate system. If you're going to make use of "*cs", then the coordinate system must be specified for everything, so a coordinate system must be in effect for all "*fix" commands, and you must set the output coordinate system before any points are fixed. Also, if "*cs" is in use, then you can't omit the coordinates in a "*fix" command, and a fixed point won't be invented if none exists. If you use "*cs out" more than once, the second and subsequent commands are silently ignored - this makes it possible to combine two datasets with different "*cs out" settings without having to modify either of them. Something to be aware of with "*cs" is that altitudes are currently assumed to be "height above the ellipsoid", whereas GPS units typically give you "height above sea level", or more accurately "height above a particular geoid". This is something we're looking at how best to address, but you shouldn't need to worry about it if your fixed points are in the same coordinate system as your output, or if they all use the same ellipsoid. For a more detailed discussion of this, please see: http://expo.survex.com/handbook/survey/coord.htm See Also *fix Syntax *data <style> <ordering> Example *data normal from to compass tape clino *data normal station ignoreall newline compass tape clino Description <style> = DEFAULT|NORMAL|DIVING|CARTESIAN|TOPOFIL|CYLPOLAR|NOSURVEY|PASSAGE <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 addition, interleaved data can have a DIRECTION reading, which can be "F" for a foresight or "B" for a backsight. 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. DEFAULT Select the default data style and ordering (NORMAL style, ordering: from to tape compass clino). NORMAL The usual tape/compass/clino centreline survey. For non-interleaved data the allowed readings are: FROM TO TAPE COMPASS CLINO BACKCOMPASS BACKCLINO; for interleaved data the allowed readings are: STATION DIRECTION TAPE COMPASS CLINO BACKCOMPASS BACKCLINO. The CLINO/BACKCLINO reading is not required - if it's not given, the vertical standard deviation is taken to be proportional to the tape measurement. Alternatively, individual clino readings can be given as OMIT (default "-") which allows for data where only some clino readings are missing. E.g.: *data normal from to compass clino tape 1 2 172 -03 12.61 *data normal station newline direction tape compass clino 1 F 12.61 172 -03 2 *data normal from to compass clino fromcount tocount 1 2 172 -03 11532 11873 *data normal station count newline direction compass clino 1 11532 F 172 -03 2 11873 DIVING An underwater survey where the vertical information is from a diver's depth gauge. This style can also be also used for an above-water survey where the altitude is measured with an altimeter. DEPTH is defined as the altitude (Z) so increases upwards by default. So for a diver's depth gauge, you'll need to use *CALIBRATE with a negative scale factor (e.g. *calibrate depth 0 -1). For non-interleaved data the allowed readings are: FROM TO TAPE COMPASS BACKCOMPASS FROMDEPTH TODEPTH DEPTHCHANGE (the vertical can be given as readings at each station, (FROMDEPTH/TODEPTH) or as a change along the leg (DEPTHCHANGE)). For interleaved data the allowed readings are: STATION DIRECTION TAPE COMPASS BACKCOMPASS DEPTH DEPTHCHANGE. (the vertical change can be given as a reading at the station (DEPTH) or as a change along the leg (DEPTHCHANGE)). *data diving from to tape compass fromdepth todepth 1 2 14.7 250 -20.7 -22.4 *data diving station depth newline tape compass 1 -20.7 14.7 250 2 -22.4 *data diving from to tape compass depthchange 1 2 14.7 250 -1.7 CARTESIAN Cartesian data style allows you to specify the (x,y,z) changes between stations. It's useful for digitising surveys where the original survey data has been lost and all that's available is a drawn up version. *data cartesian from to northing easting altitude 1 2 16.1 20.4 8.7 *data cartesian station newline northing easting altitude 1 16.1 20.4 8.7 2 Cartesian data are relative to true North not magnetic North (i.e. they are unaffected by *calibrate declination). CYLPOLAR A CYLPOLAR style survey is very similar to a diving survey, except that the tape is always measured horizontally rather than along the slope of the leg. *data cypolar from to tape compass fromdepth todepth 1 2 9.45 311 -13.3 -19.0 *data cylpolar station depth newline tape compass 1 -13.3 9.45 311 2 -19.0 *data cylpolar from to tape compass depthchange 1 2 9.45 311 -5.7 NOSURVEY A NOSURVEY survey doesn't have any measurements - it merely indicates that there is line of sight between the pairs of stations. *data nosurvey from to 1 7 5 7 9 11 *data nosurvey station 1 7 5 *data nosurvey station 9 11 PASSAGE This survey style defines a 3D "tube" modelling a passage in the cave. The tube uses the survey stations listed in the order listed. It's permitted to use survey stations which aren't directly linked by the centre-line survey. This can be useful - sometimes the centreline will step sideways or up/down to allow a better sight for the next leg and you can ignore the extra station. You can also define tubes along unsurveyed passages, akin to "nosurvey" legs in the centreline data. This means that you need to split off side passages into seperate tubes, and hence separate sections of passage data, starting with a new *data command. Simple example of how to use this data style (note the use of ignoreall to allow a free-form text description to be given): *data passage station left right up down ignoreall 1 0.1 2.3 8.0 1.4 Sticking out point on left wall 2 0.0 1.9 9.0 0.5 Point on left wall 3 1.0 0.7 9.0 0.8 Highest point of boulder 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. Syntax *date <year>[.<month>[.<day>]][-<year>[.<month>[.<day>]]] Example *date 2001 *date 2000.10 *date 1987.07.27 *date 1985.08.12-1985.08.13 Validity valid at the start of a *begin/*end block. Description *date specifies the date that the survey was done. A range of dates can be specified (useful for overnight or multi-day surveying trips). See Also *begin, *instrument, *team Syntax *default <settings list>|all Description 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. See Also *calibrate, *data, *units Syntax *end [<survey>] Validity valid for closing a block started by *begin in the same file. Description Closes a block started by *begin. See Also *begin Syntax *entrance <station> Example *entrance P163 Description *entrance sets the entrance flag for a station. This information is used by aven to allow entrances to be highlighted. Syntax *equate <station> <station>... Example *equate chosspot.1 triassic.27 Description *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. See Also *infer equates Syntax *export <station>... Example *export 1 6 17 Validity valid at the start of a *begin/*end block. Description *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. See Also *begin, *infer exports Syntax *fix <station> [reference] [ <x> <y> <z> [ <x std err> <y std err> <z std err> [ <cov(x,y)> <cov(y,z)> <cov(z,x)> ] ] ] Example *fix entrance.0 32768 86723 1760 *fix KT114_96 reference 36670.37 83317.43 1903.97 Description *fix fixes the position of <station> at the given coordinates. If you haven't specified the coordinate system with "*cs", you can omit the position and it will default 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. Syntax *flags <flags> Example *flags duplicate not surface Description *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. See Also *begin Syntax *include <filename> Example *include mission *include "the pits" Description *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 "/". 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 &survexsuite; on any supported platform, it would be prudent not to go overboard with nested include files. Syntax *infer plumbs on|off *infer equates on|off *infer exports on|off Description "*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. Syntax *instrument <instrument> <identifier> Example *instrument compass "CUCC 2" *instrument clino "CUCC 2" *instrument tape "CUCC Fisco Ranger open reel" Validity valid at the start of a *begin/*end block. Description *instrument specifies the particular instruments used to perform a survey. See Also *begin, *date, *team Syntax *prefix <survey> Example *prefix flapjack Description *prefix sets the current survey. Caveats *prefix is deprecated - you should use *begin and *end instead. See Also *begin, *end Syntax *require <version> Example *require 0.98 Description *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. Syntax *sd <quantity list> <standard deviation> Example *sd tape 0.15 metres Description *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. See Also *units Syntax *set <item> <character list> Example *set blank x09x20 *set decimal , Note that you need to eliminate comma from being a blank before setting it as a decimal - otherwise the comma in "*set decimal ," is parsed as a blank, and you set decimal to not have any characters representing it. Description *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. Syntax *solve Example *include 1997data *solve *include 1998data Description 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. Syntax *team <person> <role>... Example *team "Nick Proctor" compass clino tape *team "Anthony Day" notes pictures tape Validity valid at the start of a *begin/*end block. Description *team specifies the people involved in a survey and what role they filled during that trip. See Also *begin, *date, *instrument Syntax *title <title> Example *title Dreamtime *title "Mission Impossible" Description *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. Syntax *truncate <length>|off Description Station names may be of any length in &survexsuite;, 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 &survexsuite; 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, Smaps 4 had a limit of 8, Surveyor87/8 used 8. &survexsuite; 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). Syntax *units <quantity list> [<factor>] <unit> *units default Example *units tape metres *units compass backcompass clino backclino grads *units dx dy dz 1000 metres ; data given as kilometres *units left right up down feet Description <quantity> is one of the following (grouped entries are just alternative names for the same thing): TAPE/LENGTH, COMPASS/BEARING, BACKCOMPASS/BACKBEARING, CLINO/GRADIENT, BACKCLINO/BACKGRADIENT, COUNTER/COUNT, DEPTH, DECLINATION, DX/EASTING, DY/NORTHING, DZ/ALTITUDE, LEFT, RIGHT, UP/CEILING, DOWN/FLOOR 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/EASTING, DY/NORTHING, DZ/ALTITUDE in YARDS|FEET|METRIC|METRES|METERS (default: METRES) CLINO/GRADIENT, BACKCLINO/BACKGRADIENT in DEG|DEGREES|GRADS|MILS|PERCENT|PERCENTAGE (default: DEGREES) COMPASS/BEARING, BACKCOMPASS/BACKBEARING, DECLINATION in DEG|DEGREES|GRADS|MILS|MINUTES (default: DEGREES) (360 degrees = 400 grads (also known as Mils)) See Also *calibrate Here is some example &survexsuite; data (a very small cave numbered 1623/163): 2 1 26.60 222 17.5 2 3 10.85 014 7 2 4 7.89 254 -11 4 5 2.98 - DOWN 5 6 9.29 271 -28.5 You can vary the data ordering. The default is: from-station to-station tape compass clino This data demonstrates a number of useful features of &survexsuite;: Legs can be measured either way round, which allows the use of techniques like "leap-frogging" (which is where legs alternate forwards and backwards). Also notice that there is a spur in the survey (2 to 3). You do not need to specify this specially. &survexsuite; places few restrictions on station naming (see "Survey Station Names" in the previous section), so you can number the stations as they were in the original survey notes. Although not apparent from this example, there is no requirement for each leg to connect to an existing station. &survexsuite; can accept data in any order, and will check for connectedness once all the data has been read in. Each survey is also likely to have other information associated with it, such as instrument calibrations, etc. This has been omitted from this example to keep things simple. Most caves will take more than just one survey trip to map. Commonly the numbering in each survey will begin at 1, so we need to be able to tell apart stations with the same number in different surveys. To accomplish this, &survexsuite; has a very flexible system of hierarchical prefixes. All you need do is give each survey a unique name or number, and enter the data like so: *begin 163 *export 1 2 1 26.60 222 17.5 2 3 10.85 014 7 2 4 7.89 254 -11 4 5 2.98 - DOWN 5 6 9.29 271 -28.5 *end 163 &survexsuite; will name the stations by attaching the current prefix. In this case, the stations will be named 163.1, 163.2, etc. We have a convention with the CUCC Austria data that the entrance survey station of a cave is named P<cave number>, P163 in this case. We can accomplish this like so: *equate P163 163.1 *entrance P163 *begin 163 *export 1 2 1 26.60 222 17.5 2 3 10.85 014 7 2 4 7.89 254 -11 4 5 2.98 - DOWN 5 6 9.29 271 -28.5 *end 163 Say you have 2 underground surveys and 2 surface ones with 2 fixed reference points. You want to mark the surface surveys so that their length isn't included in length statistics, and so that Aven knows to display them differently. To do this you mark surface data with the "surface" flag - this is set with "*flags surface" like so: ; fixed reference points *fix fix_a 12345 56789 1234 *fix fix_b 23456 67890 1111 ; surface data (enclosed in *begin ... *end to stop the *flags command ; from "leaking" out) *begin *flags surface *include surface1 *include surface2 *end ; underground data *include cave1 *include cave2 You might also have a survey which starts on the surface and heads into a cave. This can be easily handled too - here's an example which goes in one entrance, through the cave, and out of another entrance: *begin BtoC *title "161b to 161c" *date 1990.08.06 ; trip 1990-161c-3 in 1990 logbook *begin *flags surface 02 01 3.09 249 -08.5 02 03 4.13 252.5 -26 *end 04 03 6.00 020 +37 04 05 3.07 329 -31 06 05 2.67 203 -40.5 06 07 2.20 014 +04 07 08 2.98 032 +04 08 09 2.73 063.5 +21 09 10 12.35 059 +15 *begin *flags surface 11 10 4.20 221.5 -11.5 11 12 5.05 215 +03.5 11 13 6.14 205 +12.5 13 14 15.40 221 -14 *end *end BtoC Note that to avoid needless complication, Survex regards each leg as being either "surface" or "not surface" - if a leg spans the boundary you'll have to call it one or the other. It's good surveying practice to deliberately put a station at the surface/underground interface (typically the highest closed contour or drip line) so this generally isn't an onerous restriction. The *DATA command is used to specify the data style, and the order in which the readings are given. Plumbed legs should be given using 'UP' or 'DOWN' in place of the clino reading and a dash (or a different specified 'OMIT' character) in place of the compass reading. This distinguishes them from legs measured with a compass and clino. Here's an example: 1 2 21.54 - UP 3 2 7.36 017 +17 3 4 1.62 091 +08 5 4 10.38 - DOWN U/D or +V/-V may be used instead of UP/DOWN; the check is not case sensitive. Legs surveyed across the surface of a static body of water where no clino reading is taken (since the surface of the water can be assumed to be flat) can be indicated by using LEVEL in place of a clino reading. This prevents the clino correction being applied. Here's an example: 1 2 11.37 190 -12 3 2 7.36 017 LEVEL 3 4 1.62 091 LEVEL The *SD command can be used to specify the standard deviations of the various measurements (tape, compass, clino, etc). Examples files are supplied which define BCRA Grade 3 and BCRA Grade 5 using a number of *sd commands. You can use these by simply including them at the relevant point, as follows: *begin somewhere ; This survey is only grade 3 *include grade3 2 1 26.60 222 17.5 2 3 10.85 014 7 ; etc *end somewhere The default values for the standard deviations are those for BCRA grade 5. Note that it is good practice to keep the *include Grade3 within *Begin and *End commands otherwise it will apply to following survey data, which may not be what you intended. For example, suppose the tape on the plumbed leg in this survey is suspected of being less accurate than the rest of the survey because the length was obtained by measuring the length of the rope used to rig the pitch. We can set a higher sd for this one measurement and use a *begin/*end block to make sure this setting only applies to the one leg: 2 1 26.60 222 17.5 2 3 10.85 014 7 2 4 7.89 254 -11 *begin ; tape measurement was taken from the rope length *sd tape 0.5 metres 4 5 34.50 - DOWN *end 5 6 9.29 271 -28.5 This is done by using the *SD command to specify the appropriate errors for the radiolocation `survey leg' so that the loop closure algorithm knows how to distribute errors if it forms part of a loop. The best approach for a radiolocation where the underground station is vertically below the surface station is to represent it as a plumbed leg, giving suitable SDs for the length and plumb angle. The horizontal positioning of this is generally quite accurate, but the vertical positioning may be much less well known. E.g: we have a radiolocation of about 50m depth +/- 20m and horizontal accuracy of +/- 8m. Over 50m the +/-8m is equivalent to an angle of 9 degrees, so that is the expected plumb error. 20m is the expected error in the length. To get the equivalent SD we assume that 99.74% of readings will be within 3 standard deviations of the error value. Thus we divide the expected errors by 3 to get the SD we should specify: *begin *sd length 6.67 metres *sd plumb 3 degrees surface underground 50 - down *end We wrap the radiolocation leg in a *begin/*end block to make sure that the special *sd settings only apply to this one leg. For more information on the expected errors from radiolocations see Compass Points Issue 10, available online at http://www.chaos.org.uk/survex/cp/CP10/CPoint10.htm Surveys made underwater using a diver's depth gauge can be processed - use the *Data command to specify that the following data is of this type. Theodolite data with turned angles is not yet explicitly catered for, so for now you will need to convert it into equivalent legs in another style - normal or cylpolar are likely to be the best choices. If there is no vertical info in your theodolite data then you should use the cylpolar style and use *sd command to specify very low accuracy (high SD) in the depth so that the points will move in the vertical plane as required if the end points are fixed or the survey is part of a loop. 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 &survexsuite;. 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 *begin *calibrate tape 0 8 7 35.64 262 +86 ;true length measured for this leg *end 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 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. This is actually a large subject. There are many ways you can organise your data using &survexsuite;. Take a look at the example dataset for some ideas of ways to go about it. 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. 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: *begin *calibrate compass 1.0 *calibrate clino 0.5 *begin altroute ; first survey *end altroute *begin faraway ; second survey *end faraway *end We intend to allow import of terrain data in DEM format, and also any other formats in common use. But at present the simplest approach is 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. In the USA, usable resolution data can be obtained for free. In other countries, it's harder to come by. 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 http://www.chaos.org.uk/survex/cp/CP11/CPoint11.htm#Art_5 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 00 01 02 10 11 12 20 21 22 00 10 20 01 11 21 02 12 22 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. SpeleoGen can also help with this process if you want final output in DXF form. See the 'Related Tools' section of the Survex website for download links. 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. &survexsuite; supports a number of features to help with importing existing data. You can specify the ordering of items on a line using *Data (see &survexsuite; Keywords above), and you can specify the characters used to mean different things using *Set (see &survexsuite; 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. 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: *SET NAMES ?+ 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 *SET DECIMAL , to specify that ',' is now the decimal separator instead of '.'. 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. When you run &survexsuite; 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. Use the Extend program. This takes &x3d; files and 'flattens' them. See 'Extend' for details. Survex can read Compass survey data - both raw data (.DAT and .MAK files) and processed survey data (.PLT and .PLF files). You can even use *include compassfile.dat in a &svx; file and it'll work! One point to note (this tripped us up!): station names in DAT files are case sensitive and so Survex reads DAT files with the equivalent of *case preserve. The default in SVX files is *case lower. So this won't work: *fix CE1 0 0 0 *include datfilewhichusesCE1.dat Because the CE1 in the *fix is actually interpreted as ce1. This is what you have to do: *begin *case preserve *fix CE1 0 0 0 *include datfilewhichusesCE1.dat *end The best way to contact the authors and other Survex users is the Survex mailing list - for details visit: http://survex.com/maillist.html We'd be delighted to hear how you get on with &survexsuite; and welcome comments and suggestions for improvements. And we'd love you to contribute your skills to help make &survexsuite; even better. Point out areas of the documentation which could be made clearer, or sections which are missing entirely. Download test releases, try them out, and let us know if you find problems or have suggestions for improvements. If there's no translation to your language, you could provide one. Or if your a developer, "Say it with code". There's plenty to do, so feel free to join in. Now that &survexsuite; has reached version 1.0, we are continuing progress towards version 2, in a series of steps, evolving out of Survex 1.0. The GUI framework is being based on aven, with the printer drivers and other utility programs being pulled in and integrated into the menus. Aven is built on &wxwidgets;, which means that it can easily support Unix, Microsoft Windows, and Mac OS X. More information on our plans is on the web site.