doc/extend.sgml

   1 <refmeta>
   2 <refentrytitle>extend</refentrytitle>
   3 <manvolnum>1</manvolnum>
   4 </refmeta>
   5
   6 <refnamediv>
   7 <refname>extend</refname>
   8 <refpurpose>produce an extended elevation from a <filename>.3d</filename> file
   9 </refpurpose>
  10 </refnamediv>
  11
  12 <refsynopsisdiv>
  13 <cmdsynopsis>
  14 <command>extend</command>
  15 <arg choice="opt">--survey=SURVEY</arg>
  16 <arg choice="opt">--specfile=ESPEC_FILE</arg>
  17 <arg choice="opt">--show-breaks</arg>
  18 <arg choice="req">INPUT_3D_FILE</arg>
  19 <arg choice="opt">OUTPUT_3D_FILE</arg>
  20 </cmdsynopsis>
  21 </refsynopsisdiv>
  22
  23 <refsect1><title>Description</title>
  24
  25 <Note>
  26 <Para>
  27 The <command>extend</command> program can also work on
  28 <Application>Compass</Application> <filename>.plt</filename> (as can
  29 <command>aven</command> and any other <Application>Survex</Application> program which reads <filename>.3d</filename>
  30 files).
  31 </Para>
  32 </Note>
  33
  34 <Para>
  35 If no specfile is given, extend starts with the highest station marked
  36 as an entrance which has at least one underground survey leg attached
  37 to it.  If there are no such stations, the highest deadend station in
  38 the survey (or the highest station if there are no deadends) is used.
  39 Extend puts the first station on the left, then folds each leg out
  40 individually to the right, breaking loops arbitrarily (usually at
  41 junctions).</Para>
  42
  43 <Para>If the output filename is not specified, extend bases the output
  44 filename on the input filename, but ending "_extend.3d".  For example,
  45 <command>extend deep_pit.3d</command> produces an extended elevation
  46 called <filename>deep_pit_extend.3d</filename>.</Para>
  47
  48 <Para>If you pass <option>--show-breaks</option> then a leg flagged as
  49 "surface survey" will be added between each point at which a loop has
  50 been broken - this can be very useful for visualising the result in
  51 aven.</Para>
  52
  53 <Para>
  54 This approach suffices for simple caves or sections of cave, but for more
  55 complicated situations human intervention is required.  More complex
  56 sections of cave can be handled with a specfile giving directions to
  57 switch the direction of extension between left and right, to
  58 explicitly specify the start station, or to break the extension at
  59 particular stations or legs. </Para>
  60
  61 <Para>
  62 The specfile is in a format similar to cavern's data format:</Para>
  63
  64 <programlisting>
  65 ;This is a comment
  66
  67 ; start the elevation at station entrance.a
  68 *start entrance.a  ;this is a comment after a command
  69
  70 ; start extending leftwards from station half-way-down.5
  71 *eleft half-way-down.5
  72
  73 ; change direction of extension at further-down.8
  74 *eswap further-down.8
  75
  76 ; extend right from further-down.junction, but only for
  77 ; the leg joining it to very-deep.1, other legs continuing
  78 ; as before
  79 *eright further-down.junction  very-deep.1
  80
  81 ; break the survey at station side-loop.4
  82 *break side-loop.4
  83
  84 ; break survey at station side-loop.junction but only
  85 ; for leg going to complex-loop.2
  86 *break side-loop.junction complex-loop.2
  87 </programlisting>
  88
  89 <Para>
  90 This approach requires some trial and error, but gives useful results
  91 for many caves.  The most complex systems would benefit from an
  92 interactive interface to select and view the breaks and switches of
  93 direction.</Para>
  94
  95 </refsect1>