Survex 1.4.6 Manual Olly Betts Wookey Copyright © 1998-2018 Olly Betts This is the manual for Survex - an open-source software package for cave surveyors. __________________________________________________________ Table of Contents 1. Introduction 1.1. About Survex 1.2. About this Manual 1.2.1. Terminology 2. Getting Started 2.1. Obtaining Survex 2.2. Installing Survex 2.2.1. Linux 2.2.2. Other versions of UNIX 2.2.3. macOS 2.2.4. Microsoft Windows 2.3. Configuration 2.3.1. Selecting Your Preferred Language 2.4. Using Survex 3. Survex Programs 3.1. Standard Options 3.2. Short and Long Options 3.3. Filenames on the Command Line 3.4. Command Reference cavern -- process raw survey data aven -- sophisticated cave viewer for Unix and MS Windows diffpos -- compare the contents of two .3d files extend -- produce an extended elevation from a .3d file sorterr -- re-sort .err file by various criteria survexport -- convert a processed survey data file (such as a Survex .3d file) to another format. 4. Survex data files 4.1. Readings 4.2. Survey Station Names 4.2.1. Anonymous Stations 4.3. Numeric fields 4.4. Accuracy 4.5. Cavern Commands 4.5.1. ALIAS 4.5.2. BEGIN 4.5.3. CALIBRATE 4.5.4. CASE 4.5.5. COPYRIGHT 4.5.6. CS 4.5.7. DATA 4.5.8. DATE 4.5.9. DECLINATION 4.5.10. DEFAULT 4.5.11. END 4.5.12. ENTRANCE 4.5.13. EQUATE 4.5.14. EXPORT 4.5.15. FIX 4.5.16. FLAGS 4.5.17. INCLUDE 4.5.18. INFER 4.5.19. INSTRUMENT 4.5.20. PREFIX 4.5.21. REF 4.5.22. REQUIRE 4.5.23. SD 4.5.24. SET 4.5.25. SOLVE 4.5.26. TEAM 4.5.27. TITLE 4.5.28. TRUNCATE 4.5.29. UNITS 5. Contents of .svx files: How do I? 5.1. Specify surface survey data 5.2. Specify the ordering and type of data 5.3. Deal with Plumbs or Legs Across Static Water 5.4. Specify a BCRA grade 5.5. Specify different accuracy for a leg 5.6. Enter Repeated Readings 5.7. Enter Radiolocation Data 5.8. Enter Diving Data 5.9. Enter Theodolite data 6. General: How do I? 6.1. Create a new survey 6.2. Join surveys together 6.3. Organise my surveys 6.3.1. Fixed Points (Control Points) 6.3.2. More than one survey per trip 6.4. Add surface topography 6.5. Overlay a grid 6.6. Import data from other programs 6.6.1. Changing Meanings of Characters 6.7. Export data from Survex 6.8. See errors and warnings that have gone off the screen 6.9. Create an Extended Elevation 7. Working with Larry Fish's Compass 7.1. Compass .DAT support 7.2. Compass .MAK support 7.3. Compass .CLP support 7.4. Compass .PLF/.PLT support 8. Mailing List 9. Future Developments 1. Introduction This section describes what Survex is, and outlines the scope of this manual. __________________________________________________________ 1.1. About Survex Survex is a multi-platform open-source cave surveying package. Versions 1.2 and later run on UNIX, Microsoft Windows, and macOS. We're investigating support for phones and tablets. 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 Survex 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 Survex on a slow machine. Survex 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 25,000 survey legs, and over 140km 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 OFD survey, the OUCC Picos expeditions, and the Hong Meigui China expeditions. Survex 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. See the "Mailing List" section of this manual for the best way to contact us. __________________________________________________________ 1.2. About 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. __________________________________________________________ 1.2.1. Terminology 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 __________________________________________________________ 2. Getting Started This section covers how to obtain the software, and how to unpack and install it, and how to configure it. __________________________________________________________ 2.1. Obtaining Survex The latest version is available from the Survex website: https://survex.com/. It is also freely redistributable, so you welcome to get a copy from someone else who has already downloaded it. If you want some sample data to experiment with, you can download some from the Survex website too: https://survex.com/software/sample.tar.gz __________________________________________________________ 2.2. Installing Survex The details of installation depend greatly on what platform you are using, so there is a separate section below for each platform. __________________________________________________________ 2.2.1. Linux 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). __________________________________________________________ 2.2.2. Other versions of UNIX 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. __________________________________________________________ 2.2.3. macOS The easiest way to install a recent release of Survex on macOS is by using the Homebrew package manager. If you don't already use Homebrew, you'll need to install it first. See the macOS download page on the website for installation instructions. __________________________________________________________ 2.2.4. Microsoft Windows This version comes packaged with an installation wizard. Just run the downloaded package and it will lead you through the installation process. If you want the file associations to be set up for all user, run the installer as administrator, or as a user with administrator rights. The survey viewer that's part of Survex is called aven, and uses OpenGL for 3d rendering. 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, .3d, .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 .3d file, right click and choose "Process" from the menu - this runs aven to process the .svx file and automatically load the resultant .3d file. All the Survex file types can be right clicked on to give a menu of possible actions. .svx Process Process file with aven to produce .3d file (and .err file) .3d Open Load file into Aven Print Print the file via Aven Extend Produce extended elevation Convert to DXF This entry used to be provided to allow converting to a DXF file (suitable for importing into many CAD packages) but this functionality is now available from inside Aven with the ability to control what is exported, and this entry was dropped in 1.2.35. Convert for hand plotting This entry used to be provided to allow converting to a .pos file listing all the stations and their coordinates, but this functionality is now available from inside Aven with the ability to control what is exported. and this entry was dropped in 1.2.35. .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 __________________________________________________________ 2.3. Configuration 2.3.1. Selecting Your Preferred Language 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 Survex 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: Code Language en International English en_US US English bg Bulgarian ca Catalan de German de_CH Swiss German el Greek es Spanish fr French hu Hungarian id Indonesian it Italian pl Polish pt Portuguese pt_BR Brazillian Portuguese ro Romanian ru Russian sk Slovak zh_CN Chinese (Simplified) Here are examples of how to set this environment variable to give messages in French (language code fr): Microsoft Windows For MS Windows proceed as follows (this description was written from MS Windows 2000, but it should be fairly similar in other versions): 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 Survex 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. __________________________________________________________ 2.4. Using Survex Most common tasks can now be accomplished through Aven - processing survey data, viewing the processed data, printing, exporting to other formats, and producing simple extended elevations. A few tasks still require you to use the command line. And some functionality is available both via aven and from the command line, which allows it to be scripted. The command line programs that come with Survex are: extend Produces extended elevations - this is probably the most useful of these command line tools. Since version 1.2.27 you can produce simple extended elevations from Aven using the "Extended Elevation" function. However the command line tool allows you to specify a spec file to control how the survey is extended, which you can't currently do via Aven. diffpos Compares the positions of stations in two .3d, .pos, etc files. sorterr Sorts a .err file by a specified field. survexport Provides access to Aven's "Export" functionality from the command line, which can be useful in scripts. cavern Processes survey data, but since version 1.2.3 you can process .svx files by simply opening them with Aven, so you no longer need to run cavern from the command line. The main reason to run cavern directly is for use in scripts. dump3d Dumps out a list of the items in a .3d file - it's mainly useful for debugging. __________________________________________________________ 3. Survex Programs __________________________________________________________ 3.1. Standard Options All Survex programs respond to the following command line options: --help display option summary and exit --version output version information and exit __________________________________________________________ 3.2. 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. 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). __________________________________________________________ 3.3. 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 cavern survey will look first for survey, then for survey.svx. __________________________________________________________ 3.4. Command Reference Table of Contents cavern -- process raw survey data aven -- sophisticated cave viewer for Unix and MS Windows diffpos -- compare the contents of two .3d files extend -- produce an extended elevation from a .3d file sorterr -- re-sort .err file by various criteria survexport -- convert a processed survey data file (such as a Survex .3d file) to another format. cavern Name cavern -- process raw survey data Synopsis cavern [options] {survex data file...} Description Cavern is the Survex data processing engine. 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. 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 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. Output Cavern reads in text files containing the survey data .svx) and outputs two files, with the extensions .3d and .err. By default these files are put in the current directory, with the same base filename as the first .svx file read, but a different extension. You can change the directory and/or base filename using the --output command line option. E.g. if you process the data file entrance.svx with the command cavern entrance then the files entrance.3d and entrance.err will be created. Cavern also gives a range of statistics at the end of a successful run: * The highest and lowest stations and the height difference between them * 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 East-West and North-South ranges, and the North-most, South-most, East-most, and West-most stations. * 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. .3d - data describing the loop-closed centre line This file contains details of the stations and legs, and any flags associated with them. .err - loop closure statistics (percentage errors, etc) This file contains statistics about each traverse in the survey which is part of a loop. It includes various statistics for each traverse, such as the percentage error per leg. You should study this information to determine if any parts of the survey are of lower quality or contain gross errors. Error Messages There are a number of error messages that you may get when processing data. Most of these are self explanatory, and will be caused by such problems as typing mistakes, or by your survey data not being attached to fixed points (in this situation, Survex will list some of the stations that are not connected). Along with the error message, the filename and line number of the offending line will be printed (or the filename for errors such as `file not found'). The format of the filename and line number is that used by gcc, so if your editor can parse errors from gcc, you should be able to set it to allow you to jump to the file and line of each error. Cavern will stop after more than 50 errors. This usually indicates something like the incorrect data order being specified. Deluging the user with error messages makes the actual problem less clear. aven Name aven -- sophisticated cave viewer for Unix and MS Windows Synopsis aven [--survey=SURVEY] [--print] {.3d file} Description Aven displays processed cave surveys in a window and allows you to manipulate the view. Note that there is no perspective in the view. This means that it is impossible to tell which way round a cave is rotating, or whether you are viewing something from behind, or in front. So if you think the direction of rotation in wrong, or changes as you watch, this is just your brain being confused, not a bug! Mouse Control The best way to move the cave is with the mouse. 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 cave is dragged when you move the mouse. If you hold down the left button, then the cave is rotated if you move left or right, and zoomed if you move up and down. If you hold down Ctrl while dragging with the left mouse button, then the cave rotates and tilts at the same time instead. 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 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. Comma ', and Slash / tilt up and down respectively. Tilt goes 180 degrees from plan view to a view from directly below (upside down plan). Space toggles automatic rotation about a vertical axis on and off. The speed of rotation for this, and animated transitions between plan and elevation, is 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. 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 instead of the mouse - Shift helps here as it accelerates all movements: Z, X : Faster/Slower Rotation R: Reverse direction of rotation Enter, Space: Start and stop auto-rotation Ctrl-Cursor Left, Ctrl-Cursor Right: Rotate cave one step clockwise/anti -clockwise (also: C, V) Ctrl-Cursor Up , Ctrl-Cursor Down: Higher/Lower Viewpoint (also: ' , /) ] , [: Zoom in/Out U, D: Set view to Up/Down N, S, E, W: Set view to North, South, East, West Delete: Reset to default scale, rotation rate, etc P, L: Plan, Elevation Cursor Left, Cursor Right: Pan survey Left/Right (on screen) Cursor Up, Cursor Down: Pan survey Up/Down (on screen) Ctrl-N: Toggle display of station names Ctrl-X: Toggle display of crosses at stations Ctrl-L: Toggle display of survey legs Ctrl-F: Toggle display of surface legs Ctrl-G: Toggle display of grid Ctrl-B: Toggle display of bounding box O: Toggle display of non-overlapping/all names Ctrl-R: reverse sense of controls Shift: accelerates all movement keys A little experimentation should give a better understanding of how this works. There is an auto-resizing scale bar along the bottom of the screen which varies in length as you zoom in or out. In the lower right corner is a compass pointer showing which way is North, and a clino pointer showing the angle of tilt. And in the upper right is a colour key showing the correspondence between colour and depth (by default - you can also colour by date or by error). Options -p, --print Print the specified file and exit. -s, --survey=SURVEY Only load the sub-survey 'SURVEY'. diffpos Name diffpos -- compare the contents of two .3d files Synopsis diffpos {.3d file} {.3d file} [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. The threshold distance is given in metres and defaults to 0.01m if not specified. For backward compatibility diffpos will also read the .pos files produced by earlier versions of cavern, by the (now removed) 3dtopos tool, by survexport, or by aven's export feature (requires 1.2.19 or later). extend Name extend -- produce an extended elevation from a .3d file Synopsis extend [--survey=SURVEY] [--specfile=ESPEC_FILE] [--show-breaks] {INPUT_3D_FILE} [OUTPUT_3D_FILE] Description Note The extend program can also work on Compass .plt (as can aven and any other Survex program which reads .3d files). If no specfile 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 ending "_extend.3d". For example, extend deep_pit.3d produces an extended elevation called deep_pit_extend.3d. If you pass --show-breaks 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 Name sorterr -- re-sort .err file by various criteria 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 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 entries after sorting are returned. survexport Name survexport -- convert a processed survey data file (such as a Survex .3d file) to another format. Synopsis survexport [options] {.3d file} [output file] 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] generate grid (default 100m) -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 --skencil produce Skencil output --pos produce Survex POS output --svg produce SVG output --help display short help and exit --version output version information and exit 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, Skencil, and SVG. Also survexport can produce Compass .plt files, which are primarily intended for importing into Carto, but can also be used with Compass itself. 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. 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 number part first, so you'd get: 040.sv8 040.sv8a 040.sv8b 040.sv8c 040.sv9 040.sv10 040.sv11 40_entrance_tag 40b_entrance_tag DXF Export 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 configurable. __________________________________________________________ 4. Survex data files 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. __________________________________________________________ 4.1. Readings 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. __________________________________________________________ 4.2. Survey Station Names 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. __________________________________________________________ 4.2.1. Anonymous Stations 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: Single separator ('.' by default) An anonymous non-wall point at the end of an implicit splay. Double separator ('..' by default) An anonymous wall point at the end of an implicit splay. Triple separator ('...' by default) 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. __________________________________________________________ 4.3. Numeric fields [|] [ [ ] ] or [|] 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 __________________________________________________________ 4.4. Accuracy 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. __________________________________________________________ 4.5. Cavern Commands 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 __________________________________________________________ 4.5.1. ALIAS Syntax *alias station [] 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 __________________________________________________________ 4.5.2. BEGIN Syntax *begin [] 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 __________________________________________________________ 4.5.3. CALIBRATE Syntax *calibrate [] *calibrate [] *calibrate default Example *calibrate tape +0.3 Description *calibrate is used to specify instrument calibrations, via a zero error and an optional scale factor (which defaults to 1.0 if not specified). Without an explicit calibration the zero error is 0.0 and the scale factor is 1.0. is one or more of: Quantity Aliases LENGTH TAPE BEARING COMPASS GRADIENT CLINO BACKLENGTH BACKTAPE BACKBEARING BACKCOMPASS BACKGRADIENT BACKCLINO COUNT COUNTER LEFT RIGHT UP CEILING DOWN FLOOR DEPTH DECLINATION EASTING DX NORTHING DY ALTITUDE DZ DECLINATION The specified calibration is applied to each quantity in the list, which is handy if you use the same instrument to measure several things, for example: *calibrate left right up down +0.1 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. See Also *declination, *units __________________________________________________________ 4.5.4. CASE 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). See Also *truncate __________________________________________________________ 4.5.5. COPYRIGHT Syntax *copyright 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 allows the copyright information to be stored in a way that can be automatically collated. See Also *begin __________________________________________________________ 4.5.6. CS Syntax *cs [out] 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=-5200 000 +ellps=bessel +towgs84=577.326,90.129,463.919,5.137,1.474,5.297,2.42 32" Description *cs allows the coordinate systems used for fixed points and for processed survey data to be specified. The "input" coordinate system is set with *cs and you can change it between fixed points if you have some fixed points in different coordinate systems to others. The "output" coordinate system is set with *cs out and is what the survey data is processed in and the coordinate system used for resultant .3d file. The output coordinate system must be in metres with axis order (East, North, Up), so for example *cs out long-lat isn't valid. *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. Also *fix with standard deviations specified also didn't work until 1.2.21. The currently supported coordinate systems are: CUSTOM followed by a PROJ 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. For example, EPSG:4167 is NZGD2000. 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. Its axes point West and South, so it's not supported 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. NB *fix expects the coordinates in the order x,y,z which means longitude (i.e. E/W), then latitude (i.e. N/S), then altitude. 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'. For example, OSGB:SD. 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 the 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 __________________________________________________________ 4.5.7. DATA Syntax *data