\subchapter {Drawing maps in therion}.


\fitpic{../samples.doc/000001-rabbit-plan.pdf}



\fitpic{../samples.doc/000002-rabbit-xelev.pdf}


\subchapter {Listing caves}.


 When surveying caves in some large area, you often need to generate 
 an up to date list of all caves in that area. In therion dataset, "cave" 
 can be defined in several ways, depending on the level of cave survey.




 If you have just surveyed entrance station (e.g. using GPS or standard
 surveying methods), all you need to do is to assign |entrance|
 flag using


|station cave-1 "Unsurveyed cave" entrance
|


 If there is some explored passage behind this entrance, but you did not
 survey it properly, you should add also |continuation| flag
 and |explored| flag followed by explored length. Explored but
 unsurveyed passage lengths are also part of summary statistics.


|station cave-2 "Unsurveyed but explored" entrance \
        continuation explored 80m
|


 If you have properly surveyed some cave, its data are usually in some
 |survey| structure. Survey becomes a cave, if it has main entrance
 station specified using |-entrance| option. Example:


|survey small_cave -title "Tunnel cave" -entrance 0
|


 If survey contains survey data, but it has no main entrance specified, it
 is not considered as a cave, just as data organization unit and thus not
 present in the cave list. Only surveys containing some caves (i.e. entrance 
 stations or surveys with main entrance defined) are present in the final
 cave list table.




 After caves in your data have been properly defined, you can generate
 table using


|export cave-list -o caves.html
|


 Resulting table looks like this


\bigskip\begingroup\input etc/TXSruled.tex \LeftJustifyTables\ruledtable
{\bf Title}&{\bf Length}&{\bf Depth}&{\bf Explored}&{\bf Altitude}\cr
Tunnel cave&25&7& &1244.000\nr
Unsurveyed cave& & & &1234.000\nr
Unsurveyed but explored& & &80&1256.000\endruledtable\endgroup\bigskip
\subchapter {Area symbols}.


\fitpic{../samples.doc/000000-types.pdf}


\subchapter {Sketch morphing}.


 Original survey sketch:




\fitpic{../samples.doc/000007-cave1.jpg}



 Image after morphing:




\fitpic{../samples.doc/000008-cave1.pdf}



 Walls after morphing:




\fitpic{../samples.doc/000009-cave2.pdf}



 Another survey sketch:




\fitpic{../samples.doc/000010-cave.png}



 This image after morphing:




\fitpic{../samples.doc/000011-cave1.pdf}



 Morphed sketch after {\it extra} points insertion:




\fitpic{../samples.doc/000012-cave2.pdf}



 And the morphed walls:




\fitpic{../samples.doc/000013-cave3.pdf}


\subchapter {Extended elevation control}.


 Assume following situation (in plan view),
 when there is a loop in centerline between stations 1 and 4, 
 small chimney near station 5
 and entrance to the cave is at station 6.




\fitpic{../samples.doc/000025-map1p.pdf}



 By default, centerline extended elevation of this situation looks like this:




\fitpic{../samples.doc/000026-map1x.pdf}



 This is obviously not what we would like to get.




 To control process of extended elevation, there is a special
 |extend| option in centerline command. 




 First of all, we would like to start our extended elevation
 at station 6 (where the entrance is). This can be done by specifying


|extend start 6
|


 in the centerline. Now it looks better,




\fitpic{../samples.doc/000027-map2.pdf}



but there is still a problem with a branch containing station 5.




 If we would like to start this branch from station 4, we need
 to forbid therion to extend station 5 from 1. This can be done
 by specifying


|extend ignore 1 5
|


 This means, that shot from 1 to 5 will be ignored, when extended
 elevation is generated. 




 If we would like to extend branch starting
 with station 5 to the left, we need to specify also


|extend left 5
|


 This will extend all stations from station 5 to the left.




\fitpic{../samples.doc/000028-map3.pdf}



 As we have mentioned before, there is a small chimney above station 5.
 In this case, it is much more natural to draw this shot as vertical
 (because it is a chimney). To specify this, use 


|  extend vertical 5 5'
|


\fitpic{../samples.doc/000029-map6.pdf}



 Or you can completely hide this leg from extended centerline using:


|  extend hide 5 5'
|


\fitpic{../samples.doc/000030-map7.pdf}

\subsubchapter {Stations in extended elevation scraps}.


 Even if the station 1 is present more then one time in the map, 
 therion automatically
 detects correct position of this station in each scrap and they are
 usually drawn correctly.




\fitpic{../samples.doc/000031-map4.pdf}



 The only thing that is missing is connection line between stations 1
 in these two branches.
 Therion does not automatically generate these lines because their
 shape usually depends on particilar map. 




 To draw such a line all you need to do is to create a simple scrap 
 with this line. Here is an example:


|scrap sc -proj extended
  point 0 0 station -name 1 -from 5 -visibility off
  point 100 0 station -name 1 -from 2 -visibility off
  line map-connection
      0   5
      0  15
    100  15
    100   5
  endline
endscrap
|


 As you can see, even there are two stations with same name, they
 are distinguished by |-from| option, which specifies
 previous station in extended elevation. Using this scrap you receive the
 final map:




\fitpic{../samples.doc/000032-map5.pdf}


\subchapter {Displaying overlaying maps in offset}.


 Assume that there are two maps {\it m1} and {\it m2} 
 ({\it m1} is above {\it m2}). By default therion displays 
 {\it m1} overlying {\it m2}.




\fitpic{../samples.doc/000003-map1.pdf}



 To display map {\it m2} in offset you need to create a map
 containing {\it m2} and specify offset and preview type
 for {\it m2} in this map. Example:


|map m12
  m1
  m2 [0 8 m] below
endmap
|


 After selecting the {\it m12} in configuration file you
 receive:




\fitpic{../samples.doc/000004-map2.pdf}



 Joining arrows are created from {\it map-connection} points
 specified in scraps that are moved. Otherwise these points are
 ignored.




 If the situation is more complicated, e.g. there is {\it m3}
 below {\it m2}




\fitpic{../samples.doc/000005-map3.pdf}



 you need to create more complicated map structure
 to handle this.


|map m23
  m2
  m3 [-8 0 m] below
endmap

map m123
  m1
  m23 [0 8 m] below
endmap
|


 Then {\it m123} looks like this:




\fitpic{../samples.doc/000006-map4.pdf}


\subchapter {Importing survex .3d files}.


 Therion surveys nearly correspond to station prefixes defined by
 |*begin|/|*end| pairs in survex source files. Usually there
 does not exist one-to-one mapping between them. So if you want
 to keep your centerline in survex files you need to solve the
 problem how to match survex and therion data structures. This
 sample shows three different ways, how to deal with station prefixes
 when importing survex .3d files to therion.


\subsubchapter {Using surveys specified in .th files}.


 If you will import .3d file with |-surveys use| switch,
 then therion tries to find the match between {\it survex prefix} 
 and {\it therion survey name}. If this match is found, stations
 are inserted into survey found. Otherwise prefix is left with 
 station names. Example code:


|import use.3d -surveys use
input use-out.th2
survey use
  input use-in.th2
endsurvey
|


 In this case you should take care where you input your .th2 files
 containing scraps. In {\it use-out.th2} file you should refer to station names
 using:


|point 165.744 176.58 station -name 2@use
|


 but in the {\it use-in.th} file using


|point 321.454 236.22 station -name 1
|


 Map with station names in this case looks like this:




\fitpic{../samples.doc/000018-use.pdf}



 Station names are before '@' symbol, survey names follow this symbol.


\subsubchapter {Creating non-existing surveys}.


 If you import your .3d file using


|import create.3d -surveys create
|


 all survex prefixes are taken into account and if surveys with
 corresponding names do not exist, they are created. In this case,
 if you do


|input create.th2
|


 right after |import| command, you refer to stations in .th2
 file with names shown on the map.




\fitpic{../samples.doc/000019-create.pdf}

\subsubchapter {Ignoring station prefixes}.


 Last possibility is to import your .3d file using


|import ignore.3d -surveys ignore
|


 Also in this case, station references in corresponding .th2 file
 are same as station names on the next map.




\fitpic{../samples.doc/000020-ignore.pdf}



 Note that no surveys are created in this case. Station names
 are taken from .3d files without change.


\subsubchapter {Managing large projects}.


 Assume a situation when you want to join these three small maps
 within single large project. Assume that coordinates of cave
 entrances are specified in the top-level cave.3d file. If your
 joining code will be


|import cave.3d -surveys use
survey cave
  input use/use.th
  input create/create.th
  input ignore/ignore.th
endsurvey
|


 not all stations are replaced correctly. The "created" series
 is placed wrong on the map.




\fitpic{../samples.doc/000021-cave1.pdf}



 This is because in top level import command, survey {\it create} is
 imported from file |create/create.3d| with wrong coordinates,
 and we import top-level .3d file with |-surveys use| switch.
 This means, cave.create.1 will be imported here as create.1@cave and not
 1@create.cave.




 To solve this problem, we need to re-import stations
 from top-level cave.3d file once more with |-surveys create|
 switch.


|import cave.3d -surveys use
import cave.3d -surveys create
survey cave
  input use/use.th
  input create/create.th
  input ignore/ignore.th  
endsurvey
|


 After this additional |import| final looks as expected.




\fitpic{../samples.doc/000022-cave2.pdf}

\subsubchapter {Conclusion}.


Even if there are several possibilities how to map survex prefix structure
to therion survey structure, the most clean solution is to create
survey structure to desired depth in .th files using empty 
|survey|/|endsurvey| pairs and always use
|-surveys use| switch when importing .3d files.



\subchapter {Question marks handling}.


 Possible continuations are treated special way in therion
 in both centerline and map files. You may associate text
 description, explored length (behind this continuation)
 or any other atribute to it (like Code if you have your
 own coding standard for continuations).


\subsubchapter {Question marks in centerline}.


 In the centerline object, you may add a special flags to the station,
 where continuation is possible. Just use following syntax


|station 5 "pit" continuation attr Code V explored 20m
|


 When you export map and use


|symbol-show point flag:continuation
|


 in your layout, station with continuation flag specified
 is marked by question mark (continuation
 symbol is shown above the station).




\fitpic{../samples.doc/000014-map1.pdf}



 You may redefine continuation symbol to show also
 continuation description (stored in |_text| 
 attribute) using following layout code


|code metapost
  def p_continuation(expr pos,theta,sc,al) =
  
    % draw default continuation symbol
    p_continuation_UIS(pos,theta,sc,al);

    % if text attribute is set
    if known(ATTR__text) and picture(ATTR__text):
    
      % set labeling color to light orange
      push_label_fill_color(1.0, 0.9, 0.8);   
      
      % draw filled label with text next to ?
      p_label.urt(ATTR__text,(.5u,-.25u) transformed T,0.0,8);      
      
      % restore original labeling color
      pop_label_fill_color;                   
      
    fi;
  enddef;
endcode
|


 Then also continuation description is displayed in the map.




\fitpic{../samples.doc/000015-map2.pdf}

\subsubchapter {Question marks in maps}.


 In the scrap (.th2 file), you can use |-text|, |-code|
 and |-explored| options to continuation symbol.


|point 796.0 676.0 continuation -attr Code A -explored 50m \
    -text "water too cold to continue survey"
|


 In the map, also the question marks only are displayed by default.




\fitpic{../samples.doc/000016-map3.pdf}



 When you redefine continuation symbol as mentioned above, 
 you can show also continuation codes and descriptions.




\fitpic{../samples.doc/000017-map4.pdf}

\subsubchapter {Exporting question mark lists}.


 You may also export a list of all continuations from your project
 project using


|export continuation-list -o questions.html
|


 File questions.html then contains following list:


\bigskip\begingroup\input etc/TXSruled.tex \LeftJustifyTables\ruledtable
{\bf Comment}&{\bf Explored}&{\bf Survey}&{\bf Station}&{\bf Code}\cr
water too cold to continue survey&50.0&Sample cave&7&A\nr
strong wind from breakdown& &Sample cave&3&B\nr
pit&20.0&Sample cave&5&V\endruledtable\endgroup\bigskip
\subchapter {Using user defined symbol types}.


 If therion does not offer any appropriate symbol for the feature
 you want to draw to the map, you can use user defined symbol type
 (type |u|, valid for point, line and area objects).




 The syntax is very simple. Assume you want to create "bat" point, line
 and area. You just use |u:bat| as a type (bat is in fact subtype)
 of u type. So your code will be like this:


|point 555.0 480.0 u:bat
|


 or


|line u:bat
|


 or


|area u:bat
|


 When you export map without defining the symbols in \MP{}, user defined symbols are highlighted
 in red without any graphical representation.




\fitpic{../samples.doc/000023-map1.pdf}



 To display them correctly you need to define symbols for them in
 \MP{} languge the same way as ordinary symbols are usually redefined.




 Firstly point symbol. In the


|code metapost
|


 section of your layout define point u:bat symbol like this


|def p_u_bat(expr pos, theta, sc, al) = 
  T := identity shifted pos;
  thfill (bat_path scaled 2.0);
enddef;
|


 similarly the line u:bat symbol


|def l_u_bat(expr P) =
  T:=identity;
  cas := 0;
  dlzka := arclength P;
  mojkrok:=adjust_step(dlzka, 1.0u);
  pickup PenD;
  forever:
    t := arctime cas of P;
    thfill bat_path scaled 0.5 shifted (point t of P);
    cas := cas + mojkrok;
    exitif cas > dlzka + (mojkrok / 3); % for rounding errors
  endfor;
enddef;
|


 and finally the area u:bat symbol (pattern in this case)


|% bat pattern
beginpattern(pattern_bat);
    fill bat_path;
endpattern;

% bat area symbol
def a_u_bat (expr Path) =
  T:=identity;
  thclean Path;
  thfill Path withpattern pattern_bat;
enddef;
|


 These symbols will be included also in the legend. To
 change the way how they are drawn there just define appropriate
 macro. Its name should be symbol macro name with |_legend| 
 suffix.


|def l_u_bat_legend = 
  l_u_bat(((.2,.2) -- (.8,.8)) inscale) 
enddef;
|


 Finally, add description of your new symbols that will be shown 
 in the legend using |text| command anywhere 
 in the configuration file.


|text en "point u:bat" "bat"
text en "line u:bat" "bat path"
text en "area u:bat" "lot of bats"
|


 After all these definitions you receive bat point, line and area symbols
 with proper graphical representation and legend boxes.




\fitpic{../samples.doc/000024-map2.pdf}


