NAME¶
caveconverter - convert cave survey data between formats
SYNOPSIS¶
caveconverter infile outfile in_format
out_format [ lrud
]
DESCRIPTION¶
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.
- Survex -
- Supports the most common data formats (from to tape compass clino)
assuming units are metres and degrees. Single data files only.
- PocketTopo text export -
- Text export option in PocketTopo menu.
- DXF -
- Reads Lines and Polylines as survey centreline data.
- Toporobot -
- For using to import data into PocketTopo software on a PDA.
- Survex -
- Normal formated metric units only.
OPTIONS¶
The format codes are:
d - DXF
p - PocketTopo text export
s - Survex
t - Toporobot
- lrud -
- Adding the lrud flag to the end of the command causes LRUD (left rght up
down) info to be generated from splay data
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
This is also how you can generate a DXF file to convert to Toporobot using
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
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.
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.
If you find files that give errors on conversion, send them to me (Footleg). I
can be contacted by email: drfootleg [at] gmail.com
While
caveconverter can regenerate survey data files from DXF files
generated from Survex 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.
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.
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.
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.
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.
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.
EXAMPLES¶
To convert existing Survex data into Toporobot format so you can import it in to
PocketTopo:
caveconverter survexfile.svx output.text s t
To convert data exported from PocketTopo into Survex format, including LRUD info
from splays:
caveconverter pdaexport.txt survexfile.svx p s lrud
To convert data from DXF format into Toporobot format so you can import it into
PocketTopo:
caveconverter datafile.dxf toporobotfileout.text d t
To convert data from DXF format into Survex format:
caveconverter datafile.dxf survexfile.svx d s
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.
AUTHOR¶
Paul 'Footleg' Fretwell (drfootleg@gmail.com)
SEE ALSO¶
HTML doc is in
/usr/share/doc/caveconverter/readme.html