==================
General: How do I?
==================

-------------------
Create a new survey
-------------------

You create a text file containing the relevant survey data, using a text
editor, and save it with a suitable name with a ``.svx`` extension.  The easiest
way is to look at some of the example data and use that as a template.  Nearly
all surveys will need a bit of basic info as well as the survey data itself:
e.g.  the date (``*date``), comments about where, what cave, a name for the
survey (using ``*begin`` and ``*end``), instrument error corrections, etc. Here
is a typical survey file:

All the lines starting with ``;`` are comments, which are ignored by Survex.
You can also see the use of ``DOWN`` for plumbs, and ``*calibrate tape`` for
dealing with a tape length error (in this case the end of the tape had fallen
off so measurements were made from the 20cm point).
::

   *equate chaos.1 triassic.pt3.8
   *equate chaos.2 triassic.pt3.9

   *begin chaos
   *title "Bottomless Pit of Eternal Chaos to Redemption pitch"
   *date 1996.07.11
   *team "Nick Proctor" compass clino tape
   *team "Anthony Day" notes pictures tape
   *instrument compass "CUCC 2"
   *instrument clino "CUCC 2"
   ;Calibration: Cairn-Rock 071 072 071,  -22 -22 -22
   ;       Rock-Cairn 252 251 252,  +21 +21 +21
   ;Calibration at 161d entrance from cairn near entrance to
   ;prominent rock edge lower down. This is different from
   ;calibration used for thighs survey of 5 July 1996

   *export 1 2

   ;Tape is 20cm too short
   *calibrate tape +0.2

   1 2 9.48 208 +08
   2 3 9.30 179 -23
   3 4 2.17 057 +09
   5 4 10.13 263 +78
   5 6 2.10 171 -73
   7 6 7.93 291 +75
   *begin
   *calibrate tape 0
   8 7 35.64 262 +86 ;true length measured for this leg
   *end
   8 9 24.90 - DOWN
   10 9 8.61 031 -43
   10 11 2.53 008 -34
   11 12 2.70 286 -20
   13 12 5.36 135 +23
   14 13 1.52 119 -12
   15 14 2.00 036 +13
   16 15 2.10 103 +12
   17 16 1.40 068 -07
   17 18 1.53 285 -42
   19 18 5.20 057 -36
   19 20 2.41 161 -67
   20 21 27.47 - DOWN
   21 22 9.30 192 -29
   *end chaos

-------------------
Organise my surveys
-------------------

This is actually a large subject.  There are many ways you can
organise your data using Survex.  Take a look at the example
dataset for some ideas of ways to go about it.

Fixed Points (Control Points)
=============================

The ``*fix`` command is used to specify fixed points (also know as
control points).  See the description of this command in the
"Cavern Commands" section of this manual.

More than one survey per trip
=============================

Suppose you have two separate bits of surveying which were done
on the same trip.  So the calibration details, etc. are the same
for both, but you want to give a different survey name to the
two sections.  This is easily achieved like so:
::


    *begin
    *calibrate compass 1.0
    *calibrate clino 0.5
    *begin altroute
    ; first survey
    *end altroute
    *begin faraway
    ; second survey
    *end faraway
    *end

----------------------
Add surface topography
----------------------

Survex 1.2.18 added support for loading terrain data and rendering
it as a transparent surface.  Currently the main documentation for
this is maintained as a `wiki
page <https://trac.survex.com/wiki/TerrainData>`__ as this allows
us to update it between releases.

This supports loading data in the HGT format that NASA offers SRTM
data in.  The SRTM data provides terrain data on a 1 arc-second
grid (approximately 30m) for most of the world.

--------------
Overlay a grid
--------------

Aven is able to display a grid, but this functionality isn't
currently available in printouts.  You can achieve a similar effect
for now by creating a ``.svx`` file where the survey legs form a
grid.

If you want to do this, we suggest fixing points at the end of
each grid line and using the ``NOSURVEY`` data style to add
effectively elastic legs between these fixed points.  This is
simpler to generate than generating fake tape/compass/clino legs
and is very fast for cavern to process.
Some tips for doing this

Here's a small example of a 500mx500m grid with lines 100m apart:
::

   *fix 0W 000 000 0
   *fix 1W 000 100 0
   *fix 2W 000 200 0
   *fix 3W 000 300 0
   *fix 4W 000 400 0
   *fix 5W 000 500 0

   *fix 0E 500 000 0
   *fix 1E 500 100 0
   *fix 2E 500 200 0
   *fix 3E 500 300 0
   *fix 4E 500 400 0
   *fix 5E 500 500 0

   *fix 0S 000 000 0
   *fix 1S 100 000 0
   *fix 2S 200 000 0
   *fix 3S 300 000 0
   *fix 4S 400 000 0
   *fix 5S 500 000 0

   *fix 0N 000 500 0
   *fix 1N 100 500 0
   *fix 2N 200 500 0
   *fix 3N 300 500 0
   *fix 4N 400 500 0
   *fix 5N 500 500 0

   *data nosurvey from to

   0W 0E
   1W 1E
   2W 2E
   3W 3E
   4W 4E
   5W 5E

   0S 0N
   1S 1N
   2S 2N
   3S 3N
   4S 4N
   5S 5N

-------------------------------
Import data from other programs
-------------------------------

Survex supports a number of features to help with importing
existing data.

Unprocessed survey data in Compass or Walls format can be processed
directly, and mixed datasets are support to aid combining data from
different projects using different software.  This also can help if
you want to migrate data into Survex from another format as you can
leave the existing data in its original format and just use Survex
native format for new data, or if you prefer to convert everything
to Survex native format it can be done in phases.

Processed survey data in Compass or CMAP formats can be viewed in
``aven`` and used with any Survex command line tool which takes
processed survey data.

For data in formats without explicit support, you may be able to read the data
by renaming the file to have a ``.svx`` extension and adding a few Survex
commands at the start of the file to set things up so Survex can read the data
which follows.  For example, you can specify the ordering of items on a
line using ``*data`` (see Survex Keywords above), and you can specify
the characters used to mean different things using ``*set`` (see
Survex Keywords above).

The ``ignore`` and ``ignoreall`` items in the ``*data`` command are often
particularly useful, e.g. if you have a dataset with LRUD info or
comments on the ends of lines.

-----------------------------------------------------
See errors and warnings that have gone off the screen
-----------------------------------------------------

When you run Survex it will process the specified survey data
files in order, reporting any warnings and errors. If there are no
errors, the output files are written and various statistics about
the survey are displayed. If there are a lot of warnings or
errors, they can scroll off the screen and it's not always
possible to scroll back to read them.

The easiest way to see all the text is to use ``cavern --log`` to
redirect output to a ``.log`` file, which you can then inspect
with a text editor.

----------------------------
Create an Extended Elevation
----------------------------

You can create a simple extended elevation from ``aven``, using the
``File->Extended Elevation...`` menu option.  This takes the currently
loaded survey file and "flattens" it.

Behind the scenes this runs the ``extend`` command-line program.  This program
offers more powerful features, such as being able to control which way legs are
folded and where loops are broken, but currently these features are only
accessible from the command line (the intention is to allow them to be used
from ``aven`` in the future).
