Ubuntu Manpage: caveconverter - convert cave survey data between formats

Provided by: caveconverter_0~20131117~beta-2_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  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.

   Formats written:
       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)