doc/aven.sgml

   1 <refmeta>
   2 <refentrytitle>aven</refentrytitle>
   3 <manvolnum>1</manvolnum>
   4 </refmeta>
   5
   6 <refnamediv>
   7 <refname>aven</refname>
   8 <refpurpose>sophisticated cave viewer for Unix and MS Windows
   9 </refpurpose>
  10 </refnamediv>
  11
  12 <refsynopsisdiv>
  13 <cmdsynopsis>
  14 <command>aven</command>
  15 <arg choice="opt">--survey=SURVEY</arg>
  16 <arg choice="opt">--print</arg>
  17 <arg choice="req">.3d file</arg> <!--FIXME  rep="repeat"-->
  18 </cmdsynopsis>
  19 </refsynopsisdiv>
  20
  21 <refsect1><title>Description</title>
  22
  23 <Para>
  24 Aven displays processed cave surveys in a window and allows you to
  25 manipulate the view.
  26 </Para>
  27
  28 <Para>Note that there is no perspective in the view. This means that
  29 it is impossible to tell which way round a cave is rotating, or
  30 whether you are viewing something from behind, or in front. So
  31 if you think the direction of rotation in wrong, or changes as
  32 you watch, this is just your brain being confused, not a bug!
  33 </Para>
  34
  35 <refsect2><Title>Mouse Control</Title>
  36
  37 <Para>
  38 The best way to move the cave is with the mouse.  We suggest you
  39 try each of these out after reading this section to get a feel
  40 for how they work.
  41 </Para>
  42
  43 <Para>
  44 If you hold down the right button then the cave is dragged when you move the
  45 mouse.
  46 </Para>
  47
  48 <Para>
  49 If you hold down the left button, then the cave is rotated if you move
  50 left or right, and zoomed if you move up and down.
  51 If you hold down <keycap>Ctrl</keycap> while dragging with the left
  52 mouse button, then the cave rotates and tilts at the same time instead.
  53 </Para>
  54
  55 <Para>
  56 If your mouse has a middle button then holding it down and moving the
  57 mouse up and down tilts the cave.  Moving the mouse left and right has
  58 no effect.
  59 </Para>
  60
  61 <Para>
  62 And if you have a scrollwheel, this can be used to zoom in/out.
  63 </Para>
  64
  65 <Para>
  66 By default the mouse moves the cave, but if you press <keycap>Ctrl-R</keycap>,
  67 then the mouse will move the viewpoint instead (i.e. everything will
  68 go in the opposite direction). Apparently this feels more natural to some
  69 people.
  70 </Para>
  71
  72 </refsect2>
  73
  74 <refsect2><Title>Keyboard Control</Title>
  75
  76 <Para><keycap>P</keycap> and <keycap>L</keycap> select Plan and eLevation
  77 respectively.  Changing between plan to elevation is animated to help
  78 you see where you are and how things relate. This animation is
  79 automatically disabled on slow machines to avoid user frustration.
  80 </Para>
  81
  82 <Para>
  83 Comma <keycap>'</keycap>, and Slash <keycap>/</keycap> tilt up
  84 and down respectively. Tilt goes 180 degrees from plan view to a view
  85 from directly below (upside down plan).
  86 </Para>
  87
  88 <Para>
  89 <keycap>Space</keycap> toggles automatic rotation about a vertical
  90 axis on and off.  The speed of rotation for this, and animated transitions
  91 between plan and elevation, is controlled by <keycap>Z</keycap> and <keycap>X</keycap>.
  92 </Para>
  93
  94 <Para>Crosses and/or labels can be displayed at survey stations.
  95 <keycap>Ctrl-X</keycap> toggles crosses and <keycap>Ctrl-N</keycap> station names.
  96 <keycap>Ctrl-L</keycap> toggles the display of survey legs.
  97 </Para>
  98
  99 <!--
 100 <para>By default, labels and crosses are not redrawn during
 101 movement, to improve responsiveness.  With a small cave, or a fast
 102 computer, you can enable redraw of everything during movement with
 103 <keycap>Ctrl-A</keycap>.  <keycap>Ctrl-O</keycap> toggles whether all names are
 104 displayed, or only non-overlapping ones.
 105 </para>
 106 -->
 107
 108 <para><keycap>Delete</keycap> is useful if you get lost - it resets the scale,
 109 position, and rotation speed, so that the cave returns to the centre
 110 of the screen. There are also keyboard controls to use instead of the
 111 mouse - <keycap>Shift</keycap> helps here as it accelerates all
 112 movements:
 113 </para>
 114
 115 <screen>
 116 <keycap>Z</keycap>, <keycap>X</keycap> : Faster/Slower Rotation
 117 <keycap>R</keycap>: Reverse direction of rotation
 118 <keycap>Enter</keycap>, <keycap>Space</keycap>: Start and stop auto-rotation
 119 <keycap>Ctrl-Cursor Left</keycap>, <keycap>Ctrl-Cursor Right</keycap>: Rotate cave one step clockwise/anti-clockwise (also: <keycap>C</keycap>, <keycap>V</keycap>)
 120 <keycap>Ctrl-Cursor Up</keycap> , <keycap>Ctrl-Cursor Down</keycap>: Higher/Lower Viewpoint (also: <keycap>'</keycap> , <keycap>/</keycap>)
 121 <keycap>]</keycap> , <keycap>[</keycap>: Zoom in/Out
 122 <keycap>U</keycap>, <keycap>D</keycap>: Set view to Up/Down
 123 <keycap>N</keycap>, <keycap>S</keycap>, <keycap>E</keycap>, <keycap>W</keycap>: Set view to North, South, East, West
 124 <keycap>Delete</keycap>: Reset to default scale, rotation rate, etc
 125 <keycap>P</keycap>, <keycap>L</keycap>: Plan, Elevation
 126 <keycap>Cursor Left</keycap>, <keycap>Cursor Right</keycap>: Pan survey Left/Right (on screen)
 127 <keycap>Cursor Up</keycap>, <keycap>Cursor Down</keycap>: Pan survey Up/Down (on screen)
 128 <keycap>Ctrl-N</keycap>: Toggle display of station names
 129 <keycap>Ctrl-X</keycap>: Toggle display of crosses at stations
 130 <keycap>Ctrl-L</keycap>: Toggle display of survey legs
 131 <keycap>Ctrl-F</keycap>: Toggle display of surface legs
 132 <!--<keycap>Ctrl-A</keycap>: Toggle display of All/skeleton when moving-->
 133 <keycap>Ctrl-G</keycap>: Toggle display of grid
 134 <keycap>Ctrl-B</keycap>: Toggle display of bounding box
 135 <keycap>O</keycap>: Toggle display of non-overlapping/all names
 136 <keycap>Ctrl-R</keycap>: reverse sense of controls
 137 <keycap>Shift</keycap>: accelerates all movement keys
 138 </screen>
 139
 140 <Para>A little experimentation should give a better understanding of how
 141 this works.
 142 </Para>
 143
 144 <Para>There is an auto-resizing scale bar along the bottom of the screen
 145 which varies in length as you zoom in or out.
 146 In the lower right corner is a compass pointer showing which way
 147 is North, and a clino pointer showing the angle of tilt.
 148 And in the upper right is a colour key showing the correspondence between
 149 colour and depth (by default - you can also colour by date or by error).
 150 </Para>
 151
 152 </refsect2>
 153
 154 </refsect1>
 155
 156 <refsect1><Title>Options</Title>
 157
 158 <VariableList>
 159 <VarListEntry>
 160 <Term>-p, --print</Term>
 161 <ListItem>
 162 <Para>
 163 Print the specified file and exit.
 164 </Para>
 165 </ListItem>
 166 </VarListEntry>
 167
 168 <VarListEntry>
 169 <Term>-s, --survey=SURVEY</Term>
 170 <ListItem>
 171 <Para>
 172 Only load the sub-survey 'SURVEY'.
 173 </Para>
 174 </ListItem>
 175 </VarListEntry>
 176
 177 </VariableList>
 178
 179 </refsect1>