1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
|
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>cavern — Survex 1.4.17 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d1102ebc" />
<link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=12dfc556" />
<script src="_static/documentation_options.js?v=91e0adf2"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.htm" />
<link rel="search" title="Search" href="search.htm" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="cavern">
<h1>cavern<a class="headerlink" href="#cavern" title="Link to this heading">¶</a></h1>
<section id="synopsis">
<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Link to this heading">¶</a></h2>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">cavern</span></code> [<cite>OPTIONS</cite>] <cite>SURVEY_DATA_FILE</cite>…</p>
</div></blockquote>
</section>
<section id="description">
<h2>DESCRIPTION<a class="headerlink" href="#description" title="Link to this heading">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">cavern</span></code> is the Survex data processing engine.</p>
<p><code class="docutils literal notranslate"><span class="pre">cavern</span></code> is a command line tool, but if you’re not a fan of working from the
command line you can open unprocessed survey data files with <code class="docutils literal notranslate"><span class="pre">aven</span></code> and it
will run <code class="docutils literal notranslate"><span class="pre">cavern</span></code> for you, and if successful, display the processed data. If
there are any warnings and errors, <code class="docutils literal notranslate"><span class="pre">aven</span></code> will show a log window with the
output with clickable links to open the affected file at the problematic line.</p>
<p>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.</p>
<p>Each <cite>SURVEY_DATA_FILE</cite> must be unprocessed survey data in a format
which Survex supports, either native format (<code class="docutils literal notranslate"><span class="pre">.svx</span></code>) or Compass format
(<code class="docutils literal notranslate"><span class="pre">.mak</span></code>, <code class="docutils literal notranslate"><span class="pre">.dat</span></code> or <code class="docutils literal notranslate"><span class="pre">.clp</span></code>), or Walls format (<code class="docutils literal notranslate"><span class="pre">.wpj</span></code> or <code class="docutils literal notranslate"><span class="pre">.srv</span></code>).</p>
<p>Support for Compass <code class="docutils literal notranslate"><span class="pre">.clp</span></code> was added in Survex 1.4.6; support for
Walls was added in Survex 1.4.9.</p>
</section>
<section id="options">
<h2>OPTIONS<a class="headerlink" href="#options" title="Link to this heading">¶</a></h2>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">-o</span></code>, <code class="docutils literal notranslate"><span class="pre">--output=</span></code><cite>OUTPUT</cite></dt><dd><p>Sets location for output files.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">-q</span></code>, <code class="docutils literal notranslate"><span class="pre">--quiet</span></code></dt><dd><p>Only show a brief summary (<code class="docutils literal notranslate"><span class="pre">--quiet</span> <span class="pre">--quiet</span></code> or <code class="docutils literal notranslate"><span class="pre">-qq</span></code> will display
warnings and errors only).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">-s</span></code>, <code class="docutils literal notranslate"><span class="pre">--no-auxiliary-files</span></code></dt><dd><p>do not create .err file.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">-w</span></code>, <code class="docutils literal notranslate"><span class="pre">--warnings-are-errors</span></code></dt><dd><p>turn warnings into errors.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--log</span></code></dt><dd><p>Send screen output to a .log file.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">-v</span></code>, <code class="docutils literal notranslate"><span class="pre">--3d-version=</span></code><cite>3D_VERSION</cite></dt><dd><p>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.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--help</span></code></dt><dd><p>display short help and exit</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--version</span></code></dt><dd><p>output version information and exit</p>
</dd>
</dl>
</section>
<section id="output">
<h2>OUTPUT<a class="headerlink" href="#output" title="Link to this heading">¶</a></h2>
<p>If there were no errors during processing, cavern produces two
output files, with the extensions <code class="docutils literal notranslate"><span class="pre">.3d</span></code> and <code class="docutils literal notranslate"><span class="pre">.err</span></code> (unless
<code class="docutils literal notranslate"><span class="pre">--no-auxiliary-files</span></code> is specified in which case only the <code class="docutils literal notranslate"><span class="pre">.3d</span></code>
file is produced).</p>
<p>These two files are always created with their respective extensions. By
default they are created in the current directory, with the same base filename
as the first <cite>SURVEY_DATA_FILE</cite> listed on the command line.</p>
<p>E.g. if you process the data file <code class="docutils literal notranslate"><span class="pre">entrance.svx</span></code> with the command
<code class="docutils literal notranslate"><span class="pre">cavern</span> <span class="pre">entrance</span></code> or <code class="docutils literal notranslate"><span class="pre">cavern</span> <span class="pre">entrance.svx</span></code> then the files <code class="docutils literal notranslate"><span class="pre">entrance.3d</span></code>
and <code class="docutils literal notranslate"><span class="pre">entrance.err</span></code> will be created.</p>
<p>You can change the directory and/or base filename using the <code class="docutils literal notranslate"><span class="pre">--output</span></code>
command line option. If you specify a directory then output files will
go there instead of the current directory, but still use the basename
of the first <cite>SURVEY_DATA_FILE</cite>. If you specify a filename which is not a
directory (note that it doesn’t need to actually exist as a file) then the
directory this file is in is used, and also the basename of the filename
is used instead of the basename of the first <cite>SURVEY_DATA_FILE</cite>.</p>
<p>Details of the output files:</p>
<dl>
<dt><code class="docutils literal notranslate"><span class="pre">.3d</span></code></dt><dd><p>This is a binary file format containing the adjusted survey data and
associated meta data.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">.err</span></code></dt><dd><p>This is a text file which contains statistics about each traverse in the
survey which is part of a loop. It includes various statistics for each
traverse:</p>
<dl class="simple">
<dt>Original length</dt><dd><p>This is the measured length of the traverse (for a “normal” or “diving”
survey this is the sum of the tape readings after applying calibration
corrections).</p>
</dd>
<dt>Number of legs</dt><dd><p>The number of survey legs in the traverse</p>
</dd>
<dt>Moved</dt><dd><p>How much one end of the traverse moved by relative to the other after
loop closure</p>
</dd>
<dt>Moved per leg</dt><dd><p><cite>Moved</cite> / <cite>Number of legs</cite></p>
</dd>
<dt>Percentage error</dt><dd><p>(<cite>Moved</cite> / <cite>Original length</cite>) as a percentage. This seems to be a
popular measure of how good or bad a misclosure is, but it’s a
problematic one because a longer traverse will naturally tend to
have a lower percentage error so you can’t just compare values
between traverses. We recommend using the <cite>E</cite>, <cite>H</cite> and <cite>V</cite> values
instead.</p>
</dd>
<dt>Error (<cite>E</cite>)</dt><dd><p>This isn’t labelled in the <cite>.err</cite> file but is the value on a line by
itself. In <code class="docutils literal notranslate"><span class="pre">aven</span></code> it’s the value used by <cite>Colour by Error</cite>. It
is <cite>Moved</cite> divided by the standard deviation for the traverse based on
the standard errors specified for the instruments. This tells us how
plausible it is that the misclosure is just due to random errors. It
is a number of standard deviations, so the <a class="reference external" href="https://en.wikipedia.org/wiki/68%E2%80%9395%E2%80%9399.7_rule">68-95-99.7 rule</a>
applies - e.g. approximately 99.7% of traverses should have a value of
3.0 or less (assuming the specified instrument standard deviations are
realistic).</p>
</dd>
<dt>Horizontal Error (<cite>H</cite>)</dt><dd><p>This is like <cite>E</cite> but only considers the horizontal component. In
<code class="docutils literal notranslate"><span class="pre">aven</span></code> it’s the value used by <cite>Colour by Horizontal Error</cite>. You
can identify suspect traverses by looking at <cite>E</cite> and then compare
<cite>H</cite> and <cite>V</cite> to see what sort of blunder might explain the misclosure.
For example, if <cite>H</cite> is small but <cite>V</cite> is large it could be a clino reading
or plumb with an incorrect sign, or a tape blunder on a plumbed leg; if
<cite>H</cite> is large but <cite>V</cite> is small it could be a compass blunder, or a tape
blunder of a nearly-flat leg.</p>
</dd>
<dt>Vertical Error (<cite>V</cite>)</dt><dd><p>This is like <cite>E</cite> but only considers the vertical component. In
<code class="docutils literal notranslate"><span class="pre">aven</span></code> it’s the value used by <cite>Colour by Vertical Error</cite>.</p>
</dd>
</dl>
<p>This information is now also present in the <code class="docutils literal notranslate"><span class="pre">.3d</span></code> file so you can view the
survey coloured by these errors, but the <code class="docutils literal notranslate"><span class="pre">.err</span></code> file can
still be useful as you can sort it using <code class="docutils literal notranslate"><span class="pre">sorterr</span></code> to get a ranked list of
the sections of survey with the worst misclosure errors.</p>
</dd>
</dl>
<p>Cavern also reports a range of statistics at the end of a successful
run:</p>
<ul class="simple">
<li><p>The highest and lowest stations and the height difference between
them</p></li>
<li><p>The East-West and North-South ranges, and the Northernmost,
Southernmost, Easternmost, and Westernmost stations.</p></li>
<li><p>The total length of the survey (before and after adjustment). This
total excludes survey legs flagged as <code class="docutils literal notranslate"><span class="pre">SURFACE</span></code>, <code class="docutils literal notranslate"><span class="pre">DUPLICATE</span></code>, or
<code class="docutils literal notranslate"><span class="pre">SPLAY</span></code>.</p></li>
<li><p>The number of stations and legs. Note that a <code class="docutils literal notranslate"><span class="pre">*equate</span></code> is counted
as a leg in this statistic.</p></li>
<li><p>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.</p></li>
<li><p>How long the processing took and how much CPU time was used.</p></li>
</ul>
<p>If you successfully processed your data by loading it into <code class="docutils literal notranslate"><span class="pre">aven</span></code> then you
can see this log output by using <code class="docutils literal notranslate"><span class="pre">File->Show</span> <span class="pre">Log</span></code> (also available as an icon
in the toolbar).</p>
<section id="error-messages">
<h3>Error Messages<a class="headerlink" href="#error-messages" title="Link to this heading">¶</a></h3>
<p>There are many different error messages that you can get when processing
data. Along with the error message, a location is reported. For an error
like “file not found” this only reports the filename, but usually it will
give the filename and line number of the offending line, and in many cases also
an offset or span within the line.</p>
<p>The format of the location data follows that used by the GCC compiler
so if your text editor can parse errors from GCC then you should be able to set
it to allow you to jump to the file and line of each error.</p>
<p>One common cause of errors and warnings are typing mistakes. Another is
your survey data not being all attached to fixed points (which is a warning
since Survex 1.4.10, but was an error prior to this; in this situation, Survex
will list at least one station in each piece of survey data which is not
connected).</p>
<p>We try to make error and warning messages self-explanatory, but welcome
feedback on cases where you get a message which seems unclear.</p>
<p>Generally you want to look at the first reported error first as there
can be a cascade effect where one error triggers another. Cavern will stop
after more than 50 errors. This usually indicates something like the incorrect
data order being specified and deluging the user with error messages in such
cases usually makes the actual problem less clear.</p>
</section>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="index.htm">Survex</a></h1>
<h3>Navigation</h3>
<ul>
<li class="toctree-l1"><a class="reference internal" href="intro.htm">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="getstart.htm">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="cmdline.htm">Survex Programs</a></li>
<li class="toctree-l1"><a class="reference internal" href="datafile.htm">Survex data files</a></li>
<li class="toctree-l1"><a class="reference internal" href="svxhowto.htm"><code class="docutils literal notranslate"><span class="pre">.svx</span></code> Cookbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="genhowto.htm">General: How do I?</a></li>
<li class="toctree-l1"><a class="reference internal" href="compass.htm">Larry Fish’s Compass</a></li>
<li class="toctree-l1"><a class="reference internal" href="walls.htm">David McKenzie’s Walls</a></li>
<li class="toctree-l1"><a class="reference internal" href="cmap.htm">Bob Thrun’s CMAP</a></li>
<li class="toctree-l1"><a class="reference internal" href="img.htm">Using the img library</a></li>
<li class="toctree-l1"><a class="reference internal" href="maillist.htm">Mailing List</a></li>
<li class="toctree-l1"><a class="reference internal" href="future.htm">Future Developments</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.htm">Documentation overview</a><ul>
</ul></li>
</ul>
</div>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.htm" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©1998-2025.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
</div>
</body>
</html>
|
