Ubuntu Manpage: caveconverter - convert cave survey data between formats

Provided by: caveconverter_0~20170114-6_all

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.

   Formats read:
       Survex -  Supports  normal,  diving  and  nosurvey format data (in any supported units and field orders).
                 Multi-file reading now supported (but ignores FIX commands currently) (.svx files)

       Compass - The data file format generated by the Compass cave survey software. (.dat files)

       PocketTopo text export -
                 Text export option in PocketTopo menu. (.txt files)

       DXF -     Reads Lines and Polylines as survey centreline data. (.dxf files)

   Formats written:
       Toporobot -
              For using to import data into PocketTopo software on a PDA. (.text files)

       Survex -
              Converts to metric units currently, and entire series will be output in same field order (matching
              order of fields from last leg per series from input file). (.svx files)

OPTIONS

       The format codes are:
       c - Compass
       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 caveconverter (e.g. because it contains some unimplemented feature)
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 caveconverter 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
.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.

SPLAY/LRUD conversion
The original approach to reading splay legs from PocketTopo files in caveconverter 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 caveconverter 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
caveconverter 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.

Another bugbear of previous versions of caveconverter 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.

Convert existing survey data for loading into PocketTopo on a PDA
To load an existing survey into PocketTopo on a PDA in order to extend a survey with reference to the
existing data for the cave, you can convert to Toporobot format using the caveconverter. Then import the
Toporobot file into PocketTopo on the PDA. The input survey data could be read from a Compass file, or a
Survex file. Where a Survex file contains formats which caveconverter is not yet able to read, you can
instead process the data in Survex to generate a .3d file, and then use Survex convert this to a DXF file
(right-click on a .3d file to select this option from the pop-up menu in Windows Explorer). Cave
Converter can then read this DXF file and generate a Toporobot file. Converting survey data to Toporobot
will unfortunately cause all the survey station numbers and series names to be changed. This is because
Toporobot format requires survey series to consist only of linear chains of survey stations. Junctions
are not allowed in these chains, so junctions in the cave require a new chain to be started. This means
that data from other formats cannot be simply converted, so all stations are renumbered and organised
into new numbered series to conform to these constraints of the Toporobot format.

Regenerate Editable Survey Data from DXF or Survex 3D Files
Sometimes the survey data for a project from the past has been lost, and all that remains is some
processed output. caveconverter can regenerate editable survey data from DXF files where the survey
centreline is represented by straight line objects or polylines. This includes DXF files generated by
Survex from Survex .3d files. The Aven viewer in Survex can export a DXF file from a cave model, or
right-click on a .3d file in Windows Explorer to select the Convert to DXF option from the pop-up menu.

While 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.

Survex to Survex with LRUD generation
caveconverter can create LRUD passage data blocks for Survex files containing splays. Just read and write
Survex format, using the LRUD option. The Survex file reader in caveconverter does not currently read
existing passage data blocks. So be aware that existing 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 (or the Generate LRUD option is run after loading the data into the
windowed application) then new passage data blocks will be generated from the splays and replace any
previously present passage data blocks in the output file.

Specifying Character Set Encoding
If you are reading in data files which contain extended character set symbols (e.g. accented characters
or non-punctuation symbol characters) then caveconverter will assume these files are using UTF-8 encoding
by default. To specify a different encoding in the Windows application you can edit the app.properties
file. (This file is written to the same folder as the CaveConverterGUI.jar file when you close the
application. So run the application once and close it, then you should find the app.properties file which
will contain the line 'character.set=UTF8'. Edit this line to specify an alternative character set
encoding if you are not using UTF-8. See the command line reference html page for more details on
alternative character set codes, and also how to specify them for command line conversions.

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)