The map command allows to organize the scraps and the "surveys" in the presentation of the output cave map. It is a multiline command with syntax

   map map_name -proj projection_type
     scrap | survey | map
     ...
     break
     scrap | survey | map
     ...
     preview above map
   endmap

All the objects in a map must be of the same type. Therefore you can make "maps" of "scraps", "maps" of "surveys", and "maps" of "maps". If the map is made of scraps (or maps) these must have the same projection type, otherwise there is an error of "projection mishmash".

The -proj option is not necessary when therion can infer the projection from the scraps or maps included in the map. The projection type can be "plan", "elevation", "extended", or "none". The "elevation" projection has an additional parameter specifying the direction of view. For example "[elevation 270]" means to project towards west. This parameter must be supplied also to the scraps projection attribute, otherwise a 0 (north) direction of view is assumed. The elevation direction of view must be written besides the word "elevation" in xtherion (see image), without square braces. A units can be added, eg, "[elevation 270 degrees]" (degrees can be abbreviated to "degree" or "deg").

The break command breaks the map on several levels. There can be more than one break. Each level contains one or more objects of type "scrap" or "survey" or "map". Each object is written on a line.

The select command is important when one wants an output with a specific structure. The argument of the "select" command must be a map. It is not possible to "select" scraps. If there are several maps and there is no "select" command the output contains all the maps, even the partial maps that are commented in the global one [thwiki 13, 16]. If there are maps, the scraps not included in any map do not appear in the output. It is possible to repeat the "select" command more than once in the configuration file. All the selected maps appear in the output. The resulting pdf will have a layer for each of the selected maps (and one for the surface image if defined). These layers can be toggled visible or not by the user of the pdf viewer.

The order of definition of the maps in the file or the order in which they are selected is important. The maps are rendered in reverse order of selection, from the last one selected (or defined) to the first selected (or defined). Therefore the maps defined first stay on top.

There is only one selection in a configuration file. Therefore it is not possible to select a map, export it in a file, unselect it, and select another map to export on a second file. To have outputs with different selections you need distinct configuration files.

With a double click on the map name in the "Map structure" control of the compilation window, a "select" command for that map is inserted in the configuration file.

With the select command you specify all the maps that must be included in the output. This opens the possibility for unusual results:

• if you put a map inside another as "above" or "below" and select the same map as well, you get the map both in the big picture as well as aside.
• if you make two maps, one with the survey (centerline), the other with the scraps, and select first th esurvey map then the scrap map the result contains the drawings (scraps) with the centerline sizes as rectangles on top of them.

The preview command is optional. It has two forms:

   preview above map_to_preview
   preview below map_to_preview

In the first case only the outline of the previewed map is drawn. In the second case a shade of it is drawn. The preview command requires a map as argument, not a scrap. It is useful when there is a cave passage underneath another and you want to draw its contour only, or its shade. The foreground and background color of the previewed map can be set with the layout options preview-above and preview-below. For example "preview-above [100 0 0]" sets the outline color to red, "preview-below [50 50 100]" sets the shade to light blue. The above and below preview colors affect also the shifted maps. This is useful for complex cave maps.

Preview below means that the passage is part of the lower layer for an atlas. It does not work with map export (M. Sluka). If you use "break" it is enough to draw lower passages with a lighter color.

The previewed maps do not immediately transfer when the map is included in another. The maps (or scraps) included in the output depend on the structure of the map commands and the select commands. Suppose to have the following hierarchy of scraps and maps:

  m1
   +-- s1 # s1 is a scrap
  m2
   +-- s2 # s2 is a scrap
  mA
   +-- s1
   +-- s2
  mB 
   +-- m1
   +-- m2 [...] above
  mC
   +-- m1
   +-- preview above m2
  mD
   +-- mB
  mE 
   +-- mC

In the usual situations, simple join commands with the name of the scraps is enough. You may optionally add a parameter count that specifies the number of connections. This works in most of the cases and is much simpler than adding ids to every object (and keeping track of them).

For example the code below joins scrap "testF1s" and scrap "testF2s" in two places (the option -count has been added with value 2). The outcome is shown in the figure below (with layout debug option on). The two surveys are positioned by fixing the station named "1" on each. Each shot is 10 m, and equate commands have not been used.

   survey testF
      input testF1.th
      input testF2.th
      join testF1s@testF1 testF2s@testF2 -count 2
   endsurvey

The subdivision of the cave drawing in scraps and maps must be made with care, trying to prevent problems that might arise when they are composed together to form the map of the cave. This requires planning, and, as such, some experience with therion is of great help.

The splitting of the map in scraps does not often correspond to the splitting in surveys. Surveys are usually ended at intersections of passages (crossways), and can cross over themselves following the cave passage in its winding. Scraps, on the other hand, should and in places where the cave passage is simple, to make scrap joining easier, and cannot intersect themselves, therefore the cave passage cannot pass over itself in the same scrap. but two or more scraps must be used for the drawing of a overlying passage. A crossway should be covered by a single scrap.

It is convenient to put the scrap files at the second level of the data file hierarchy, so that each scrap can refer to any survey. A global map file is necessary to collect the other map files and this should be located at the highest level (the first) of the hierarchy.

The scrap files are subdivided in directories, and the scrap files in each directory can be grouped in a "index.th2" file (or with the name of the cave branch). This file "include"s the individual scrap files specifies the joins among the scraps, and defines the maps.

The naming of scraps, maps, and other graphical items should follow a simple format and be reminescent of what part of the cave draing they refer to. For example the scraps of the file "gm0.th2" could be named "gm0_s1", "gm0_s2" etc.. The cross-section could be named "gm0_c1" etc. The lines could be "gm0_l1", the points "gm0_p1" and so on.

For a complex cave, with sevral surveys and scraps, it becomes necessary to follow some conevtion to avoid a mess of surveys and maps. This is particularly the case for maps, as their structure affects the resulting cave maps.

One way is to have one survey file for each survey trip, include in it the files with its scraps, and define the corresponding maps,

  # file survey1.th
  survey survey1
    centerline
      ...
    endcenterline

    input scrap1.th2

    map map11
      scrap11
    endmap

    map map12
      scrap12
    endmap

    map map1
      map11
      map12
    endmap
  endsurvey

At the next level of the hierarchy there is

  #file indexA.th
  survey surveyA
    input survey1.th
    input survey2.th

    centerline
      equate ...
    endcenterline

    map mapA
      map1@survey1
      ...
    endmap
  endsurvey

As an example we consider a simple piece of a fictitious cave with two branches. We assume to have two survey for each branch and three scraps for the drawing: one for the intersection, the other two, one each for the two branches. The figure below shows this subdivision.

The data hierarchical structure is

   cave
     +-- branch1
     |     +-- survey1
     |     +-- survey2
     |     +-- scrap1
     +-- branch2
     |     +-- survey3
     |     +-- survey4
     |     +-- scrap2
     +-- scrap3

The four surveys are contained each in one file. For example "survey1" is contained in the file "survey1.th":

   survey survey1
      centerline
         data normal from to length compass clino
         1 2 5.00   0 0
         2 3 5.00  45 0
         3 4 5.00  90 0
      endcenterline
   endsurvey

The surveys are grouped in the branches. For example "survey1" and "survey2" compose "branch1", together with "scrap1", as specified in the file "branch1.th". This file imports the two surveys and the scrap, identifies stations in the surveys (equate command), and defines a map "map1", containing only the scrap "scrap1".

   survey branch1
      input survey1.th
      input survey2.th
      input scrap1.th2
      equate 4@survey1 1@survey2
      map map1
         scrap1
      endmap
   endsurvey

The two branches and the third scrap ("scrap3") are collected in the file "cave.th" which identifies the stations at the intersection and defines how the lines of "scrap3" must join with those of the surveys "branch1" and "branch2". Finally it defines the map "map3", with all the three scraps.

   survey cave
      input branch1.th
      input branch2.th
      equate 2@survey3.branch2 1@survey1.branch1
      input scrap3.th2
      join line1@branch1:0   line2:end
      join line2@branch1:end line3:0
      join line1@branch2:0   line1:end
      join line2@branch2:end line2:0
      map map3
        scrap3
        break
        scrap1@branch1
        break
        scrap2@branch2
        #preview below map2@branch2
      endmap
   endsurvey

Notice the naming of the stations in the scraps. For example "scrap1" has the stations of "survey1" and "survey2". Therefore in the definition of the points of type "station" you must give the full name of the station, eg, "1@scrap1". Likewise the full name must be used in the equate command of the file "branch1.th". In "scrap3" and in the file "cave.th", which stay at a higher level, the stations are referred to with the subservey suffix too, eg, "2@survey3.branch2".

Finally the configuration file has the commands

   source cave.th
   select map3@cave
   export map ...

The first says to use the file "cave.th". The second says to select the map "map3" for drawing. The third says which output to generate and how. The result is shown in the figure below.

The join command (1)
The join command (2)
The join command (3)
Surveys