The therion data syntax is thoroughly explained in the Therion book [thbook 10-11].

The therion data files are text files, with lines of commands (with arguments and options), lines of data, and lines of comments (these begin with a character '#'). The commands can be single-line or multiline. In this case there is a termination command, that is a command with the name made by prefixing the command name with "end". For example the command centerline is terminated by the command endcenterline.

The data lines can contain numerical values or options for the command. In the case of options this applies to the data that follow.

The character '#' marks the beginning of a comment. Inline comments are allowed: everything that follows a '#' up to the end of the line is treated as comment (and ignored). The backslash character 'at the end of a line denotes continuation on the following line as if they were a single line Arguments and options with spaces must be enclosed in double quotes '"', if they are character strings, or square brackets '[' ']', for numerical values. For example the value of a RGB color is composed by three numbers (between 0 and 100) and is written in square brackets: for instance [100 0 0] is the red color.

The keywords may contain the letters of the alphabeth, digits, underscore '_', minus sign '-', and slash '/'. Words can contain also plus sign '+', star '*', comma ',', period '.', and single quotation "'". To use a keyword as value in a data line you must prefix (escape) it with an exclamation mark '!'.

The format of the dates is yyyy.mm.dd$hh:mm:ss.ss. A time interval is composed by two dates joined by a dash (minus sign '-'). The name of a person is made of two strings separated by a space, ie, "name surname". Only one space is allowed. If the name has more than one space use slash '/' in place of the first space. Among the units there are meter centimeter (also m and cm), degree (deg) and percent.

therion commands have a context, ie, a command must occur inside another which is its context. The following figure shows the hierarchy of contexts: the contexts of the commands are shown as arrows.

encoding type.
This command defines the encoding used to write the data that follows. For example encoding UTF-8 or encoding ASCII.

input file.
This command tells therion to read in another file. If the filename contains a directory separator you should use the slash '/' for better portability. It is good practice to avoid absolute names.

survey name.
This command defines a level in the namespace of the surveys. The name of the level is the argument to the command (the name of the survey). Among the option there are declination (to specify the value of the magnetic declination correction that must be applied to the data) and title, that defines the title of the survey.

The entrance option is used to specify the main entrance to the cave, in case there are several entrances. For example, "-entrance station_01", where "station_01" is the name of the entrance station. The entrance is used in the list export.

centerline or centreline.
This command defines the start of survey data. It has sevral options:

• date date_value
• team person [roles]
• units quantity [factor] units: units for a certain quantity. A scale factor can be specified, eg, "units length 0.01 meters". The quantity can be a measured quantity, such as "length" or "compass", or "dimensions", to indicate all the transversal dimensions.
• sd quantity value units: standard deviation for a certain quantity. For example, "sd compass 5 deg" means that, with a 70% probability, the compass readings have a +/- 5 degrees error. The units for fix points standard deviation is the same as the units for fix points. However if you change the coordinate system for fixed points the units for their standard deviations are not changed; you can specify the units explicitly (eg, with the command "units position m"), or use the units in the sd command (eg, "sd z 10 m").
• declination value units sets the magnetic declination for the data: the true bearing is the magnetic (measured) bearing plus the declination value;
• infer object on/off, where "object" can be either "plumbs" or "equates".
• mark [stations] type, where the type can be fixed, painted, or temporary (default)
• station name comment flags associates a comment to a station, and, optionally, a list of flags. If the comment has spaces it must be enclosed in quotations '"'. Example: station 32 "continuable, with less rock". The flags can be either entrance, continuation, fixed, not-fixed, attr (followed by the name-value pair of the attribute), air-draught (possibly qualified by ":summer" or ":winter"), doline, sink, spring, dig, arch, overhang, probe, and explored (followed by the explored length, requires that the continuation flag has been specified). To specify only the flag, insert an empty comment, ie "". Example: (in the centerline block) station 3a "" continuation explored 23m.
• fix station x y z: fixes the geographical coordinates of a station. Example "fix 1 1529802.9 5089076.7 2214.6" defines the coordinates (in this case the reference system is Rome-40) of station 1: X is the east coordinate, Y the north one, and Z is the altitude. They are all in meters.
• cs name sets the coordinate system for the fix commands.
• flag: "flag surface" specifies that the shots that follow belong to a surface survey, and do not count in the statistics of the cave. "flag duplicate" denotes shots that are duplicates, and do not count towards the cave length. The flag "splay" denotes splay legs, ie, sideway legs that do not contribute to the survey length. Shots that have one station either '.' (dot) or '-' (dash) are considered splay shots even if the flag is not specified. The dot is for splay shots to point inside the passage; the dash for splay shots to points on the walls.
• equate stations: defines the coincidence of two or more stations. For example "equate 1 24@main_passage". It's an error to equate two fixed stations, even if they have the same fixed coordinates.
• data style data_order: defines the type and order of the survey data on the data lines
• walls type: the type can be auto, on, or off. It specifies whether the LRUD data must be used in generating the 3d models. If set to auto LRUD are used only when there is no scrap for the givel centerline.
• extend type [stations]: it is used for the extended section. The type can be left, right, break, start, ignore. It can have zero, one, or two stations. In the first case the extend specification applies to the shots that follow until a new extend specification. With one station the extend specification applies to the shots that connect to that station. With two stations the specification applies to the shot(s) that connects them; if there is none it's an error.
• vthreshold value unit: defines the angle threshold above which the LRUD data are interpreted as left, right, front, back (perperdicular to the shot).

The command infer plumbs on specifies that the shots +/- 90 must not be corrected in inclination. The command infer equates on states that shots of length 0 must be treated as an equate command (no error correction).

Currently supported coordinate systems are "UTM", "long-lat", "lat-long", czechoslovak "JTSK" and "iJTSK", and ESRI and EPGS codes. Coordinate systems are internally specified in PROJ4 library format, http://proj.maptools.org . Briefly this is a string with keyowrd prefixed by plus sign and separated by the value by the equal sign. For example,

  +proj=latlong +datum=wgs84 +pm=rome

Other keywords are the ellipsoid (+ellps), the false origin parameters (+lat_0, +lon_0, +x_0, +y_0), the scale (+k), and the units (+units).

Coordinate system can be specified also in the surface and layout commands, as well as in the configuration file (for the output). By default the coordinate system is "local", ie, therion assumes that you are working with a local coordinate system. The data entered are interpreted as in the defined coordinate system. For example

  cs long-lat
  fix 1 19:20 34:30 1500

means fixing point 1 at E19deg20min, N34deg30min altitude (above sea level) 1500 [m].

scrap.
A scrap encloses a portion of cave map that contains no overlapping passages. It usually cover about hundred meters of cave passages. It contains points (symbols and texts), lines, and areas. The contour of the scrap is formed by lines with the option -outline. This can be "out", "in" or "none". Lines of type "wall" have -outline out by default. Other lines have -outline none by default. The lines of the contour must not intersect, otherwise MetaPost gives a warning message (therion sees the message but continues). It is good practice to check for these messages and fix them anyways.

A scrap must have two stations that provide its reference frame. If it has only one station (or none), as is the case for most cross-sections, it must have the option -scale. The scrap options are

• projection specifies the type of projection. It can be none (cross sections), plan, elevation (vertical projection), and extended (extended elevation).
• the scale option defines how to calibrate the scrap, ie, how to convert canvas pixel coordinates to real meter coordinates. It is used if the scrap does not contain enough station points to calibrate it. The most general form has eight numbers (and an optional units of length), The eight numbers are pairs of pixel coordinates and real coordinates for two points. These are set when you calibrate the scrap by dragging the red arrow endpoints over two points for which you know the real coordinates, that you write in the Scrap control of the xtherion map editor. More simply the scale option defines only how to scale canvas pixel to meters. In this case it takes just one number (the meters per drawing unit), possibly followed by the length units, if it not "meter". Alternatively, it can take two numbers, say scale A B; it says that A drawing units correspond to B meters.
• stations ... lists the stations that must be drawn in the scrap and are not used to calibrate the scrap. The need not be listed among the points of the scrap.
• cs defines the coordinate system for the scrap. It is useful when you want to import an image with no survey station, but with points in the system coordinates grid.
• sketch filename x y specifies to include the given bitmap under the scrap. The (x,y) position corresponds to the lower-left corner of the bitmap. To add a background sketch to a scrap you can use the background-sketch button of the Scrap control in xtherion map editor. You need the layout sketches on option to display it on the output. Furthermore you may select the warp algorithm with the sketch-warp thconfig command.
• walls. It can be "on", "off" or "auto". It specifies whether the scrap should be used or not in the 3d reconstruction.
• flip can take values "none" (default), "horizontal", or "vertical". Its effect is to flip the scrap after the scale transformation. A horizontal flip may come handy when you need to reverse your scrap in the extended elevation map.
• title specifies the title of the scrap;
• author specifies the author of the scrap;
• copyright specifies the scrap copyright.

point x y type.
This command defines a point in the drawing, giving its coordinates and its type. Most of the cave symbols are associated with types of points. Text labels are also point objects. There are also points that do not have a representation on the drawing (for instance points that define the dimensions of the passage). The types of points are

• objects:
  • "station"; it must have the option "-name" with the name of the station
  • "section" is a reference for a cross-section, that is specifed with the option "-scrap"
  • "dimensions" specifies the dimensions of the passage. It must have the option "-value"
• labels
  • "label",
  • "remark", a note
  • "altitude", to show the altitude of the point relative to the grid.
  • "height" is used for the height of cave features such as chimneys.
  • "passage-height" for the height of the passage;
  • "station-name", to write the name of a station on the map.
  • "date", for the dates
  • "continuation", with a description (option "-text") and a continuation code (option "-code"). The continuation code can be any word.
• fillings: "bedrock" (solid rock), sand, raft, clay, pebbles, debris, blocks, water, ice, guano, snow
• speleothems: flowstone, moonmilk, stalactite, stalagmite, pillar, curtain, helictite, soda-straw, crystal, wall-calcite, popcorn, disk, gypsum, gypsum-flower, aragonite, cave-pearl, rimstone-pool, rimstone-dam, anastomosis, karren, scallops, flute, raft-cone
• riggings: anchor, rope, fixed-ladder, steps, bridge, traverse, camp, no-equipement
• entrance and terminations: continuation, narrow-end, low-end, flowstone-choke, breakdown-choke, entrance, dig;
• others: archeo-material, paleo-material, vegetable-debris, root, water-flow, spring (water source), sink (of water), air-draught (the intensity is specified by the option "-scale"), gradient

Certain types of points can have options:

• -subtype:
  • "station" can have subtype "temporary", "painted", "natural" and "fixed";
  • "water-flow" can have subttype "permanent", "intermittent" and "paleo"
• -orientation, the value is given in degrees
• -align: usually for texts. It can be "center", "top", "left", etc.
• -scale specifies the dimension of the symbol from extra-small to extra-large: "xs", "s", "m", "l" or "xl" ("tiny", "small", "normal", "large", "huge"). At aglobal level the dimensions of the symbols can be set with the layout option "base-scale" (or with the command "u:=dimension" in a "code metapost" section, eg. "u:=10pt", "ahlength:=dimension" for the lines).
• -place, specifies the level where to place the symbol, during the construction of the map. For example "-place bottom".
• -clip, specifies whether the symbol is clipped to the scrap outline or not.
• -visibility, if "off" the symbol is not drawn
• -context, defines the context of the symbol, ie the current symbol is drawn as the context symbol in the output.
• -id, defines the id of the symbol.
• -name, for points of type "station" specifies the name of the station.
• -extend, for points of type "station". It has only a possible argument, namely "prev" followed by a station name. For example -extend "prev 1" (the quotes are necessary).
• -scrap,
• -text, for points of type "label" and "remark" ...
• -value, for points like "altitude", "dimensions" etc..

line type.
The "line" command, like the "point" command, has a type: wall, contour, slope, ... or it can be a filling, a label, or a special line type (border, arrow, section, survey).

The difference between "gradient" and "slope" is that the first draws a single arrow (in the direction of the line), while the second drawn several ticks (in directions roughly orthogonal to the line) [thmail 2006-05-05].

The "line" command can have options:

• -subtype. The following subtypes are possible
  • for the "wall" lines: invisible, bedrock, sand, clay, pebbles, debris, blocks, ice, underlying, presumed;
  • for the "border" lines: visible, invisible, temporary, presumed;
  • for the "water-flow" lines: permanent, conjectural, intermittent (temporary);
  • for the "air-draught" lines: summer, winter;
  • for the "survey" lines: cave, surface.
• -close can be "on" or "off" and it specifies whether the line is a closed path or not.
• -mark,
• -orientation,
• -outline, specifies whether the line is part of the contour of the scrap (if it has value "in" or "out") or not (value "none"). By default lines of type "wall" have "-outline out" and the others do not have outline [thwiki 9].
• -reverse, states whether the direction of the line is reversed;
• -size, defines the thickness of the line;
• -smooth,
• -adjust, is used for horizontal (value "horizontal") and vertical (value "vertical") straight lines: the points with this options are aligned with the previous point, horizontally or vertically, respectively. It has effect only in elevation maps, not for plan maps.
• -place specifies on which level to place the line when the map is generated. It can be "default", "bottom", or "top".
• -clip can be "on" or "off";
• -visibility specifies whether the line should be drawn or not. It can be "on" (default) or "off".
• -context defines the context of the line, ie, which line type should be used to draw the line.
• -altitude,
• -border,
• -gradient,
• -head,
• -text.

area.
An area is defined by the lines that make its contour. These can be of any type, but they must be listed in order, and intersect each-other consecutively. The simplest way to ensure that this is the case is to draw a closed line and use only that for the contour of the area. However this is often not possible.

The "area" command has a type (the type of the area):

• water, a pool of water, a pond
• sump,
• sand,
• debris,
• blocks,
• snow,
• ice,
• clay,
• pebbles,
• bedrock.

The "area" command can have options:

• place specifes on which level to place the area to make the map. For example, "-place top".
• clip can be "on" or "off". This option is important when you must join scraps and you need to continue an area beyond the outline of the scrap it belongs: add the option "-clip off".
• visibility can be "on" or "off". If it is "off" the area is not drawn.
• context defines how to draw the area, ie, which area type to use to draw it.

join.
The "join" command connects two scraps, or a set of two or more points of the map. It is advisable to put the joins in places where the cave is simple (a passage with no features), otherwise you must put "join" commands for any object. There are two syntaxes of "join":

In the first case you join points and/or line points. The point name used in the "join" command must be id of scrap points ("point" command) or line-points (point belonging to a "line" command). In the latter case the id is the line-id followed by the point index; for example "my_line:2" denotes the third point on the line "my_line" (point indices start from 0). "my_line:end" is the final point of the line "my_line". Depending where the join command is the point name and line name might need to be completed with the survey path, eg, "my_line@subsurvey1.survey2:0".

Examples of "join" are in chapter 3 .

In the second case you join two scraps. Only the lines of type "wall" are joined. To continue a graphical element beyond the outline of the scrap it belongs to, it must have the option "-clip off".

join has two options:

• -smooth can be "on" or "off". It defines whether the line join should be smoothed or not.
• -count, which is followed by a number, specifies the number of connections for a scrap "join".

The join command do not chain. Therefore you cannot type and have "a", "b", "c" all coincide. You must type

equate.
Identifies two (or more) station names. See survex for more details.

map.
A map is acollection of scraps or maps (cannot mix them together). It can include a survey (the centerline will be displayed with the map). This command specifies as assemble of scraps (or maps) and surveys. The "map" command is multiline,

   map id [opzioni]
      <ids of scraps or maps>     <--- level 0
      break
      <ids of scraps or maps>     <--- level 1
      preview <above|below> another_map
   endmap

The break command splits the map on different levels. It is not possible to mix together ids of scraps and ids of maps: only one type can be used. The map is drawn in the output starting with the lowest level, therefore the scrap at level "1" are covered by those at level "0". The preview command includes the outline of another map.

The select option -map-level N specifies the levels up to which elements of the map are included in the export. The "normal" elements of the selected map are at level 0. Each element with on offset is on a lavel one step higher. In the following example map "m12" is at level 1 of map "m", therefore map "m2" is at level 2 of map "m". With "select m -map-level 1" only map "m2" is displayed with an offset.

  map m1 ...
  endmap

  ...

  map m12 ...
    m1                 # this is at level 0 with respect to m12
    m2 [10 10 m] above # this is at level 1 in m12
  endmap

  map m ...
    m3 
    m12 [10 10 m] above
  endmap

The map elements with a preview are displayed only if they are at level 0.

The map command has options:

• title specifies the title of the map;
• proj specifies the projection type. It can be "none" (cross-sections), "plan", "extended" (extended elevation), and "elevation" (vertical projection).

surface.
This is a multiline command, used to include surface topography data. These can be given as a bitmap file, or as grid of altitudes. Therefore there are two possible syntaxes. In the first case you must provide the filename and its relation to the cave map,

   surface
     bitmap file_name calibration
   endsurface

where the calibration connects two points in the file (expressed as X-Y pairs in pixel units, with the origin (0,0) at the lower-left corner) to two points in the drawing, expressed as x-y in meters, or as station names. Therefore the syntax is

    X1 Y1 x1 y1 X2 Y2 x2 y2
\br
    X1 Y1 station_1 X2 Y2 station_2

In the second case you must specify parameters of the grid and provide its data,

   surface
      grid-units units
      grid origin_x origin_y step_x step_y size_x size_y
      grid-flip [none|vertical|horizontal]
      data_of_the_grid
   endsurface

In this case the origin is the lower-left corner of the grid. The step is the dimension of the grid-cells, and the size is the number of grid nodes on the rows (x) and on the columns (y). The grid data are the altitudes (above sea level, in meters) at the nodes of the grid. They must be written by rows (from the west to the east), scanning the rows from the bottom (south) to the top (north).

import.
This command is used to import survey data in an external format, "3d", "plt" or "xyz".

grade.
This command defines the grade, ie, the accuracy, of the survey. For example the option grade N in the centerline, specifies the BCRA grade of the survey. Here N anges from 0 to 7. Grade 0 refers to data with no quality, ie data that nobody can locate now. Grade 7 is grade BCRA X.

The sd option of data overcomes the general grade specification.

The following is a table of accuracies (at 2 std, ie, 95 % confidence) for the position grades.

grade	position error	altitude error	comment
0		td position unknown
1	1000 m	1000 m	rough estimate, by memory
2	100 m	100 m	GPS in bad conditions
3	15 m	45 m	GPS with large-scale map
4	5 m	15 m	GPS with long observation
5	1 m	3 m	GIS GPS
6	15 cm	15 cm	geodetic GPS, theodolite, technical
7	5 cm	5 cm	geodetic GPS, precise theodolite

TODO an example and explain more.

revise.
This command is used to redefine properties of an object. It can ebe single-line, eg, "revise id -option1 value1 -option2 value2 ..." or multiline, terminated by the command endrevise.

TODO an example and explain more.

Data names
The join count option