Article Index

Creating a Therion Project

In this lesson we are going to create a new Therion project, import our survey data and create a model of the cave centre-line.

Run the XTherion application. This is the Therion editor. There are three main views in the editor. The text editor, the map editor and the compiler. You can switch between these by selecting the appropriate items from the Window menu, or using the buttons on the toolbar near the top of the application, or by pressing one of the function keys F1, F2 or F3.

Starting with the Text Editor (press F1 to switch to this view), we are going to create the main project file for our survey. Select ‘File/New’ from the file menu to create a new file, then ‘File/Save As’ to save the empty file. Name this file ‘’ and save it in the main folder we created for our project (the folder we named ‘Bull Pot’).

We now need to define our cave survey in the .th file. Enter the following text in the editor window:

  survey bpw


What this does is define a cave survey named ‘bpw’ into which we need to put our survey data. We can import this directly from the therion export file that we exported from PocketTopo. Click in between the ‘survey’ and ‘endsurvey’ lines to place the cursor there, and then select ‘File/Import’ from the menu. Select the therion export file we created in the previous lesson (bpwth.txt). When this file is imported, you should see a block of centre-line data has been put between the ‘survey’ and ‘endsurvey’ lines. This data block starts with ‘centreline’ and ends with ‘endcentreline’. Save the file (File/Save).

We now have everything in our file that we need to build our first model of the cave. To do this we need to create a file in the compiler window to describe what sort of output we want to create.

Compiling the Therion Project

Switch to the compiler window (press F3 or use the toolbar button or menus to switch views). We need to create a configuration file to tell Therion what we want it to do with our cave survey data. Create a new file using the ‘File/New’ menu. The default filename will be shown as ‘thconfig’. Change this to ‘thconfig.thc’ and save it in the project folder (which we called ‘Bull Pot’).

You should now be able to click in the top pane on the compiler window and type into the window. Enter the following text:


export model -fmt survex -o bpwth.3d

This pair of instructions are first telling Therion the name of our project file to process (‘’) and then telling it to generate a model of the cave. We are asking for the format of the model to be a Survex 3D file, and giving the filename for the output file as ‘bpwth.3d’. This filename can be anything you like, but here we are using a convention of naming it the same as our project ‘bpw’ plus a ‘th’ to indicate that this file was generated from Therion and not directly from Survex.

We have now provided all the information that Therion needs to generate some output. Click the compile button (looks like a black cog wheel in the toolbar) or press F9. If everything is in good order then you should see a green OK bar in the pane on the right, and a load of output log text in the lower pane of the compiler window. You should also find a new file named ‘bpwth.3d’ has appeared in your project directory. Double click to open this file in Aven (the Survex cave viewer) and you can rotate and zoom your model to see your cave. You can also launch the Therion viewer ‘Loch’ from the Therion group on your start menu and open the .3d file in that.

Adding additional information to the survey data

The essential numerical data for the cave centre-line was automatically imported from PocketTopo, but it is generally good practice to include some additional data to record who the surveyors were. It is also helpful to label cave entrances as these can then be highlighted on the models. If you switch back to the text editor view (F1) and look at the centre-line data block you will see that the date of the survey has already been imported. Below the date is a data line detailing the order that the numerical data is provided in. We are going to insert some more information between these two lines. So click to place the cursor at the end of the date line and press the ‘Enter’ key a couple of times to create a couple of blank lines after the date. The enter the following lines:

  team "Joe Bloggs" instruments
team "Jane Bloggs" notes
team "Tim Bloggs" dog

These lines provide the information on the surveyors. The person reading the instruments, the person recording/drawing the survey on the PDA (notes) and the person who did all the running around setting stations etc. (the dog). For traditional tape measure surveys you can also specify a team member followed by the word ‘tape’. There are other roles and also many other pieces of information you can provide (what types of instruments were used, author, copyright information, etc.). Take a look in the Therion Book for details of all the supported roles and other information that can be added in a centreline data block (look for ‘centreline’ in the table of contents). Note that the team members names are only allowed to contain one space character, so use the forward slash '/' character for additional spaces or your project will generate an error when you try to compile it. (e.g. "Joe Horatio/Bloggs" will appear on the final survey as "Joe Horatio Bloggs".)

We also want to indicate which survey stations are at entrances to the cave. In our case none of our stations were at a real entrance, but for demonstration purposes we will pretend that station 1.8 was at the cave entrance. We can indicate this with the following line:

  station 1.8 "main ent." entrance

Note that we have to provide a comment or this line does not work. We have put the comment ‘main ent.’ in quotes. If you do not want a comment then you still need the double quotes, but can enter them without any text between them.

Now recompile the project (F9 or click the black cog wheel toolbar button). Open the model in the viewer again and now you can turn on the option to view entrances and will see the entrance highlighted in the viewer.

It is also very useful to give the location of the cave, because it can then be positioned with respect to other locations in the world. This is required if you want to position the cave on Google Earth, or under a surface landscape overlay, or in the same model as other nearby caves. We can specify the position of a station using the fix command. We will deal with coordinate systems later when we build a KML model to view in Google Earth. But for now we will just give the coordinates for the position of one of our stations. The entrance station makes most sense because we can position it using a GPS. Until we specify otherwise, the units of any coordinates we use are assumed to be metres. So we will enter the position using the OS Grid reference within the OS grid 10km square where our cave is located, based on the GPS position and altitude of the entrance station. The order has to be Easting, Northing, Elevation. Our cave entrance is at approximately the OS grid location SD 662 812 and at around 290m above sea level. So to specify this grid location in metres we enter the following line:

  fix 1.8 66200 81200 290

Now if we recompile our project, our Survex model will give us the correct grid coordinates and elevation for any station when we view it in the Aven viewer. More importantly if we were to include a second cave in the same model then both caves would be positioned in the correct location relative to one another so we could see how far apart the nearest parts of each cave are to one another.

Therion can output a variety of different models. We are going to generate one more to complete this lesson. The default model for Therion is the lox model. This is the model which the Loch viewer is mainly designed for. So we need to switch to the compiler window again and enter on the following line to instruct the compiler to build a lox model:

  export model -o bpw.lox

Now if we compile the project again we should find a new output file ‘bpw.lox’. Double click on this file in Windows Explorer to open it in the Loch viewer. We can view a solid 3D model now by turning on some of the options in the Loch viewer. Select ‘Tools/Options’ from the menus in the Loch viewer and select the option to ‘Extrapolate only files without walls information’. Click OK and then reload the lox file in the viewer (just click the toolbar button near the left end of the toolbar showing twin green arrows). Now we should see solid tubes representing our cave passages. These are derived from the survey leg lengths at this stage. But later as we develop our drawing of the cave the model will improve as we provide more information.

The final project files for this lesson have been copied into the Lesson 2 folder of the supplied project data zip file. So if you are unsure about anything or find your project is not working then use these files as a reference to how the complete project should look at this stage. In the next lesson we will start drawing the plan sketch for our cave survey.