I'm interested in the ways people organise their Therion datasets. Feel free to add your own templates or add your own page to explain your own approach to organising your cave survey data, or how mine can be improved.

Therion works best if you take advantage of a number of other applications and utilities such as text editors, terrain modelling, electronic surveying and version control
See also Windows OS and Therion


These pages do not describe 'the official word' on Therion. For that you should refer to The Therion Book, or pages on this wiki by those more knowledgeable. This is just my attempt to tame the beast, or a least understand it a little so that I can keep it under control.


Templates Standardised files for use with Therion, including a drawing checklist to refer to each time drawings are edited…

Data Structures

Bruces data structure An incomplete and not yet well thought out description of concepts and ways to organise Therion data.
Therion by Examples Playground Simple examples that demonstrate particular features one at a time using 'bare bones' data structures.

Paperless Survey

Paperless Survey Electronic cave surveying using laser, wireless, pda and Therion

When I first found the Therion website (2007-2008) I thought that my 15+ year search for cave drawing software was over. (Having suffered that many years of what I imagine were similar frustrations and wasted effort that prompted a Cave Surveying Group article on Sustainable Mapping of Caves) Straight away I had visions of, from a single set of input, many types of cartographed maps of the same piece of cave, various symbol sets, orientations, levels of text detail and symbol visibility depending on scale, languages, comprehensive data reporting, etc etc.

Advantages I saw, in some sort of order starting with the most significant, were;

  • The obvious one, drawings are morphed to fit the survey centerline, regardless of any changes or loop closures that may subsequently occur
  • Uses textual input data files (reading will be with us for a while yet, have you ever tried to decipher your original input from a binary file 10 years after the software became defunct?)
  • With the exception of the drawing files, Therion never writes to the input files, so a bug in the software can never trash your data. Drawing files are textual, so if there is a problem, you can generally get in there with a text editor and figure out what is wrong, and then fix it.
  • Text files, and hence Therion, are version control software friendly. Go back to inspect any change ever made to the input data, or recreate the dataset as it was five years ago. Simultaneously edit and process your dataset while others in the survey team are doing the same on different sides of the mountain. Merge and share all your edits later on with removable media or via a central web repository.
  • Symbolic representation of entities. The output language and drawings can be chosen from a number of predetermined sets, or they can be customized quite readily.
  • Batch processing (make one or more changes, propagate them easily to selected outputs).
  • Features are added or modified on request of, or in consultation with users.
  • Open source (source code is available to inspect and modify, we are not constrained to a single author) and the software originates in Europe (less likely to have those unit conversion bugs if you use si units!)

All that a wannabe cave geek could wish for!

In hindsight my expectations were too high. Some of my wishes were met easily and others are above what Therion can (readily) deliver (5.3.9 Nov 2011). I now realize that Therion is still in the early stages of it’s development cycle, and many of the features are only developed to a rudimentary level. So, new users need to be prepared for this, and either have the faith and patience to wait for development to evolve, or move on to other cave documentation tools, that may sacrifice some of the above advantages.

Back when I first started exploring Therion, I struggled with understanding how it all worked. I still have ‘game changing’ insights after 5 years of tinkering. The Therion (reference – not instruction) Book and wiki provide basic and advanced information, but there is little direct guidance on how to organize large projects. Therion provides a means of producing cave maps, but allows the user complete freedom to create long tangled files with spaghetti like dependencies. At present, to manage a modest cave dataset, you need a good working knowledge of computing best practices (not me), or be satisfied with all your maps at similar scales, preview arrangements and orientations. While these pages are quite likely to be just as confusing as the rest of the documentation, they (will hopefully eventually) contain stuff that I think would have got me going much quicker.

So if like me you are tempted to incorporate all of the features at once, here is some advice regarding those things that don’t yet work as well as they might.

Plan Rotation

Plan view maps and atlases can be produced rotated to any angle, but if you want to produce maps of a particular cave at a variety of angles you are probably making things difficult for yourself (5.3.9 Nov 2011).

The easy way is to be satisfied with all maps having the north direction towards the top of the page
ie rotate 000 deg
and, when scanning sketches as background to scraps (or collecting data with PocketTopo – see the cautions at the bottom of data_transfer_from_pockettopo_to_therion) ensure that north is approximately towards the top of the page.

The reasoning for sketch scans is because point insertion alignments (left, top-left, right etc) are based on the orientation of the scrap (sketch) and not on the orientation of the output produced. (Thus rotate 160 deg, -align top-left for a north aligned sketch will likely produce an output aligned bottom-right, very confusing).

The reasoning for map and atlas outputs is because, unless you use the default alignment (centre) the position of the symbol will vary with respect to the cave depending on the rotation. In both cases this mainly causes problems with text labels.

Short of creating independent scraps for labels at different rotations (which I think is unreasonable duplication) I cannot think of a way to resolve this. My approach has been to choose a rotation for all map and atlas outputs at the start of a project, ensure all sketches are scanned at this rotation (not essential, but helpful) and accept that all future maps and atlases will be produced at that rotation unless you want to check and tweak the position of every label each time you change the rotation.

Atlas Elevations

Therion support for elevations in atlas is not finished yet (5.3.9 Nov 2011) see forum post If you want to produce an atlas in elevation, you will find that only the x part and z part of the origin is used for positioning pages, regardless of the projection angle.

The easy way is to only produce elevation atlases looking north.
You can fudge an elevation in any direction, but you will have to experiment with the x part of the origin to get a good result. It’s a long time since I tried, but from memory non-orthogonal elevation projection atlases are next to impossible to control with any degree of refinement.

Text Visibility Dependant on Scale or Importance

The easy way is to accept that you will only produce a good looking map with labels within a narrow range of scales (5.3.9 Nov 2011).

While the size of the text naturally scales with the map, the positioning that works at one scale will be too far from, or overlap the cave at other scales. A reasonable compromise would be to progressively hide small text at smaller scales.

Unless you devise custom parameters and incorporate these in your text labels, see forum posts from Stacho Mudrak, from Ben Cooper there is no tidy way to tell Therion to print some labels and not others. On the face of it there is a built-in parameter, -size xs s m l xl, that would seem to lend itself to scale dependant visibility of text, but the features required have not yet been implemented. I have provided a work-around hack on the templates page

Survey and map ids are replaced by survey and map titles

Survey and map ids are replaced (5.3.9 Nov 2011)by survey and map titles in;

  • Xtherion Compiler window ‘survey structure’ and ‘map structure’ panes
  • Exported list output

If you use a –title for surveys or maps, then the id of the survey is no longer reported by the Xtherion user interface or to exported outputs. This can become totally chaotic if;
a) you don’t realize this, and
b) the title does not match very closely the id.

Two work arounds are;
a) not to use titles except perhaps for top level surveys and maps, or
b) ensure that the first several characters of the title match exactly the id (except for top level surveys that need to ‘read nicely’ on the outputs produced).

Data Organization to Facilitate Obtaining Any Particular Output with Ease

This one still eludes me, although to be honest, once I came up with a system I have not experimented too widely. Too time consuming to make changes to large projects, especially when new cave is constantly being added to the dataset! Somewhere there is a balance between having many modular codependent components that are linked together, ensuring consistent outputs and the alternative of having a few independent components which require duplication of edits to migrate changes through to all appropriate outputs.

I started out trying to use a single thconfig file that was capable of producing any output possible for a particular cave, with only minor edits such as commenting or uncommenting particular lines. It works pretty well, and can be reasonably compact provided most of the layouts and indexes are in referenced files, but inevitably they require edits in a number of places (usually only about 3 lines or blocks of lines) that need to be consistent else you don’t get what you want.

ie, decide which surveys, maps and projections you want to export,

  • select the surveys and or maps
  • refer to (input) the relevant layout files for the maps and projections
  • refer to the relevant export statements.

It might be better to have multiple thconfig files, referencing the same sets of layout and index files as above, but avoiding the need to comment and uncomment so many lines. Anyway, if you can see what could be done better, or even just differently, add a page here, or make a suggestion on the forum.