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
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
|
<!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>Survex data files — 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="next" title=".svx Cookbook" href="svxhowto.htm" />
<link rel="prev" title="Survex Programs" href="cmdline.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="survex-data-files">
<h1>Survex data files<a class="headerlink" href="#survex-data-files" title="Link to this heading">¶</a></h1>
<p>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 text
file in UTF-8 or ASCII encoding. 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.</p>
<p>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 changed to be a comma (as used in
continental Europe), or a slash (sometimes used for clarity in written survey
notes), 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.</p>
<p>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.</p>
<p>The usual arrangement is to have one file which lists all the others that are
included (e.g., <code class="docutils literal notranslate"><span class="pre">161.svx</span></code>). Then <code class="docutils literal notranslate"><span class="pre">cavern</span> <span class="pre">161</span></code> will process all your data.
To just process a section use the filename for that section, e.g. <code class="docutils literal notranslate"><span class="pre">cavern</span>
<span class="pre">dtime</span></code> will process the dreamtime file/section of Kaninchenhöhle. To help you
out, if the survey has no fixed points and you are using Survex’s default
unspecified coordinate system, <code class="docutils literal notranslate"><span class="pre">cavern</span></code> will pick a station and fix it at
(0,0,0) (and print a info message to this effect).</p>
<p>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.</p>
<section id="readings">
<h2>Readings<a class="headerlink" href="#readings" title="Link to this heading">¶</a></h2>
<p>Blank lines (i.e. lines consisting solely of <code class="docutils literal notranslate"><span class="pre">BLANK</span></code> characters) are ignored,
except that in interleaved data a blank line ends the current traverse.</p>
<p>The last line in the file need not be terminated by an end of line character.</p>
<p>All fields on a line must be separated by at least one <code class="docutils literal notranslate"><span class="pre">BLANK</span></code> character.
An <code class="docutils literal notranslate"><span class="pre">OMIT</span></code> character (default <code class="docutils literal notranslate"><span class="pre">-</span></code>) indicates that a field is omitted. If the
field is not optional, then an error is given.</p>
</section>
<section id="survey-station-names">
<h2>Survey Station Names<a class="headerlink" href="#survey-station-names" title="Link to this heading">¶</a></h2>
<p>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) can just be
referred to as station 6 in the context of that particular survey, but it has
the fully qualified name: 161.entrance.6</p>
<p>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:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*begin Loser
*include 161
*include 2YrGest
*include 145
*end Loser
</pre></div>
</div>
<p>The entrance series point mentioned above would now be referred to as:
Loser.161.entrance.6</p>
<p>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.</p>
<p>Station and survey names may contain any alphanumeric characters and
additionally any characters in <code class="docutils literal notranslate"><span class="pre">NAMES</span></code> (default <code class="docutils literal notranslate"><span class="pre">_</span></code> and <code class="docutils literal notranslate"><span class="pre">-</span></code>).
Alphabetic characters may be forced to upper or lower case by using the
<code class="docutils literal notranslate"><span class="pre">*case</span></code> 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 <code class="docutils literal notranslate"><span class="pre">*truncate</span></code> command.</p>
<p>If you have survey data which uses <code class="docutils literal notranslate"><span class="pre">.</span></code> as part of the station name (for
example, if you use the Toporobot convention of naming stations along a
side passage from station <code class="docutils literal notranslate"><span class="pre">6</span></code> as <code class="docutils literal notranslate"><span class="pre">6.1</span></code>, <code class="docutils literal notranslate"><span class="pre">6.2</span></code>, <code class="docutils literal notranslate"><span class="pre">6.3</span></code>, etc) then
there are two sensible options:</p>
<blockquote>
<div><ul>
<li><p>You can change the separator to a different character which you don’t want
to use in station names (e.g. <code class="docutils literal notranslate"><span class="pre">:</span></code>) and set <code class="docutils literal notranslate"><span class="pre">.</span></code> as an allowed name
character like so:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*set separator :
*set names ._-
</pre></div>
</div>
<p>Note that the character(s) listed replace those previously allowed, so here
we have explicitly list <code class="docutils literal notranslate"><span class="pre">_</span></code> and <code class="docutils literal notranslate"><span class="pre">-</span></code> as still allowed in station names to
effectively add <code class="docutils literal notranslate"><span class="pre">.</span></code>.</p>
<p>If you want to do this, you should use Survex 1.4.6 or later. 1.4.12 also
fixed a bug with survey filtering when loading <code class="docutils literal notranslate"><span class="pre">.3d</span></code> files which use a
separator other than <code class="docutils literal notranslate"><span class="pre">.</span></code>.</p>
</li>
<li><p>You can use a different character instead of <code class="docutils literal notranslate"><span class="pre">.</span></code> for naming such
side-passage stations, e.g. <code class="docutils literal notranslate"><span class="pre">6_1</span></code>, <code class="docutils literal notranslate"><span class="pre">6_2</span></code>, etc. This has the advantage
of working with older Survex versions.</p></li>
</ul>
</div></blockquote>
<section id="anonymous-stations">
<h3>Anonymous Stations<a class="headerlink" href="#anonymous-stations" title="Link to this heading">¶</a></h3>
<p>Survex supports the concept of anonymous survey stations, that is survey
stations without a name. Each time an anonymous station name is used it
represents a different point. Currently three types of anonymous station are
supported, referred to by one, two or three separator characters - with the
default separator of <code class="docutils literal notranslate"><span class="pre">.</span></code>, that means <code class="docutils literal notranslate"><span class="pre">.</span></code>, <code class="docutils literal notranslate"><span class="pre">..</span></code>, and <code class="docutils literal notranslate"><span class="pre">...</span></code> are anonymous
stations. Their meanings are:</p>
<dl class="simple">
<dt>Single separator (<code class="docutils literal notranslate"><span class="pre">.</span></code> by default)</dt><dd><p>An anonymous non-wall point at the end of an implicit splay.</p>
</dd>
<dt>Double separator (<code class="docutils literal notranslate"><span class="pre">..</span></code> by default)</dt><dd><p>An anonymous wall point at the end of an implicit splay.</p>
</dd>
<dt>Triple separator (<code class="docutils literal notranslate"><span class="pre">...</span></code> by default)</dt><dd><p>An anonymous point with no implicit flags on the leg (intended for cases
like a disto leg along a continuing passage).</p>
</dd>
</dl>
<p>You can map <code class="docutils literal notranslate"><span class="pre">-</span></code> to <code class="docutils literal notranslate"><span class="pre">..</span></code> (for compatibility with data from pocket topo)
using the command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*alias station - ..
</pre></div>
</div>
<p>Support for anonymous stations and for <code class="docutils literal notranslate"><span class="pre">*alias</span> <span class="pre">station</span> <span class="pre">-</span> <span class="pre">..</span></code> was added in
Survex 1.2.7.</p>
<p>Support for anonymous stations in the <code class="docutils literal notranslate"><span class="pre">cartesian</span></code> data style was added in
Survex 1.4.10.</p>
</section>
</section>
<section id="numeric-fields">
<h2>Numeric fields<a class="headerlink" href="#numeric-fields" title="Link to this heading">¶</a></h2>
<p>Measurements start with an optional <code class="docutils literal notranslate"><span class="pre">PLUS</span></code> or <code class="docutils literal notranslate"><span class="pre">MINUS</span></code> character (<code class="docutils literal notranslate"><span class="pre">+</span></code>
and <code class="docutils literal notranslate"><span class="pre">-</span></code> by default), and have an optional decimal point (represented by a
<code class="docutils literal notranslate"><span class="pre">DECIMAL</span></code> character, default: <code class="docutils literal notranslate"><span class="pre">.</span></code>) which may be embedded, leading or
trailing. No spaces are allowed between the various elements.</p>
<p>All of these are valid examples: +47, 23, -22, +4.5, 1.3, -0.7, +12., 23., -34,
+.15, .4, -.05</p>
<p>In formal syntax that’s either:</p>
<p><code class="docutils literal notranslate"><span class="pre">[<MINUS>|<PLUS>]</span> <span class="pre"><integer</span> <span class="pre">part></span> <span class="pre">[</span> <span class="pre"><DECIMAL></span> <span class="pre">[</span> <span class="pre"><decimal</span> <span class="pre">fraction></span> <span class="pre">]</span> <span class="pre">]</span></code></p>
<p>or</p>
<p><code class="docutils literal notranslate"><span class="pre">[<MINUS>|<PLUS>]</span> <span class="pre"><DECIMAL></span> <span class="pre"><decimal</span> <span class="pre">fraction></span></code></p>
</section>
<section id="accuracy">
<h2>Accuracy<a class="headerlink" href="#accuracy" title="Link to this heading">¶</a></h2>
<p>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 <code class="docutils literal notranslate"><span class="pre">*SD</span></code> for more information.</p>
</section>
<section id="cavern-commands">
<h2>Cavern Commands<a class="headerlink" href="#cavern-commands" title="Link to this heading">¶</a></h2>
<p>Commands in <code class="docutils literal notranslate"><span class="pre">.svx</span></code> files are introduced by an asterisk (by default - this can
be changed using the <code class="docutils literal notranslate"><span class="pre">set</span></code> command).</p>
<p>The commands are documented below in a common format:</p>
<ul class="simple">
<li><p>Command Name</p></li>
<li><p>Syntax</p></li>
<li><p>Example</p></li>
<li><p>Validity</p></li>
<li><p>Description</p></li>
<li><p>Caveats</p></li>
<li><p>See Also</p></li>
</ul>
<section id="alias">
<h3>ALIAS<a class="headerlink" href="#alias" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*alias</span> <span class="pre">station</span> <span class="pre"><alias></span> <span class="pre"><target></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*alias</span> <span class="pre">station</span> <span class="pre"><alias></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*begin parsons_nose
*alias station - ..
1 2 12.21 073 -12
2 - 4.33 011 +02
2 - 1.64 180 +03
2 3 6.77 098 -04
*end parsons_nose
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*alias</span></code> allows you to map a station name which appears in the survey data
to a different name internally. At present, you can only create an alias of
<code class="docutils literal notranslate"><span class="pre">-</span></code> to <code class="docutils literal notranslate"><span class="pre">..</span></code>, which is intended to support the pocket topo style notation
of <code class="docutils literal notranslate"><span class="pre">-</span></code> being a splay to an anonymous point on the cave wall. You can also
unalias <code class="docutils literal notranslate"><span class="pre">-</span></code> with <code class="docutils literal notranslate"><span class="pre">*alias</span> <span class="pre">station</span> <span class="pre">-</span></code>.</p>
<p>Aliases are scoped by <code class="docutils literal notranslate"><span class="pre">*begin</span></code>/<code class="docutils literal notranslate"><span class="pre">*end</span></code> blocks - when a <code class="docutils literal notranslate"><span class="pre">*end</span></code> is
reached, the aliases in force at the corresponding <code class="docutils literal notranslate"><span class="pre">*begin</span></code> are restored.</p>
<p><code class="docutils literal notranslate"><span class="pre">*alias</span></code> was added in Survex 1.2.7.</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*begin</span></code>, <code class="docutils literal notranslate"><span class="pre">*end</span></code></p>
</dd>
</dl>
</section>
<section id="begin">
<h3>BEGIN<a class="headerlink" href="#begin" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*begin</span> <span class="pre"><survey></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*begin</span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*begin littlebit
1 2 10.23 106 -02
2 3 1.56 092 +10
*end littlebit
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>; length of leg across shaft estimated
*begin
*sd tape 2 metres
9 10 6. 031 -07
*end
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*begin</span></code> 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 <code class="docutils literal notranslate"><span class="pre">*end</span></code>. If a survey name is given, this
is used inside the <code class="docutils literal notranslate"><span class="pre">*begin</span></code>/<code class="docutils literal notranslate"><span class="pre">*end</span></code> block, and the corresponding <code class="docutils literal notranslate"><span class="pre">*end</span></code>
should have the same survey name. <code class="docutils literal notranslate"><span class="pre">*begin</span></code>/<code class="docutils literal notranslate"><span class="pre">*end</span></code> blocks may be nested
to indefinite depth.</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*end</span></code>, <code class="docutils literal notranslate"><span class="pre">*prefix</span></code></p>
</dd>
</dl>
</section>
<section id="cartesian">
<h3>CARTESIAN<a class="headerlink" href="#cartesian" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*cartesian</span> <span class="pre">grid</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*cartesian</span> <span class="pre">magnetic</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*cartesian</span> <span class="pre">true</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*cartesian</span> <span class="pre">grid</span> <span class="pre"><rotation></span> <span class="pre"><units></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*cartesian</span> <span class="pre">magnetic</span> <span class="pre"><rotation></span> <span class="pre"><units></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*cartesian</span> <span class="pre">true</span> <span class="pre"><rotation></span> <span class="pre"><units></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*cartesian magnetic
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*cartesian true 90 degrees
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*cartesian</span></code> specifies which North cartesian data is aligned to, and can
optionally specify an extra rotation to apply. The default is that it’s
aligned with True North.</p>
<p>Notes on the different North options:</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">GRID</span></code></dt><dd><p>North in the current input coordinate system (as set by e.g. <code class="docutils literal notranslate"><span class="pre">*cs</span>
<span class="pre">UTM30</span></code>). If no input or output coordinate system is set then this is
the same as <code class="docutils literal notranslate"><span class="pre">TRUE</span></code> since in Survex’s default unspecified coordinate
system True North is the same as Grid North.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">MAGNETIC</span></code></dt><dd><p>Magnetic North. If using automatically calculated declinations then
this will be calculated at the <code class="docutils literal notranslate"><span class="pre">*date</span></code> in effect for each cartesian
data reading.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">TRUE</span></code></dt><dd><p>True North. If no input or output coordinate system is set then
this is the same as <code class="docutils literal notranslate"><span class="pre">GRID</span></code> since in Survex’s default unspecified
coordinate system True North is the same as Grid North.</p>
</dd>
</dl>
<p><code class="docutils literal notranslate"><span class="pre">*cartesian</span></code> was added in Survex 1.4.10. Prior to this cartesian data was
documented as aligned with True North, but if an output coordinate system
was specified it was actually aligned with this (which was not intended and
doesn’t really make sense since changing the output coordinate system would
rotate cartesian data by the difference in grid convergence).</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*cs</span></code>, <code class="docutils literal notranslate"><span class="pre">*data</span> <span class="pre">cartesian</span></code>, <code class="docutils literal notranslate"><span class="pre">*date</span></code>, <code class="docutils literal notranslate"><span class="pre">*declination</span></code></p>
</dd>
</dl>
</section>
<section id="calibrate">
<h3>CALIBRATE<a class="headerlink" href="#calibrate" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*calibrate</span> <span class="pre"><quantity</span> <span class="pre">list></span> <span class="pre"><zero</span> <span class="pre">error></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*calibrate</span> <span class="pre"><quantity</span> <span class="pre">list></span> <span class="pre"><zero</span> <span class="pre">error></span> <span class="pre"><scale></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*calibrate</span> <span class="pre"><quantity</span> <span class="pre">list></span> <span class="pre"><zero</span> <span class="pre">error></span> <span class="pre"><units></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*calibrate</span> <span class="pre"><quantity</span> <span class="pre">list></span> <span class="pre"><zero</span> <span class="pre">error></span> <span class="pre"><units></span> <span class="pre"><scale></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*calibrate</span> <span class="pre">default</span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*calibrate tape +0.3
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*calibrate</span></code> is used to specify instrument calibrations, via a zero error
and an optional scale factor (which defaults to 1.0 if not specified).
Without an explicit calibration the zero error is 0.0 and the scale factor
is 1.0.</p>
<p><code class="docutils literal notranslate"><span class="pre"><quantity</span> <span class="pre">list></span></code> is one or more of:</p>
<blockquote>
<div><table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Quantity</p></th>
<th class="head"><p>Aliases</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>LENGTH</p></td>
<td><p>TAPE</p></td>
</tr>
<tr class="row-odd"><td><p>BEARING</p></td>
<td><p>COMPASS</p></td>
</tr>
<tr class="row-even"><td><p>GRADIENT</p></td>
<td><p>CLINO</p></td>
</tr>
<tr class="row-odd"><td><p>BACKLENGTH</p></td>
<td><p>BACKTAPE</p></td>
</tr>
<tr class="row-even"><td><p>BACKBEARING</p></td>
<td><p>BACKCOMPASS</p></td>
</tr>
<tr class="row-odd"><td><p>BACKGRADIENT</p></td>
<td><p>BACKCLINO</p></td>
</tr>
<tr class="row-even"><td><p>COUNT</p></td>
<td><p>COUNTER</p></td>
</tr>
<tr class="row-odd"><td><p>LEFT</p></td>
<td></td>
</tr>
<tr class="row-even"><td><p>RIGHT</p></td>
<td></td>
</tr>
<tr class="row-odd"><td><p>UP</p></td>
<td><p>CEILING</p></td>
</tr>
<tr class="row-even"><td><p>DOWN</p></td>
<td><p>FLOOR</p></td>
</tr>
<tr class="row-odd"><td><p>DEPTH</p></td>
<td></td>
</tr>
<tr class="row-even"><td><p>EASTING</p></td>
<td><p>DX</p></td>
</tr>
<tr class="row-odd"><td><p>NORTHING</p></td>
<td><p>DY</p></td>
</tr>
<tr class="row-even"><td><p>ALTITUDE</p></td>
<td><p>DZ</p></td>
</tr>
<tr class="row-odd"><td><p>DECLINATION</p></td>
<td></td>
</tr>
</tbody>
</table>
</div></blockquote>
<p>The specified calibration is applied to each quantity in the list, which is
handy if you use the same instrument to measure several things, for example:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*calibrate left right up down +0.1
</pre></div>
</div>
<p>You need to be careful about the sign of the ZeroError. Survex follows the
convention used with scientific instruments - the ZeroError is what the
instrument reads 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:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*CALIBRATE tape +0.3
</pre></div>
</div>
<p>If you tape was too long, starting at -20cm (it does happen!) then you can
correct it with:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*CALIBRATE tape -0.2
</pre></div>
</div>
<p>Note: ZeroError is irrelevant for Topofil counters and depth gauges since
pairs of readings are subtracted.</p>
<p>In the first form in the synopsis above, the zero error is measured by the
instrument itself (e.g. reading off the number where a truncated tape now
ends) and any scale factor specified applies to it, like so (Scale defaults
to 1.0):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Value = ( Reading - ZeroError ) * Scale
</pre></div>
</div>
<p>In the second form above (supported since Survex 1.2.21), the zero error has
been measured externally (e.g. measuring how much too long your tape is
with a ruler) - the units of the zero error are explicitly specified and
any scale factor is not applied to it:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Value = ( Reading * Scale ) - ZeroError
</pre></div>
</div>
<p>With the default scale factor of 1.0 the two forms are equivalent, though
they still allow you to document how the zero error has been determined.</p>
<p>With older Survex versions, you would specify the magnetic declination
(difference between True North and Magnetic North) by using <code class="docutils literal notranslate"><span class="pre">*calibrate</span>
<span class="pre">declination</span></code> to set an explicit value (with no scale factor allowed).
Since Survex 1.2.22, it’s recommended to instead use the new
<code class="docutils literal notranslate"><span class="pre">*declination</span></code> command instead - see the documentation of that command for
more details.</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*declination</span></code>, <code class="docutils literal notranslate"><span class="pre">*units</span></code></p>
</dd>
</dl>
</section>
<section id="case">
<h3>CASE<a class="headerlink" href="#case" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*case</span> <span class="pre">preserve</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*case</span> <span class="pre">toupper</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*case</span> <span class="pre">tolower</span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*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
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*case</span></code> 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 <code class="docutils literal notranslate"><span class="pre">2a</span></code> and <code class="docutils literal notranslate"><span class="pre">2A</span></code> will be regarded as different).</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*truncate</span></code></p>
</dd>
</dl>
</section>
<section id="copyright">
<h3>COPYRIGHT<a class="headerlink" href="#copyright" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*copyright</span> <span class="pre"><year></span> <span class="pre"><text></span></code>
<code class="docutils literal notranslate"><span class="pre">*copyright</span> <span class="pre"><year1>-<year2></span> <span class="pre"><text></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*begin littlebit
*copyright 1983 CUCC
1 2 10.23 106 -02
2 3 1.56 092 +10
*end littlebit
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*copyright 1976-2024 "CUCC Expo"
</pre></div>
</div>
</dd>
<dt>Validity</dt><dd><p>valid at the start of a <code class="docutils literal notranslate"><span class="pre">*begin</span></code>/<code class="docutils literal notranslate"><span class="pre">*end</span></code> block.</p>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*copyright</span></code> allows the copyright information to be recorded in a way that
can be automatically collated.</p>
<p>The date can be specified as a single year or a range of years. Two digit
years are not allowed and the end of the range can not be before the start.</p>
<p>The text is expected to identify the copyright holder - typically it will be
the name of a person or group. Unless it is a single word you should put
double quotes around it.</p>
<p>Prior to Survex 1.4.17 there weren’t any checks of the syntax. Essentially
<code class="docutils literal notranslate"><span class="pre">*copyright</span></code> used to be treated like a named comment line.</p>
<p>With Survex 1.4.17 and later you’ll get a warning for an empty
<code class="docutils literal notranslate"><span class="pre">*copyright</span></code>, for an invalid date, or if you open but fail to close double
quotes around the text.</p>
<p>These diagnostic messages were made warnings to avoid breaking processing
of existing datasets which might contain <code class="docutils literal notranslate"><span class="pre">*copyright</span></code> lines which don’t
conform with the defined syntax (especially as the format of the date and
text fields were not documented prior to 1.4.17).</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*begin</span></code></p>
</dd>
</dl>
</section>
<section id="cs">
<h3>CS<a class="headerlink" href="#cs" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*cs</span> <span class="pre"><coordinate</span> <span class="pre">system></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*cs</span> <span class="pre">out</span> <span class="pre"><coordinate</span> <span class="pre">system></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*cs UTM60S
*fix beehive 313800 5427953 20
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>; Output in the coordinate system used in the Totes Gebirge in Austria
*cs out custom "+proj=tmerc +lat_0=0 +lon_0=13d20 +k=1 +x_0=0 +y_0=-5200000 +ellps=bessel +towgs84=577.326,90.129,463.919,5.137,1.474,5.297,2.4232"
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*cs</span></code> allows the coordinate systems used for fixed points and for
processed survey data to be specified.</p>
<p>The “input” coordinate system is set with <code class="docutils literal notranslate"><span class="pre">*cs</span></code> and you can change it
between fixed points if you have some fixed points in different coordinate
systems to others.</p>
<p>The “output” coordinate system is set with <code class="docutils literal notranslate"><span class="pre">*cs</span> <span class="pre">out</span></code> and is what the
survey data is processed in and the coordinate system used for resultant
<code class="docutils literal notranslate"><span class="pre">.3d</span></code> file (which means Aven knows how to translate coordinates to allow
export to formats such as GPX and KML, and to overlay terrain data and other
geodata). The output coordinate system must be in metres with axis
order (East, North, Up), so for example <code class="docutils literal notranslate"><span class="pre">*cs</span> <span class="pre">out</span> <span class="pre">long-lat</span></code> isn’t valid
because it isn’t in metres, while <code class="docutils literal notranslate"><span class="pre">*cs</span> <span class="pre">out</span> <span class="pre">jtsk</span></code> isn’t valid because
the axes point West and South.</p>
<p><code class="docutils literal notranslate"><span class="pre">*cs</span></code> was added in Survex 1.2.14, but handling of fixed points specified
with latitude and longitude didn’t work until 1.2.21. Also <code class="docutils literal notranslate"><span class="pre">*fix</span></code> with
standard deviations specified also didn’t work until 1.2.21.</p>
<p>The currently supported coordinate systems are:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">EPSG:</span></code> followed by a positive integer code. EPSG codes cover most
coordinate systems in use. The website <a class="reference external" href="https://epsg.io/">https://epsg.io/</a> is a useful
resource for finding the EPSG code you want. For example, <code class="docutils literal notranslate"><span class="pre">EPSG:4167</span></code>
is NZGD2000. Supported since Survex 1.2.15.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CUSTOM</span></code> followed by a PROJ string (like in the example above).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ESRI:</span></code> followed by a positive integer code. ESRI codes are used by
ArcGIS to specify coordinate systems (in a similar way to EPSG codes)
and PROJ supports many of them. Supported since Survex 1.2.15.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">EUR79Z30</span></code> for UTM zone 30, EUR79 datum. Supported since Survex
1.2.15.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">IJTSK</span></code> for the modified version of the Czechoslovak S-JTSK system
where the axes point East and North. Supported since Survex 1.2.15.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">IJTSK03</span></code> for a variant of IJTSK. Supported since Survex 1.2.15.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">JTSK</span></code> for the Czechoslovak S-JTSK system. Its axes point West and
South, so it’s not supported as an output coordinate system. Supported
since Survex 1.2.16.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">JTSK03</span></code> for a variant of JTSK. Supported since Survex 1.2.16.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">LONG-LAT</span></code> for longitude/latitude. The WGS84 datum is assumed.
NB <code class="docutils literal notranslate"><span class="pre">*fix</span></code> expects the coordinates in the order x,y,z which means
longitude (i.e. E/W), then latitude (i.e. N/S), then altitude.
Supported since Survex 1.2.15.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">OSGB:</span></code> followed by a two letter code for the UK Ordnance Survey
National Grid. The first letter should be ‘H’, ‘N’, ‘O’, ‘S’ or ‘T’;
the second any letter except ‘I’. For example, <code class="docutils literal notranslate"><span class="pre">OSGB:SD</span></code>. Supported
since Survex 1.2.15.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">S-MERC</span></code> for the “Web Mercator” spherical mercator projection, used by
online map sites like OpenStreetMap, Google maps, Bing maps, etc.
Supported since Survex 1.2.15.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">UTM</span></code> followed by a zone number (1-60), optionally followed
by “N” or “S” specifying the hemisphere (default is North). The WGS84
datum is assumed. A potential source of confusion here is the
<a class="reference external" href="https://en.wikipedia.org/wiki/Military_Grid_Reference_System">Military Grid Reference System</a>
which divides each UTM zone into latitude bands represented by a
letter suffix, so here 33S and 33N have different meanings to those
in Survex - they are both parts of UTM zone 33, but both are in the
Northern hemisphere (33S is around Sicily, 33N around Cameroon).
To use such coordinates in Survex, replace suffixes “C” to “M” with “S”,
and “N” to “X” with “N”.</p></li>
</ul>
<p>By default, Survex works in an unspecified coordinate system (and this was
the only option before <code class="docutils literal notranslate"><span class="pre">*cs</span></code> was added). However, it’s useful for the
coordinate system which the processed survey data is in to be specified if
you want to use the processed data in ways which required knowing the
coordinate system (such as exporting a list of entrances for use in a
GPS). You can now do this by using <code class="docutils literal notranslate"><span class="pre">*cs</span> <span class="pre">out</span></code>.</p>
<p>It is also useful to be able to take coordinates for fixed points in
whatever coordinate system you receive them in and put them directly into
Survex, rather than having to convert with an external tool. For example,
you may have your GPS set to show coordinates in UTM with the WGS84 datum,
even though you want the processed data to be in some local coordinate
system. Someone else may provide GPS coordinates in yet another
coordinate system. You just need to set the appropriate coordinate system
with <code class="docutils literal notranslate"><span class="pre">*cs</span></code> before each group of <code class="docutils literal notranslate"><span class="pre">*fix</span></code> commands in a particular
coordinate system.</p>
<p>If you’re going to make use of <code class="docutils literal notranslate"><span class="pre">*cs</span></code>, then a coordinate system must be
specified for everything, so a coordinate system must be in effect for all
<code class="docutils literal notranslate"><span class="pre">*fix</span></code> commands, and you must set the output coordinate system before
any points are fixed.</p>
<p>Also, if <code class="docutils literal notranslate"><span class="pre">*cs</span></code> is in use, then you can’t omit the coordinates in a
<code class="docutils literal notranslate"><span class="pre">*fix</span></code> command, and a fixed point won’t be invented if none exists.</p>
<p>If you use <code class="docutils literal notranslate"><span class="pre">*cs</span> <span class="pre">out</span></code> more than once, the second and subsequent commands
are silently ignored - this makes it possible to combine two datasets with
different <code class="docutils literal notranslate"><span class="pre">*cs</span> <span class="pre">out</span></code> settings without having to modify either of them.</p>
<p>Something to be aware of with <code class="docutils literal notranslate"><span class="pre">*cs</span></code> is that altitudes are currently
assumed to be “height above the ellipsoid”, whereas GPS units typically
give you “height above sea level”, or more accurately “height above a
particular geoid”. This is something we’re looking at how best to
address, but you shouldn’t need to worry about it if your fixed points are
in the same coordinate system as your output, or if they all use the same
ellipsoid. For a more detailed discussion of this, please see:
<a class="reference external" href="https://expo.survex.com/handbook/survey/coord.htm">https://expo.survex.com/handbook/survey/coord.htm</a></p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*declination</span> <span class="pre">auto</span></code>, <code class="docutils literal notranslate"><span class="pre">*fix</span></code></p>
</dd>
</dl>
</section>
<section id="data">
<h3>DATA<a class="headerlink" href="#data" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*data</span> <span class="pre"><style></span> <span class="pre"><ordering></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*data</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*data</span> <span class="pre">default</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*data</span> <span class="pre">ignore</span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data normal from to compass tape clino
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data normal station ignoreall newline compass tape clino
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre"><style></span></code></dt><dd><p><code class="docutils literal notranslate"><span class="pre">NORMAL|DIVING|CARTESIAN|TOPOFIL|CYLPOLAR|NOSURVEY|PASSAGE</span></code></p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre"><ordering></span></code></dt><dd><p>ordered list of instruments - which are valid depends on the style.</p>
</dd>
</dl>
<p>In Survex 1.0.2 and later, <code class="docutils literal notranslate"><span class="pre">TOPOFIL</span></code> is simply a synonym for <code class="docutils literal notranslate"><span class="pre">NORMAL</span></code>,
left in to allow older data to be processed without modification. Use the
name <code class="docutils literal notranslate"><span class="pre">NORMAL</span></code> by preference.</p>
<p>Most of the styles support two variants - interleaved and non-interleaved.
Non-interleaved is “one line per leg”, interleaved has a line for the data
shared between two legs (e.g. <code class="docutils literal notranslate"><span class="pre">STATION</span></code>:<code class="docutils literal notranslate"><span class="pre">FROM</span></code>/<code class="docutils literal notranslate"><span class="pre">TO</span></code>,
<code class="docutils literal notranslate"><span class="pre">DEPTH</span></code>:<code class="docutils literal notranslate"><span class="pre">FROMDEPTH</span></code>/<code class="docutils literal notranslate"><span class="pre">TODEPTH</span></code>, <code class="docutils literal notranslate"><span class="pre">COUNT</span></code>:<code class="docutils literal notranslate"><span class="pre">FROMCOUNT</span></code>/<code class="docutils literal notranslate"><span class="pre">TOCOUNT</span></code>).
Note that not all readings that can be shared have to be, for example here
the to/from station name is shared but the depth gauge readings aren’t:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data diving station newline fromdepth compass tape todepth
</pre></div>
</div>
<p>In addition, interleaved data can have a <code class="docutils literal notranslate"><span class="pre">DIRECTION</span></code> reading, which can
be <code class="docutils literal notranslate"><span class="pre">F</span></code> for a foresight or <code class="docutils literal notranslate"><span class="pre">B</span></code> for a backsight (meaning the direction of
the leg is reversed).</p>
<p>In interleaved data, a blank line (one which contains only characters
which are set as <code class="docutils literal notranslate"><span class="pre">BLANK</span></code>) ends the current traverse so can be used to
handle branches in the survey, e.g.:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data normal station newline tape compass clino
1
9.34 087 -05
2
; single leg up unexplored side passage
4.30 002 +06
3
2
; and back to the main package
6.29 093 -02
4
</pre></div>
</div>
<p>In data styles which include a <code class="docutils literal notranslate"><span class="pre">TAPE</span></code> reading (i.e. <code class="docutils literal notranslate"><span class="pre">NORMAL</span></code>,
<code class="docutils literal notranslate"><span class="pre">DIVING</span></code>, and <code class="docutils literal notranslate"><span class="pre">CYLPOLAR</span></code> data styles), <code class="docutils literal notranslate"><span class="pre">TAPE</span></code> may be replaced by
<code class="docutils literal notranslate"><span class="pre">FROMCOUNT</span></code>/<code class="docutils literal notranslate"><span class="pre">TOCOUNT</span></code> (or <code class="docutils literal notranslate"><span class="pre">COUNT</span></code> in interleaved data) to allow
processing of surveys performed with a Topofil instead of a tape.</p>
<p>In Survex 1.2.44 and later, you can use <code class="docutils literal notranslate"><span class="pre">*data</span></code> without any arguments to
keep the currently set data style, but resetting any state. This is useful
when you’re entering passage tubes with branches - see the
description of the <code class="docutils literal notranslate"><span class="pre">PASSAGE</span></code> style below. (This feature was originally
added in 1.2.31, but was buggy until 1.2.44 - any data up to the next
<code class="docutils literal notranslate"><span class="pre">*data</span></code> gets quietly ignored.)</p>
<dl>
<dt>DEFAULT</dt><dd><p>Select the default data style and ordering (<code class="docutils literal notranslate"><span class="pre">NORMAL</span></code> style, ordering:
<code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">to</span> <span class="pre">tape</span> <span class="pre">compass</span> <span class="pre">clino</span></code>).</p>
</dd>
<dt>IGNORE</dt><dd><p>Ignores survey data until another <code class="docutils literal notranslate"><span class="pre">*data</span></code> command sets a different
style, or until the end of the enclosing <code class="docutils literal notranslate"><span class="pre">*begin</span></code>…<code class="docutils literal notranslate"><span class="pre">*end</span></code> block.
Note that commands are still processed, only survey data is ignored.
This is useful if you have some survey data which has been superseded by
a better survey of the same passage, but you want to keep the superseded
data around, just not process it. Added in Survex 1.4.11.</p>
</dd>
<dt>NORMAL</dt><dd><p>The usual tape/compass/clino centreline survey. For non-interleaved data
the allowed readings are: <code class="docutils literal notranslate"><span class="pre">FROM</span></code> <code class="docutils literal notranslate"><span class="pre">TO</span></code> <code class="docutils literal notranslate"><span class="pre">TAPE</span></code> <code class="docutils literal notranslate"><span class="pre">COMPASS</span></code> <code class="docutils literal notranslate"><span class="pre">CLINO</span></code>
<code class="docutils literal notranslate"><span class="pre">BACKTAPE</span></code> <code class="docutils literal notranslate"><span class="pre">BACKCOMPASS</span></code> <code class="docutils literal notranslate"><span class="pre">BACKCLINO</span></code>; for interleaved data the
allowed readings are: <code class="docutils literal notranslate"><span class="pre">STATION</span></code> <code class="docutils literal notranslate"><span class="pre">DIRECTION</span></code> <code class="docutils literal notranslate"><span class="pre">TAPE</span></code> <code class="docutils literal notranslate"><span class="pre">COMPASS</span></code>
<code class="docutils literal notranslate"><span class="pre">CLINO</span></code> <code class="docutils literal notranslate"><span class="pre">BACKTAPE</span></code> <code class="docutils literal notranslate"><span class="pre">BACKCOMPASS</span></code> <code class="docutils literal notranslate"><span class="pre">BACKCLINO</span></code>.</p>
<p><code class="docutils literal notranslate"><span class="pre">BACKTAPE</span></code> was added in Survex 1.2.25.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">CLINO</span></code>/<code class="docutils literal notranslate"><span class="pre">BACKCLINO</span></code> reading is not required - if it is omitted
in the <code class="docutils literal notranslate"><span class="pre">*data</span></code> command then the vertical standard deviation is taken to
be proportional to the tape measurement for all reading. Alternatively,
if the reading is included in the <code class="docutils literal notranslate"><span class="pre">*data</span></code> command then individual clino
readings can be given as <code class="docutils literal notranslate"><span class="pre">OMIT</span></code> (default <code class="docutils literal notranslate"><span class="pre">-</span></code>) and will be treated in
this way, which allows for data where only some clino readings are
missing.</p>
<p>Examples of style <code class="docutils literal notranslate"><span class="pre">NORMAL</span></code>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data normal from to compass clino tape
1 2 172 -03 12.61
2 3 202 - 8.59 ; clino not recorded
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data normal station newline direction tape compass clino
1
F 12.61 172 -03
2
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data normal from to compass clino fromcount tocount
1 2 172 -03 11532 11873
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data normal station count newline direction compass clino
1 11532
F 172 -03
2 11873
</pre></div>
</div>
<dl>
<dt>DIVING</dt><dd><p>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
survey where the altitude is measured with an altimeter. <code class="docutils literal notranslate"><span class="pre">DEPTH</span></code> is
defined as the altitude (Z) so increases upwards by default. So for a
diver’s depth gauge, you’ll need to use <code class="docutils literal notranslate"><span class="pre">*CALIBRATE</span></code> with a negative
scale factor (e.g. <code class="docutils literal notranslate"><span class="pre">*calibrate</span> <span class="pre">depth</span> <span class="pre">0</span> <span class="pre">-1</span></code>).</p>
<p>For non-interleaved data the allowed readings are: <code class="docutils literal notranslate"><span class="pre">FROM</span></code> <code class="docutils literal notranslate"><span class="pre">TO</span></code>
<code class="docutils literal notranslate"><span class="pre">TAPE</span></code> <code class="docutils literal notranslate"><span class="pre">COMPASS</span></code> <code class="docutils literal notranslate"><span class="pre">CLINO</span></code> <code class="docutils literal notranslate"><span class="pre">BACKTAPE</span></code> <code class="docutils literal notranslate"><span class="pre">BACKCOMPASS</span></code>
<code class="docutils literal notranslate"><span class="pre">BACKCLINO</span></code> <code class="docutils literal notranslate"><span class="pre">FROMDEPTH</span></code> <code class="docutils literal notranslate"><span class="pre">TODEPTH</span></code> <code class="docutils literal notranslate"><span class="pre">DEPTHCHANGE</span></code> (the vertical
can be given as readings at each station, (<code class="docutils literal notranslate"><span class="pre">FROMDEPTH</span></code>/<code class="docutils literal notranslate"><span class="pre">TODEPTH</span></code>)
or as a change along the leg (<code class="docutils literal notranslate"><span class="pre">DEPTHCHANGE</span></code>)).</p>
<p><code class="docutils literal notranslate"><span class="pre">BACKTAPE</span></code> was added in Survex 1.2.25.</p>
<p>For interleaved data the allowed readings are: <code class="docutils literal notranslate"><span class="pre">STATION</span></code>
<code class="docutils literal notranslate"><span class="pre">DIRECTION</span></code> <code class="docutils literal notranslate"><span class="pre">TAPE</span></code> <code class="docutils literal notranslate"><span class="pre">COMPASS</span></code> <code class="docutils literal notranslate"><span class="pre">BACKTAPE</span></code> <code class="docutils literal notranslate"><span class="pre">BACKCOMPASS</span></code>
<code class="docutils literal notranslate"><span class="pre">DEPTH</span></code> <code class="docutils literal notranslate"><span class="pre">DEPTHCHANGE</span></code>. The vertical change can be given as a
reading at the station (<code class="docutils literal notranslate"><span class="pre">DEPTH</span></code>) or as a change along the leg
(<code class="docutils literal notranslate"><span class="pre">DEPTHCHANGE</span></code>):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data diving from to tape compass fromdepth todepth
1 2 14.7 250 -20.7 -22.4
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data diving station depth newline tape compass
1 -20.7
14.7 250
2 -22.4
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data diving from to tape compass depthchange
1 2 14.7 250 -1.7
</pre></div>
</div>
<p>Survex 1.2.20 and later allow an optional <code class="docutils literal notranslate"><span class="pre">CLINO</span></code> and/or
<code class="docutils literal notranslate"><span class="pre">BACKCLINO</span></code> reading in <code class="docutils literal notranslate"><span class="pre">DIVING</span></code> style. At present these extra
readings are checked for syntactic validity, but are otherwise
ignored. The intention is that a future version will check them
against the other readings to flag up likely blunders, and average
with the slope data from the depth gauge and tape reading.</p>
</dd>
<dt>CARTESIAN</dt><dd><p>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.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data cartesian from to northing easting altitude
1 2 16.1 20.4 8.7
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data cartesian station newline northing easting altitude
1
16.1 20.4 8.7
2
</pre></div>
</div>
<p>By default, the North used is True North, but you can specify to use
Magnetic or Grid North (in the input coordinate system) with the
<code class="docutils literal notranslate"><span class="pre">*cartesian</span></code> command, and also specify an additional rotation to
apply (since Survex 1.4.10).</p>
<p>In Survex < 1.4.10, if <code class="docutils literal notranslate"><span class="pre">*cs</span></code> was used then cartesian data were
incorrectly interpreted as relative to Grid North in the output
coordinate system (if <code class="docutils literal notranslate"><span class="pre">*cs</span></code> is not used then Grid North in the
default unspecified coordinate system is the same as True North).</p>
</dd>
<dt>CYLPOLAR</dt><dd><p>A <code class="docutils literal notranslate"><span class="pre">CYLPOLAR</span></code> 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.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data cylpolar from to tape compass fromdepth todepth
1 2 9.45 311 -13.3 -19.0
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data cylpolar station depth newline tape compass
1 -13.3
9.45 311
2 -19.0
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data cylpolar from to tape compass depthchange
1 2 9.45 311 -5.7
</pre></div>
</div>
</dd>
<dt>NOSURVEY</dt><dd><p>A <code class="docutils literal notranslate"><span class="pre">NOSURVEY</span></code> survey doesn’t have any measurements - it merely
indicates that there is line of sight between the pairs of stations.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data nosurvey from to
1 7
5 7
9 11
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data nosurvey station
1
7
5
*data
9
11
</pre></div>
</div>
</dd>
<dt>PASSAGE</dt><dd><p>This survey style defines a 3D “tube” modelling a passage in the cave.
The tube joins the survey stations listed in the order listed. It’s
permitted to go between survey stations which aren’t directly linked
by the centre-line survey. This can be useful - sometimes the
centreline will step sideways or up/down to allow a better sight for
the next leg and you can ignore the extra station. You can also
define tubes along unsurveyed passages, akin to “nosurvey” legs in the
centreline data.</p>
<p>This means that you need to split off side passages into separate
tubes, and hence separate sections of passage data, starting with a
new <code class="docutils literal notranslate"><span class="pre">*data</span></code> command with no arguments.</p>
<p>Simple example of how to use this data style (note the use of
ignoreall to allow a free-form text description to be given):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data passage station left right up down ignoreall
1 0.1 2.3 8.0 1.4 Sticking out point on left wall
2 0.0 1.9 9.0 0.5 Point on left wall
3 1.0 0.7 9.0 0.8 Highest point of boulder
</pre></div>
</div>
<p>Each <code class="docutils literal notranslate"><span class="pre">*data</span> <span class="pre">passage</span></code> data block describes a single continuous tube -
to break a tube or to enter a side passage you need to have a second
block. With Survex 1.2.30 and older, you had to repeat the entire
<code class="docutils literal notranslate"><span class="pre">*data</span> <span class="pre">passage</span></code> line to start a new tube, but in Survex 1.2.31 and
later, you can just use <code class="docutils literal notranslate"><span class="pre">*data</span></code> without any arguments.</p>
<p>For example here the main passage is 1-2-3 and a side passage is 2-4:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*data passage station left right up down ignoreall
1 0.1 2.3 8.0 1.4 Sticking out point on left wall
2 0.0 1.9 9.0 0.5 Point on left wall opposite side passage
3 1.0 0.7 9.0 0.8 Highest point of boulder
; If you need to be compatible with Survex 1.2.30 or earlier
; you need to repeat the full "*data" command here instead.
*data
2 0.3 0.2 9.0 0.5
4 0.0 0.5 6.5 1.5 Fossil on left wall
</pre></div>
</div>
</dd>
</dl>
</dd>
</dl>
<p><code class="docutils literal notranslate"><span class="pre">IGNORE</span></code> skips a field (it may be used any number of times), and
<code class="docutils literal notranslate"><span class="pre">IGNOREALL</span></code> may be used last to ignore the rest of the data line.</p>
<p><code class="docutils literal notranslate"><span class="pre">LENGTH</span></code> is a synonym for <code class="docutils literal notranslate"><span class="pre">TAPE</span></code>; <code class="docutils literal notranslate"><span class="pre">BEARING</span></code> for <code class="docutils literal notranslate"><span class="pre">COMPASS</span></code>;
<code class="docutils literal notranslate"><span class="pre">GRADIENT</span></code> for <code class="docutils literal notranslate"><span class="pre">CLINO</span></code>; <code class="docutils literal notranslate"><span class="pre">COUNT</span></code> for <code class="docutils literal notranslate"><span class="pre">COUNTER</span></code>.</p>
<p>The units of each quantity may be set with the <code class="docutils literal notranslate"><span class="pre">*units</span></code> command.</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*units</span></code></p>
</dd>
</dl>
</section>
<section id="date">
<h3>DATE<a class="headerlink" href="#date" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*date</span> <span class="pre"><date</span> <span class="pre">type(s)></span> <span class="pre"><ISO</span> <span class="pre">date></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*date</span> <span class="pre"><date</span> <span class="pre">type(s)></span> <span class="pre"><ISO</span> <span class="pre">date1></span> <span class="pre"><ISO</span> <span class="pre">date2></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*date</span> <span class="pre"><ISO</span> <span class="pre">date></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*date</span> <span class="pre"><ISO</span> <span class="pre">date1></span> <span class="pre"><ISO</span> <span class="pre">date2></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*date</span> <span class="pre"><legacy</span> <span class="pre">date></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*date</span> <span class="pre"><legacy</span> <span class="pre">date1>-<legacy</span> <span class="pre">date2></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*date explored 1987-06-20 1987-06-28
*date surveyed 1987-07-11
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*date explored surveyed 2024-11-29
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*date 1976-08
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*date 1968
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*date 1987.07.27
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*date 1985.08.12-1985.08.13
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*date 2000.10
</pre></div>
</div>
</dd>
<dt>Validity</dt><dd><p>valid at the start of a <code class="docutils literal notranslate"><span class="pre">*begin</span></code>/<code class="docutils literal notranslate"><span class="pre">*end</span></code> block.</p>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*date</span></code> specifies the date that the survey was done. A range of dates can
be specified (e.g. for “surveyed” date, this is useful for overnight or
multi-day surveying trips).</p>
<p>Date components must be in the order year then month then day. Later
components can be omitted to specify the date to the granularity of a month
or year (which is sometimes useful for older survey data where the exact
date of a survey may no longer be known). Such partial dates are treated
as a date range for that whole month or year; if used in a date range, the
appropriate extreme of the year or month is used as that end of the range -
e.g. <code class="docutils literal notranslate"><span class="pre">2001</span> <span class="pre">2004-06</span></code> is from the start of 2001 to the end of June 2004.</p>
<p>Survex 1.4.13 added support for date types <code class="docutils literal notranslate"><span class="pre">explored</span></code> and <code class="docutils literal notranslate"><span class="pre">surveyed</span></code>
(<code class="docutils literal notranslate"><span class="pre">*date</span></code> without a type is assumed to be specifying the <code class="docutils literal notranslate"><span class="pre">surveyed</span></code> date
only).</p>
<p>Survex 1.4.13 also added support for the ISO date format, where the
separator between components is <code class="docutils literal notranslate"><span class="pre">-</span></code>. In older versions the separator
between components had to be <code class="docutils literal notranslate"><span class="pre">.</span></code> (with <code class="docutils literal notranslate"><span class="pre">-</span></code> used between dates in a
range). The older date format is still accepted, but we strongly recommend
using ISO format dates in new data because it’s a standardised date format.</p>
<p>We recommend avoiding two digit years because of the inherent ambiguity, but
they are accepted (with a warning) and assumed to be 19xx.</p>
<p>Currently dates before 1900 and after 2078 result in a warning and are
ignored.</p>
<p>A date which is in the future in the local timezone will also be warned
about to help catch date errors. This warning could be incorrectly
triggered if you surveyed some data and promptly sent it to somebody in a
timezone behind yours - e.g. American Samoa (UTC-11) is always a day behind
Samoa (UTC+13). This could be avoided by making the threshold for the
warning less tight (e.g. add a day or interpret today’s date as “anywhere on
Earth”), but then we could fail to warn when locally processed data you’ve
just entered with tomorrow’s date which seems worse than an incorrect
warning in an unusual case which will go away after less than a day.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">explored</span></code> date is parsed but not currently stored anywhere. A future
version will write it to the <code class="docutils literal notranslate"><span class="pre">.3d</span></code> file and make it available to aven, etc.</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*begin</span></code>, <code class="docutils literal notranslate"><span class="pre">*instrument</span></code>, <code class="docutils literal notranslate"><span class="pre">*team</span></code></p>
</dd>
</dl>
</section>
<section id="declination">
<h3>DECLINATION<a class="headerlink" href="#declination" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*declination</span> <span class="pre">auto</span> <span class="pre"><x></span> <span class="pre"><y></span> <span class="pre"><z></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*declination</span> <span class="pre"><declination></span> <span class="pre"><units></span></code></p>
</dd>
<dt>Description</dt><dd><p>The <code class="docutils literal notranslate"><span class="pre">*declination</span></code> command is the modern way to specify magnetic
declinations in Survex. It was added in Survex 1.2.21 but buggy so not
really usable until 1.2.22.</p>
<p>Magnetic declination is the difference between Magnetic North and True
North. A compass measures an angle relative to Magnetic North
- adding the magnetic declination gives bearings relative to True North.
The magnetic declination varies with location and also with time as the
Earth’s magnetic field moves.</p>
<p>Generally it’s best to specify a suitable output coordinate system, and use
<code class="docutils literal notranslate"><span class="pre">*declination</span> <span class="pre">auto</span></code> so Survex corrects for magnetic declination for you.
Survex 1.2.27 and later will also automatically correct for grid convergence
(the difference between Grid North and True North).</p>
<p>If you don’t specify an output coordinate system, but fix one or more points
then Survex works implicitly in the coordinate system your fixed points were
specified in. This mode of operation is provided for compatibility with
datasets from before support for explicit coordinate systems was added to
Survex - it’s much better to specify the output coordinate system as above.
But if you have a survey of a cave which isn’t connected to any known fixed
points then you’ll need to handle it this way, either fixing an entrance to
some arbitrary coordinates (probably (0,0,0)) or letting Survex pick a
station as the origin. If the survey was all done in a short enough period
of time that the magnetic declination won’t have changed significantly, you
can just ignore it and Grid North in the implicit coordinate system will be
Magnetic North at the time of the survey. If you want to correct
for magnetic declination, you can’t use <code class="docutils literal notranslate"><span class="pre">*declination</span> <span class="pre">auto</span></code> because the
IGRF model needs the real world coordinates, but you can specify literal
declination values for each survey using <code class="docutils literal notranslate"><span class="pre">*declination</span> <span class="pre"><declination></span>
<span class="pre"><units></span></code>. Then Grid North in the implicit coordinate system is True North.</p>
<p>Prior to 1.2.21, <code class="docutils literal notranslate"><span class="pre">*calibrate</span> <span class="pre">declination</span></code> was used instead. If you use a
mixture of <code class="docutils literal notranslate"><span class="pre">*calibrate</span> <span class="pre">declination</span></code> and <code class="docutils literal notranslate"><span class="pre">*declination</span></code>, they interact in
the natural way - whichever was set most recently is used for each compass
reading (taking into account survey scope). We don’t generally recommend
mixing the two, but it’s useful to understand how they interact if you want
to combine datasets using the old and new commands, or if you have a large
existing dataset and want to migrate it without having to change everything
at once.</p>
<p>Note that the value specified uses the conventional sign for magnetic
declination, unlike the old <code class="docutils literal notranslate"><span class="pre">*calibrate</span> <span class="pre">declination</span></code> which needed a value
with the opposite sign (because <code class="docutils literal notranslate"><span class="pre">*calibrate</span></code> specifies a zero error), so
take care when updating old data, or if you’re used to the semantics of
<code class="docutils literal notranslate"><span class="pre">*calibrate</span> <span class="pre">declination</span></code>.</p>
<p>When <code class="docutils literal notranslate"><span class="pre">*declination</span> <span class="pre">auto</span></code> is used cavern uses the IGRF (International
Geomagnetic Reference Field) model to compute magnetic declinations. A
revised version of the IGRF model is usually issued every 5 years, and
calculates values using a model based on observations for years
before it is issued, and on predictions for 5 years after it is issued.</p>
<p>Here’s a table of the first Survex version to support each version of the
IGRF model:</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>IGRF Version</p></th>
<th class="head"><p>Survex version</p></th>
<th class="head"><p>Survex version release date</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>14</p></td>
<td><p>1.4.13</p></td>
<td><p>2024-12-01</p></td>
</tr>
<tr class="row-odd"><td><p>13</p></td>
<td><p>1.2.43</p></td>
<td><p>2020-02-28</p></td>
</tr>
<tr class="row-even"><td><p>12</p></td>
<td><p>1.2.21</p></td>
<td><p>2015-07-28</p></td>
</tr>
</tbody>
</table>
<p>The IGRF model takes a date and a location as inputs. Survex uses the
specified date of the survey (if the survey’s date is a range, the centre
of that range is used), and uses the “x y z” coordinates specified in
the <code class="docutils literal notranslate"><span class="pre">*declination</span> <span class="pre">auto</span></code> command as the location in the current input
coordinate system (as set by <code class="docutils literal notranslate"><span class="pre">*cs</span></code>). Most users can just specify a single
representative location somewhere in the area of the cave. If you’re not
sure what to use, pick some coordinates roughly in the middle of the
bounding box of the cave - it doesn’t need to be a fixed point or a known
refindable location, though it can be if you prefer.</p>
<p>You might wonder why Survex needs a representative location instead of
calculating the magnetic declination and grid convergence for the actual
position of each survey station. The reason is that we need to adjust the
compass bearings before we can solve the network to find survey station
locations. Both magnetic declination and grid convergence don’t generally
vary significantly over the area of a typical cave system - if you are
mapping a very large cave system, or caves over a wide area, or are working
close to a magnetic pole or where the output coordinate system is rather
distorted, then you can specify <code class="docutils literal notranslate"><span class="pre">*declination</span> <span class="pre">auto</span></code> several times with
different representative locations for different areas of the cave system -
the one currently in effect is used for each survey leg.</p>
<p>For each <code class="docutils literal notranslate"><span class="pre">*declination</span> <span class="pre">auto</span></code> command cavern will (since Survex 1.4.2)
report the range of calculated declination values and the dates at which the
ends of the range were obtained, and also the grid convergence (which
doesn’t vary with time). This appears in the log - if you processed the
data with aven you can view this by using “File->View Log”. It looks like
this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>1623.svx:20: info: Declination: -0.4° @ 1977-07-02 / 3.8° @ 2018-07-21, grid convergence: -0.9°
*declination auto 36670.37 83317.43 1903.97
</pre></div>
</div>
<p>It also (since Survex 1.4.16) reports the approximate true range of
convergence values - by comparing this with the reported convergence values
for the representative locations you can see if you might need to add more.
This looks like:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Approximate full range of grid convergence: -0.9° at 1626.5.1 to -0.8° at 1624.133.1-6
</pre></div>
</div>
<p>This is “approximate” because it’s only computed for the North-most,
South-most, East-most and West-most stations and it’s possible the actual
minimum or maximum not at one of these. It’s unlikely to be much outside
the reported range though.</p>
<p>We don’t (currently) attempt to report a similar range for declination
values (it’s harder to do because declination also varies by date).</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*calibrate</span></code>, <code class="docutils literal notranslate"><span class="pre">*cs</span></code></p>
</dd>
</dl>
</section>
<section id="default">
<h3>DEFAULT<a class="headerlink" href="#default" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*default</span> <span class="pre">calibrate</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*default</span> <span class="pre">data</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*default</span> <span class="pre">units</span></code></p>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*default</span></code> restores defaults for given settings. This command is
deprecated - you should instead use: <code class="docutils literal notranslate"><span class="pre">*calibrate</span> <span class="pre">default</span></code>, <code class="docutils literal notranslate"><span class="pre">*data</span>
<span class="pre">default</span></code>, <code class="docutils literal notranslate"><span class="pre">*units</span> <span class="pre">default</span></code>.</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*calibrate</span></code>, <code class="docutils literal notranslate"><span class="pre">*data</span></code>, <code class="docutils literal notranslate"><span class="pre">*units</span></code></p>
</dd>
</dl>
</section>
<section id="end">
<h3>END<a class="headerlink" href="#end" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*end</span> <span class="pre"><survey></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*end</span></code></p>
</dd>
<dt>Validity</dt><dd><p>valid for closing a block started by <code class="docutils literal notranslate"><span class="pre">*begin</span></code> in the same file.</p>
</dd>
<dt>Description</dt><dd><p>Closes a block started by <code class="docutils literal notranslate"><span class="pre">*begin</span></code>.</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*begin</span></code></p>
</dd>
</dl>
</section>
<section id="entrance">
<h3>ENTRANCE<a class="headerlink" href="#entrance" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*entrance</span> <span class="pre"><station></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*entrance P163
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*entrance</span></code> marks a station as an entrance. This information is
used by aven to allow entrances to be highlighted.</p>
</dd>
</dl>
</section>
<section id="equate">
<h3>EQUATE<a class="headerlink" href="#equate" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*equate</span> <span class="pre"><station></span> <span class="pre"><station>...</span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*equate chosspot.1 triassic.27
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*equate</span></code> 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.</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*infer</span> <span class="pre">equates</span></code></p>
</dd>
</dl>
</section>
<section id="export">
<h3>EXPORT<a class="headerlink" href="#export" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*export</span> <span class="pre"><station>...</span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*export 1 6 17
</pre></div>
</div>
</dd>
<dt>Validity</dt><dd><p>valid at the start of a <code class="docutils literal notranslate"><span class="pre">*begin</span></code>/<code class="docutils literal notranslate"><span class="pre">*end</span></code> block.</p>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*export</span></code> 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.</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*begin</span></code>, <code class="docutils literal notranslate"><span class="pre">*infer</span> <span class="pre">exports</span></code></p>
</dd>
</dl>
</section>
<section id="fix">
<h3>FIX<a class="headerlink" href="#fix" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*fix</span> <span class="pre"><station></span> <span class="pre">[reference]</span> <span class="pre"><x></span> <span class="pre"><y></span> <span class="pre"><z></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*fix</span> <span class="pre"><station></span> <span class="pre">[reference]</span> <span class="pre"><x></span> <span class="pre"><y></span> <span class="pre"><z></span> <span class="pre"><std</span> <span class="pre">err></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*fix</span> <span class="pre"><station></span> <span class="pre">[reference]</span> <span class="pre"><x></span> <span class="pre"><y></span> <span class="pre"><z></span> <span class="pre"><horizontal</span> <span class="pre">std</span> <span class="pre">err></span> <span class="pre"><vertical</span> <span class="pre">std</span> <span class="pre">err></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*fix</span> <span class="pre"><station></span> <span class="pre">[reference]</span> <span class="pre"><x></span> <span class="pre"><y></span> <span class="pre"><z></span> <span class="pre"><x</span> <span class="pre">std</span> <span class="pre">err></span> <span class="pre"><y</span> <span class="pre">std</span> <span class="pre">err></span> <span class="pre"><z</span> <span class="pre">std</span> <span class="pre">err></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*fix</span> <span class="pre"><station></span> <span class="pre">[reference]</span> <span class="pre"><x></span> <span class="pre"><y></span> <span class="pre"><z></span> <span class="pre"><x</span> <span class="pre">std</span> <span class="pre">err></span> <span class="pre"><y</span> <span class="pre">std</span> <span class="pre">err></span> <span class="pre"><z</span> <span class="pre">std</span> <span class="pre">err></span> <span class="pre"><cov(x,y)></span> <span class="pre"><cov(y,z)></span> <span class="pre"><cov(z,x)></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*fix</span> <span class="pre"><station></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*fix entrance.0 32768 86723 1760
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*fix KT114_96 reference 36670.37 83317.43 1903.97
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*fix</span></code> fixes the position of <station> at the given coordinates. If you
haven’t specified the coordinate system with <code class="docutils literal notranslate"><span class="pre">*cs</span></code>, you can omit the
position and it will default to (0,0,0) which provides an easy way to
specify a point to arbitrarily fix rather than rely on <code class="docutils literal notranslate"><span class="pre">cavern</span></code> picking
one (which has the downsides of the choice potentially changing when more
survey data is added, and of triggering an “info” message).</p>
<p>The standard errors default to zero (fix station exactly). <code class="docutils literal notranslate"><span class="pre">cavern</span></code> 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.</p>
<p>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).</p>
<p>If you have covariances for the fix, you can also specify these - the order
is cov(x,y) cov(y,z) cov(z,x).</p>
<p>If you’ve specified a coordinate system (see <code class="docutils literal notranslate"><span class="pre">*cs</span></code>) then that determines
the meaning of X, Y and Z (if you want to specify the units for altitude,
note that using a PROJ string containing <code class="docutils literal notranslate"><span class="pre">+vunits</span></code> allows this - e.g.
<code class="docutils literal notranslate"><span class="pre">+vunits=us-ft</span></code> for US survey feet). If you don’t specify a coordinate
system, then the coordinates must be in metres. The standard deviations
must always be in metres (and the covariances in metres squared).</p>
<p>You can fix as many stations as you like - just use a <code class="docutils literal notranslate"><span class="pre">*fix</span></code> 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. If
there is unconnected survey data then you’ll get a warning (since Survex
1.4.10; in earlier versions this was an error) and only the connected data
is processed.</p>
<p>By default cavern will warn about stations which have been <code class="docutils literal notranslate"><span class="pre">*fix</span></code>-ed but
are not used otherwise, as this might be due to a typo in the station name.
Uses in survey data and (since 1.4.9) <code class="docutils literal notranslate"><span class="pre">*entrance</span></code> count for these
purposes. This warning 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 <code class="docutils literal notranslate"><span class="pre">reference</span></code> after the station name in the <code class="docutils literal notranslate"><span class="pre">*fix</span></code> command to
suppress this warning for a particular station. It’s OK to use
<code class="docutils literal notranslate"><span class="pre">reference</span></code> on a station which is used.</p>
<p>Since Survex 1.4.10 it’s an error to specify <code class="docutils literal notranslate"><span class="pre">reference</span></code> without
coordinates (e.g. <code class="docutils literal notranslate"><span class="pre">*fix</span> <span class="pre">a</span> <span class="pre">reference</span></code>) as this usage doesn’t really make
sense.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>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.</p>
</div>
</dd>
</dl>
</section>
<section id="flags">
<h3>FLAGS<a class="headerlink" href="#flags" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*flags</span> <span class="pre"><flags></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*flags duplicate not surface
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*flags</span></code> updates the currently set flags. Flags not mentioned retain
their previous state. Valid flags are <code class="docutils literal notranslate"><span class="pre">duplicate</span></code>, <code class="docutils literal notranslate"><span class="pre">splay</span></code>, and
<code class="docutils literal notranslate"><span class="pre">surface</span></code>, and a flag may be preceded with <code class="docutils literal notranslate"><span class="pre">not</span></code> to turn it off.</p>
<p>Survey legs marked <code class="docutils literal notranslate"><span class="pre">surface</span></code> are hidden from plots by default, and not
included in cave survey length calculations.</p>
<p>Survey legs marked as <code class="docutils literal notranslate"><span class="pre">duplicate</span></code> or <code class="docutils literal notranslate"><span class="pre">splay</span></code> are also not included in
cave survey length calculations; legs marked <code class="docutils literal notranslate"><span class="pre">splay</span></code> are ignored by the
extend program. <code class="docutils literal notranslate"><span class="pre">duplicate</span></code> 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); <code class="docutils literal notranslate"><span class="pre">splay</span></code> is intended for cases
such as radial legs in a large chamber, or to walls and other features with
a disto-x or similar device.</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*begin</span></code></p>
</dd>
</dl>
</section>
<section id="include">
<h3>INCLUDE<a class="headerlink" href="#include" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*include</span> <span class="pre"><filename></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*include mission
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*include "the pits"
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*include</span></code> processes <code class="docutils literal notranslate"><span class="pre"><filename></span></code> as if it were inserted at this place
in the current file - i.e. the current settings are carried into the included
file and any alterations to settings in the included file will be carried
back again. There’s one exception to this for historical reasons, which is
that the survey prefix is restored upon return to the original file. Since
<code class="docutils literal notranslate"><span class="pre">*begin</span></code> and <code class="docutils literal notranslate"><span class="pre">*end</span></code> nesting cannot cross files, this can only make a
difference if you use the deprecated <code class="docutils literal notranslate"><span class="pre">*prefix</span></code> command.</p>
<p>If the filename contains spaces, it must be enclosed in double quotes.</p>
<p>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).</p>
<p>The included file can be any filetype which cavern can process, so you can
<code class="docutils literal notranslate"><span class="pre">*include</span> <span class="pre">compassdata.mak</span></code>, <code class="docutils literal notranslate"><span class="pre">*include</span> <span class="pre">compassdata.dat</span></code>, <code class="docutils literal notranslate"><span class="pre">*include</span>
<span class="pre">wallsdata.wpj</span></code> or <code class="docutils literal notranslate"><span class="pre">*include</span> <span class="pre">wallsdata.srv</span></code> to allow processing
mixed-format datasets.</p>
<p>If the filename as specified is not found, cavern will try adding a <code class="docutils literal notranslate"><span class="pre">.svx</span></code>
extension, and will also try translating <code class="docutils literal notranslate"><span class="pre">\</span></code> to <code class="docutils literal notranslate"><span class="pre">/</span></code>.</p>
</dd>
</dl>
</section>
<section id="infer">
<h3>INFER<a class="headerlink" href="#infer" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*infer</span> <span class="pre">plumbs</span> <span class="pre">on</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*infer</span> <span class="pre">plumbs</span> <span class="pre">off</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*infer</span> <span class="pre">equates</span> <span class="pre">on</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*infer</span> <span class="pre">equates</span> <span class="pre">off</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*infer</span> <span class="pre">exports</span> <span class="pre">on</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*infer</span> <span class="pre">exports</span> <span class="pre">off</span></code></p>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*infer</span> <span class="pre">plumbs</span> <span class="pre">on</span></code> 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 you have data which uses this convention for plumbed legs.</p>
<p><code class="docutils literal notranslate"><span class="pre">*infer</span> <span class="pre">equates</span> <span class="pre">on</span></code> tells cavern to interpret a leg with a tape reading of
zero as a <code class="docutils literal notranslate"><span class="pre">*equate</span></code> which this prevents tape corrections being applied to
them. This is useful when you have data which uses this convention for
equating stations.</p>
<p><code class="docutils literal notranslate"><span class="pre">*infer</span> <span class="pre">exports</span> <span class="pre">on</span></code> is necessary when you have a dataset which is partly
annotated with <code class="docutils literal notranslate"><span class="pre">*export</span></code>. It tells cavern not to complain about missing
<code class="docutils literal notranslate"><span class="pre">*export</span></code> commands in the parts of the dataset it is enabled for. Also
stations which were used to join surveys are marked as exported in the 3d
file.</p>
</dd>
</dl>
</section>
<section id="instrument">
<h3>INSTRUMENT<a class="headerlink" href="#instrument" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*instrument</span> <span class="pre"><instrument></span> <span class="pre"><identifier></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*instrument compass "CUCC 2"
*instrument clino "CUCC 2"
*instrument tape "CUCC Fisco Ranger open reel"
</pre></div>
</div>
</dd>
<dt>Validity</dt><dd><p>valid at the start of a <code class="docutils literal notranslate"><span class="pre">*begin</span></code>/<code class="docutils literal notranslate"><span class="pre">*end</span></code> block.</p>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*instrument</span></code> specifies the particular instruments used to perform a
survey.</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*begin</span></code>, <code class="docutils literal notranslate"><span class="pre">*date</span></code>, <code class="docutils literal notranslate"><span class="pre">*team</span></code></p>
</dd>
</dl>
</section>
<section id="prefix">
<h3>PREFIX<a class="headerlink" href="#prefix" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*prefix</span> <span class="pre"><survey></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*prefix flapjack
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*prefix</span></code> sets the current survey.</p>
</dd>
<dt>Caveats</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*prefix</span></code> is deprecated - you should use <code class="docutils literal notranslate"><span class="pre">*begin</span></code> and <code class="docutils literal notranslate"><span class="pre">*end</span></code> instead.</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*begin</span></code>, <code class="docutils literal notranslate"><span class="pre">*end</span></code></p>
</dd>
</dl>
</section>
<section id="ref">
<h3>REF<a class="headerlink" href="#ref" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*ref</span> <span class="pre"><string></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*ref "survey folder 2007#12"
</pre></div>
</div>
</dd>
<dt>Validity</dt><dd><p>valid at the start of a <code class="docutils literal notranslate"><span class="pre">*begin</span></code>/<code class="docutils literal notranslate"><span class="pre">*end</span></code> block.</p>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*ref</span></code> allows you to specify a reference. If the reference contains
spaces, you must enclose it in double quotes. Survex doesn’t try to
interpret the reference in any way, so it’s up to you how you use it - for
example it could specify where the original survey notes can be found.</p>
<p><code class="docutils literal notranslate"><span class="pre">*ref</span></code> was added in Survex 1.2.23.</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*begin</span></code>, <code class="docutils literal notranslate"><span class="pre">*date</span></code>, <code class="docutils literal notranslate"><span class="pre">*instrument</span></code>, <code class="docutils literal notranslate"><span class="pre">*team</span></code></p>
</dd>
</dl>
</section>
<section id="require">
<h3>REQUIRE<a class="headerlink" href="#require" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*require</span> <span class="pre"><version></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span> *require 1.2.14 ; for *cs
::
*require 1.4 ; equivalent to 1.4.0
::
*require 1 ; equivalent to 1.0.0
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*require</span></code> checks that the version of cavern in use is at least
<code class="docutils literal notranslate"><span class="pre"><version></span></code> and stops with an error if not.</p>
<p>If your dataset requires a feature introduced in a particular version, you
can add a <code class="docutils literal notranslate"><span class="pre">*require</span></code> 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. We suggest noting the reason for the requirement in
a comment after the <code class="docutils literal notranslate"><span class="pre">*require</span></code> command, like in the first example above.</p>
</dd>
</dl>
</section>
<section id="sd">
<h3>SD<a class="headerlink" href="#sd" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*sd</span> <span class="pre"><quantity</span> <span class="pre">list></span> <span class="pre"><standard</span> <span class="pre">deviation></span> <span class="pre"><units></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*sd tape 0.15 metres
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*sd compass backcompass clino backclino 0.5 degrees
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*sd</span></code> specifies the standard deviation of a measurement.</p>
<p><code class="docutils literal notranslate"><span class="pre"><quantity></span></code> is one of (each group gives alternative names
for the same quantity):</p>
<ul class="simple">
<li><p>TAPE, LENGTH</p></li>
<li><p>BACKTAPE, BACKLENGTH (added in Survex 1.2.25)</p></li>
<li><p>COMPASS, BEARING</p></li>
<li><p>BACKCOMPASS, BACKBEARING</p></li>
<li><p>CLINO, GRADIENT</p></li>
<li><p>BACKCLINO, BACKGRADIENT</p></li>
<li><p>COUNTER, COUNT</p></li>
<li><p>DEPTH</p></li>
<li><p>DECLINATION</p></li>
<li><p>DX, EASTING</p></li>
<li><p>DY, NORTHING</p></li>
<li><p>DZ, ALTITUDE</p></li>
<li><p>LEFT</p></li>
<li><p>RIGHT</p></li>
<li><p>UP, CEILING</p></li>
<li><p>DOWN, FLOOR</p></li>
<li><p>LEVEL</p></li>
<li><p>PLUMB</p></li>
<li><p>POSITION</p></li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre"><standard</span> <span class="pre">deviation></span></code> is a positive real number, e.g. <code class="docutils literal notranslate"><span class="pre">0.05</span></code>.</p>
<p><code class="docutils literal notranslate"><span class="pre"><units></span></code> specifies the units, which must be appropriate for the
quantity or quantities in the list (e.g. <code class="docutils literal notranslate"><span class="pre">metres</span></code> for distance,
<code class="docutils literal notranslate"><span class="pre">degrees</span></code> for an angle). See <code class="docutils literal notranslate"><span class="pre">*units</span></code> below for full list of valid
units.</p>
<p>To utilise this command fully you need to understand what
a <em>standard deviation</em> 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, e.g. a tape SD of 0.25
metres means that the actual length of a tape measurement
is within ±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.</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*units</span></code></p>
</dd>
</dl>
</section>
<section id="set">
<h3>SET<a class="headerlink" href="#set" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*set</span> <span class="pre"><item></span> <span class="pre"><character</span> <span class="pre">list></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*set blank x09x20
*set decimal ,
</pre></div>
</div>
<p>This example sets the decimal separator to be a comma. Note that here we
need to eliminate comma from being a blank before setting it as a decimal -
otherwise the comma in <code class="docutils literal notranslate"><span class="pre">*set</span> <span class="pre">decimal</span> <span class="pre">,</span></code> is parsed as a blank, and cavern
sets decimal to not have any characters representing it.</p>
<p>Here’s an example of how to allow additional characters in station names:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*set names ?+_
</pre></div>
</div>
<p>After this <code class="docutils literal notranslate"><span class="pre">?</span></code>, <code class="docutils literal notranslate"><span class="pre">+</span></code> and <code class="docutils literal notranslate"><span class="pre">_</span></code> will be allowed in names (in addition to
characters A-Z, a-z and 0-9 which are always allowed). <code class="docutils literal notranslate"><span class="pre">*set</span></code> replaces
the previous setting so while <code class="docutils literal notranslate"><span class="pre">_</span></code> and <code class="docutils literal notranslate"><span class="pre">-</span></code> are both allowed by default,
<code class="docutils literal notranslate"><span class="pre">-</span></code> no longer is after this command because it isn’t in the list.</p>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*set</span></code> sets the specified <code class="docutils literal notranslate"><span class="pre"><item></span></code> to the character or characters given
in <code class="docutils literal notranslate"><span class="pre"><character</span> <span class="pre">list></span></code>.</p>
<p>The characters specified in <code class="docutils literal notranslate"><span class="pre"><character</span> <span class="pre">list></span></code> may not be alphanumeric
since these characters are used for station names and for readings.</p>
<p>In <code class="docutils literal notranslate"><span class="pre"><character</span> <span class="pre">list></span></code>, <code class="docutils literal notranslate"><span class="pre">x</span></code> followed by two hex digits means the
character with that hex value, e.g. <code class="docutils literal notranslate"><span class="pre">x20</span></code> is a space.</p>
<p>The complete list of items that can be set, the defaults (in brackets), and
the meaning of the item, is:</p>
<dl class="simple">
<dt>BLANK (<code class="docutils literal notranslate"><span class="pre">x09x20,</span></code>)</dt><dd><p>Separates fields</p>
</dd>
<dt>COMMENT (<code class="docutils literal notranslate"><span class="pre">;</span></code>)</dt><dd><p>The rest of the current line is a comment</p>
</dd>
<dt>DECIMAL (<code class="docutils literal notranslate"><span class="pre">.</span></code>)</dt><dd><p>Decimal point character</p>
</dd>
<dt>EOL (<code class="docutils literal notranslate"><span class="pre">x0Ax0D</span></code>)</dt><dd><p>End of line character</p>
</dd>
<dt>KEYWORD (<code class="docutils literal notranslate"><span class="pre">*</span></code>)</dt><dd><p>Introduces keywords</p>
</dd>
<dt>MINUS (<code class="docutils literal notranslate"><span class="pre">-</span></code>)</dt><dd><p>Indicates negative number</p>
</dd>
<dt>NAMES (<code class="docutils literal notranslate"><span class="pre">_-</span></code>)</dt><dd><p>Non-alphanumeric chars permitted in station names (letters and numbers
are always permitted).</p>
</dd>
<dt>OMIT (<code class="docutils literal notranslate"><span class="pre">-</span></code>)</dt><dd><p>Contents of field omitted (e.g. in plumbed legs)</p>
</dd>
<dt>PLUS (<code class="docutils literal notranslate"><span class="pre">+</span></code>)</dt><dd><p>Indicates positive number</p>
</dd>
<dt>ROOT (<code class="docutils literal notranslate"><span class="pre">\</span></code>)</dt><dd><p>Prefix in force at start of current file (use of <code class="docutils literal notranslate"><span class="pre">ROOT</span></code> is deprecated)</p>
</dd>
<dt>SEPARATOR (<code class="docutils literal notranslate"><span class="pre">.</span></code>)</dt><dd><p>Level separator in prefix hierarchy</p>
</dd>
</dl>
</dd>
</dl>
</section>
<section id="solve">
<h3>SOLVE<a class="headerlink" href="#solve" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*solve</span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*include 1997data
*solve
*include 1998data
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*solve</span></code> distributes misclosures around any loops in the survey (in the
same way that happens implicitly after reading all the data), then fixes
the positions of all existing stations.</p>
<p>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 <code class="docutils literal notranslate"><span class="pre">*solve</span></code> 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.</p>
</dd>
</dl>
</section>
<section id="team">
<h3>TEAM<a class="headerlink" href="#team" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*team</span> <span class="pre"><person></span> <span class="pre">[<role>...]</span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*team "Nick Proctor" compass clino tape
*team "Anthony Day" notes pictures tape
*team Wookey assistant
; Role not recorded
*team "Olly Betts"
</pre></div>
</div>
</dd>
<dt>Validity</dt><dd><p>valid at the start of a <code class="docutils literal notranslate"><span class="pre">*begin</span></code>/<code class="docutils literal notranslate"><span class="pre">*end</span></code> block.</p>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*team</span></code> specifies the people involved in a survey and optionally what role
or roles they filled during that trip. Unless the person is only identified
by one name you need to put double quotes around their name.</p>
<p>The syntax of <code class="docutils literal notranslate"><span class="pre">*team</span></code> commands has been defined for a very long time, but
prior to Survex 1.4.17 there weren’t any checks of the syntax. Essentially
<code class="docutils literal notranslate"><span class="pre">*team</span></code> used to be treated like a named comment line.</p>
<p>With Survex 1.4.17 and later you’ll get a warning for an empty <code class="docutils literal notranslate"><span class="pre">*team</span></code> or
if you open but fail to close double quotes around the person’s name.</p>
<p>Roles are now checked against an allowed list (which is the same list that
Therion uses, with the addition of <code class="docutils literal notranslate"><span class="pre">explorer</span></code> which Therion handles via
a separate <code class="docutils literal notranslate"><span class="pre">explo-team</span></code> command). You’ll get a warning if a role is not
recognised.</p>
<p>These diagnostic messages were made warnings to avoid breaking processing
of existing datasets which might contain <code class="docutils literal notranslate"><span class="pre">*team</span></code> lines which don’t conform
with the defined syntax, or with this newly adopted list of roles.</p>
<p><code class="docutils literal notranslate"><span class="pre"><role></span></code> should be one of the following (grouped entries are just
alternative names for the same thing). The intended meanings are noted
to encourage consistent usage:</p>
<blockquote>
<div><table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Role</p></th>
<th class="head"><p>Alias</p></th>
<th class="head"><p>Intended meaning</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>tape</p></td>
<td><p>length</p></td>
<td><p>Measured leg lengths</p></td>
</tr>
<tr class="row-odd"><td><p>compass</p></td>
<td><p>bearing</p></td>
<td><p>Measured bearings</p></td>
</tr>
<tr class="row-even"><td><p>clino</p></td>
<td><p>gradient</p></td>
<td><p>Measured vertical angles</p></td>
</tr>
<tr class="row-odd"><td><p>backtape</p></td>
<td><p>backlength</p></td>
<td><p>Like <code class="docutils literal notranslate"><span class="pre">tape</span></code> but for backsights</p></td>
</tr>
<tr class="row-even"><td><p>backcompass</p></td>
<td><p>backbearing</p></td>
<td><p>Like <code class="docutils literal notranslate"><span class="pre">compass</span></code> but for backsights</p></td>
</tr>
<tr class="row-odd"><td><p>backclino</p></td>
<td><p>backgradient</p></td>
<td><p>Like <code class="docutils literal notranslate"><span class="pre">clino</span></code> but for backsights</p></td>
</tr>
<tr class="row-even"><td><p>instruments</p></td>
<td><p>insts</p></td>
<td><p>All instruments: both compass and clino; use
for all-in-one instruments such as Disto-X.</p></td>
</tr>
<tr class="row-odd"><td><p>counter</p></td>
<td><p>count</p></td>
<td><p>Topofil length measurements</p></td>
</tr>
<tr class="row-even"><td><p>depth</p></td>
<td></td>
<td><p>Measured differences in height between stations,
e.g. underwater with a diver’s depth gauge, or
above water with a manometer</p></td>
</tr>
<tr class="row-odd"><td><p>station</p></td>
<td></td>
<td><p>Added markers at stations</p></td>
</tr>
<tr class="row-even"><td><p>position</p></td>
<td></td>
<td><p>Recorded absolute positions of stations (e.g.
fixed surface stations with a GPS)</p></td>
</tr>
<tr class="row-odd"><td><p>notes</p></td>
<td><p>notebook</p></td>
<td><p>Recorded instrument readings</p></td>
</tr>
<tr class="row-even"><td><p>pictures</p></td>
<td><p>pics</p></td>
<td><p>Drew sketches</p></td>
</tr>
<tr class="row-odd"><td><p>assistant</p></td>
<td><p>dog</p></td>
<td><p>General helper (e.g. held the end of the
tape on stations)</p></td>
</tr>
<tr class="row-even"><td><p>altitude</p></td>
<td><p>dz</p></td>
<td><p>Recorded the altitudes of stations (e.g. with an
altimeter)</p></td>
</tr>
<tr class="row-odd"><td><p>dimensions</p></td>
<td></td>
<td><p>Measured all passage dimensions</p></td>
</tr>
<tr class="row-even"><td><p>left</p></td>
<td></td>
<td><p>Measured <code class="docutils literal notranslate"><span class="pre">left</span></code> passage dimension</p></td>
</tr>
<tr class="row-odd"><td><p>right</p></td>
<td></td>
<td><p>Measured <code class="docutils literal notranslate"><span class="pre">right</span></code> passage dimension</p></td>
</tr>
<tr class="row-even"><td><p>up</p></td>
<td><p>ceiling</p></td>
<td><p>Measured <code class="docutils literal notranslate"><span class="pre">up</span></code> passage dimension</p></td>
</tr>
<tr class="row-odd"><td><p>down</p></td>
<td><p>floor</p></td>
<td><p>Measured <code class="docutils literal notranslate"><span class="pre">down</span></code> passage dimension</p></td>
</tr>
<tr class="row-even"><td><p>explorer</p></td>
<td></td>
<td><p>Explored the area of cave being surveyed</p></td>
</tr>
</tbody>
</table>
</div></blockquote>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*begin</span></code>, <code class="docutils literal notranslate"><span class="pre">*date</span></code>, <code class="docutils literal notranslate"><span class="pre">*instrument</span></code></p>
</dd>
</dl>
</section>
<section id="title">
<h3>TITLE<a class="headerlink" href="#title" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*title</span> <span class="pre"><title></span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*title Dreamtime
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*title "Mission Impossible"
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*title</span></code> allows you to set a descriptive title for a survey. If the title
contains spaces, you need to enclose it in double quotes (“”). If there is
no <code class="docutils literal notranslate"><span class="pre">*title</span></code> command, the title defaults to the survey name given in the
<code class="docutils literal notranslate"><span class="pre">*begin</span></code> command.</p>
</dd>
</dl>
</section>
<section id="truncate">
<h3>TRUNCATE<a class="headerlink" href="#truncate" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*truncate</span> <span class="pre"><length></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*truncate</span> <span class="pre">off</span></code></p>
</dd>
<dt>Description</dt><dd><p>Station names may be of any length in Survex, but some other (mostly older)
cave surveying software only regards 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).</p>
<p>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, Smaps 4 had a limit of 8, 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).</p>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*case</span></code></p>
</dd>
</dl>
</section>
<section id="units">
<h3>UNITS<a class="headerlink" href="#units" title="Link to this heading">¶</a></h3>
<dl>
<dt>Syntax</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*units</span> <span class="pre"><quantity</span> <span class="pre">list></span> <span class="pre">[<factor>]</span> <span class="pre"><unit></span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">*units</span> <span class="pre">default</span></code></p>
</dd>
<dt>Example</dt><dd><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*units tape metres
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*units compass backcompass clino backclino grads
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*units dx dy dz 1000 metres ; data given as kilometres
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*units left right up down feet
</pre></div>
</div>
</dd>
<dt>Description</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*units</span></code> changes the current units of all the quantities listed to
[<factor>] <unit>. Note that quantities can be expressed either as the
instrument (e.g. <code class="docutils literal notranslate"><span class="pre">COMPASS</span></code>) or the measurement (e.g. <code class="docutils literal notranslate"><span class="pre">BEARING</span></code>).</p>
<p><code class="docutils literal notranslate"><span class="pre"><quantity></span></code> is one of the following (grouped entries are
just alternative names for the same thing):</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">TAPE</span></code>/<code class="docutils literal notranslate"><span class="pre">LENGTH</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">BACKTAPE</span></code>/<code class="docutils literal notranslate"><span class="pre">BACKLENGTH</span></code> (added in Survex 1.2.25)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">COMPASS</span></code>/<code class="docutils literal notranslate"><span class="pre">BEARING</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">BACKCOMPASS</span></code>/<code class="docutils literal notranslate"><span class="pre">BACKBEARING</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CLINO</span></code>/<code class="docutils literal notranslate"><span class="pre">GRADIENT</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">BACKCLINO</span></code>/<code class="docutils literal notranslate"><span class="pre">BACKGRADIENT</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">COUNTER</span></code>/<code class="docutils literal notranslate"><span class="pre">COUNT</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">DEPTH</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">DECLINATION</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">DX</span></code>/<code class="docutils literal notranslate"><span class="pre">EASTING</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">DY</span></code>/<code class="docutils literal notranslate"><span class="pre">NORTHING</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">DZ</span></code>/<code class="docutils literal notranslate"><span class="pre">ALTITUDE</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">LEFT</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">RIGHT</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">UP</span></code>/<code class="docutils literal notranslate"><span class="pre">CEILING</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">DOWN</span></code>/<code class="docutils literal notranslate"><span class="pre">FLOOR</span></code></p></li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre"><factor></span></code> allows you to easy specify situations such as
measuring distance with a diving line knotted every 10cm
(<code class="docutils literal notranslate"><span class="pre">*units</span> <span class="pre">distance</span> <span class="pre">0.1</span> <span class="pre">metres</span></code>). If <code class="docutils literal notranslate"><span class="pre"><factor></span></code> is omitted it
defaults to <code class="docutils literal notranslate"><span class="pre">1.0</span></code>. If specified, it must be non-zero.</p>
<p>Valid units for listed quantities are:</p>
<p><code class="docutils literal notranslate"><span class="pre">TAPE</span></code>/<code class="docutils literal notranslate"><span class="pre">LENGTH</span></code>, <code class="docutils literal notranslate"><span class="pre">BACKTAPE</span></code>/<code class="docutils literal notranslate"><span class="pre">BACKLENGTH</span></code>, <code class="docutils literal notranslate"><span class="pre">COUNTER</span></code>/<code class="docutils literal notranslate"><span class="pre">COUNT</span></code>, <code class="docutils literal notranslate"><span class="pre">DEPTH</span></code>,
<code class="docutils literal notranslate"><span class="pre">DX</span></code>/<code class="docutils literal notranslate"><span class="pre">EASTING</span></code>, <code class="docutils literal notranslate"><span class="pre">DY</span></code>/<code class="docutils literal notranslate"><span class="pre">NORTHING</span></code>, <code class="docutils literal notranslate"><span class="pre">DZ</span></code>/<code class="docutils literal notranslate"><span class="pre">ALTITUDE</span></code> in
<code class="docutils literal notranslate"><span class="pre">YARDS</span></code>|<code class="docutils literal notranslate"><span class="pre">FEET</span></code>|<code class="docutils literal notranslate"><span class="pre">METRIC</span></code>|<code class="docutils literal notranslate"><span class="pre">METRES</span></code>|<code class="docutils literal notranslate"><span class="pre">METERS</span></code> (default: <code class="docutils literal notranslate"><span class="pre">METRES</span></code>)</p>
<p><code class="docutils literal notranslate"><span class="pre">CLINO</span></code>/<code class="docutils literal notranslate"><span class="pre">GRADIENT</span></code>, <code class="docutils literal notranslate"><span class="pre">BACKCLINO</span></code>/<code class="docutils literal notranslate"><span class="pre">BACKGRADIENT</span></code> in
<code class="docutils literal notranslate"><span class="pre">DEGS</span></code>|<code class="docutils literal notranslate"><span class="pre">DEGREES</span></code>|<code class="docutils literal notranslate"><span class="pre">GRADS</span></code>|<code class="docutils literal notranslate"><span class="pre">MINUTES</span></code>|<code class="docutils literal notranslate"><span class="pre">PERCENT</span></code>|<code class="docutils literal notranslate"><span class="pre">PERCENTAGE</span></code> (default:
<code class="docutils literal notranslate"><span class="pre">DEGREES</span></code>)</p>
<p><code class="docutils literal notranslate"><span class="pre">COMPASS</span></code>/<code class="docutils literal notranslate"><span class="pre">BEARING</span></code>, <code class="docutils literal notranslate"><span class="pre">BACKCOMPASS</span></code>/<code class="docutils literal notranslate"><span class="pre">BACKBEARING</span></code>, <code class="docutils literal notranslate"><span class="pre">DECLINATION</span></code> in
<code class="docutils literal notranslate"><span class="pre">DEGS</span></code>|<code class="docutils literal notranslate"><span class="pre">DEGREES</span></code>|<code class="docutils literal notranslate"><span class="pre">GRADS</span></code>|<code class="docutils literal notranslate"><span class="pre">MINUTES</span></code>|<code class="docutils literal notranslate"><span class="pre">QUADS</span></code>|<code class="docutils literal notranslate"><span class="pre">QUADRANTS</span></code> (default:
<code class="docutils literal notranslate"><span class="pre">DEGREES</span></code>)</p>
<p><code class="docutils literal notranslate"><span class="pre">FEET</span></code> and <code class="docutils literal notranslate"><span class="pre">YARDS</span></code> use the international definition of a foot (exactly
0.3048m). If you want to use a different definition, you can specify it
explicitly - for example, for the US survey foot:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*units tape 0.3048006096012192 meters ; US survey foot
</pre></div>
</div>
<p>or for the Indian survey foot:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*units tape 0.3047996 meters ; Indian survey foot
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">QUADRANTS</span></code> are a style of bearing used predominantly in
land survey, and occasionally in survey with handheld
instruments. All bearings are N or S, a numeric from 0 to
90, followed by E or W. For example S34E to refer to 146
degrees, or 34 degrees in the SE quadrant. In this
format, exact cardinal directions may be simply
alphabetic. E.g. N is equivalent to N0E and E is
equivalent to N90E. This unit was added in Survex 1.2.44.</p>
<p><code class="docutils literal notranslate"><span class="pre">GRADS</span></code> are an angle unit where 400 grads = 360 degrees.
They’re also known as “neugrads” (or sometimes “gons”).</p>
<p>Survex has long supported <code class="docutils literal notranslate"><span class="pre">MILS</span></code> as an alias for <code class="docutils literal notranslate"><span class="pre">GRADS</span></code>.
However, this seems to be a bogus definition of a “mil”
which is unique to Survex (except that Therion has since
copied it) - there are several different definitions of a
“mil” but they vary from 6000 to 6400 in a full circle,
not 400. Because of this we deprecated <code class="docutils literal notranslate"><span class="pre">MILS</span></code> in Survex
1.2.38 - you can still process data which uses them but
you’ll now get a warning, and we recommend you update
your data.</p>
<p>For example, if your data uses</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*units compass mils
</pre></div>
</div>
<p>then you need to determine what the intended units
actually are. If there are 400 in a full circle, then
instead use this (which will work with older Survex
versions too):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>*units compass grads
</pre></div>
</div>
<p>If the units are actually mils, you can specify that in
terms of degrees. For example, there are 6400 NATO mils
in a full circle, so one NATO mil is 360/6400 degrees, and
360/6400=0.05625 so you can use this (which also works
with older Survex versions):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>; Compass readings are NATO mils (6400 = 360 degrees)
*units compass 0.05625 degrees
</pre></div>
</div>
</dd>
<dt>See Also</dt><dd><p><code class="docutils literal notranslate"><span class="pre">*calibrate</span></code></p>
</dd>
</dl>
</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 class="current">
<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 current"><a class="current reference internal" href="#">Survex data files</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#readings">Readings</a></li>
<li class="toctree-l2"><a class="reference internal" href="#survey-station-names">Survey Station Names</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#anonymous-stations">Anonymous Stations</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#numeric-fields">Numeric fields</a></li>
<li class="toctree-l2"><a class="reference internal" href="#accuracy">Accuracy</a></li>
<li class="toctree-l2"><a class="reference internal" href="#cavern-commands">Cavern Commands</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#alias">ALIAS</a></li>
<li class="toctree-l3"><a class="reference internal" href="#begin">BEGIN</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cartesian">CARTESIAN</a></li>
<li class="toctree-l3"><a class="reference internal" href="#calibrate">CALIBRATE</a></li>
<li class="toctree-l3"><a class="reference internal" href="#case">CASE</a></li>
<li class="toctree-l3"><a class="reference internal" href="#copyright">COPYRIGHT</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cs">CS</a></li>
<li class="toctree-l3"><a class="reference internal" href="#data">DATA</a></li>
<li class="toctree-l3"><a class="reference internal" href="#date">DATE</a></li>
<li class="toctree-l3"><a class="reference internal" href="#declination">DECLINATION</a></li>
<li class="toctree-l3"><a class="reference internal" href="#default">DEFAULT</a></li>
<li class="toctree-l3"><a class="reference internal" href="#end">END</a></li>
<li class="toctree-l3"><a class="reference internal" href="#entrance">ENTRANCE</a></li>
<li class="toctree-l3"><a class="reference internal" href="#equate">EQUATE</a></li>
<li class="toctree-l3"><a class="reference internal" href="#export">EXPORT</a></li>
<li class="toctree-l3"><a class="reference internal" href="#fix">FIX</a></li>
<li class="toctree-l3"><a class="reference internal" href="#flags">FLAGS</a></li>
<li class="toctree-l3"><a class="reference internal" href="#include">INCLUDE</a></li>
<li class="toctree-l3"><a class="reference internal" href="#infer">INFER</a></li>
<li class="toctree-l3"><a class="reference internal" href="#instrument">INSTRUMENT</a></li>
<li class="toctree-l3"><a class="reference internal" href="#prefix">PREFIX</a></li>
<li class="toctree-l3"><a class="reference internal" href="#ref">REF</a></li>
<li class="toctree-l3"><a class="reference internal" href="#require">REQUIRE</a></li>
<li class="toctree-l3"><a class="reference internal" href="#sd">SD</a></li>
<li class="toctree-l3"><a class="reference internal" href="#set">SET</a></li>
<li class="toctree-l3"><a class="reference internal" href="#solve">SOLVE</a></li>
<li class="toctree-l3"><a class="reference internal" href="#team">TEAM</a></li>
<li class="toctree-l3"><a class="reference internal" href="#title">TITLE</a></li>
<li class="toctree-l3"><a class="reference internal" href="#truncate">TRUNCATE</a></li>
<li class="toctree-l3"><a class="reference internal" href="#units">UNITS</a></li>
</ul>
</li>
</ul>
</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>
<li>Previous: <a href="cmdline.htm" title="previous chapter">Survex Programs</a></li>
<li>Next: <a href="svxhowto.htm" title="next chapter"><code class="docutils literal notranslate"><span class="pre">.svx</span></code> Cookbook</a></li>
</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>
|
