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)