source: git/trunk/doc/aven.sgml @ 7bb8184

<refmeta>
<refentrytitle>aven</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>

<refnamediv>
<refname>aven</refname>
<refpurpose>sophisticated cave viewer for Unix and MS Windows
</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>aven</command>
<arg choice="opt">options</arg>
<arg choice="req">.3d file</arg> <!--FIXME  rep="repeat"-->
</cmdsynopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>

<Para>
Aven displays processed cave surveys in a window and allows you to
manipulate the view.
</Para>

<Para>Note that there is no perspective in the view. This means that
it is impossible to tell which way round a cave is rotating, or
whether you are viewing something from behind, or in front. So
if you think the direction of rotation in wrong, or changes as
you watch, this is just your brain being confused, not a bug!
</Para>

<refsect2><Title>Mouse Control</Title>

<Para>
The best way to move the cave is with the mouse.  We suggest you
try each of these out after reading this section to get a feel
for how they work.
</Para>

<Para>
If you hold down the right button then the cave is dragged when you move the
mouse.
</Para>

<Para>
If you hold down the left button, then the cave is rotated if you move
left or right, and zoomed if you move up and down.
If you hold down <keycap>Ctrl</keycap> while dragging with the left
mouse button, then the cave rotates and tilts at the same time instead.
</Para>

<Para>
If your mouse has a middle button then holding it down and moving the
mouse up and down tilts the cave.  Moving the mouse left and right has
no effect.
</Para>

<Para>
And if you have a scrollwheel, this can be used to zoom in/out.
</Para>

<Para>
By default the mouse moves the cave, but if you press <keycap/Ctrl-R/,
then the mouse will move the viewpoint instead (i.e. everything will
go in the opposite direction). Apparently this feels more natural to some
people.
</Para>

</refsect2>

<refsect2><Title>Keyboard Control</Title>

<Para><keycap/P/ and <keycap/L/ select Plan and eLevation
respectively.  Changing between plan to elevation is animated to help
you see where you are and how things relate. This animation is
automatically disabled on slow machines to avoid user frustration.
</Para>

<Para>
Comma <keycap/'/, and Slash <keycap>/</keycap> tilt up
and down respectively. Tilt goes 180 degrees from plan view to a view
from directly below (upside down plan).
</Para>

<Para>
<keycap>Space</keycap> toggles automatic rotation about a vertical
axis on and off.  The speed of rotation for this, and animated transitions
between plan and elevation, is controlled by <keycap/Z/ and <keycap/X/.
</Para>

<Para>Crosses and/or labels can be displayed at survey stations.
<keycap/Ctrl-X/ toggles crosses and <keycap/Ctrl-N/ station names.
<keycap/Ctrl-L/ toggles the display of survey legs.
</Para>

<!--
<para>By default, labels and crosses are not redrawn during
movement, to improve responsiveness.  With a small cave, or a fast
computer, you can enable redraw of everything during movement with
<keycap/Ctrl-A/.  <keycap/Ctrl-O/ toggles whether all names are
displayed, or only non-overlapping ones.
</para>
-->

<para><keycap/Delete/ is useful if you get lost - it resets the scale,
position, and rotation speed, so that the cave returns to the centre
of the screen. There are also keyboard controls to use instead of the
mouse - <keycap/Shift/ helps here as it accelerates all
movements:
</para>

<screen>
<keycap/Z/, <keycap/X/ : Faster/Slower Rotation
<keycap/R/: Reverse direction of rotation
<keycap/Enter/, <keycap/Space/: Start and stop auto-rotation
<keycap/C/, <keycap/V/: Rotate cave one step clockwise/anti-clockwise
<keycap/'/ , <keycap>/</keycap>: Higher/Lower Viewpoint
<keycap/]/ , <keycap/[/: Zoom in/Out
<keycap/U/, <keycap/D/: Set view to Up/Down
<keycap/N/, <keycap/S/, <keycap/E/, <keycap/W/: Set view to North, South, East, West
<keycap/Delete/: Reset to default scale, rotation rate, etc
<keycap/P/, <keycap/L/: Plan, Elevation
<keycap/Cursor Left/, <keycap/Cursor Right/: Pan survey Left/Right (on screen)
<keycap/Cursor Up/, <keycap/Cursor Down/: Pan survey Up/Down (on screen)
<keycap/Ctrl-N/: Toggle display of station names
<keycap/Ctrl-X/: Toggle display of crosses at stations
<keycap/Ctrl-L/: Toggle display of survey legs
<keycap/Ctrl-F/: Toggle display of surface legs
<!--<keycap/Ctrl-A/: Toggle display of All/skeleton when moving-->
<keycap/Ctrl-G/: Toggle display of grid
<keycap/Ctrl-B/: Toggle display of bounding box
<keycap/O/: Toggle display of non-overlapping/all names
<keycap/Ctrl-R/: reverse sense of controls
<keycap/Shift/: accelerates all movement keys
</screen>

<Para>A little experimentation should give a better understanding of how
this works.
</Para>

<Para>There is an auto-resizing scale bar along the bottom of the screen
which varies in length as you zoom in or out.  
In the lower right corner is a compass pointer showing which way
is North, and a clino pointer showing the angle of tilt.
And in the upper right is a depth bar showing the correspondence between
colour and depth.
</Para>

</refsect2>

</refsect1>