File: caveconverter.1

package info (click to toggle)
caveconverter 0~20170114-1
  • links: PTS
  • area: main
  • in suites: stretch
  • size: 4,792 kB
  • sloc: java: 9,290; xml: 242; makefile: 18
file content (211 lines) | stat: -rw-r--r-- 9,339 bytes parent folder | download | duplicates (2)
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
.\" Manpage for caveconvter
.TH caveconverter 1 "2013 09 21"
.SH NAME
caveconverter \- convert cave survey data between formats
.SH SYNOPSIS
.B caveconverter 
.I infile 
.I outfile
.I in_format
.I out_format
.B [
lrud
.B ]
.SH DESCRIPTION
.B caveconverter 
is a program for converting cave survey data from one
format into another. It can read and write a variety of cave survey
data file formats, translating the data, and can also generate LRUD
info from splay shots.

.SS Formats read:
.TP 10
Survex \- 
Supports the most common data formats (from to tape
compass clino) assuming units are metres and degrees. Single data
files only.
.TP
PocketTopo text export \-
Text export option in PocketTopo menu.
.TP
DXF \-
Reads Lines and Polylines as survey centreline data. 

.SS Formats written:
.TP
Toporobot \-
For using to import data into PocketTopo software on a PDA.
.TP
Survex \-
Normal formated metric units only.
.SH OPTIONS
The format codes are:
.br
.B d \-
DXF
.br
.B p \-
PocketTopo text export 
.br
.B s \-
Survex 
.br
.B t \-
Toporobot
.br
.TP
.B lrud \-
Adding the lrud flag to the end of the command causes LRUD (left rght
up down) info to be generated from splay data
.SH CONVERSION DETAILS

Converting from DXF files to survex shows how editable survey data can
be regenerated from Survex .3d files via the Convert to DXF option
provided by Survex 
.P
This is also how you can generate a DXF file to convert to Toporobot
using 
.B caveconverter
, enabling existing cave surveys to be
imported into PocketTopo regardless of the original Survex format
data. So if your Survex file is not readable by 
.B caveconvter
(e.g. because it contains diving data, or different units or data ordering
than the default) then you can still process it using Survex to
generate a 3d file and convert that to DXF using Survex. Then convert
it to Toporobot format using Cave Converter and import that file into
PocketTopo. This enables existing surveys to be loaded into PocketTopo
so that new data can be tied into the known cave on surveying trips.
.P
Converting Survex data to Toporobot will cause all the survey station
numbers and series names to get regenerated unfortunately. This is
because Toporobot format requires survey series to consist only of
linear chains of survey stations. Junctions are not allowed in series.
This means that data from other formats cannot be simply converted, so
all stations are renumbered and reorganised into new numbered series
to conform to this constraint of the Toporobot format.
.P
If you find files that give errors on conversion, send them to me
(Footleg). I can be contacted by email: drfootleg [at] gmail.com
.P
While 
.B caveconverter 
can regenerate survey data files from DXF files generated from Survex
.3d files, you will not get back the complete original data. What you
do get is the equivalent calculated survey leg data (tape, compass,
clino) for the positions of the stations in the DXF file. So any loop
closure corrections and instrument calibrations will have already been
applied to the data. This feature is really intended as a way to
recover some sort of workable data when the original data has been
lost and only the 3d files remain. Some small rounding errors occur
during the Conversion to DXF from the .3d file, so the exact positions
of survey stations and the cave length reported may differ by a few cm
compared to the original data. This is because in the DXF file, Survex
has rounded all station positions to the nearest 1cm.
.P
The Survex file reader does not currently read passage data blocks. So
any passage data blocks will be removed if a Survex file is read in
and written out again. However if the Survex file contains splays and
the lrud option is specified on the command line then new passage data
blocks will be generated from the splays and replace any previously
present passage data blocks in the file which is generated.
.SS SPLAY/LRUD conversion
The original approach to reading splay legs from PocketTopo files in
Cave Converter was to treat them as just a way of measuring passage
dimensions as Left, Right, Up, Down measurements at each station. So
when no more than four splays were found at a station the code used
their lengths as LRUD measurements and removed the splays from the
data in the process. This kept Survex models looking like they used to
before we started measuring lots of splays. But as my own surveying
experience increased over recent years I realised that splays are a
much more useful tool than just a way to take LRUD measurements. With
a DistoX the splays can quickly and accurately be fired from stations
to pick out key features and passage shapes at corners and in
chambers. These splays aid drawing the correct position of walls,
ceiling and floor as well as passage features. They are valuable data
which should not be replaced with LRUD passage dimension data. LRUD
data still has value. A number of file formats support LRUD data to
represent the position of passage walls at each station, and 3D model
generation uses this data. But the splays should still be kept when
generating LRUD data from them. The latest Aven viewer (part of the
Survex 1.2.7 release) and the Loch Viewer (part of Therion) now both
allow splay legs to be shown or hidden. So it is possible to view
centreline only models without actually removing the splays from the
data.
.P
So this latest version of Cave Converter no longer removes splay legs
used to generate LRUD measurements. The LRUD generation code has also
been completely rewritten and made part of the core data model rather
than an operation done during reading of PocketTopo files. This means
it is now possible to generate LRUD data from splays in any data file
which can be read. Unfortunately for those of you who used Cave
Converter in the past to convert PocketTopo data to Survex format it
will have removed a lot of the splays, so you will want to convert
from the original PocketTopo exported text files again with this
version. The LRUD generation does a much better job of selecting the
best splay to determine a passage dimension measurement from in this
version of the code. The splay which contributes the greatest distance
of the wall/ceiling/floor from the station is used to calculate the
distance to the wall. Previous versions of the code just used the
total length of the best splay, rather than the distance in the
direction of the LRUD measurement being set. This was flawed and
splays almost parallel to a survey leg could generate much larger
passage dimension measurements than was appropriate. Now trigonometry
is used to determine the appropriate distance in the direction of the
passage dimension, and the direction for the left and right
measurements is calculated from the best matching previous leg as well
as the onward leg from the station.
.P
The conversion of Survex data (containing splays) to Toporobot format
in order to import existing survey data into PocketTopo to extend off
on new survey trips can now generate and output LRUD data too.
PocketTopo will display this data as splays orthogonal to the
direction of the survey legs to indicate passage width and height.
Note that Cave Converter does not yet read passage data back in from
Survex files. So unless you have all the splays in a Survex file you
will lose the LRUD data if you read in a Survex file and output it
again in the same or another format.
.P
Another bug bear of previous versions of Cave Converter was that LRUD
data was output in Survex files as one continuous block of stations
with LRUD data regardless of how the stations were connected by survey
legs. This has now been fixed so the survey legs in each series are
used to determine the grouping of passage data stations into blocks of
connected stations. The following screenshots of a model in Aven for
the same survey data using previous and the latest versions of Cave
Converter illustrate the improved passage data generation.
.SH EXAMPLES
To convert existing Survex data into Toporobot format so you can
import it in to PocketTopo: 
.br
.B  caveconverter survexfile.svx output.text s t
.P
To convert data exported from PocketTopo into Survex format, including
LRUD info from splays: 
.br
.B  caveconverter pdaexport.txt survexfile.svx p s lrud
.P
To convert data from DXF format into Toporobot format so you can
import it into PocketTopo: 
.br
.B  caveconverter datafile.dxf toporobotfileout.text d t
.P
To convert data from DXF format into Survex format: 
.br
.B  caveconverter datafile.dxf survexfile.svx d s 
.SH BUGS
Survex output re-uses 'to station' numbers for splay legs if all
splays from a station are not together in the file. So if a set of
splay legs occur in a series of legs within the same begin/end block
followed by a leg from a different station, and then another splay leg
from the original station is found further down the block then the 'to
station' numbering will start from 'a' again. So you can for example
get two splays from station 10 with to station names of '10a' in the
file. The file can be processed but shows a large loop closure error
for the splays as it equates the two 10a stations at the end of the
two splays as being the same point.
.SH AUTHOR
Paul 'Footleg' Fretwell (drfootleg@gmail.com)
.SH SEE ALSO
HTML doc is in 
.I /usr/share/doc/caveconverter/readme.html