Provided by: caveconverter_0~20170114-6_all bug

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)

SEE ALSO

       HTML documentation is in /usr/share/doc/caveconverter/readme.html

                                            2017 01 14                           caveconverter(1)