The basic building block is the centreline command. If the cave is larger than a few meters it’s a good idea to split the data into more than one file and separate centreline data from map data.
We usually use one *.th file containing centreline per survey trip. It’s handy to start with an empty template file as shown bellow, where the dots will be replaced with appropriate text.
encoding ISO8859-1 survey ... -title "..." centreline team "..." team "..." date ... units clino compass grad data normal from to compass clino length ... ... ... ... ... endcentreline endsurvey
To create a unique namespace the centreline command is enclosed in survey
… endsurvey
commands. It’s useful when the survey has the same name as the file which contains it.22) The points will than be referenced using the ‘@’ character — see the survey
command description.
For really large caves it’s possible to build a hierarchical structure of directories. In such a case we create one special file called INDEX.th which includes all other *.th files from given directory and contains equate commands to define connections between surveys.
The most important thing is to decide how the cave is divided into scraps. The Scrap is the basic building block of the map. It’s almost always a bad idea to try to fit each scrap to the corresponding *.th file containing the centreline from one survey trip. The reason is that connections between scraps should be as simple as possible, and surveys often start/end at junctions. Scraps in general are independent of the centreline hierarchy so try to forget the survey hierarchy when drawing maps and choose the best scrap joins.
We recommend inserting maps in the last-but-one level in survey hierarchy.23) Each scrap may then contain arbitrary parts of any survey in the last level of hierarchy. For example, there is a survey main which contains surveys a, b, c and d. Surveys a – d contain centreline data from four survey trips and each of them is in a separate file. There is a map main_map which contains scraps s1 and s2. If main_map is located in the main survey, scrap s1 may cover part of the centreline from survey a, complete survey b and part of c; s2 will cover part of the a and c surveys and a complete d survey. The survey stations names will be referenced using the ‘@’ symbol (e.g. 1@a) in the scraps.24)
Scraps are usually stored in *.th2 files. Each file may contain several scraps. To keep data well organized, we have some naming conventions: in the file foo.th2 all scraps are named foo_si, where i is 1, 2 and so on. Cross-sections are named foo_ci, lines foo_li etc. This helps a lot with large cave systems: if some scrap is referenced, you immediately know in which file it had been defined.
Similar to *.th files, there may be one file INDEX.th2 per directory which includes all *.th2 files, defines scrap joins and maps.
When drawing scraps you should check if the outline is properly defined: all lines creating the outer border should have -outline out option; all lines surrouding inner pillars -outline in option. Scrap outlines can’t intersect themselves — otherwise the inner side of the scrap can’t be determined. There are two simple tests that scrap outline is correct:
A model is created from scrap outlines. The height and depth of the passage are computed from passage-height point map symbols. In the future, there will be a dimensions map symbol which will allow more precise floor and ceiling height specification.
If you create an object outside the scrap ... endscrap construction, you can use Move up, Move down or Move to buttons in the map editor window to move the object to the desired place. See the attached picture.
Click on image to see original size
I think we need a better understanding of what makes a ‘pillar’. I thought a pillar was a closed loop within a passage, but the enclosed area in the picture below is not a closed loop (a passage goes off underneath from the gap). So when does therion need to be told that an outline is ‘in’?
Nobody would call the massif between two passages in a cave a ‘pillar’, but therion sees things purely geometrically – it doesn’t matter if a closed loop within a passage is small or large, formed by a fallen block or two passages. So everything surrounded by a scrap border and not belonging to the scrap is a ‘pillar’ and need to have the -outline
in
option specified for the walls.
This picture illustates the above case. The red and cyan lines have to have “-outline in” option specified.
Click on image to see original size
There is another problem. Even if scrap boundary has correctly specified all -outline out/in/none options, there may be problem to determine which area is inside of the scrap if the outline crosses itself (like figure 8). In such a case you get a MetaPost warning
Warning: scrap outline intersects itself in foo_s1@foo
and it is than random if MetaPost determines the interior of scrap correctly. The solution is to
The enclosed pictures make it more clear.
and correction –>
Click on image to see original size
I have a bit of a problem with your example fix. Now the wall does not follow the wall on my survey - I have had to distort it a little to solve this problem. This seems to me to be the wrong answer - the original version is a correct drawing of the cave, therion needs to be able to join (and distort if necessary) that drawing without telling me it it ‘wrong’ and I have to draw the cave a slightly different shape in order for it to be accepted.
There is a problem that therion does some calculations itself and some lets to MetaPost. When the scraps are joined, therion has no idea if the border is intersecting itself. When MetaPost examines the border, it’s too late for changing the scrap distortion – it may only give a warning.
I realise this may not be easy, but I don’t really think that telling the user their correct drawing causes an error is good enough. Perhaps when the outline intersection happens on a line that is a scrap end line (i.e one that therion invented, not one the user drew) then that should not be an error
It can’t be just ignored, because metapost needs non-intersecting outline to determine the interior of scrap correctly.
and therion could adjust its own line to compensate? Is that practical?
It can’t right now – the intersection is detected only in metapost. We would have to implement the algorithm in therion, which would be not trivial.
The easiest way to examine stations is to put -name
in the search field. Then click “Find first” and then “Find next” and check each station, to see whether it has the correct name and position, and is associated with the correct scrap.
Click on picture to see original size
If your map is coming out distorted or joins are not connecting in the right place then debug mode is a very useful way to see what is going on. Indeed it is generaly useful to get a visual display of the distortions in the map.
You turn it on by putting “debug on” in your layout command for the map.
layout debug debug on ... ... endlayout export map -proj plan -layout debug -o debug.pdf
This will produce a map which, as well as the finished result, also contains red and blue outlines, various coloured points, and yellow and black lines indicating distortions. The meaning of these is as follows:
If there is only one black point this indicates two stations with different names at the same point.
No it is not. In the map - all joined scraps have to be from the same projection.
Let us say I have a survey on a piece of paper, but the centreline data has been lost, and I know nothing but the distance that corresponds to 50m. How would I go about therionising this survey?
-visibility off
option, that it will not be visible in the map).-scale
option. If you have a horizontal 50 m scalebar on the paper, and the page/scan is facing north, than I would use 0 0 50 0
as the real scale coordinates for the ends of the scalebar. See attached pictures. Real coordinates are not important, only their difference (vector) is. Scrap will be positioned according to stations specified in it.Mixing projections, or calibrating scraps only using scale option I do not consider as a good idea. If you decide to use other coordinates (e.g. GPS), then you will need to shift all pages/scans somewhere else. If the real coordinats are in the form:
fix paper1 10 20 30
fix paper2 20 30 40
then it will be very simple, because it is in one table. If the scaling points were in the scrap headers, then it would be very hard, as they will all have to be changed individually.
Another point - this way (one station per scrap or page) each scrap also receives some vertical information. This will allow you to color scraps by altitude, it will be also possible. When scaling scraps only using -scale
option, there is no vertical information.
Let us say we have three scraps going from one survey point - Y or T-shape
If we connect such scraps in the ‘normal’ way - the result would be a triangular hole in the connection (rectangular, if there are four scraps, etc). We may use a virtual wall with the ‘‘-visibility off’ option to fill this hole, but it is much simpler to use a trick - add a small section of wall to one of the scraps where the two others scraps are joined. See attached pictures.
Xtherion “normal”: pdf “normal”:
Xtherion “tricky”:
pdf “tricky”:
Click on picture to see original size
Only do this when you have no choice. It is much better to design the layout of scraps so you never need to move this around.
If both scraps are in the same .th2 file:
If you want to move a part of wall you should split it first:
If both scraps are in different .th2 files:
You may do it with caution in text editor. You may use id option in object control section to help identify the correct object.
There are a couple of places where there are ‘gaps’ in the grey background. The most obvious example is the large chamber in the middle is foo_s2 (with lots of boulders). The main chamber has a RH wall which is in the ‘middle’ of 3 walls. The rightmost wall is the RH wall of a lower passage, formed by the large pile of rocks in the middle separating the upper and lower parts for 30m or so. What is the ‘therion way’ to draw something like this? Just use a border for the central line? Or split the lower portion into a very small scrap, I suppose? And there is a similar problem on the other side of the chamber (where a steep ramp goes up on the left)
The separate scrap is the best solution. The other is to split the inner wall and set the ‘outline in’ option as displayed in the attached picture.
click on image to see original size
The exact rule is that each line forming the outer border of the scrap has to have ‘outline out’ option (walls have this by default), each line forming inner pillars ‘outline in’ option, and all other lines (even walls lying inside of scrap) ‘outline none’ option. For all walls which shouldn’t form the scrap border you have to set ‘outline none’ option. See the second attachment to see how to specify this.
click on image to see original size
It seems that if I include any of soundriver2_s1 soundriver3_s1 or soundrivercrab_s1 then it breaks. soundriver2_s1 is particularly perplexing as it is a straight bit of passage with no areas in it, 3 stations, and not much detail - seems to me there is very little to go wrong.
I’ll start with easier problems. The problem in soundriver3_s1 was really tricky. Step by step description:
uncommented soundrivercrab_s1:
I got an MetaPost error
"! Paths 6 and 5 don't intersect."
It’s always related to areas so I used “search & select” in the map area to find all areas. There was only one area (line 6 in File commands). I looked to Command preview window to see the definition and tried to locate all area border lines in the scrap. There was one line too much (l26-1164-70), which I deleted in Area control.
uncommented soundriver2_s1:
I got an error:
l_flowstone->...as>dlzka+(mojkrok/3);t1:=t2;endfor ; l.5074 )) ; The `angle' between two identical points is undefined. I'm zeroing this one. Proceed, with fingers crossed.
The first error line gives the name of symbol in which the error ocured (l_flowstone) with a piece of its definition (which is not interesting now) and the second line gives a line number in the metapost file (created from all scraps) where the error ocurred and the text on that line.
I knew that problem was in some line flowstone symbol so I used “search & select” to find all “line flowstone” occurences, and checked the definition in the “Command preview”. Fortunately already the first flowstone line had duplicated point
703.0 793.0 703.0 793.0
I deleted it in Line control→Edit line→Delete point
uncommented soundriver3_s1:
Similar error:
l_arrow->...d(angle(direction.infinity.of(EXPR0))-90)shifted(point.infinity....l.5728 ),2) ; The `angle' between two identical points is undefined. I'm zeroing this one. Proceed, with fingers crossed.
As before I searched for the given symbol (line arrow): search & select line arrow (Find first, Find next, ...) and watched the Command preview window to see the definition. I suspected that problematic is line 24 in the File commands window:
363.0 573.5 363.0 573.5 317.0 604.5 295.0 642.5
with the control point of bezier line equal to previous point. After playing a bit with control points and even deleting the line the problem remained. I couldn’t imagine which arrow casues problems so I had to identify it acoording to the line number given in MP error.
I run therion in debugging mode (-d argument), opened the file data.mp in the $TEMP/thTMPDIR directory and jumped to line 5728.
The problem with the file data.mp is that it doesn’t contain original coordinates from th2 files so I couldn’t identify the arrow using coordinates. I counted how many arrows are in the scrap containing line 5728 before the arrow ending on line 5728. Our arrow was the second in this scrap. Metapost file has reverse order of symbols (in order to display first object in the th2 file on top) so the final result is that problematic arrow is last-but-one in the file, i.e. line 23 in the File commands window.
There is actually nothing wrong with that arrow – that is the reason why it took so long to find it :) It has the last control point identical with the last point, which is perfectly acceptable in metapost. Unfortunately there is some bug in the arrow definition, which doesn’t allow this. I hope it will be possible to fix it. In the meantime you may change the line either to a straight segment (no control points) or add a control point different from the endpoint.
Warning: scrap outline intersects itself in bmb3_s3@fake.
I have this warning in a few scraps in that survey - I wondered how serious it was, and what I should do about it. But without more details of _where_ it intersects itself (and why this is a problem), I could not do anything but ignore it.
The only information we can give here is the scrap name. There is no way how to find out in MetaPost where exactly the closed path intersects itself
I have several more scraps which I cannot include in the overall survey at the moment because if I do I get cryptic metapost errors. We have to work out a way of getting better feedback to the user about _where_ the problem lies as it is currently extremely difficult to fix as you don’t know which of many lines is at fault.
We think it’s doable to give a line number in th2 file where the error occures. It would be perhaps possible to also identify area border lines which don’t intersect.
How did you find the above problem. If I understood the process you used to find this it might help me next time.
We got this error (uncorrectly determined interior of the scrap) long time ago in Dead Bats Cave map. There was some strange clipping by the scrap border, which we could’t explain. In that time there was no MP warning, no map colouring. We don’t remember exactly but it took quite long till we identified that the problem is in the border and than what is wrong with the border. After reading thoroughly the apprpriate chapter of the Metafont book we knew that problem is in the loop – but even than we couldn’t find any – so small it was, in fact very similar to yours.
We added the MP warning to point to this problem. When we see it now, we first check scrap ends if something could cause the problem. The biggest problem is if the loop is introduced only after morphing the scrap ends before joining scraps. We can only recommend to move control point in the last bezier arc of wall just before the scrap end, run therion, undo the change by pressing Ctrl+Z and repeat with other walls until the problem remains.
The loop may occur also in the middle of the wall, but it should be visible, at least in 400% zoom.
We are sorry that there is no cleverer algorithm to find the loop :(
There are two underlying rooms connected with a large pit. If you draw raw overhang and pits lines you will receive a bit strange looking picture:
Click on picture to see original size
If you set the options for overhang and pit lines to: -outline in -clip off, the pit will be transparent:
Check the TherionBook - you have to add to your layout:
code tex-map \legendcontent={% \hsize=\legendwidth \ifnortharrow\vbox to 0pt{\line{\hfil\northarrow}\vss}\fi \edef\tmp{\the\cavename} \ifx\tmp\empty \else {\size[26]\the\cavename} \vskip1cm \fi \ifscalebar\scalebar\vskip1cm\fi {\rightskip=0pt plus 3em\parskip=3bp \edef\tmp{\the\comment} \ifx\tmp\empty \else {\size[12]\the\comment} \par\medskip \fi \everypar{\hangindent=2em\hangafter=1} \edef\tmp{\the\cavelength} \ifx\tmp\empty \else {\size[12]\si\the\cavelengthtitle: \ss\the\cavelength\par} \fi \edef\tmp{\the\cavedepth} \ifx\tmp\empty \else {\size[12]\si\the\cavedepthtitle: \ss\the\cavedepth\par} \fi \edef\tmp{\the\exploteam} \ifx\tmp\empty \else {\size[12]\si\the\explotitle: \ss\the\exploteam\quad\si\the\explodate\par} \fi \edef\tmp{\the\topoteam} \ifx\tmp\empty \else {\size[12]\si\the\topotitle: \ss\the\topoteam\quad\si\the\topodate\par} \fi \edef\tmp{\the\cartoteam} \ifx\tmp\empty \else {\size[12]\si\the\cartotitle: \ss\the\cartoteam\quad\si\the\cartodate\par} \fi \edef\tmp{\the\copyrights} \ifx\tmp\empty \else {\size[12]\ss\the\copyrights\par} \fi } \formattedlegend }
where you may replace the size of font - “default\size[26]” before “\the\cavename”.
Here is a part of .th file with survey, input and map definitions
survey rotunda_perlovy -title "Cachticka jaskyna, Rotunda + Dom starcov" input ../rotunda_dlhy_hlboky/rotunda.th input ../rotunda_dlhy_hlboky/dlhy_dom.th input dom_starcov.th input bordel.th input oranzovy.th input perlovy.th map rotunda_perlovy.map perlovy.map@perlovy oranzovy.map@oranzovy break #rotunda.map@rotunda break #dom_starcov.map@dom_starcov break #bordel.map@bordel endmap
As you may see, there are several files inputed to this survey and there are several maps, some of them commented. When you use thconfig file without “select” command, the final map will include all partial maps, doesn’t matter if they are uncommented or not.
endlayout export map -o rotunda_perlovy.pdf -layout my_layout
The reason is, the maps definitions are in the included files and configuration file will use all of them.
Click on picture to see original size
If you want to generate map with only two submaps - perlovy.map and oranzovy.map - you should use “select” command in configuration file and select the rotunda_perlovy.map. Therion will generate the map with only perlovy.map and oranzovy.map now.
endlayout select rotunda_perlovy.map@rotunda_perlovy export map -o rotunda_perlovy.pdf -layout my_layout
Click on picture to see original size
If you uncomment all the submaps in map definition you will receive the next map:
map rotunda_perlovy.map perlovy.map@perlovy oranzovy.map@oranzovy break rotunda.map@rotunda break dom_starcov.map@dom_starcov break bordel.map@bordel endmap
Note: the break command coerces dividing the maps to appropriate levels. Without break command all the maps would be in one level. Check the situation on left side of pictures - the presumed walls.
Click on picture to see original size
There are three very useful buttons in compilation window menu - Survey structure, Survey info and Map structure. You may use the Map structure information to easy select the maps or submaps to your configuration file - just doubleclick on map you want to select and it will be copied to your thconfig file
Click on picture to see original size
Survey structure and Map structure
Map structure with all submaps uncommented
The cross-section scrap must have option “-projection none”. It must be calibrated - see “How to add old ‘lost data’ survey to some new data?”
Section lines - they must be of type “section”
Point “section” - it defines the place where the cross-section will be drawn. There is an optional parameter -align [tr, tl, br, bl] - the TopRight option means the section rectangle will be drawn in TopRight quadrant of the point.
Both line “section” and point “section” belong to plan or elevation scrap.
–If you draw only segment line, without control points, you get the solid line crossing the passage - the arrow could be added by “direction” option.
–If you preffer lines only by sides of passage you should draw line as a curve, with control points on both sides. The control points will control the length of visible segments of section line.
Click on image to see original size
If the base-scale is the same as the scale, it has no effect (such as 1:1 photocopy).
If there is for example “scale 1 200” and “base-scale 1 100” the symbols and text will be printed in 1/2 size because of base-scale setting.
If you printed the survey at 1:1000 and photoreduced it to 1:2000, the symbols and text would be halved in size by the photoreduction. Just printing at 1:2000 will give symbols and text twice as large as this, so changing base-scale from 1:1000 to 1:2000 doubles the symbol and text sizes in the same way.
You may forget the base-scale if the default settings work well. We introduced the base-scale to make it possible to do simple adjustments to the size of symbols used without the need of metapost programming (e.g. when symbols appear too big in the 1:400 scale, but OK in 1:200 scale, it’s sufficient to set “base-scale 1 200” and “scale 1 400” and I get map in 1:400 scale with symbols proportionally as large as on 1:200 map). If therion gives you suitable symbol sizes, then just use the scale setting. If not, experiment with base-scale or redefine metapost.
A scale is a problem in map mode (page larger than PDF and pdfTeX cann’t manage – more than about 5*5 m), but there are no limitations in atlas mode and SVG map size.
An additional limitation is the size of a picture, which can metapost process – it’s about 2.8 m. Each scrap is processed separately in one picture, so it means, that each scrap must be smaller than 2.8 * 2.8 m _in the output scale_. We don’t think it’s a big issue unless you try to draw the whole cave in one scrap. (At 1:100 scale a scrap can contain 280*280 m section of the cave).
(the number 33 is just an example):
* The therion log window displays metapost’s progress, it displays [33] just before the error; that means that picture number 33 has been sucessfuly processed and the error is in the next one
It’s not particularly straightforward but it’s difficult to make a better link between metapost and therion when an error occurs.
> Currently if an area crosses a scrap join we just put an area either > side - one in each scrap. This needs a ‘border -subtype invisible’ > line across the passage at the join on _both_ scraps - these lines > are directly on top of each other. The problem here is that you > can’t click on the line which is ‘below’ so you can’t complete one > of the areas without first moving the top line to the side > temporarily. This is clearly not satisfactory. Is there a better > way? If not then selecting the new scrap should move the border line > to the ‘top’ for the purpose of clicking.
Did you try right-click on the line point? Each right-click changes the line used for editing if there are more of them on top of each other.