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

SEE ALSO

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

                                            2013 09 21                           caveconverter(1)