To create and export cave maps, therion collects all the informations of the commands of the data files and the configuration file (layout) and make a multilevel drawing. The process is explained in the "Therion Book" [thbook 36-37].

The organization of the drawings (scraps) in maps allows to build different hierarchies of maps, each one suited for a specific output, map or atlas, emphasizing survey date or cave development, etc. The map hierarchy is a very flexible tool, although some care becomes necessary when the number of hierarchies grows.

Graphical elements are points (symbols and texts), lines and areas. Each element can be

• visible or invisible (option -visibility: either "on" or "off"). Only the visible elements are exported in the map.
• clipped to the outline or continuing outside of it (option -clip: either "on" or "off");
• masked because it depends on another alement, that is its context (option -context);
• placed on a specific leyer (option -place: either "bottom", or "top", or "default").

A graphical element is visible (ie, it appears in the outcome) if

• its -visibility is not "off" (it is "on" by default for every element);
• it is not hidden due to layout options (symbol-hide);
• it does not depend on a context that has been hidden.

At configuration level (layout) it is possible to hide graphical elements depending on their type. For example, you can use the layout option "symbol-hide line wall" to inhibit the drawing of the cave walls on the map. The option "symbol-hide line survey" hides the certerline segments. Other examples are "symbol-hide point cave-station" and "symbol-hide point surface-station", to hide the stations of the cave surveys and of the surface surveys, respectively, or just "symbol-hide point station", for both.

At the same level the user as control on what to show with the command "symbol-show". For example "symbol-show point station" determines whether the cross marking the stations should appear in the output pdf. On the other hand "symbol-show point cave-station" (or surface-station) determines the display of the glyph of the flag and the text.

The "group" type defines groups of symbols. The possible groups are

• "group centerline"
  • subgroups: "surface-centerline", "cave-centerline"
  • lines: survey:surface survey:cave
  • points: surface-station cave-station
• "group sections":
  • lines: section
  • points: section
• "group water"
  • lines: water-flow
  • points: water-flow, water, sink, spring
  • areas: water, sump
• "group sediments"
  • lines: wall:sand, wall:clay
  • points: sand, clay, clay-tree, raft, raft-cone, guano
  • areas: sand, clay,
• "group passage-fills"
  • lines: rock-border, rock-edge, water-flow
  • points: bedrock, sand raft, clay, pebbles, debris, blocks, water, ice, guano, snow
  • areas: water, sump, bedrock, blocks, clay, debris, ice, pebbles, sand, snow
• "group equipment"
  • lines: rope
  • points: anchor, rope, fixed-ladder, rope-ladder, steps, bridge, traverse, camp, no-equipement
• "group speleothems"
  • lines: flowstone, moonmilk
  • points: flowstone, moonmilk, stalactite, stalagmite, pillar, curtain, helictite, soda-straw, crystal, wall-calcite, popcorn, disk, gypsum, gypsum-flower, aragonite, cave-pearl, rimstone-pool, rimstone-dam,
  • areas: flowstone, moonmilk
• "group ice"
  • lines: wall:ice
  • points: ice, ice-stalactite, ice-stalagmite, ice-pillar, snow,
  • areas: ice, snow
• "all"

The option "symbol-hide group all" hides all the elements of the map, except those that are explicitly rendered with the option "symbol-show". For instance you could use the option "symbol-show line survey" to draw only the stations after hiding all the elements.

Certain points and lines can be further qualified,

• "point flags:flag_name"
  • flag_name: entrance, continuation, sink, spring, doline, dig, air-draught, arch, overhang
• "line wall", "line wall:subtype"
  • subtype: bedrock, blocks, clay, debris, ice, pebbles, presumed, sand, underlying, unsurveyed, pit, overlying, moonmilk, flowstone
• "line water-flow", "line water-flow:subtype"
  • subtype: conjectural, intermittent, permanent
• "line border", "line border:subtype"
  • subtypes: temporary, visible
• "line survey", "line survey:subtype"
  • subtype: surface, cave
• "point station", "point station:subtype"
  • subtype: fixed, natural, painted, temporary, surface station, cave station
• "point air-draught", "point air-draught:subtype"
  • subtypes: winter, summer
• "point water-flow", "point water-flow:subtype"
  • subtypes: intermittent, paleo, permanent
• "point passage-height", "point passage-height:specification"
  • specification: positive, negative, both, unsigned
• "point height", "point height:specification"
  • specification: positive, negative, unsigned

To hide/show stations according the certain flags use flag:flag as symbol-type. Here "flag" is one of entrance, continuation, spring, sink, doline, dig, etc. For example: "symbol-show point flag:entrance".

It is possible to pre-define various sets of symbols which should be hidden at particular scale (in separate layouts which are copied into layout in use). If you want to hide only some (not all) of the symbols in a given type, you can use custom attributes combined with modifications in MetaPost definitions of symbols. For example, for p_label you would add condition that it should be displayed if the scale (denominator) is <=1000 or the custom attribute is_important is set to 1. For example

  code metapost
  def p_label(expr txt,pos,rot,mode) =
  if (mode=1) or (mode=7): interim labeloffset:=(u/8) fi;
  if (Scale > 4):
    lab:=thelabel(txt scaled 0.0001, pos);
  else:
    lab:=thelabel(txt, pos);
  fi;
  if mode>1: pickup PenD fi;
  ...

The remaining part of the definition is unchanged from the therion source file. The normal label mode is 0. The "Scale" variable is the layout scale denominator divided by 100.

It is also possible to color all the symbols of a certain type or group. The command is symbol-color and its syntax is similar to that of symbol-hide.

Some symbols are clipped by default to the inside of the map outline:

• the symbols of fillings ("sand", "mud", "guano", ...).
• the lines that do not have the -outline option, except section, arrow, label, gradient and water-flow.
• all the areas

Some graphical elements, that are clipped by default, can be extended beyond the outline using the option -clip off.

Every graphical element belongs to a layer (or group). The graphical elements are rendered in the cave map following the order of the layers. There are five layers:

• bottom, the lowest layer. It contains only elements that have the option -place bottom.
• default-bottom. It contains the areas.
• default;
• default-top. This contains the ceiling-step and chimney elements by default.
• top. It contains the elements that have the option -place top.

The default layer contains all the elements that do not belong to one of the other layers. The ordering of the graphical elements in a layer follow that of the commands in the input data files. The graphical elements are drawn starting from the last, therefore an element is drawn over those that follow it in the file. The map command defines a layer: if it contains two scraps these are on the same layer, and they are drawn at the same level (unless you put a break command in between). If it contains two maps these forms two layers and the second one is drawn underneath the first.

The cave map is built in steps:

1. the drawing area is filled with the background color (color map-bg).
2. if there is the surface command and the layout option surface bottom, the surface image is drawn.
3. the outline of each scrap of the map is filled with white, so that it can be drawn in the next steps.
4. if the layout has the option grid bottom the rectangular grid is drawn (with the specified size).
5. if there is a map with the "map" option preview below, this is drawn, with the specified color: color preview-below (layout command).
6. for each level of the map command, starting from the last (the lowest level):
   1. the outline of each scrap is filled with the foreground color, color map-fg.
   2. the areas of each scrap are rendered, clipped to the inside of the outline.
   3. for each scrap all the clipped elements are drawn, following the order of definition (of the layer).
   4. the centerline segments are drawn
   5. for every scrap all the unclipped elements are drawn, following the order of definition (of the layer).
   6. the station points are drawn.
   7. all the labels (including wall-altitude) are written.
7. if there is the preview above map, this is drawn with the specified color, color preview-above (layout command).
8. if there is a surface image and the layout has the option surface top, the image is drawn.
9. the grid is drawn if the layout has the option grid top.

When you add a scrap, or a map to the project, by deafault the output map contains only those and the rest of the centerline is no longer shown. If you want to get a map with the scraps you have drawn so far, and the centerline as well, you should define a top-level map that lists the scraps (or the maps at lower level) and, after them, the top-level survey. Next you select this top-level map for the export.

  source testU

  source
    map the_map
      mapU@surveyU
      surveyU
    endmap
  endsource

  select the_map

The figure below shows the result with the survey in the top-level map (on the right) and without it (on the left).

The contents and the position of the header of themap are configurable. The option "map-comment" allows to insert a comment in the header, for example map-comment "Scale 1:500". The comment string is interpreted as HTML. If you put more than one "map-comment"s, only one will appear. To put a multiline comment in the output, you must write the comment as a single string with the HTML tag "br".

The option "map-header-bg" can have argument "on" or "off" (default). If it is "on" the header is written on a background which could hide part of the map.

The header position is specified through the layout option "map-header". This has three arguments, the value of X, the value of Y, and a string that says the type of the reference and can be one of "n", "ne", "e", ..., "nw", "center", "off". If it is "off" the header is not written. Any other value specifies the reference point (north, north-east, etc.) of the map header, for the placement. The (X,Y) values specify the shift of this reference point with respect to the lower left corner of the map. Positive X values denote shifts to the right (in meters). Positive Y values denote upward shifts. The figure below shows some placements of a map header with respect to the map.

You can insert a picture in the map header with the following map-image command. Images in pdf, png, jpg are supported. Therefore you can insert photoes, logos, and also a map, say the extented elevation on the page of the plan. For example,

  -layout-map-image 0 50 ne "./elev.pdf"

The object is added as a raster image, even if it is a pdf file. Therefore you cannot search the text or turn their layers independently on or off. The first two arguments specify the position of the inserted object in percent of the size of the map. The third argument is the corner of the inserted image used to compute its position. In the example, the elevation plan is inserted with its north-east cornet at offset (0,half-width) from the south-west corner of the current map (the origin of the current map is always the south-west corner and the axes are oriented to the right and upwards).

This feature is ok when you have to add a logo to your map, or for small caves where you want to put extended elevation and plan on the same pdf page. In this case prepare an extended elevation map without map-header and legend because you want to include only one in the final page. For bigger caves it is better to make separate pdf and join them together with other tools (e.g., pdftk on Linux and PdfMerge on Windows).

The output map title as determined by Therion will be empty if there are multiple maps selected for any one projection or there are multiple source surveys identified in the thconfig file, so that Therion cannot infer a unique title from the input data given.

If you don't select any maps, by default therion selects all maps. If there is no map therion exports surveys: if you don't select any surveys, by default therion selects all surveys. If you have defined more than one map and more than one survey in your source, then therion will probably not have a basis on which to choose a title. The simple approach is to select just one map.

If you are intentionally selecting multiple maps (so that they may individually be turned on and off in the resulting output pdf), you can override the map title with a bit of TeX code, (the code could test and replace the cavename only if this is empty)

  code tex-map
    \cavename={New Cave Name}
  endcode 

The option "statistics" includes or not, in the header informations about the survey statistics. It has an argument that can be a number, or "off" or "all". The number specifies how many data to write. For example "statistics topo 3" tells to write only the names of the first three surveyors. The value "off" specifies not to write anything, and "all" to write all the data. The statistics are

• "topo", informations about who did the survey ("centerline" "team" option) and the year. The names are ordered by the length of the surveys. In case of equal length, the order is alphabetical. It is possible to specify explicitly what to write using a layout option "code tex-map" containing the command \def\topoteam{...}
• "carto", the data of the author of the map;
• "copyright", copyright informations;
• "explo", informations on the people that explored the cave ("centerline" option "explo-team");
• "explo-length", it can be either "on" or "off", and it states whether to include the data of the length of explored cave for each explorer;
• "topo-length", it can be either "on" or "off", and it states whether to include the data of the length of survey for each surveyor.

The authors are defined with the scrap option "author". For example -author 2005 "marco corvi". The "copyright" are defined similarly (for each scrap). The author names appear after the header "Drawn by:", the copyright names appear after the copyright symbol "(c)".

For small caves you may want to place both the plan and the extended elevation on the same page (ie, the same pdf document). To do this you need to generate one of them and import it when you generate the other with the layout option map-image. For example, the layout command

   -layout-map-image 0 200 s plan.pdf

places the generated map at position (0,200) on the south side of "plan.pdf" (the Y axis is upward). For that matter any pdf file can be specified, so that this command allows to include any pdf file in the output map (the first page of the file is used). The included file pathname must be relative to the working directory.

Other image file formats are supported: JPEG and PNG. Furthermore many images can be inserted, by repeating the layout map-image command for each image.

When you put two maps together, it is a good idea to suppress the map header on one of them. If you insert in the configuration of the imported map the layout command that switches the map header off (ie, -layout-map-header 0 0 off) you cannot get the map comment either. You may want to have comments that say which map is the plan and which is the extended section. A way to get this done is to override the TeX map header commands for the imported map,

  layout empty_header
    code tex-map
      \legendtitle={}
      \cavename={}
      \scalebarfalse
      \cavelengthtitle={}
      \cavelength={}
      \cavedepthtitle={}
      \cavedepth={}
    endcode
  endlayout

  export map -output ext.pdf -proj extended \
    ...
    -layout-map-header 0 20 nw \
    -layout-map-comment "Extended section" \
    -layout empty_header

  export map -output cave.pdf -proj plan \
    -layout-map-image 0 200 s ext.pdf \
    ...
    -layout-map-header 0 0 n \
    -layout-map-comment "Plan"

  system "rm ext.pdf"

Here we played a little to adjust the map comment/header positions and that of the imported map. Notice also the system command to remove the intermediate map of the extended section.

The "export" command has a few options that refer to the PDF document [thbook 44]:

• "doc-author" specifies the author of the PDF document;
• "doc-keywords", lists the keywords of the document;
• "doc-subject", is a short description of the contents of the document;
• "doc-title", for the title of the document.

For example, you can define a layout with these options, and include it in the "export" command (using the option "-layout xpdf"),

   layout xpdf
      doc-author "your name"
      doc-keywords "cave, system"
      doc-subject "plan map of cave"
      doc-title "cave - plan"
   endlayout

If you open the PDF document of the map with acroread, under the menu "File | Doc properties", you can see these properties, as shown in the figure below.

Scrap and centerline
Maps shift
The map-image option
Plan and extended elevation together
Inserting a PNG image