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.

       -v, --3d-version
                 Specify  the 3d file format version to output.  By default the latest version is
                 written, but you can override this to produce a 3d file which  can  be  read  by
                 software  which doesn't understand the latest 3d file format version.  Note that
                 any information which the  specified  format  version  didn't  support  will  be
                 omitted.

Output

       Cavern  reads  in  text files containing the survey data .svx) and outputs two files, with
       the extensions .3d and .err.  By default these files are put  in  the  current  directory,
       with  the  same base filename as the first .svx file read, but a different extension.  You
       can change the directory and/or base filename using the --output command line option.

       E.g. if  you  process  the  data  file  entrance.svx  with  the  command  cavern  entrance
       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.

See Also

       3dtopos(1), aven(1), cad3d(1), diffpos(1), extend(1), sorterr(1), svxedit(1)

                                                                                        cavern(1)