p   a   g   e     u   n   d   e   r      c   o   n   s   t   r   u   c   t   i  o   n

Here are examples of how to organise cave data associated with the survey and drawings. Here it is assumed that Therion is used to collate everything and survey data is manually collected (hand sketches) or electronically collected (PocketTopo).

I usually name the root folder after the cave, eg thMyBigCaveSystem
If I am using version control software, then there is an extra level of folders. The root folder name in the examples below matches the Branch name (version control jargon), and all of the branches are within thMyBigCaveSystem.

FOLDER               CONTENTS
.<root>              = indexes, layouts, thconfig files for cave and surface combined
|_CaveName           = cave survey data files, drawings, indexes, layouts, thconfig files
|    |____ Sketches  = intermediate sketches, jpg, png and xvi files
|_Output             = all output files 
|_StdFiles           = preferred standard layouts
|_Surface            = terrain model and jpg surface overlays

FOLDER               CONTENTS
.<root>                      = system indexes, layouts, thconfig files
|_Area01                     = area   indexes, layouts, thconfig files,
|   |                          
|   |_____Cave01A            = cave survey data files, drawings, indexes, layouts, thconfig files
|   |        |____ Sketches  = intermediate sketches, jpg, png and xvi files
|   |        |____ ptopo     = PocketTopo top, txt and xvi files (seperate folders required for disconnected surveys)
|   |
|   |_____Cave01B            = ditto
|   |        |____ Sketches  
|   |        |____ ptopo     
|   |_____Output             = outputs for area01
|   |_____Surface            = area01 surface surveys, gps points, drawings, indexes, layouts, thconfig files
|
|_Area02    
|   |_____Cave02C           = ditto
|   |        |____ Sketches 
|   |        |____ ptopo   	
|   |_____Output     
|   |_____Surface           	
|
|_Output             = region/system output files 
|_StdFiles           = preferred standard layouts to be consistent across region/system
|_Surface            = terrain model and jpg surface overlays for whole region 

Once the cave you are documenting gets to be more than just a little one, you will have to manage lots of objects (folders, files, surveys, scraps, maps ad infinitum). Therion allows complete flexibility, but even (especially?) for cavers some order is needed. Generally I try to stick to these guidelines;

1. Only one or two things (or types of things grouped together) in each object (I break this one sometimes)
2. The name of the object should describe what it contains or does
3. The naming system should be such that (for folders and files anyway), when sorted , they group together or form some sort of useful order.
4. Avoid using spaces and other delimiters unless really necessary. CamelCaseIsEasyToReadAndFastToTypeAndIsRecognisableAsASingleEntityName.
5. For dates in names use <yyyymmdd> ie 20081205 or 2008.12.05(sorts in the correct order).
6. Examples of names…

• A-EntranceRF.th contains ‘survey a’ which is in the entrance rockfall area and also contains map definitions tying together scraps that belong to survey 'a'.
• A-EntranceRFPlan.th2 contains scrap drawings of survey a. It might contain the scraps A-EntranceRFPlan-s1, A-EntranceRFPlan-s2, A-EntranceRFPlan-x2 (for a cross section).
• INDEXMiddleEarth.th contains survey MiddleEarth which collects together and collates individual surveys and contains aggregations of ‘maps’ that comprise Middle Earth cave. When the file becomes unmanageably large the later can be extended to INDEXMiddleEarthPlan.th, INDEXMiddleElev020.th etc
• LayoutStandards.thc contains a layout (formatting) common to all 2d outputs for this cave dataset.
• LayoutMapThisCavePlan.thc contains a layout (formatting) that defines how a plan view pdf map of ‘this cave’ will look.
• LayoutAtlasThisCaveElev290.thc contains a layout (formatting) that defines how a pdf atlas elevation of ‘this cave’, looking at a bearing of 290 degrees, will look.
• LayoutMiddleEarthAnnotation.thc contains a layout (formatting) that defines the map-comment (annotation) for Middle Earth cave.
• LayoutAtlasPaperSizes.thc contains formatting for standard paper size definitions for Atlas production, for example
  • LayoutAtlasLandscapeA2
  • LayoutAtlasLandscapeA3
  • LayoutAtlasPortraitA3
  • LayoutAtlasLandscapeA4
  • LayoutAtlasPortraitA4

• LayoutScales.thc contains formatting common to outputs at particular scales.
• thconfig-MiddleEarth.thc contains instructions defining what cave data and projections to process, which files to use to determine the appearance, and the output type and location.
• middleearthcave is a folder that contains all the files that relate to Middle Earth cave that Therion might need.
• th_GLMESMCaveSystemData contains folders for each of the caves in the Greelink-Middle Earth-Swiss Maid cave system, as well as INDEX files, layout files and thconfig- files for producing output for the whole system.

I tend to keep my layouts in seperate files, grouped by topic, so that I can call upon them in a generic and modular fashion. In general my layout files contain ‘layouts’ with the same or similar names to the name of the file. For example see the LayoutAtlasPaperSizes.thc example in the 'Templates' section. I use a standardised form of export command to produce 2d outputs, for example;

export map -projection plan \
-layout LayoutMapThisCave \ # called first, processed first
-layout LayoutMapThisCavePlan \ # called last, processed last
-output ./Output/MapBulmerSystem_Plan.pdf

It references two layout files, one with formatting common to all ‘2d map’ outputs for this cave (containing file will include copy statements for various standard layouts), and one with formatting for this particular projection (plan view in this case). I have a similar statement to produce Atlas outputs.

So my convention for naming these two layout files (and the layouts within them) is;

I tend to use 'ThisCave' as the context is obvious by virtue of the folder that contains the file, and it minimizes the edits that need to be made when reusing the file elsewhere.

Elevations should always be identified with the direction of the projection, or an EXT for extended.

The following set of concepts and conventions takes those recommended by the Therion authors, and adds to them just a little to, hopefully, make it easier to learn and to build small datasets that can easily be grown into large datasets.

https://therion.speleo.sk/wiki/lib/images/toolbar/bold.png

*.th            survey                  (collections of caves)
                  |–survey              (caves)
                     |–survey	        (parts of cave)	
                          |–centreline	(parts of survey)

Centrelines are the fundamental building blocks of surveys. They contain data collected during or about a survey session in the cave, or about this particular part of the cave. Can contain dates, people’s names, entrances, co-ordinates and co-ordinate system, if known, as well as the obvious stations, tape, compass, clino, LRUD measurements.
One reason to have multiple centrelines in a survey might be because the original exploration dates and teams might differ along parts of the passage surveyed.
Another reason might be to allow more accurate resolution of passage statistics to be output to maps that do not cover all of the passage surveyed (Statistics in maps are not resolved survey leg by survey leg, but centreline by centreline, so if you later decide to produce a map that covers only part of the cave system and one of the surveys is continuous across the boundary, you might like to split that survey into two centrelines at this point).

Surveys are collections of centrelines and or surveys. Can be treated completely independently of map objects.

*.th             map	                (collections of caves)
                  |–map	                (caves)
                     |–map	        (parts of cave)	
-------------------------------------------------------
*.th2                   |–scrap	        (parts of cave)	

Scraps are the fundamental building blocks for 2D drawing outputs. Plan projection scraps also define the shape of the Loch 3D model outputs.

Map objects (not to be confused with map outputs)are generally the building blocks for 2D outputs. They can contain scraps, surveys and other map objects (but if they contain scraps, they must ONLY contain scraps).* Can be treated completely independently of survey objects. There is no requirement for the boundaries between map objects and surveys to be in the same place. Often for convenience they are nearby, but if the data is organised suitably, then map objects can be completely independently defined.

(thconfig-)*.thc  (thconfig)
                    |-source     (of surveys and drawings to compile)
                    |-maps       (enables or disables output map structure for the selected surveys)
                    |-maps-offset (enables or disables output of defined passage offsets from their true positions) 
                    |-select     (particular surveys and or maps to export)
                    |-input      (other files that contain text, lookups and layouts, so as not to clutter your thconfig)
                    |---text       (if you want to redefine default legend and map-header text strings)
                    |---lookup     (if you want to redefine default colour palettes and text strings that can be used with map-fg layout options)
                    |–--layout     (to define options for appearance and 'layout' of 2D outputs)
                    |-cs         (to specify the output coordinate system)
                    |-log extend (to add a transcript of the extend sequence to therion.log)
                    |-export     (selected maps and specify layout, projection, filename, format etc)

Th(erion) Config(uration) files select surveys and map objects to output. Type of output is defined by the export command, and can be a 2D drawing (which contains information defined in map objects), or a 3D model (which contains information defined mainly in surveys) or one of the text-like outputs (which contain information only defined in surveys). Therefore, at present (June 2011 version 5.3.8), if you select both maps and surveys for export (remembering that NOT selecting one of those will select them all) then it is most unlikely that the statistics in the map outputs will match the statistics in the survey/list/database outputs. This is because for any significant system it is unlikely that every piece of survey has a map defined, or any map object has drawing that encompasses exactly all centrelines on which it is based. More on this on the Export selection and Formats page.


Source specifies the survey data and scraps or maps that are to be compiled. You must specify at least one source.

maps if maps OFF is chosen, defined map structures are NOT parsed to the outputs (therefore offsets are disabled and previews of passages are not shown). Only scraps from the selected (or source) surveys or maps are output. Survey centrelines and stations are not output. Optional.

maps-offset if OFF is chosen, defined offsets are ignored, and the scraps are drawn in their true positions. Previews are exported as usual (although previews associated with any offsets are of course not required). Maps-offset has no meaning or effect if maps off is also chosen. Optional.

Select selects particular surveys and or maps to export. If you do not select a survey, all surveys are selected by default. If you do not select a map, all scraps are selected by default and map features such as offsets and previews are not actioned. Optional.

Input enters the text of other files, as though they were typed herein. You can use input to refer to standard text, lookup or layout files, and avoid having long cumbersome thconfig files. Optional.

Text commands redefine Therions default output text strings, such as those in map-headers and legends. Mostly you will not need to use text. Optional.

Lookups define colour palettes for map and atlas outputs, and can apply to various parameters such as altitude, exploration or survey dates, or 'by map or 'by scrap'. Optional.

Layouts define the look of 2D outputs. ie scale, symbols, headings, graphics, co-ordinate system (which can differ to those used for survey data entry)** You almost always need to use a layout to create an output that looks the way you want it to.

cs specifies the coordinate system to use for outputs. If you do not specify this, Therion will use one of the coordinate systems used in the source survey files. Optional.

log extend to add a transcript of the extend option and station sequence to therion.log. See enumerating_extend_station_sequence and breakingextend. Optional.

export exports the maps selected above and specifies the format (type) of output to produce, the projection, if applicable, and many other options. Required.

<TODO: Include links to more specific use/description of layouts and other commands>

*Each map can contain only a whole number of sub- maps/scraps/surveys. Therefore when deciding where to start and finish scraps (and to some extent surveys – but you can modify them back in the office, so don’t worry in the cave) bear in mind that they control where it is possible start and finish component maps, previews and offset maps. Also Therion joins the maps much better (read - easier on the user) in plain passages with no infills (water/clay etc) and no side passages.

**2D outputs can either be map output (no relation to the map object concept described above) or atlas output.

A map output (not to be confused with a map object) is contained on a single ‘page’ and the size of the page is automatically made big enough to fit the cave by the software. A number of formats are supported but pdf seems to be the most comprehensive. Pdf maps can include graphics such as photos, logos, other pdf files or previously created cave maps. If you would like to force a map output to a particular size or proportion see how_to_make_map_outputs_match_iso_paper_size_proportions

An atlas output cuts the cave up to fit a user defined ‘paper size’ and adds a navigation pane. Hyperlinks in the navigation pane and at the page edges facilitate rapid navigation. If multiple maps are selected in the thconfig file, then chapters are automatically created separating the maps. These may be different caves or different levels in the cave – with hyperlinks to navigate between different levels. Only pdf format is supported. Inserted graphic images are NOT supported.

In theory you could produce every type of output each time you run Therion, but in practice the 2d and 3d outputs can take a long time to process, so it can be a good idea to comment out the rows for these types of outputs when you don’t need them.

With so many layout files it is inevitable that some parameters are changed and changed back and changed back again by the various layouts called.

The key to understanding which setting will prevail is knowing that;

• the order in which the layouts are called (by a copy statement for example) determines the order that the parameters are changed, the last one called determines the final value (but see https://github.com/therion/therion/issues/425),
• layouts called in an export statement are processed in order, the last one called determines the final value, and
• the order or presence of an input statement has no effect on the order the parameters are changed. The input statement just tells Therion in which file(s) to look for layouts.

Usually there is no problem with all this changing and changing back, but some parameters don't take kindly to it at all. On rare occasions you will find anomalies or even strange errors because of this. To debug for this type of problem, first comment out all the layouts, and then incrementally add layouts or individual statements back into the mix.

So, with my data structure then, there are two layouts called by the export statements in the thconfig file, and each of these in turn calls a variety of layouts, by way of copy statements. In general my order of calls is;

…in the Layout[Map or Atlas]Cave layout;

copy LayoutStandard       # sets most parameters, symbol-set, then symbol-assignment, then other settings you want to standardise across the project
copy LayoutScale    
# now call symbol redefinitions
copy water-blue           # comment out for default hatching
copy sump-blue            # comment out for default cross hatching
copy scalebar-with-text   # comment out for default with no scale id  
# maybe hide some symbols
symbol-hide point remark
copy LayoutCave_Annotation # a specific layout describing this cave

…in the Layout[Map or Atlas]Cave[Plan or Elev] layout;

copy LayoutShowContinuationQmarkOnly  
copy LayoutStatisticsNormal
copy LayoutAtlasPortraitA4    #set paper size

The most common confusions and conflicts seem to arise between the user and;

Layout[Map or Atlas]Cave.thc,
LayoutScale.thc, and
Layout[Map or Atlas]Cave[Plan or Elev].thc

Actually not much of an example, but here it is anyway…
th_waitomocavessurface.zip