Survex 1.0.39 Manual

Olly Betts

<olly@survex.com>

Wookey

<wookey@survex.com>

$Id: manual.sgml,v 1.116 2005/05/24 01:04:40 olly Exp $

Copyright ? 1998-2002 Olly Betts

$Date: 2005/05/24 01:04:40 $

This is the manual for Survex - an open-source software package for cave
surveyors.

-------------------------------------------------------------------------------

Introduction

This section describes what Survex is, and outlines the scope of this manual.

-------------------------------------------------------------------------------

About Survex

Survex is a multi-platform open-source cave surveying package. currently runs
on UNIX, Microsoft Windows 95/NT and successors, MacOS X, DOS, and Acorn RISC
OS machines. We're investigating support for various palmtop devices.

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 11,500
survey legs, and over 66km of underground survey data). This can all be
processed in a few seconds on a low-end Pentium machine. 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 is 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.

-------------------------------------------------------------------------------

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.

-------------------------------------------------------------------------------

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

-------------------------------------------------------------------------------

Getting Started

This section covers how to obtain the software, and how to unpack and install
it, and how to configure it.

-------------------------------------------------------------------------------

Obtaining Survex

The latest version is available from the Survex website: http://www.survex.com/
. 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 Survex 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.

-------------------------------------------------------------------------------

Installing Survex

The details of installation depend greatly on what platform you are using, so
there is a separate section below for each platform.

-------------------------------------------------------------------------------

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

-------------------------------------------------------------------------------

Other versions of UNIX

For other UNIX versions you'll need to get the source code and compile it on
your system. Survex uses GNU automake and autoconf to streamline the compile
process, so all you need to do is unpack the sources, then simply type ./
configure followed by make to build the programs and then make install to
install them.

    Note: If you're building to install in your home directory (for example if
    you don't have root access on the machine you wish to install Survex on)
    configure and build with ./configure --prefix=/home/olly/survex then make
    to build and make install to install.

There's a GUI cave viewer called aven, which needs wxWindows to build, which in
turn needs Gtk+ (or Motif or just X11, but we only regularly test with the Gtk+
version).

-------------------------------------------------------------------------------

Microsoft Windows 95/NT and successors

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, or XP 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.

This version includes a GUI cave survey viewer called aven, and a Survex
printer driver (printwin) which uses the Windows printer system.

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 processes it to produce a .3d file. Double-clicking the .3d file views it
in aven. You can also right click on these files to bring up a menu of other
possible actions:

.svx

    Open

        Load file into SvxEdit

    Process

        Process file with cavern to produce .3d file (and .err file)

.3d

    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

-------------------------------------------------------------------------------

MS Windows 3.1 and DOS (Intel 80386 or newer CPU)

For MS Windows 3.1 we suggest using the DOS version. This version is compiled
with the free DJGPP C compiler (http://www.delorie.com/djgpp/) which uses DPMI
to access memory above DOS's 640k. Windows has DPMI services built in, as do
QEMM and Novell DOS 7. For those situations where DPMI services aren't
available, we include the free cwsdpmi.exe, which will be used automatically if
it's needed.

-------------------------------------------------------------------------------

DOS (Intel 80286 or earlier CPU)

We also supply a version suitable for use on pre-386 machines. You might wonder
why - the reason is that many surveying projects have little or no budget and
can acquire such machines for free. This version is suitable for caves up to
medium size - a few thousand stations - which typically equates to a few
kilometres of survey. A very loopy cave may need more memory.

This version is built with Borland C. A feature of this is that the best way to
force a program to terminate is with Ctrl-Break. Ctrl-C sometimes works, but is
less reliable.

-------------------------------------------------------------------------------

RISC OS

Survex for RISC OS comes in a zip archive. Installation is just a matter of
opening the archive with !SparkPlug, !SparkFS, or similar and dragging the
contents to where you want them installed. This version is known to work with
RISC OS 3.1 or newer. We are unable to test compatibility with earlier versions
of RISC OS.

-------------------------------------------------------------------------------

Configuration

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, from the value passed to COUNTRY in CONFIG.SYS on
MSDOS (but this doesn't distinguish between the different languages used in a
country in most cases), or from the configured Territory on RISC OS). 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            |
|-----+----------------------|
|ca   |Catalan               |
|-----+----------------------|
|de   |German                |
|-----+----------------------|
|de_CH|Swiss German          |
|-----+----------------------|
|de_DE|German German         |
|-----+----------------------|
|es   |Spanish               |
|-----+----------------------|
|fr   |French                |
|-----+----------------------|
|it   |Italian               |
|-----+----------------------|
|pt   |Portuguese            |
|-----+----------------------|
|pt_BR|Brazillian Portuguese |
|-----+----------------------|
|sk   |Slovak                |
+----------------------------+

Here are examples of how to set this environment variable to give messages in
French (language code fr):

DOS

    Put SET SURVEXLANG=fr in your AUTOEXEC.BAT script. You will need to restart
    DOS before it notices this setting - to set it for the current DOS session
    enter SET SURVEXLANG=fr at the MSDOS command prompt.

Microsoft Windows

    For MS Windows 95 and 98 (and probably ME), you'll need to add a line to
    AUTOEXEC.BAT as for MSDOS (see above). 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

RISC OS

    Hold down Shift and double-click on !Cavern, then hold down Shift again and
    double-click on !Boot. Edit the line which says Set SurvexLang en and
    change the value to the code for the language you want from the table
    above. Save the file, and double-click on !Boot. This sets the language for
    all the Survex programs.

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.

-------------------------------------------------------------------------------

Configuring the Printer Drivers

Table of Contents
print.ini -- survex printer settings

On Microsoft Windows, we recommend you print using printwin which uses the
built in drivers and so requires no separate configuration - if you can print
from other programs, you can print from Survex. The only thing you may want to
configure is the colours used if you have a colour printer.

The drivers used for other platforms may require a small amount of
configuration, which is described in the following section.

print.ini

Name

print.ini -- survex printer settings

Description

The print.ini file contains printer descriptions for the Survex printer
drivers.

File Format

The format of the print.ini file is similar to the .ini files used on Microsoft
Windows. The file is divided into sections, each section corresponding to a
separate printer description. A section starts with a section name in square
brackets, e.g.:

[generic_pcl]

followed by some options of the form <option>=<setting>, e.g.:

pixels_across_page=960

Most options are preceded by a comment (indicated by a semicolon ';') briefly
explaining the option.

Each section can contain a 'like' option. If present this contains the name of
another section (possibly in another print.ini file). Options not specified in
the current section will be taken from that section. This allows a printer
definition to be based on that for another similar model of printer.

Here is an example of how this works:

[dm_9pin_12inch]
like=dm_11inch_9pin
lines_down_page=108

This says that the definition 'dm_9pin_12inch' (for a 9pin dot matrix printer
using 12 inch paper), is just like the 11 inch definition for the same printer,
except that there are more lines per page.

Each printer driver reads a different section - printdm (the Dot Matrix driver)
reads:

[dm]

printhpgl (for HPGL plotters) reads:

[hpgl]

printpcl (for PCL printers) reads:

[pcl]

printps (for Postscript printers) reads:

[ps]

Several definitions are supplied for each printer driver, covering most
commonly encountered printers of each type.

printdm

The definitions provided for printdm are: dm_8pin_a4, dm_8pin_11inch,
dm_8pin_12inch, dm_9pin_a4, dm_9pin_11inch, dm_9pin_12inch, dm_24pin_a4,
dm_24pin_11inch, dm_24pin_12inch, dm_panasonic_24pin, dm_lx86_9pin_11inch, and
bj (for driving Canon BJ printers).

In the unlikely event that you need to change the printer control codes, here
is a quick overview of the format: printable characters are literal, except for
backslash. A backslash '\' indicates that the following character or characters
are to be interpreted as a control code, as follows: \ followed by an 'x'
followed by two hex digits represents the character with that hex value; a
double backslash means a literal backslash; \0 is nul (0); \t is tab (9); \n is
newline (10); \r is return (13); \[ is escape (27); \? is delete (127); \A - \Z
are (1) to (26).

This is all rather cryptic (printer codes inherently are) but the provided
set-ups will work with nearly all dot matrix printers, so you are unlikely to
need to fiddle with these runes.

printhpgl

The definitions provided for printhpgl are: hpgl_generic_a4landscape,
hpgl_generic_a1landscape, and hpgl_generic_a0landscape.

printpcl

The definitions provided for printpcl are: pcl_generic_a4 and pcl_modern_a4.

Note that if you are using a PCL printer the defaults are set not to use
advanced printer features for compatibility. If you want to try these
(equivalent to HP Laserjet III or later), then you should use the modern_pcl_a4
printer definition (see below for how to do this). This will enable horizontal
and vertical tabbing.

printps

There's only one definition provided at present: ps_generic_a4.

Customising Printer Settings

The only settings most users will want to customise are which printer
definition is used, and where to send the output. If you're using a Dot Matrix
Printer you will also need to set calibration details.

You shouldn't modify the master print.ini (located in /usr/share/survex on
Unix, or in the same directory as the Survex program files on other systems),
or your changes will be overwritten by upgrades. Instead create:

  * /etc/survex/print.ini (Unix - system-wide settings)

  * ~/.survex/print.ini (Unix - per user settings)

  * myprint.ini in the directory where Survex is installed (other platforms)

The drivers look for the section "[dm]", "[ps]", "[pcl]" or "[hpgl]" as
appropriate. The file you create should should contain something like this to
select a particular printer:

[pcl]
like=pcl_modern_a4

For printdm, it should also contain calibration measurements (calibrate your
printer by running printdm --calibrate):

[dm]
like=dm_24pin_a4
mm_across_page=202
mm_down_page=278

You can override other settings too, such as the output destination. This is
usually inherited from [base], and can be overridden in [base] (where it'll
apply to all printer drivers) or in a printer driver specific section (such as
[dm]). The output destination is set by an option of the form output_<platform>
=<device>, where device can be a device name (e.g. PRN, LPT1, LPT2 under DOS,
Printer: under RISC OS) or a filename:

[dm]
output_msdos=LPT1
like=dm_24pin_a4
mm_across_page=202
mm_down_page=278

Under UNIX output may be piped into another command like so:

[base]
; send output to printer 'oak'
output_unix=|lpr -Poak

Note you can also override the output setting using the --output command line
option.

If the output device isn't a device or a pipe command, it is taken as a
filename to write the printer data to. This can then be sent to a printer
later.

+-----------------------------------------------------------------------------+
|                                   Caution                                   |
|-----------------------------------------------------------------------------|
|If you're using DOS you need to be careful when sending output to a file -   |
|printdm, printpcl and printhpgl all produce binary files, which must then be |
|sent to the printer with COPY /B OUTPUT PRN where OUTPUT is the filename and |
|PRN the device name. Do not use COPY without the /B. If you do, the output   |
|may be corrupted. Sorry, this is a deficiency of DOS, and there is nothing we|
|can do about it.                                                             |
|                                                                             |
|If you send output straight to the printer, by putting PRN or LPT1 in the    |
|configuration file, then this problem should not occur.                      |
|                                                                             |
|printps produces text files as output, and so should be unaffected by this   |
|problem.                                                                     |
+-----------------------------------------------------------------------------+

printdm can also drive Canon bubblejets in native mode (which gives a higher
resolution than in Epson emulation mode). To use this, set "like=bj" in the "
[dm]" section - like so:

[dm]
like=bj

-------------------------------------------------------------------------------

Survex Programs

-------------------------------------------------------------------------------

Standard Options

All Survex programs respond to the following command line options:

--help

    display option summary and exit

--version

    output version information and exit

-------------------------------------------------------------------------------

Short and Long Options

Options have two forms: short (a dash followed by a single letter e.g. cavern
-p) and long (two dashes followed by one or more words e.g. cavern --percentage
). 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).

-------------------------------------------------------------------------------

Filenames on the Command Line

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

-------------------------------------------------------------------------------

Command Reference

Table of Contents
cavern -- process raw survey data
svxedit -- enter survey data
aven -- sophisticated cave viewer for Unix and MS Windows
caverot -- display .3d files on screen
xcaverot -- basic cave survey viewer for X
printdm -- print .3d files on a dot-matrix printer
printhpgl -- print .3d files on a plotter supporting Hewlett Packard's HPGL
printpcl -- print .3d files on a printer supporting Hewlett Packard's PCL
printps -- print .3d files on a PostScript printer or plotter
printwin -- print .3d files via the Microsoft Windows printer system
3dtopos -- produce a .pos file from a .3d file
cad3d -- convert a Survex .3d file into formats which can be read by CAD and
    drawing packages
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

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

-p, --percentage

    You can get cavern to display the percentage progress through the current
    file. As of Survex 0.90 this is disabled by default, but you can enable it
    if you want. Because the value given is for the current file, the values
    jump around for a multi-file survey project. Also note that displaying this
    information slows down processing a little.

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

-x, --chasm-format

    Output data in chasm's 3dx format for use with Phil Underwood's Chasm
    application.

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 (%age 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.

svxedit

Name

svxedit -- enter survey data

Synopsis

svxedit [survex data file...]

Description

SvxEdit allows you to enter and edit survey data.

aven

Name

aven -- sophisticated cave viewer for Unix and MS Windows

Synopsis

aven [options] {.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. 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 your mouse has a middle button then you can use it to
tilt the cave.

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. This seems 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).

Enter starts the cave spinning, and Space stops it. The speed of rotation for
this, and tilt, 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:

Z, X : Faster/Slower Rotation
R: Reverse direction of rotation
Enter, Space: Start and stop auto-rotation
C, V: Rotate cave one step clockwise/anti-clockwise
' , /: Higher/Lower Viewpoint
] , [: 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
O: Toggle display of non-overlapping/all names
Ctrl-R: reverse sense of controls

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.

caverot

Name

caverot -- display .3d files on screen

Synopsis

caverot [options] {.3d file...}

Description

Caverot displays .3d files on screen and allows you to manipulate the view to
understand the cave. Aven is a GUI caverot replacement which supports most of
caverot's mouse and keyboard controls but offers many additional features.

The DOS version of caverot for 286 and earlier machines works with a wide range
of graphics cards, and typically provides resolutions up to 640x480. Usually
two copies of the screen are used, and one is drawn on while the other is
displayed, to give smoother animation. Where the hardware does not allow this
you may notice a flickering or flashing during movement which since you can see
the screen being redrawn.

The standard DOS version can work with higher resolution screen modes, and
always draws into a buffer which is then copied to the screen. It tries to pick
a suitable screen mode, but if this fails you can bring up a dialog to choose a
screen mode from by using the --mode-picker command line option.

The RISC OS version will pick the highest resolution screen mode that it can
use two copies of the screen in, and that will work on the monitor in use. It
will also use three bank animation for an even more flicker-free display if
there is enough RAM.

CAVEROT reads in the data and then displays a help screen listing the control
keys/mouse buttons. Hitting a key gives the default view. This is a plan scaled
to fit on the screen, with no labels or station crosses. The view can be
panned, rotated, zoomed, tilted, or set spinning. This should be fast enough to
be almost instant with all but the largest surveys on the slowest of hardware.
Pressing H at any point will give you the help again. Escape exits the program.

Colours and multiple data files

Caverot can read in multiple data files and display them in separate colours.

The syntax is given above. E.g. caverot -c2,6 cave.3d surface.3d would display
cave.3d in colour 2 and surface.3d in colour 6. If you do not specify colours,
a predefined set is used.

Colour values range between 0 (black) and 255 (white) - experiment to find
which colours you like.

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. 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 your mouse has a middle button (and it is recognised
by your mouse driver) then you can use it to tilt the cave.

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. This seems 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).

Enter starts the cave spinning, and Space stops it. The speed of rotation for
this, and tilt, 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.

By default, labels and crosses are not redrawn during movement, to improve
responsiveness. With a small cave, or a fast computer, you can enable redraw of
everything during movement with Ctrl-A. Ctrl-O toggles whether all names are
displayed, or only non-overlapping ones.

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
Ctrl-Cursor Up , Ctrl-Cursor Down: Higher/Lower Viewpoint
] , [: 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-A: Toggle display of All/skeleton when moving
O: Toggle display of non-overlapping/all names
Ctrl-R: reverse sense of controls
Escape: quit program
Shift: accelerates all movement keys
H:  help screen giving these controls

A little experimentation should give a better understanding of how this works.

There is an auto-resizing scale bar on the left side of the screen. This varies
in length as you zoom in or out. The current length is given just below the
bearing. In the top left corner the current direction of view (for elevations),
or direction up the screen (for plans) is displayed. In the top right is a
compass pointer showing which way is North, and in the bottom right is a clino
pointer showing the angle of tilt.

xcaverot

Name

xcaverot -- basic cave survey viewer for X

Synopsis

xcaverot [options] {.3d file...}

Description

Xcaverot displays processed cave surveys in a window and allows you to
manipulate the view. Aven is a more sophisticated cave survey viewer which runs
under X and also on Microsoft Windows. We recommend you use Aven in preference.

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. 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 your mouse has a middle button then you can use it to
tilt the cave.

Keyboard Control

P and L select Plan and eLevation respectively.

Comma ,, and Slash / tilt up and down respectively. Tilt goes 180 degrees from
plan view to a view from directly below (upside down plan).

Enter starts the cave spinning, and Space stops it. The speed of rotation for
this, and tilt, 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.
Ctrl-O toggles whether all names are displayed, or only non-overlapping ones.

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:

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
Ctrl-Cursor Up , Ctrl-Cursor Down: Higher/Lower Viewpoint
] , [: 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
O: Toggle display of non-overlapping/all names
Q: quit program
Shift: accelerates all movement keys

A little experimentation should give a better understanding of how this works.

There is an auto-resizing scale bar on the left side of the screen. This varies
in length as you zoom in or out. The current length is given at the top. In the
top right is a compass pointer showing which way is North, and a clino pointer
showing the angle of tilt.

Environmental Variables

There are two environmental variables which may be used to configure xcaverot,
XCAVEROT_INDICATOR_RADIUS which sets the radius of the compass and clino
indicators, and XCAVEROT_FONTNAME which tells xcaverot what font to use.

printdm

Name

printdm -- print .3d files on a dot-matrix printer

Synopsis

printdm [options] {.3d file...}

Description

Printdm produces output suitable for most dot-matrix printers, and also for
Canon BJ inkjet printers. It supports 8, 9, and 24 pin Epson-compatible
dot-matrix printers. The 9 pin dump is about 10% faster than the 8 pin, but
some old printers will not support it. Printdm supports printers which support
Epson's ESC/P codes, and also those which support IBM's ProPrinter codes.

The configuration file print.ini, which sets various features for each printer.
See the 'Printer Settings' section for details. Even if your printer is not
standard you should be able get it to work by customising one of the supplied
definitions.

Options

The command line options are:

--survey=SURVEY

    Only load the sub-survey SURVEY

-e, --elevation

    select elevation

-p, --plan

    select plan view

-b, --bearing=BEARING

    set bearing

-t, --tilt=TILT

    set tilt

-s, --scale=SCALE

    set scale

-n, --station-names

    display station names

-c, --crosses

    display crosses at stations

-B, --no-border

    turn off the solid border around the edge of the survey. Printing to
    dot-matrix and inkjet printers can be significantly faster without this
    border as the printhead usually doesn't need to move all the way to the
    edge of the paper.

-C, --no-cutlines

    If a printout takes more than one page, alignment ticks are printed where
    the page corners need to be joined. By default dash lines are also drawn
    along internal edges to facilitate trimming down the page with scissors. If
    you have a guillotine, the alignment ticks are sufficient for trimming the
    page and this option allows you to turn off the dashed lines.

-l, --no-legs

    turn off display of survey legs

-S, --surface

    turn on display of surface survey legs. By default only underground survey
    legs are shown.

-k, --skip-blanks

    don't output blank pages With this option pages which are blank (apart from
    alignment marks and borders) will not be printed.

-o, --output=OUTPUT

    set output file

--calibrate

    print out calibration page

Interactive Use

When you run the printer driver you will be asked if you want a plan or
elevation (enter P, or E) - the default is plan. Then enter values for the
desired plot view. These values correspond to those displayed in the bottom
right hand corner when using Aven (or the top right when using caverot). You
would usually use Aven or caverot to pick the best view and then note the
angles before running the Printer Driver. This will be integrated soon.

For a plan enter bearing up the page, in degrees, 0 indicating North at the top
of the page (the default).

For an elevation enter the angle of view (i.e. the compass bearing from which
the scene is viewed), and angle of tilt, where 0 is horizontal, - is looking
down from above, and + is looking up from below, so -90 is the same as plan
view.

For an extended elevation, no viewing angles are needed.

You'll be told the scale needed to fit the plot on one page, and be asked what
scale you want to use. The you're told how many pages this will take (and the
arrangement of those pages (e.g. 6 pages (2x3)) and have the opportunity to
print, quit, or change the scale (so you can repeat this process until you have
a scale and number of pages you are happy with).

You can then print all the pages, a range of pages, or any arbitrary list of
pages and ranges (handy for when your printer mangles a page).

Printer Calibration

Dot Matrix printers do not print to an accurate size - you need to do to
calibrate your printer in order to get correctly-scaled plots. Print out a
calibration plot using printdm --calibrate and measure the width and height of
the page border.

Then create an entry in /etc/print.ini or .survex/print.ini in your home
directory (Unix) or myprint.ini in the installation directory (other platforms)
with entries mm_across_page and mm_down_page containing your values. The entry
should look something like this:

[dm]
like=dm_8pin_a4
mm_across_page=204.5
mm_down_page=278

Then run printdm --calibrate again, and check that the square is now 10cm wide
and high. This calibration is particularly necessary for older dot-matrix
printers as they vary significantly in scaling - even between two printers of
the same make and model.

printhpgl

Name

printhpgl -- print .3d files on a plotter supporting Hewlett Packard's HPGL

Synopsis

printhpgl [options] {.3d file...}

Description

Printhpgl produces output suitable for plotters that support Hewlett Packard's
HPGL.

The configuration file print.ini, which sets various features for each printer.
See the 'Printer Settings' section for details. Even if your printer is not
standard you should be able get it to work by customising one of the supplied
definitions.

Options

The command line options are:

--survey=SURVEY

    Only load the sub-survey SURVEY

-e, --elevation

    select elevation

-p, --plan

    select plan view

-b, --bearing=BEARING

    set bearing

-t, --tilt=TILT

    set tilt

-s, --scale=SCALE

    set scale

-n, --station-names

    display station names

-c, --crosses

    display crosses at stations

-B, --no-border

    turn off the solid border around the edge of the survey. Printing to
    dot-matrix and inkjet printers can be significantly faster without this
    border as the printhead usually doesn't need to move all the way to the
    edge of the paper.

-C, --no-cutlines

    If a printout takes more than one page, alignment ticks are printed where
    the page corners need to be joined. By default dash lines are also drawn
    along internal edges to facilitate trimming down the page with scissors. If
    you have a guillotine, the alignment ticks are sufficient for trimming the
    page and this option allows you to turn off the dashed lines.

-l, --no-legs

    turn off display of survey legs

-S, --surface

    turn on display of surface survey legs. By default only underground survey
    legs are shown.

-k, --skip-blanks

    don't output blank pages With this option pages which are blank (apart from
    alignment marks and borders) will not be printed.

-o, --output=OUTPUT

    set output file

Interactive Use

When you run the printer driver you will be asked if you want a plan or
elevation (enter P, or E) - the default is plan. Then enter values for the
desired plot view. These values correspond to those displayed in the bottom
right hand corner when using Aven (or the top right when using caverot). You
would usually use Aven or caverot to pick the best view and then note the
angles before running the Printer Driver. This will be integrated soon.

For a plan enter bearing up the page, in degrees, 0 indicating North at the top
of the page (the default).

For an elevation enter the angle of view (i.e. the compass bearing from which
the scene is viewed), and angle of tilt, where 0 is horizontal, - is looking
down from above, and + is looking up from below, so -90 is the same as plan
view.

For an extended elevation, no viewing angles are needed.

You'll be told the scale needed to fit the plot on one page, and be asked what
scale you want to use. The you're told how many pages this will take (and the
arrangement of those pages (e.g. 6 pages (2x3)) and have the opportunity to
print, quit, or change the scale (so you can repeat this process until you have
a scale and number of pages you are happy with).

You can then print all the pages, a range of pages, or any arbitrary list of
pages and ranges (handy for when your printer mangles a page).

printpcl

Name

printpcl -- print .3d files on a printer supporting Hewlett Packard's PCL

Synopsis

printpcl [options] {.3d file...}

Description

Printpcl produces output suitable for printers that support Hewlett Packard's
PCL (Printer Control Language), which include Deskjets and Laserjets (i.e. many
Inkjets and Laser printers).

The configuration file print.ini, which sets various features for each printer.
See the 'Printer Settings' section for details. Even if your printer is not
standard you should be able get it to work by customising one of the supplied
definitions.

Options

The command line options are:

--survey=SURVEY

    Only load the sub-survey SURVEY

-e, --elevation

    select elevation

-p, --plan

    select plan view

-b, --bearing=BEARING

    set bearing

-t, --tilt=TILT

    set tilt

-s, --scale=SCALE

    set scale

-n, --station-names

    display station names

-c, --crosses

    display crosses at stations

-B, --no-border

    turn off the solid border around the edge of the survey. Printing to
    dot-matrix and inkjet printers can be significantly faster without this
    border as the printhead usually doesn't need to move all the way to the
    edge of the paper.

-C, --no-cutlines

    If a printout takes more than one page, alignment ticks are printed where
    the page corners need to be joined. By default dash lines are also drawn
    along internal edges to facilitate trimming down the page with scissors. If
    you have a guillotine, the alignment ticks are sufficient for trimming the
    page and this option allows you to turn off the dashed lines.

-l, --no-legs

    turn off display of survey legs

-S, --surface

    turn on display of surface survey legs. By default only underground survey
    legs are shown.

-k, --skip-blanks

    don't output blank pages With this option pages which are blank (apart from
    alignment marks and borders) will not be printed.

-o, --output=OUTPUT

    set output file

Interactive Use

When you run the printer driver you will be asked if you want a plan or
elevation (enter P, or E) - the default is plan. Then enter values for the
desired plot view. These values correspond to those displayed in the bottom
right hand corner when using Aven (or the top right when using caverot). You
would usually use Aven or caverot to pick the best view and then note the
angles before running the Printer Driver. This will be integrated soon.

For a plan enter bearing up the page, in degrees, 0 indicating North at the top
of the page (the default).

For an elevation enter the angle of view (i.e. the compass bearing from which
the scene is viewed), and angle of tilt, where 0 is horizontal, - is looking
down from above, and + is looking up from below, so -90 is the same as plan
view.

For an extended elevation, no viewing angles are needed.

You'll be told the scale needed to fit the plot on one page, and be asked what
scale you want to use. The you're told how many pages this will take (and the
arrangement of those pages (e.g. 6 pages (2x3)) and have the opportunity to
print, quit, or change the scale (so you can repeat this process until you have
a scale and number of pages you are happy with).

You can then print all the pages, a range of pages, or any arbitrary list of
pages and ranges (handy for when your printer mangles a page).

printps

Name

printps -- print .3d files on a PostScript printer or plotter

Synopsis

printps [options] {.3d file...}

Description

Printps produces PostScript output for use with PostScript printers and
plotters. It's also the recommended way to print on Linux (the Linux printing
system accepts PostScript and converts it to the format your printer needs.

The configuration file print.ini, which sets various features for each printer.
See the 'Printer Settings' section for details. Even if your printer is not
standard you should be able get it to work by customising one of the supplied
definitions.

Options

The command line options are:

--survey=SURVEY

    Only load the sub-survey SURVEY

-e, --elevation

    select elevation

-p, --plan

    select plan view

-b, --bearing=BEARING

    set bearing

-t, --tilt=TILT

    set tilt

-s, --scale=SCALE

    set scale

-n, --station-names

    display station names

-c, --crosses

    display crosses at stations

-B, --no-border

    turn off the solid border around the edge of the survey. Printing to
    dot-matrix and inkjet printers can be significantly faster without this
    border as the printhead usually doesn't need to move all the way to the
    edge of the paper.

-C, --no-cutlines

    If a printout takes more than one page, alignment ticks are printed where
    the page corners need to be joined. By default dash lines are also drawn
    along internal edges to facilitate trimming down the page with scissors. If
    you have a guillotine, the alignment ticks are sufficient for trimming the
    page and this option allows you to turn off the dashed lines.

-l, --no-legs

    turn off display of survey legs

-S, --surface

    turn on display of surface survey legs. By default only underground survey
    legs are shown.

-k, --skip-blanks

    don't output blank pages With this option pages which are blank (apart from
    alignment marks and borders) will not be printed.

-o, --output=OUTPUT

    set output file

Interactive Use

When you run the printer driver you will be asked if you want a plan or
elevation (enter P, or E) - the default is plan. Then enter values for the
desired plot view. These values correspond to those displayed in the bottom
right hand corner when using Aven (or the top right when using caverot). You
would usually use Aven or caverot to pick the best view and then note the
angles before running the Printer Driver. This will be integrated soon.

For a plan enter bearing up the page, in degrees, 0 indicating North at the top
of the page (the default).

For an elevation enter the angle of view (i.e. the compass bearing from which
the scene is viewed), and angle of tilt, where 0 is horizontal, - is looking
down from above, and + is looking up from below, so -90 is the same as plan
view.

For an extended elevation, no viewing angles are needed.

You'll be told the scale needed to fit the plot on one page, and be asked what
scale you want to use. The you're told how many pages this will take (and the
arrangement of those pages (e.g. 6 pages (2x3)) and have the opportunity to
print, quit, or change the scale (so you can repeat this process until you have
a scale and number of pages you are happy with).

You can then print all the pages, a range of pages, or any arbitrary list of
pages and ranges (handy for when your printer mangles a page).

printwin

Name

printwin -- print .3d files via the Microsoft Windows printer system

Synopsis

printwin [options] {.3d file...}

Description

Printwin prints files via the MS Windows printer system. It is the recommended
way to print on MS Windows.

The configuration file print.ini, which sets various features for each printer.
See the 'Printer Settings' section for details. Even if your printer is not
standard you should be able get it to work by customising one of the supplied
definitions.

Options

The command line options are:

--survey=SURVEY

    Only load the sub-survey SURVEY

-e, --elevation

    select elevation

-p, --plan

    select plan view

-b, --bearing=BEARING

    set bearing

-t, --tilt=TILT

    set tilt

-s, --scale=SCALE

    set scale

-n, --station-names

    display station names

-c, --crosses

    display crosses at stations

-B, --no-border

    turn off the solid border around the edge of the survey. Printing to
    dot-matrix and inkjet printers can be significantly faster without this
    border as the printhead usually doesn't need to move all the way to the
    edge of the paper.

-C, --no-cutlines

    If a printout takes more than one page, alignment ticks are printed where
    the page corners need to be joined. By default dash lines are also drawn
    along internal edges to facilitate trimming down the page with scissors. If
    you have a guillotine, the alignment ticks are sufficient for trimming the
    page and this option allows you to turn off the dashed lines.

-l, --no-legs

    turn off display of survey legs

-S, --surface

    turn on display of surface survey legs. By default only underground survey
    legs are shown.

-k, --skip-blanks

    don't output blank pages With this option pages which are blank (apart from
    alignment marks and borders) will not be printed.

Interactive Use

When you run the printer driver you will be asked if you want a plan or
elevation (enter P, or E) - the default is plan. Then enter values for the
desired plot view. These values correspond to those displayed in the bottom
right hand corner when using Aven (or the top right when using caverot). You
would usually use Aven or caverot to pick the best view and then note the
angles before running the Printer Driver. This will be integrated soon.

For a plan enter bearing up the page, in degrees, 0 indicating North at the top
of the page (the default).

For an elevation enter the angle of view (i.e. the compass bearing from which
the scene is viewed), and angle of tilt, where 0 is horizontal, - is looking
down from above, and + is looking up from below, so -90 is the same as plan
view.

For an extended elevation, no viewing angles are needed.

You'll be told the scale needed to fit the plot on one page, and be asked what
scale you want to use. The you're told how many pages this will take (and the
arrangement of those pages (e.g. 6 pages (2x3)) and have the opportunity to
print, quit, or change the scale (so you can repeat this process until you have
a scale and number of pages you are happy with).

You can then print all the pages, a range of pages, or any arbitrary list of
pages and ranges (handy for when your printer mangles a page).

3dtopos

Name

3dtopos -- produce a .pos file from a .3d file

Synopsis

3dtopos [options] {.3d file} [.pos file]

Description

3dtopos takes a .3d file and produces a .pos file which contains a list of all
the stations with coordinates (ordered x,y,z [East, North, Up]) and complete
names.

The stations are sorted such that numbers occur in the correct order (so ``2''
before ``10''). 3dtopos even sorts numbers with a prefix and/or suffix, so
you'd get:

040.sv8
040.sv8a
040.sv8b
040.sv8c
040.sv9
040.sv10
040.sv11
40_entrance_tag
40b_entrance_tag

cad3d

Name

cad3d -- convert a Survex .3d file into formats which can be read by CAD and
drawing packages

Synopsis

cad3d [options] {.3d file} [output file]

Description

Cad3d can currently output DXF or Sketch files for import into CAD packages. It
can also produce Compass .plt files, which are primarily intended for importing
into Carto, but can also be used with Compass itself.

An alternative to cad3d is SpeleoGen, which can be found in the "Related Tools"
section of the Survex web site. SpeleoGen is a Windows (3.1/95/NT) utility
which reads in Survex .3d files, LRUD passage wall data (in .cav format) and
surface topography info in .csv format. The results are combined, displayed,
and saved out as a DXF file for import into CAD or drawing packages.

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, or by 3dtopos.

extend

Name

extend -- produce an extended elevation from a .3d file

Synopsis

extend [--specfile configuration .espec file] { input .3d file} [output .3d
file]

Description

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 writes its output to extend.3d.

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.

-------------------------------------------------------------------------------

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.

-------------------------------------------------------------------------------

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.

-------------------------------------------------------------------------------

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.

-------------------------------------------------------------------------------

Numeric fields

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

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.

-------------------------------------------------------------------------------

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

-------------------------------------------------------------------------------

BEGIN

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

-------------------------------------------------------------------------------

CALIBRATE

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

-------------------------------------------------------------------------------

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

-------------------------------------------------------------------------------

COPYRIGHT

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

-------------------------------------------------------------------------------

DATA

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

    <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 where
        the alititude is measured with an altimeter. DEPTH is defined as the
        altitude (Z) so increases upwards by default. So for a diver's depth
        guage, 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

         

            Note: 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


    IGNORE skips a field (it may be used any number of times), and IGNOREALL
    may be used last to ignore the rest of the data line.

    LENGTH is a synonym for TAPE; BEARING for COMPASS; GRADIENT for CLINO;
    COUNT for COUNTER.

    The units of each quantity may be set with the UNITS command.

-------------------------------------------------------------------------------

DATE

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

-------------------------------------------------------------------------------

DEFAULT

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

-------------------------------------------------------------------------------

END

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

-------------------------------------------------------------------------------

ENTRANCE

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.

-------------------------------------------------------------------------------

EQUATE

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

-------------------------------------------------------------------------------

EXPORT

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

-------------------------------------------------------------------------------

FIX

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 the
    position is omitted it defaults to (0,0,0). The standard errors default to
    zero (fix station exactly). cavern will give an error if you attempt to fix
    the same survey station twice at different coordinates, or a warning if you
    fix it twice with matching coordinates.

    You can also specify just one standard error (in which case it is assumed
    equal in X, Y, and Z) or two (in which case the first is taken as the
    standard error in X and Y, and the second as the standard error in Z).

    If you have covariances for the fix, you can also specify these - the order
    is cov(x,y) cov(y,z) cov(z,x).

    You can fix as many stations as you like - just use a *fix command for each
    one. Cavern will check that all stations are connected to at least one
    fixed point so that co-ordinates can be calculated for all stations.

    By default cavern will warn about stations which have been FIX-ed but not
    used otherwise. This is unhelpful if you want to include a standard file of
    benchmarks, some of which won't be used. In this sort of situation, specify
    "REFERENCE" after the station name in the FIX command to suppress this
    warning for a particular station.

        Note: X is Easting, Y is Northing, and Z is altitude. This convention
        was chosen since on a map, the horizontal (X) axis is usually East, and
        the vertical axis (Y) North. The choice of altitude (rather than depth)
        for Z is taken from surface maps, and makes for less confusion when
        dealing with cave systems with more than one entrance. It also gives a
        right-handed set of axes.

-------------------------------------------------------------------------------

FLAGS

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

-------------------------------------------------------------------------------

INCLUDE

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 "/" (or other appropriate tricks on RISC OS). And as a last resort,
    it will try a lower case version of the filename (so if you use Unix and
    someone sends you a DOS/Windows dataset with mismatched case, unzip it with
    "unzip -L" and unix cavern will process it).

    The depth to which you can nest include files may be limited by the
    operating system you use. Usually the limit is fairly high (>30), but if
    you want to be able to process your dataset with Survex on any supported
    platform, it would be prudent not to go overboard with nested include
    files.

-------------------------------------------------------------------------------

INFER

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.

-------------------------------------------------------------------------------

INSTRUMENT

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

-------------------------------------------------------------------------------

PREFIX

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

-------------------------------------------------------------------------------

REQUIRE

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.

-------------------------------------------------------------------------------

SD

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

-------------------------------------------------------------------------------

SET

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.

-------------------------------------------------------------------------------

SOLVE

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.

-------------------------------------------------------------------------------

TEAM

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

-------------------------------------------------------------------------------

TITLE

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.

-------------------------------------------------------------------------------

TRUNCATE

Syntax

    *truncate <length>|off

Description

    Station names may be of any length in Survex, but some other (mostly older)
    cave surveying software only regard the first few characters of a name as
    significant (e.g. "entran" and "entrance" might be treated as the same). To
    facilitate using data imported from such a package Survex allows you to
    truncate names to whatever length you want (but by default truncation is
    off).

    Figures for the number of characters which are significant in various
    software packages: Compass currently has a limit of 12, CMAP has a limit of
    6, Surveyor87/8 used 8. Survex itself used 8 per prefix level up to version
    0.41, and 12 per prefix level up to 0.73 (more recent versions removed this
    rather archaic restriction).

-------------------------------------------------------------------------------

UNITS

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

Description

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

    Changes current units of all the quantities listed to [<factor>] <unit>.
    Note that quantities can be expressed either as the instrument (e.g.
    COMPASS) or the measurement (e.g. BEARING).

    <factor> allows you to easy specify situations such as measuring distance
    with a diving line knotted every 10cm (*units distance 0.1 metres). If
    <factor> is omitted it defaults to 1.0. If specified, it must be non-zero.

    Valid units for listed quantities are:

    TAPE, LENGTH, COUNTER, COUNT, DEPTH, dX, dY, dZ in YARDS|FEET|METRIC|METRES
    |METERS

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

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

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

    Defaults are: Metres, Degrees, Degrees respectively.

See Also

    *calibrate

-------------------------------------------------------------------------------

Contents of .svx files: How do I?

Here is some example Survex 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 Survex:

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.

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

Survex 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

-------------------------------------------------------------------------------

Specify surface survey data

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.

-------------------------------------------------------------------------------

Specify the ordering and type of data

The *DATA command is used to specify the data style, and the order in which the
readings are given.

-------------------------------------------------------------------------------

Deal with Plumbs or Legs Across Static Water

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

-------------------------------------------------------------------------------

Specify a BCRA grade

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.

-------------------------------------------------------------------------------

Specify different accuracy for a leg

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

-------------------------------------------------------------------------------

Enter Radiolocation Data

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

-------------------------------------------------------------------------------

Enter Diving Data

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.

-------------------------------------------------------------------------------

Enter Theodolite data

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.

-------------------------------------------------------------------------------

General: How do I?

-------------------------------------------------------------------------------

Create a new survey

You simply create a text file containing the relevant survey data, using a text
editor, and save it with a suitable name with a .svx extension. The easiest way
is to look at some of the example data and use that as a template. Nearly all
surveys will need a bit of basic info as well as the survey data itself: e.g.
the date (*date), comments about where, what cave, a name for the survey (using
*begin and *end), instrument error corrections etc. Here is a typical survey
file:

All the lines starting with ';' are comments, which are ignored by Survex. You
can also see the use of 'DOWN' for plumbs, and *calibrate tape for dealing with
a tape length error (in this case the end of the tape had fallen off so
measurements were made from the 20cm point).

*equate chaos.1 triassic.pt3.8
*equate chaos.2 triassic.pt3.9

*begin chaos
*title "Bottomless Pit of Eternal Chaos to Redemption pitch"
*date 1996.07.11
*team "Nick Proctor" compass clino tape
*team "Anthony Day" notes pictures tape
*instrument compass "CUCC 2"
*instrument clino "CUCC 2"
;Calibration: Cairn-Rock 071 072 071,  -22 -22 -22
;       Rock-Cairn 252 251 252,  +21 +21 +21
;Calibration at 161d entrance from cairn nr entrance to
;prominent rock edge lower down. This is different from
;calibration used for thighs survey of 5 July 1996

*export 1 2

;Tape is 20cm too short
*calibrate tape +0.2

1 2 9.48 208 +08
2 3 9.30 179 -23
3 4 2.17 057 +09
5 4 10.13 263 +78
5 6 2.10 171 -73
7 6 7.93 291 +75
*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

-------------------------------------------------------------------------------

Join surveys together

Once you have more than one survey you need to specify how they link together.
To do this use *export to make the stations to be joined accessible in the
enclosing survey, then *equate in the enclosing survey to join them together.

-------------------------------------------------------------------------------

Organise my surveys

This is actually a large subject. There are many ways you can organise your
data using Survex. Take a look at the example dataset for some ideas of ways to
go about it.

-------------------------------------------------------------------------------

Fixed Points (Control Points)

The *fix command is used to specify fixed points (also know as control points).
See the description of this command in the "Cavern Commands" section of this
manual.

-------------------------------------------------------------------------------

More than one survey per trip

Suppose you have two separate bits of surveying which were done on the same
trip. So the calibration details, etc. are the same for both. But you want to
give a different survey name to the two sections. This is easily achieved like
so:

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

-------------------------------------------------------------------------------

Add surface topology

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.

-------------------------------------------------------------------------------

Overlay a grid

Aven is able to display a grid, but this functionality isn't currently
available in caverot, xcaverot, or the printer drivers. You can achieve a
similar effect for now by creating a .svx file where the survey legs form a
grid.

-------------------------------------------------------------------------------

Import data from other programs

Survex supports a number of features to help with importing existing data. You
can specify the ordering of items on a line using *Data (see Survex Keywords
above), and you can specify the characters used to mean different things using
*Set (see Survex Keywords above).

The Ignore and Ignoreall options to the *Data command are often particularly
useful, e.g. if you have a dataset with LRUD info or comments on the ends of
lines.

-------------------------------------------------------------------------------

Changing Meanings of Characters

e.g. if you have some data with station names containing the characters '?' and
'+' (which are not permitted in a name by default) then the command:

*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 BLANK x09x20
*SET DECIMAL ,

to specify that ',' is no longer a blank character, and is now the decimal
separator instead of '.'.

-------------------------------------------------------------------------------

Export data from Survex

See Rosetta Stal in the Related Tools section of the Survex web site. This is a
utility written by Taco van Ieperen and Gary Petrie. Note though that this only
supports a subset of the svx format, and only work on Microsoft Windows. The
Survex support is limited and doesn't understand the more recently added
commands.

-------------------------------------------------------------------------------

See errors and warnings that have gone off the screen

When you run Survex it will process the specified survey data files in order,
reporting any warnings and errors. If there are no errors, the output files are
written and various statistics about the survey are displayed. If there are a
lot of warnings or errors, they can scroll off the screen and it's not always
possible to scroll back to read them.

The easiest way to see all the text is to use cavern --log to redirect output
to a .log file, which you can then inspect with a text editor.

-------------------------------------------------------------------------------

Create an Extended Elevation

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

-------------------------------------------------------------------------------

Working with Larry Fish's Compass

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

-------------------------------------------------------------------------------

Mailing List

We have both email and paper mailing lists for Survex, to keep users informed
of new versions and so forth. This is available free by e-mail, or by post for
a small charge (to cover photocopying, disks, and postage). We recommend you
register to receive automatic updates and other information.

-------------------------------------------------------------------------------

Future Developments

Now that Survex 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 wxWindows, which means that can easily support Unix, Microsoft
Windows, and MacOS X. MacOS 9 support is possible, but requires somebody with
MacOS 9 and a compiler to build it with. Support for DOS is possible if there's
sufficient interest. Support for RISC OS is unlikely unless someone very
enthusiastic steps forward to do the porting work.

More information on our plans is on the web site.

-------------------------------------------------------------------------------

Contacting the authors

We'd be delighted to hear how you get on with Survex and welcome comments and
suggestions for improvements.

If you want the latest version and don't have net access, please enclose a
suitably formatted floppy and an SAE. These days, we'd probably struggle to
cope with anything other than 3.5" floppies. DOS format is easiest for us.
Alternatively, send a blank CDR and we can burn you a CD with all the versions
on.

Wookey
734 Newmarket Rd
Cambridge
CB5 8RS
UK
Tel: 01223 504881 (home)
Tel: 01223 811679 (work)
<wookey@survex.com>

or

Olly Betts
6 Ashcroft Court
Cambridge
CB4 2SN
UK
Tel: 01223 513644 (home and work)
<olly@survex.com>

Or if neither of these get any response try:

Cambridge University Caving Club,
c/o James Hickson,
Pembroke College
Cambridge
UK

-------------------------------------------------------------------------------

Contributing

Monetary donations are welcome, but if you want a more personal way to say
thankyou we'd love a copy of a survey you've produced using Survex. Two copies
would be best to save us arguing over who gets it.

Or contribute your skills to help make Survex 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.

