doc/cavern.sgml

   1 <refmeta>
   2 <refentrytitle>cavern</refentrytitle>
   3 <manvolnum>1</manvolnum>
   4 </refmeta>
   5
   6 <refnamediv>
   7 <refname>cavern</refname>
   8 <refpurpose>process raw survey data
   9 </refpurpose>
  10 </refnamediv>
  11
  12 <refsynopsisdiv>
  13 <cmdsynopsis>
  14 <command>cavern</command>
  15 <arg choice="opt">options</arg>
  16 <arg choice="req" rep="repeat">survex data file</arg> <!--FIXME-->
  17 </cmdsynopsis>
  18 </refsynopsisdiv>
  19
  20 <refsect1><title>Description</title>
  21
  22 <Para>Cavern is the <Application>Survex</Application> data processing engine.</Para>
  23
  24 <Para>If multiple survey data files are listed on the command line,
  25 they are processed in order from left to right.  Settings are reset to
  26 their defaults before processing each file.
  27 </Para>
  28
  29 </refsect1>
  30
  31 <refsect1><Title>Options</Title>
  32
  33 <VariableList>
  34
  35 <VarListEntry>
  36 <Term>-o, --output=OUTPUT</Term>
  37 <ListItem>
  38 <Para>Sets location for output files.
  39 <!--FIXME elaborate this and other option descriptions.-->
  40 </Para>
  41 </ListItem>
  42 </VarListEntry>
  43
  44 <VarListEntry>
  45 <Term>-q, --quiet</Term>
  46 <ListItem>
  47 <Para>Only show a brief summary (--quiet --quiet or -qq will display
  48 warnings and errors only).
  49 </Para>
  50 </ListItem>
  51 </VarListEntry>
  52
  53 <VarListEntry>
  54 <Term>-s, --no-auxiliary-files</Term>
  55 <ListItem>
  56 <Para>do not create .err file.
  57 </Para>
  58 </ListItem>
  59 </VarListEntry>
  60
  61 <VarListEntry>
  62 <Term>-w, --warnings-are-errors</Term>
  63 <ListItem>
  64 <Para>turn warnings into errors.
  65 </Para>
  66 </ListItem>
  67 </VarListEntry>
  68
  69 <VarListEntry>
  70 <Term>--log</Term>
  71 <ListItem>
  72 <Para>Send screen output to a .log file.
  73 </Para>
  74 </ListItem>
  75 </VarListEntry>
  76
  77 <VarListEntry>
  78 <Term>-v, --3d-version</Term>
  79 <ListItem>
  80 <Para>Specify the 3d file format version to output.  By default the latest
  81 version is written, but you can override this to produce a 3d file which can
  82 be read by software which doesn't understand the latest 3d file format version.
  83 Note that any information which the specified format version didn't support
  84 will be omitted.
  85 </Para>
  86 </ListItem>
  87 </VarListEntry>
  88
  89 </VariableList>
  90
  91 </refsect1>
  92
  93 <refsect1><Title>Output</Title>
  94
  95 <Para>Cavern reads in text files containing the survey data
  96 <filename>.svx</filename>) and outputs two files, with the extensions
  97 <filename>.3d</filename> and <filename>.err</filename>.
  98 By default these files are put in the current directory,
  99 with the same base filename as the first <filename>.svx</filename> file read,
 100 but a different extension.
 101 You can change the directory and/or base filename using the --output
 102 command line option.
 103 <!-- FIXME: link -->
 104 </Para>
 105
 106 <Para>E.g. if you process the data file <filename>entrance.svx</filename>
 107 with the command <userinput>cavern entrance</userinput> then the files
 108 <filename>entrance.3d</filename> and <filename>entrance.err</filename>
 109 will be created.
 110 </Para>
 111
 112 <!-- mention .log FIXME -->
 113
 114 <Para>
 115 Cavern also gives a range of statistics at the end of a successful run:
 116 </Para>
 117
 118 <itemizedlist>
 119 <listitem><para>The highest and lowest stations and the height difference
 120 between them
 121 </para></listitem>
 122
 123 <listitem><para>The total length of the survey (before and after
 124 adjustment).  This total excludes survey legs flagged as SURFACE,
 125 DUPLICATE, or SPLAY.
 126 </para></listitem>
 127
 128 <listitem><para>The number of stations and legs.  Note that a *EQUATE
 129 is counted as a leg in this statistic.
 130 </para></listitem>
 131
 132 <!-- FIXME loops, components, anything else -->
 133
 134 <listitem><para>The East-West and North-South ranges, and the North-most,
 135 South-most, East-most, and West-most stations.
 136 </para></listitem>
 137
 138 <listitem><para>The number of each size of node in the network (where size
 139 is number of connections to a station) i.e. a one node is the end of a
 140 dead-end traverse, a two-node is a typical station in the middle of a
 141 traverse, a three-node is a T-junction etc.
 142 </para></listitem>
 143
 144 <listitem><para>How long the processing took and how much CPU time was
 145 used.
 146 </para></listitem>
 147 </itemizedlist>
 148
 149 <refsect2><Title><filename>.3d</filename> - data describing the loop-closed centre line</Title>
 150
 151 <Para>This file contains details of the stations and legs, and any
 152 flags associated with them.
 153 </Para>
 154
 155 </refsect2>
 156
 157 <refsect2><Title><filename>.err</filename> - loop closure statistics (%age errors, etc)</Title>
 158
 159 <Para>This file contains statistics about each traverse in the survey
 160 which is part of a loop. It includes various statistics for each
 161 traverse, such as the percentage error per leg.
 162 You should study this information to determine if any parts of the survey
 163 are of lower quality or contain gross errors.
 164
 165 <!-- FIXME explain the various statistics -->
 166 </Para>
 167
 168 </refsect2>
 169
 170 </refsect1>
 171
 172 <refsect1><Title>Error Messages</Title>
 173
 174 <Para>
 175 There are a number of error messages that you may get when processing
 176 data.  Most of these are self explanatory, and will be caused by such
 177 problems as typing mistakes, or by your survey data not being attached
 178 to fixed points (in this situation, <Application>Survex</Application> will
 179 list some of the stations that are not connected).
 180 </Para>
 181
 182 <Para>
 183 Along with the error message, the filename and line number of the offending
 184 line will be printed (or the filename for errors such as `file not
 185 found').  The format of the filename and line number is that used by
 186 gcc, so if your editor can parse errors from gcc, you should be able to
 187 set it to allow you to jump to the file and line of each error.
 188 </Para>
 189
 190 <Para>
 191 Cavern will stop after more than 50 errors.  This usually indicates
 192 something like the incorrect data order being specified.  Deluging
 193 the user with error messages makes the actual problem less clear.
 194 </Para>
 195
 196 </refsect1>