**Please, feel free to add your own examples of your interesting solutions made with therion.**
======Sample Datasets======
=====All Areas, All Symbol Sets=====
This sample dataset produces eight A3 approx maps at 1:1000 in a single run. If you uncomment the LayoutStandard and other layouts you can see the effect of overlying some customisations to the built in symbol sets, or relatively easily add your own customisations.
If you typically use other scales, then, to maintain the A3 size of the page, you will need to appropriately factor the station coordinates set by the fix statements in the file Areas.th
The attached includes an example output with customised symbols, however the files as currently set up in this archive will produce reasonably standard outputs for the 8 built-in symbol sets.
{{examples:SampleAreasPlanDataset.zip}}
A comment on differences between viewers [[contrib:externalviewers#for_pdf_files]]
======Maps and Layouts======
Layouts affect only two dimensional, or map outputs. Three dimensional outputs, or models, are unaffected by layouts. Maybe, in the sections below, the distinction has been blurred, and should perhaps be rearranged to distinguish between surveys, maps, map outputs and model outputs. I'm not sure? Perhaps that is a project for another day...
====source .th file - "demo-cave.th"====
{{:therion:demo-jaskyna.zip|Source scans and .th2 file}}
survey demo-jaskyna
input demo-jaskyna.th2
map vrch
demo-jaskyna_s1
break
demo-jaskyna_s2
endmap
centerline
units compass grads
units clino grads
units tape metres
team "RSDr. Jano/Mrkva CSc." #there are more than two strings in a name
team "Jozo Zemiak"
explo-team "Budaj"
explo-date 2001.12.04
date 2004.11.20
data normal from to length compass clino
0 1 7.69 188 99
1 2 4.54 75 2
2 3 2.72 153 6
3 4 1.89 112 32
4 5 4.5 105 5
5 6 3.6 109 -20
6 7 3.36 104 7
7 8 4.89 145 22
8 9 3.2 90 -2
9 10 7.67 108 -11
10 11 7.05 90 -1
11 12 3.68 81 10
12 13 2.39 94 31
12 14 2.83 23 -1
11 15 3.85 338 -51
15 16 4.44 98 -16
endcenterline
endsurvey
====Only centerline====
**//Note - the survey "demo-jaskyna" is a part of survey "centerline" now and there is a new map definition//**
survey centerline -title "Demo cave - only centerline"
#input demo-jaskyna.th2 #no any .th2 file necessary
map vrch -projection plan #the "-projection" option must be here
demo-jaskyna #this is the survey, not a scrap
#demo-jaskyna_s1
#break
#demo-jaskyna_s2
endmap
survey demo-jaskyna
#map vrch
#demo-jaskyna_s1
#break
#demo-jaskyna_s2
#endmap
centerline
....
endcenterline
endsurvey demo-jaskyna
endsurvey centerline
**//The default centerline you may change to colored solid line with help of piece of Metapost code in layout section of thconfig file://**
code metapost
def l_survey_cave (expr P) =
T:=identity;
pair zz[];
pickup PenC;
for t = 0 upto length P - 1:
zz1 := point t of P;
zz2 := point t+1 of P;
draw zz1 -- zz2 withcolor (0.1,0.3,0.1);
endfor;
enddef;
[[:therion:example_08a|{{therion:cave_08_mini.png}}]] //Click on image to see the full resolution file//
----
====3D export - vrml, map export - different language, legend off====
source demo-jaskyna
#export model -fmt 3dmf
#export model -fmt survex
#export model -fmt compass
export model -fmt vrml
layout demo-jaskyna-header
map-header 0 100 sw
#language cz
language sk
#language en
#language fr
legend off
#colour map-fg [80 80 80]
#colour map-bg [70 90 70]
#symbol-hide group all
#symbol-show line wall
#symbol-show line survey
transparency on
opacity 60
statistics topo-length off #on
statistics explo-length off #on
endlayout
select vrch@demo-jaskyna
export map -layout demo-jaskyna-header -output cave_00.pdf
[[:therion:example_00|{{therion:cave_00_mini.png}}]] //Click on picture to see original size//
====No 3D export, map export - colored background and foreground, colored surveying lines, no legend====
source demo-jaskyna
layout demo-jaskyna-header
map-header 0 100 sw
legend off
colour map-fg [80 80 80]
colour map-bg [70 90 70]
code metapost
def l_survey_cave (expr P) =
T:=identity;
pair zz[];
pickup PenC;
for t = 0 upto length P - 1:
zz1 := point t of P;
zz2 := point t+1 of P;
draw zz1 -- zz2 withcolor (0.5,0.3,0.3);
endfor;
enddef;
endlayout
export map -layout demo-jaskyna-header -output cave_01.pdf
[[:therion:example_01|{{therion:cave_01_mini.png}}]] //Click on picture to see original size//
----
====Map export - legend on, colored foreground, background and surveying line====
source demo-jaskyna
layout demo-jaskyna-header
map-header 0 100 sw
legend on #off
colour map-fg [80 80 80]
colour map-bg [70 90 70]
code metapost
def l_survey_cave (expr P) =
T:=identity;
pair zz[];
pickup PenC;
for t = 0 upto length P - 1:
zz1 := point t of P;
zz2 := point t+1 of P;
draw zz1 -- zz2 withcolor (0.5,0.3,0.3);
endfor;
enddef;
endlayout
export map -layout demo-jaskyna-header -output cave_02.pdf
[[:therion:example_02|{{therion:cave_02_mini.png}}]] //Click on picture to see original size//
----
====Map export - another language, header in bottom left corner, legend off, colored foreground and surveying line====
source demo-jaskyna
layout demo-jaskyna-header
map-header 0 0 nw
#language cz
#language sk
#language en
language fr
legend off #on
colour map-fg [80 80 80]
#colour map-bg [70 90 70]
symbol-hide group all
symbol-show line wall
symbol-show line survey
code metapost
def l_survey_cave (expr P) =
T:=identity;
pair zz[];
pickup PenC;
for t = 0 upto length P - 1:
zz1 := point t of P;
zz2 := point t+1 of P;
draw zz1 -- zz2 withcolor (0,0,1);
endfor;
enddef;
endlayout
export map -layout demo-jaskyna-header -output cave_03.pdf
[[:therion:example_03|{{therion:cave_03_mini.png}}]] //Click on picture to see original size//
----
====Map export - map header off, legend off, colored foreground, only walls====
source demo-jaskyna
#export model -fmt 3dmf
#export model -fmt survex
#export model -fmt compass
#export model -fmt vrml
layout demo-jaskyna-header
#map-header 0 0 nw
map-header 0 0 off
#language cz
#language sk
#language en
#language fr
legend off
#legend on
colour map-fg [10 10 10]
#colour map-bg [70 90 70]
symbol-hide group all
symbol-show line wall
#symbol-show line survey
opacity 70
code metapost
def l_survey_cave (expr P) =
T:=identity;
pair zz[];
pickup PenC;
for t = 0 upto length P - 1:
zz1 := point t of P;
zz2 := point t+1 of P;
draw zz1 -- zz2 withcolor (0,0,1);
endfor;
enddef;
endlayout
select vrch@demo-jaskyna
export map -layout demo-jaskyna-header -output cave_04.pdf
[[:therion:example_04|{{therion:cave_04_mini.png}}]] //Click on picture to see original size//
----
====Map export - colored background, only walls====
source demo-jaskyna
layout demo-jaskyna-header
#map-header 0 0 nw
map-header 0 0 off
legend off
#legend on
#colour map-fg [10 10 10]
colour map-bg [70 70 70]
symbol-hide group all
symbol-show line wall
#symbol-show line survey
endlayout
select vrch@demo-jaskyna
export map -layout demo-jaskyna-header -output cave_05.pdf
[[:therion:example_05|{{therion:cave_05_mini.png}}]] //Click on picture to see original size//
----
====Map export - default layout, rotated map====
//**Note: the profile is not rotated**//
source demo-jaskyna
layout demo-jaskyna-header
rotate 30
export map -layout demo-jaskyna-header -output cave_06.pdf
[[:therion:example_06|{{therion:cave_06_mini.png}}]] //Click on picture to see original size//
----
====Map export - grid, colored background and foreground====
source demo-jaskyna
layout demo-jaskyna-header
map-header 0 100 sw
grid bottom
grid-size 5 5 5 m
colour map-fg [80 80 80]
colour map-bg [70 90 70]
endlayout
select vrch@demo-jaskyna
export map -layout demo-jaskyna-header -output cave_07.pdf
[[:therion:example_07|{{therion:cave_07_mini.png}}]] //Click on picture to see original size//
----
====Cachtice cave - example of quite complicated map====
made by Martin Sluka
[[http://cachtice.speleo.sk/mapa_cj/template.html|{{therion:cj_icon.gif}}]] //Click on picture to see original size//
----
=====Colour Palette Scales - Lookups=====
Therion 5.4.2 (8 Jan 2019) introduced a new concept, lookups, to create and control collections of map-foreground colour palettes for map and atlas outputs. Lookups can define the text and appearance of 'colour legends'.
[[https://www.mail-archive.com/therion@speleo.sk/msg06798.html|Original forum post advising of this change to the development release Nov 2017]]
Whether or not you use lookups, you can specify the parameter that is depicted in colouring of 2D outputs.
You specify this in a layout. eg, use one of...
colour map-fg [100 0 0] # hard writes a single colour to entire output
colour map-fg altitude
colour map-fg explo-date
colour map-fg topo-date
colour map-fg map
colour map-fg scrap
If you have created one or more lookups for a particular parameter, you can specify which one to use, by specifying an index.
ie
colour map-fg altitude:banded
To see the colour legend in your map header, you will need to turn it on;
colour-legend on
You can also specify the colouring in an export statement directly, without defining a layout. eg
export map -layout-color map-fg topo-date
If you do not specify a lookup, for altitude or dates, the range of values in the output is divided into 7 legend entries.
If you do not specify a lookup for map and scrap, all of the maps or scraps are listed.
Depending on how your map definitions are set up, specifying the map-level when you select maps for output may affect the number of maps that appear in the colour legend and are coloured.
select MyCavePlanMap -map-level 1
By default altitudes are sorted highest, red [100 0 0] to the top of the list, and magenta [100 0 100] to the bottom.
By default dates are sorted most recent, red to the bottom of the list, oldest, magenta, to the top of the list, and undated surveys are uncoloured.
**Form of lookup**
Lookups are defined in a thconfig, or at least outside of of any survey or layout definitions.
They take the form...
lookup [altitude | explo-date | topo-date | map | scrap][:index] [-title "custom title text"]
# now list parameters, optional colours, optional text overides to appear in each legend entry,
# as in the examples below. the parameter listings take the general form...
[colour] ["text"]
# do not specify any colours if you want Therion to use it's default colour palette, just use
# empty brackets, [], in place of a colour specification, if you want to specify text for a particular parameter.
endlookup
**lookup altitude examples**
The default automatic altitude colour bands take their highest and lowest values from the highest and lowest survey stations for the parts of the survey that are used in the rendering. It takes all the survey stations within the "cave" (ie. not in a "flags surface" section), from whichever surveys and subsurveys are going to be used in the rendering (if you are using a map, it will be whichever surveys and subsurveys have some of their parts included in that map), and finds the highest and lowest station. This happens even if the highest and lowest stations within those surveys are not even rendered because they are not included in a scrap.
The legend will then be divided up into 7 numbers; the highest station, the lowest station, and 5 equally spaced values in between. These values are then rounded to the nearest integer when rendering (this rounding will also happen when displaying legend lookup values). This makes it quite possible that no scrap will ever be the colour of the highest and lowest stations, since scraps normally have more than one station in them, and the scrap altitude and colour will be taken from the average of those. The colour, as with lookup colours, will be faded the appropriate distance between the nearest colour values on either side.
This also means that for a cave with very little vertical range, the default legend may show "10, 10, 11, 11, 11, 12, 12", when in actual fact, the numbers are all part way between 10 and 12.
Using a lookup table allows you to take much more control, giving neater colour intervals (like one colour every 10 metres), or allowing the highest and lowest scraps to actually be the top and bottom colours.
lookup altitude -title "Altitude legend"
700 [100 0 0] "700 m a.s.l."
680
660
640
620
600 [0 0 100] "below 600 m"
endlookup
It should generate red -> blue scale with desired values. Note that this is a linear fade with red at one end, blue at the other, and purple in the middle; it does **not** rotate the hue via orange, yellow or green in the middle.
You may specify multiple lookup tables for same criterion using an index, ie ":" separator in label
lookup altitude:scale1
600
800
endlookup
and
lookup altitude:scale2
800
750
700
endlookup
and use then
color map-fg altitude:scale1
or
color map-fg altitude:scale2
Also intervals, or bands, should work:
lookup altitude:banded
[1500 1600] [] "cave floor 1" #If the text is omitted, then the default will display the range, ie 1600 m - 1500 m
[1800 1900] [] "cave floor 2"
endlookup
This will produce a single colour for passage between 1500 and 1600 m and between 1800 and 1900 m, and leave all other passage, above, in between, and below, uncoloured.
The default altitude rainbow is not made with a continuous range of colour hues. Instead, it is made with 7 discrete colours, with altitudes between them fading between the discrete colours. This means that you can use a lookup table to exactly replicate this colour behaviour, using the following colour values which match the default ones used by Therion (shown here within the range of altitudes from 4 to 96 metres):
lookup altitude:manualrainbow
96 [100 25 25]
81 [100 87.25 25]
65 [49.75 100 25]
50 [25 100 61.75]
35 [25 74.5 100]
20 [37 25 100]
4 [99.25 25 100]
endlookup
**lookup date examples**
lookup topo-date
2010.12.31 [] "2010 and before"
2011.12.31 [] 2011
2012.12.31 [] 2012
- [] "2013 and later" #my experimentation suggests that '-' colours undated surveys if last in the list, and all surveys if first in list. Bruce
endlookup
**lookup map and scrap examples**
lookup map
map1@some_survey [color]
map2 [color]
map3 [color]
endlookup
Same should work with scraps.
**Specifying individual map colours at compile time**
With maps you may specify colour of a particular map when selecting it in your thconfig, overriding or without the need for any layout or lookup statements
select map1 -colour [100 0 0]
The Therion Book 6.1.7 suggests that map command-like options include colour, however this seems to be incorrect. The -colour option seems to be a select parameter (not a map parameter) and can be described like this...
**‘select’**
Description: selects objects (surveys and maps) for export…
Options:
…
• colo[u]r set the map colour when selecting a map; this option overrides the specified colour palette ONLY when the layout specifies colour map-fg [map], [scrap] or []. It has no effect when the layout specifies colour map-fg [altitude]. It has no effect when the layout specifies colour map-fg [topo-date] or [explo-date], for the scraps whose associated surveys have dates assigned.
In summary:
Select map -colour overrides layout or lookup colour map-fg statements when…
* colour map-fg [r g b]
* colour map-fg scrap
* colour map-fg map
Select map -colour does not override layout or lookup colour map-fg statements when…
* colour map-fg altitude
* colour map-fg topo-date, unless the map has no date
* colour map-fg explo-date, unless the map has no date
======Models======
=====Export to 3D data (clouds) processing softwares=====
Therion is able to export 3D model in format .lox based on LRUD data, shape of walls in plan and passage height informations recently. If the map is drawn in correct way these models are quite good. To view the model one should use internal viewer of Therion named Loch. The Loch has feature to export model in the VTK format. And several softwares for manipulating with 3D data for example CloudCompare or Paraview are able to import this VTK format.\\
Take care that if there are fixed points with coordinates they are exported as very big numbers compared to altitude. In ParaView the data are OK, if you split window, select Spreadsheet View and set the precision of X and Y to 11 numbers. But export to MeshLab will not export them. I'm sure, there is possibility to subtract those big parts of X and Y but I don't know how. (Sluka 2015.10.29)\\
There is easy way to convert binary data to ASCII with help of ParaView. Just open .vtk file exported from Loch (binary) and save it from ParaView, but as .vtp ASCII file. It is XML and you may copy, change and replace points coordinates easy. (Sluka 2015.11.18.)\\
If you change one line in file lxData.cxx around line 615 and recompile loch, you'll receive after export to VTK ASCII file (thanks Stacho). It is easy to edit it. (Sluka 2015.11.09)
w->SetFileTypeToBinary(); to w->SetFileTypeToASCII();
[[http://www.cloudcompare.org | CloudCompare]] is able to export next formats:
BIN .bin CloudCompare own format
ASCII .asc,.txt,.xyz,.neu,.pts ASCII point cloud file (X,Y,Z,etc.)
LAS .las ASPRS lidar point clouds
E57 .e57 ASTM E57 file format
PCD .pcd Point Cloud Library format
PLY .ply Stanford 3D geometry format (cloud or mesh)
OBJ .obj Wavefront mesh
VTK .vtk VTK file format (triangular mesh or cloud only)
STL .stl STereoLithography file format (mesh)
OFF .off Object File Format (mesh)
FBX .fbx Autodesk (Filmbox) File Format
DXF .dxf Autocad DXF format
SHP .shp ESRI Shape file format
RASTER .geotiff, etc. Common raster formats (GDAL)
PV .pv Point cloud + scalar field
PN .pn Point cloud + normals
Sinusx .sx Sinusx curves
**ParaView** is able to work with next formats:
ParaView files
VTK files
Parallel (partitioned) VTK files
VTK MultiBlock (MultiGroup, Hierarchical, Hierarchical Box) files
Legacy VTK files
Parallel (partitioned) legacy VTK files
EnSight files
EnSight Master Server files
Exodus files
BYU files
XDMF files
PLOT3D files
SpyPlot CTH files
HDF5 raw image data files
DEM files
VRML files
PLY Polygonal files
Protein Data Bank files
XMol Molecule files
Stereo Lithography files
Gaussian Cube files
Raw (binary) files
AVS files
Meta Image files
Facet files
PNG files
SAF files
LS-Dyna files
What is more: ParaView is able to export model to WebGL format which is possible to publish on your web pages.
=====Steps to calculate the volume and surface=====
thanks to Filippo Gregori
1) Export the lox file to vtk format
2) With Paraview software I opened the file vtk
3) Export scene as .x3d
4) Open the file x3d in Meshlab software
6) Apply the filter: Filters -> Quality measure and computation -> compute geometric Measures
7) Open log window: View -> Show Layer dialog
8) Read the lines Volume Mesh and Mesh Surface
[[http://www.paraview.org|Paraview]]
[[http://meshlab.sourceforge.net|Meshlab]]
Note: If you use coordinates for a fixed station as the result there are huge numbers for the X and Y coordinates compared to the altitude. ParaView is not able in the way described above to export scene to MeshLab correctly. I don't know a way to subtract those big parts of coordinates in ParaView till now, anyway it should be possible. Please, if somebody may help, do it.
=====Export to WebGL=====
WebGl is widely used for game creation for example. 3D objects could be covered by skins, camera may move inside of model and so on.
1) Export the lox file to vtk format
2) Open the file in ParaView
3) Export Scene as WebGL to an empty folder
4) Open the file xxx.html in a browser or publish code on your web page
Check [[http://www.radavc.speleo.sk | 3D model of Radavc cave, Kosovo]]
=====Loch Models, Paperless survey, Plan scraps and LRUD=====
In this example there is a single centreline (comprising both cave and surface survey) and 4 scraps. Compiled with Therion 5.3.11, July 2013
A short section of cave at the left hand end does not have any scrap drawn.
One interesting point is that regardless of the ‘//walls//’ setting, there is never a tube generated the left hand end once we have scraps drawn anywhere in this centreline. My deduction is that Loch uses only one type of tube generation per centreline, because in almost all my larger projects that transition between traditional survey and paperless survey methods, I have a combination of each type of tube generation within the same Loch model.
This fits with the description in the Therion Book
//“walls turn on/off passage shape generation from LRUD data for
subsequent shots. If set auto, passage is generated only if there is no scrap referencing
given centreline.”//
In these examples I have not used any ‘//point passage-height//’ or ‘//point dimensions//’ in the scraps.
{{examples:modellochpaperless01.png|Paperless survey (no LRUD), walls auto, off or on (or not specified), No plan scraps. Same if LRUD present and walls off.}}\\
**Paperless survey (no LRUD), walls auto, off or on (or not specified), No plan scraps. Same if LRUD present and walls off.**
In this case Loch always guesses tube dimensions.
----
{{examples:modellochpaperless02.png|Paperless survey (no LRUD), walls auto, off or on (or not specified), plan scraps drawn.}}
**Paperless survey (no LRUD), walls auto, off or on (or not specified), plan scraps drawn.**
In this case Loch uses scraps exactly as drawn for tube width and guesses tube height
----
Now, I added a few LRUD to the same centreline, including some with only UD, and using extra large or small numbers, so the effects can be readily observed.
data dimensions station left right up down
1.4 - - 20 20 #right hand end of picture
1.5 - - 20 20
1.6 2 2 20 20
3.13 10 10 20 20
3.14 10 10 20 20 #left hand end of picture
Tube generation, where it occurs extends one station beyond those specified.
{{examples:modellochpaperless03.png|Paperless survey (some LRUD), walls on or auto (or not specified), No plan scraps.}}
**Paperless survey (some LRUD), walls on or auto (or not specified), No plan scraps.**
In this case Loch uses LRUD for tube dimensions and only for stations where partial data is provided, it guesses the missing data ie if a station has no LRUD data, no tube is generated.
----
And now adding some scraps again, and things get interesting.
{{examples:modellochpaperless04.png|Paperless survey (some LRUD), walls off (or not specified), Plan scraps drawn.}}
**Paperless survey (some LRUD), walls off (or not specified), Plan scraps drawn.
**
In this situation Loch uses scraps, not LR, for tube plan dimensions, and UD for height where specified, otherwise height is guessed. Where there are no scraps, LRUD is not used.
That is perhaps contrary to what one might expect from the Therion Book ‘//walls//’ entry. \\
It produces the best model.
----
{{examples:modellochpaperless05.png|Paperless survey (some LRUD), walls on or auto, Plan scraps drawn.}}
**Paperless survey (some LRUD), walls on or auto, Plan scraps drawn.**
In this situation Loch uses both scraps **and** LR for tube plan dimensions, and UD for height where specified, otherwise height is guessed. Where there is no LR, then it is guessed. Where there are no scraps, LRUD **is** used. Not very pretty.
----
If I change the LRUD definition like this…
data dimensions station up down
1.4 20 20 #right hand end of picture
1.5 20 20
1.6 20 20
data dimensions station left right up down
3.13 10 10 20 20
3.14 10 10 20 20 #left hand end of picture
..then the guessed width troubles continue.
{{examples:modellochpaperless06.png|Paperless survey (some LRUD), walls on or auto, Plan scraps drawn. [same as above]}}
**Paperless survey (some LRUD), walls on or auto, Plan scraps drawn. [same as above]**
----
So my final conclusion, for paperless survey, no need to include //walls// statements in each survey, or if you do, //walls off// is better than //on// or //auto//. If you happen to provide some UD data, then your model will be improved (more realistic).
I surmise that with these same settings, scraps with //point passage-height// or //point dimensions// will have a similar effect, but I have not tested this.
Bruce\\
PS Note to self, point dimensions and passage-height do not have similar effects.\\
TO DO: experiment and document effect of these points. Consider effect in above scenarios,
* both point dimensions and passage-height
* points inside passage,
* points outside passage,
* different flavours of point passage-height