Before we can tackle an example we must discuss the Therion approach. Every run of therion depends on a configuration file, which says what to do and how. The conventional name for this file is thconfig. It can be named as you like, but it is a good idea to include the string "thconfig" in its name (so that xtherion recognizes it as a therion configuration file). Having several different configuration files is convenient when you need to generate different views and output of your data. For example

   thconfig_only_centerline
   thconfig_only_walls
   plan.thconfig
   extended.thconfig
   wet_river.thconfig
   lox.thconfig
   kml.thconfig

The configuration file contains

• the list of what makes the survey (the data files);
• options about the presentation of the results (symbols, legend, etc.);
• the requested outputs.

There are two kinds of data files.

• survey data, conventionally with extension ".th";
• drawing data files, conventionally with extension ".th2".

Therefore the necessary steps to make a cave map with Therion are:

1. prepare the survey data files (text editor);
2. make the drawing data files (map editor of xtherion);
3. write a suitable configuration file thconfig (in the compiler window of xtherion);
4. compile everything with xtherion.

If everything goes well, the result is a pdf file that you can view with any pdf viewer. If there are errors, these are shown in the lower part of the compiler window, and you must correct them.

We have seen that Therion relies mainly on three external programs to generate cave maps: cavern, pdfTeX and MetaPost (which uses TeX). Indeed if you browse through the output of the compilation in the lower part of the compiler window, when you have run the test that comes with the distribution, you could noticed the logs of these programs.

xtherion just calls therion. Infact you can compile your cave project without xtherion, by invoking therion from the command prompt. The syntax of the therion command is described in app. 2.c .

The configuration file thconfig contains the data files (with pathnames relative to its directory), listed with the command

   source file.th

It may contain layout definition blocks. For instance,

   layout xvi_export
       scale 1 500
       grid bottom
       grid-size 10 10 10 m
       grid-coords border
   endlayout

The grid command says to draw the grid on the map. The value "bottom" says to put it on the lowest layer so that it does not cover the cave drawing. If instead of "bottom" you write "top" the grid appears over the cave drawing [thexample 6]. The command grid-size defines the grid step, in X, Y and Z (the values must be followed by the units). You can also give the coordinates of the grid origin with the command grid-origin followed by the three coordinates [thbook 40]. The grid-coords command specify whether and where therion should write the coordinate at the grid points. It can take values "off", "border" and "all". For the plan the coordinates East and North are shown. For the elevation and extended elevation the height is shown.

The configuration file contains the commands that say which outputs to create. For example,

   export model -fmt survex
   export map -fmt xvi -layout xvi_export -o file.xvi
   export map -proj extended -fmt xvi -o extended.xvi
   export map -proj plan -o plan.pdf
   export atlas -proj plan -o plan_atlas.pdf

Further details on the syntax of the configuration file are in app. 2.a .

The survey data files (extension .th) have a syntax very close to that of survex [1] , but there are a few important difference:

• comments begin with '#' instead of ';'
• keywords do not have the initial '*'
• in place of "begin"-"end" therion uses survey-endsurvey
• therion refers to the stations as "station@survey.cave" instead of "cave.survey.station"
• there is no "export" command
• the survey data, and the commands that refer to them, must be enclosed in a centerline-endcenterline block
• the separator of decimals is the point '.'
• the "*title" command is replaced with the option "-title" of the survey command

The syntax of therion data files is described in app. 2.b which lists also the commands for the drawings. For the time being you can get by with the following:

• a survey file starts with the survey command. This is followed by the survey ID and, optionally, by the survey title, on the same line. For example: survey mc0 -title "My Cave". If the title has a blank space you must enclose it in double quotes. The "survey" command is like an open brace; it must be closed by the endsurvey command.
• inside the survey-endsurvey block there can be one or more centerlines (block centerline - endcenterline), and other surveys. Inside the centerline - endcenterline blocks you write the survey data and other commands.
• the command data states the style and the order of the data on the survey data lines. Examples:
  data normal from to length compass clino,
  data diving from fromdepth to todepth compass tape,
  data dimensions station left right up down;
• the command fix defines the geografical coordinates of a station. Example: fix 1 575628 4476124 1250. The coordinates are interpreted in the current coordinate system. This is specified with the command cs, for example "cs UTM32". If not specifed the "local" coordinate system is used. You can repeat the fix for several station, thus fixing more points.
• the command date says the date of the survey. Example: date 2002.05.18 is May 18, 2002. The date is sued by Therion to correct the data with the magnetic declination; if the declination is not specified Therion computes it using geomag data tables (see below).
• the command team says the name of a surveyor and his/her roles. Example: team "A. Maconi/(GGM)" compass clino.
• the command units defines the units for one of the values. For example units length 0.1 meters says that lengths are in tenths of a meter. By default distances are in meters, and angles in degrees.
• the command declination says the magnetic declination correction. If put inside a survey it applies to all the centerlines; otherwise put it inside a centerline. The declination is a correction to get the geographic bearing from the magnetic bearing, more precisely, geographic_bearing = magnetic_bearing + declination. In particular the declination is positive if the compass north points to the east of the geographic (true) north.
• the survey data are written a shot per line, and in the order defined in the data command. As separator of decimals use the point '.'
• the command extend states how to draw the shots that follow in the extended section. It takes a value that can be an abosolute specification: "left", "right", "vertical"; or a specification relative to the previous shot: "normal", "reverse". Other values, "start", "ignore" and "hide" are for the drawing of complex extended elevation maps (see below).
• comments start with the character '#'

Therion has a built-in an earth geomagnetic model, that is automatically used to correct the survey data with the magnetic declination if a supported coordinate system is specified, using the survey date. If you give the declination command, therion uses the value that you provide. The declination command, in the centerline block, can take a value with the units (for example declination 0.53 deg). The -declination option, of the survey command, can take one or more date-value pairs, with the units at the end (for example -declination "2007.01.01 0.5 2008.01.01 1.2 deg"). Finally the command can take an empty string (ie, just -declination ""); in this case the value of the magnetic declination is reset. The figure below show the effect of the magnetic declination (the value has been exagerated).

The survey data file must have a block survey/endsurvey enclosing everything, except the command encoding. Therefore the survey is a container of all other objects. As it can contain also other surveys, it is possible to structure the surveys data (including the data of the drawings) hierarchically. survey is like a directory in a filesystem. Just like a directory it has a name, which is used to refer to the survey. The name of the survey (the ID) is written after the "survey" command on the same line [thbook 12].

survey can contain the command input which includes another data file (a drawing file, or a survey file). The input command can be place either inside a centerline-endcenterline block or ouside it.

   encoding UTF-8
   survey nome -title "cave title"
     centerline -extend left
       title "survey title"
       date 2006.10.26
       team "S. Mudrak" notes 
       team "M. Budaj" clino compass tape
       data normal from to length clino compass
       1 2 4.37 12.5 321
       2 3 12.56 10 276
       ...
       ...
     endcenterline

     input file.th2
   endsurvey

The centerline command can be spelled also centreline.

The centerline command in the above example has the option -extend left. This says to draw the extended section from right to left. By default therion draws it from left to right. Alternatively you can write the extend command inline, ie, in the middle of the data lines. If it is followed by "left" or "right", the shots that follow it are drawn as stated in the command. If the extend inline command is followed by "normal" or "reverse" the shots that follow are extended as the shot before the command or in the opposite side, respectively [thbook 16].

There is also extend ignore for shots that should not be used in the computation of the extended elevation. This is useful for loops. It is not a way to have shots unstretched (ie, flattened) in the extended elevation map.

For shots that are across the main passage, and you do want to draw only the vertical displacement in the extended elevation there is extend vertical. Finally there is extend hide for shots that should not appear in the extended elevation at all.

The extend commands should be placed according to the cave sketch drawings. If the cave in the sketch goes to the right and you write extend left in your data the outcome is probably not what you expect.

The command input is used to include another data file. In the above example it includes a drawing data file (extension .th2). If the file has extension .th, this can be omitted [thbook 12].

The file with the data of the drawings (called scraps) are text files with commands for points, lines, areas, symbols, text, etc. These commands are interpreted by therion when you compile the project, to produce input files for MetaPost.

The drawing commands are listed in app. 2.b , and will be described as we go along with therion using sample data.

Extend ignore command
Magnetic declination