extend

This page is inspired by Marco Corvi’s altervista web pages on extended elevations in relation to loops and importing Survex data (near bottom of page), and others who have asked and answered ‘extended’ questions on the Therion Forum. Thank you all.

I hope this page (started in April 2018) brings some clarity. It is based on the above posts and my experiences so far, which suggest the current documentation leaves much unsaid. Therion versions 5.5.0 and 5.5.2 in 2020 saw bugs related to 'ignore station' and extended splay alignments corrected, as well as adding new features enabling stretching or shrinking the horizontal extension (extend ratio), 'three-station' path ignores and logging of the extended network development.

Further insights and corrections welcome, please post on the forum, or edit this page. Bruce Mutton September 2020

The shape of survey centrelines in plan, and in elevations projected in a particular direction, is immutable; based on the survey legs, and associated distance, bearing and inclinometer readings. So there is little or no choice as to how they look.

Drawings however, are subject to the artistic whim of the author, so it is likely therefore that two authors, using the same centreline, will come up with only similar drawings. Sometimes they will not even be similar! And one author might want to associate more than one drawing with a single centreline – for example if drawing a large cave at 1:2000 scale (-projection plan), and then drawing some parts in greater detail at 1:100 scale (-projection plan:detail) using the projection:index capability.

This no doubt is one of the reasons why Therion was developed to treat centrelines and drawings completely independently. ie centrelines in surveys, and scraps in maps.

Unlike plan views or elevations projected in a particluar direction, the shape of centrelines for extended elevations do not fit entirely within either of the paradigms above. They are largely determined by survey legs, and associated distance, bearing and inclinometer readings, but there is a large component of author discretion required to determine the shape of the centreline network. For larger caves with many commonly travelled routes and loops, it is likely that a number of extended centrelines will be desired, some of which will traverse the same parts of the overall centreline, and sometimes in opposite directions. So extended elevation centrelines could be considered to have as much in common with drawing functionality, as with survey functionality. And then it turns out that certain drawing characteristics can override and fundamentally change the shape of a carefully crafted extended centreline shape. So even drawing extended elevations has an element of centreline modification!

Initially, Therion development has supported extended elevation control functionality interleaved with the survey data (distance, bearing and inclinometer readings) for each particular survey trip. In a large cave, this makes it very difficult set up and manage a clear arrangement of extended centrelines, let alone accommodating half a dozen different extended elevations for the same cave.

It turns out, that even though we cannot take extend control outside of centreline definitions, we can take it outside of the trip surveys, and place it in a single file, one for each separate extended centreline. A bit like Survex’s ESpec file approach. Having overall control in one place, away from scraps and away from the survey data allows us to keep extended control conceptually and functionally separate, and allows multiple extended centrelines to be readily maintained.

It is helpful to remember that, as with all survey data, Therion loads all extend control information into memory before deciding on the order in which to process it. Therefore you can place your extend statements in any centreline and in any order that makes sense to you. Just remember that the order of statements is unlikely to have any effect on the order in which Therion processes them.

Shortly after defining your extended centreline, you are likely to want to know what station sequence Therion is using to develop the extended centreline. This might help you decide how to modify unexpected behaviour.
Add log extend to your thconfig before the export statement.
Therion will now add to the therion.log file, a transcript of the extend option, station sequence and (stretch, %) ratio it has used to generate each station position in the extended elevation.
For example, here is a short transcript from a therion.log file:

LEFT 95@D-K1.DwarfsDoor
LEFT 96@D-K1.DwarfsDoor (50%)
VERTICAL 2@D-K6.DwarfsDoor
LEFT 3@D-K6.DwarfsDoor

In this example only the leg 95 to 96 has been scaled to 50% of its proper length. All of the other legs are plotted unscaled (at 100%).

Descriptions of extend options behaviour when separated out from the survey data, and included in their own separate centreline:
The options can be divided into those that affect network generation control and those that affect direction:

Extend control options include start, ignore, and hide.

Extend direction options include right, left, normal, reverse, vertical, and (stretch) ratio (0 to 200%).

  • They must be followed either by a valid survey <station> id, a valid survey <leg> (pair of stations), or in the case of ignore, possibly a three station <path>.
  • For direction options, specifying a <leg> applies the option to ONLY to that leg, and specifying a <station> applies the option to the leg(s) used to reach (create) that station, AND all subsequent <legs> within the centreline (Control options start, hide, and ignore apply only to or at the <station> or <leg> specified).
  • Note that Therion differs from Survex here. Survex applies the <station> option only to the subsequent legs.
  • Therefore to help with readability and cross platform usage, it is a good approach to specify two lines, one saying to apply the option to the initial leg where it is wanted, and one saying to apply the option to the (second) station to trigger the automatic propagation. ie
extend left 3 4
extend left 4

extend start <leg> - start generating extended elevation centreline with this leg. (In one case i have found, it can have unexpected effects, even far from the starting leg. I think i prefer 'extend start station' as below.)
extend start <station> - start generating extended elevation centreline at this station.
There should only be one 'start' specification I think, but there seems to be no ill effect if there are multiple starts. There is more to know here

extend right <leg> - extend this leg only, to the right, then continue extending subsequent legs, left or right, as per the leg immediately previous.
extend right <station> - generate the leg creating this station to the right and continue generating all subsequent legs towards the right.
extend left <leg> or <station> - same as for extend right, but extending left!

extend normal <leg> - extend this leg only, in the same direction as the leg immediately previous, then continue extending subsequent legs as per leg immediately previous.
extend normal <station> - generate the leg creating this station in the same direction as the previous leg, and continue generating all subsequent legs in that same direction :)
If extend normal is the first statement after extend start, then it will extend to the right.
extend reverse <leg> - extend this leg only, in the opposite direction to the leg immediately previous, then continue extending subsequent legs as per leg immediately previous.
extend reverse <station> - generate the leg creating this station in the opposite direction as the previous leg, and continue generating all subsequent legs in that opposite direction.
If extend reverse is the first statement after extend start, then it will extend to the left.

extend vertical <leg> - do not extend this leg horizontally, extend only the vertical component of this leg, then continue extending subsequent legs as per leg immediately previous. The order of stations in your vertical statement should usually match the direction of extended elevation centreline generation. However if Therion seems to ignore this vertical statement, try reversing the order of the stations in your vertical statement, and it might work!
extend vertical <station> - generate the leg creating this station vertically and continue generating all subsequent legs vertically, without any horizontal component.

extend <0 – 200> <leg> - stretch or shrink the horizontal extension of this leg to the percentage (ratio) 0% to 200%. Stretch or shrink only this leg, then continue extending subsequent legs as per leg immediately previous. extend 0 is the same as extend vertical. extend 100 does not apply (or cancels) any stretching or shrinking to the horizontal extension of the legs.
extend <0 – 200> <station> - stretch or shrink the leg creating this station by the ratio and continue generating all subsequent legs with that ratio.

extend ignore <path> - where <path> = station1 station2 station3. The map-connection break will occur at station2
extend ignore <leg> - generation of extended centreline shall not take this leg (or path), it will take the (an)other leg (or path) if possible. The map-connection break will occur at the first named <station> of <leg>.

  • If the leg is part of an open branch (does not loop back to the main centreline), then this may have the effect of hiding the entire branch from this leg onward, or it may offset the leg to a random location (in which case extend hide may be of use.
  • If leg is part of a loop, it beaks the loop. ie a loop connection gap, with joining map-connection line will be formed between two instances of the first station in the leg specification.

The order of stations in your ignore statement should usually match the direction of extended elevation centreline generation. However if Therion seems to ignore your ignore statement, try reversing the order of the stations in your ignore statement, and it might work! In any case, try reversing the order to get a different effect (loop connection gap arrangement). Sometimes the leg specification needs to follow the direction of survey, if it differs from the current direction of extend generation.
extend ignore <station> - where <station> is one or more legs past a junction in the direction of generation. ie The generation of extended centreline shall not take this leg, but take another branch instead. The map-connection break will occur at <station>. A bug in this functionality was resolved with Therion version 094ac85 14Nov2019.
Try to avoid ignoreing the same looped passage (ie an oxbow) at each of its junctions to a main passage. This can have the effect of offsetting the whole oxbow to the far end of the map (which of course is undesirable).
extend break is mentioned in some Therion posts, presumably as an alias for extend ignore (Survex terminology). It will trigger a Therion error “unknown extend flag – break”.
Sometimes branch centrelines will be ignored (hidden?) by default, and an extend right (or similar) statement will be required to stimulate the continuation of the centreline generation.

For more details of how to use extend ignore, see the article Breaking extended elevations on specific stations.


extend hide <leg> - hides the centreline part of the specified leg only, but NOT its stations or splays. Stations that form the leg remain visible! Does not hide subsequent stations or legs.
extend hide <station> - hides the station and all leg centrelines (usually two of these) and splays that emanate directly from THIS station. It does not hide subsequent stations or legs.
Note that the centreline generation is carried out as per normal, the stations and legs are just made ‘not visible’.

General Tips

  • Remember to comment out all extend options that may be in-line with the survey data (in your trip survey file) before creating a separate extended elevation centreline. I put mine in it’s own file and call it something like Extend-CaveName-ElevEXT.th file.
  • Sometimes, if generating the centreline against the direction of survey, then every <leg> needs to be enumerated, ie they don’t autogenerate if just a single <station> is specified. Other times, they autogenerate nicely.
  • Creating a new loop (such as adding a new survey or using nosurvey legs to straighten a centreline) will often require a significant rework of the extended centreline definition.
  • Caves, or parts of caves that comprise a linear passage with one or two dead-end branches are easiest to generate extended centrelines for.
  • Caves with one or more loops are more challenging. The rate of complexity increase is perhaps closer to geometric than linear. It is definitely better to start creating the extended centreline when the cave is only one or two surveys long.
  • Therefore it is better to over enumerate (list every leg) to begin with, as this makes the extended network more resilient to the addition of future loops.

Here is how I do this. It is a bit of a hack i am afraid. I place similar statements to those below in my Extend-CaveName-ElevEXT.th file.

centreline
# Create links between caves to enable connection of extended elevations
# This is a hack, as nosurvey is intended for passage with visual but unsurveyed connection
  date 2017
  flags approximate # makes dashed centrelines (with my customisation)
  flags duplicate       # ensures distance not counted anywhere, and makes yellow (with my customisation)
  data nosurvey from to
  1.6@01 1.26@02  # cave 1 annex to end cave 2
  1.1@02 1.1@03    # cave 2 entrance to cave 3 entrance
endcentreline

If you have drawn a scrap with the opposite orientation to the extended centreline generation, it will tend to plot inside out. You need to compensate for this by including -flip horizontal in the definition of your scrap. Or you can add -revise scrap-id -flip horizontal or -flip none in your Extend-CaveName-ElevEXT.th file.

If you include in your scrap drawing a point station -name <station> where that <station> is at a survey leg junction AND is offset in the extended centreline due to extended loop connection gap, then it will force the extended station to plot, incorrectly, in its original location, distorting the scrap in the vicinity of that leg. This can be vexing, as
a) you have to be vigilant while drawing, to ensure you don’t accidentally change the shape of your extended centreline, and
b) generally the station that you cannot draw is a marked station (cairn or otherwise identified station) that you are most likely to want to identify on the drawing!

The established Therion documentation describes how to create a map-connection line between ends of loop. However I have never done this, as it seems to be built into Therion these days, at least for centreline plots.
However for completeness here is the code for a scrap to draw a connection line. For now I will put it here as a placeholder, until we figure out if it still has a practical application. The famous Extended elevation control sample

equate <stnA> <stnB>
  scrap LoopConnectionAB -proj extended
    point 0 0 station   -name <junction stnA> -from <prev station A> -visibility off
    point 100 0 station -name <junction stnB> -from <prev station B> -visibility off
    line map-connection
      0 0
      100 0
    endline
  endscrap LoopConnectionAB
  map LoopConnectionAB Map -proj extended
    LoopConnectionAB
  endmap

Alternative line shape

     line map-connection
         0 0
         0 15
       100 15
       100 0
    endline

There is also some syntax

point x y station -extend "prev <stn>” – used to specify which particular instance of a station in an extended elevation

for which i need to figure a a good use.

[To Do] Obtain sample data and drawing for famous Therion extend sample, and produce multiple extend centrelines and drawings. Post project data here.

Add some pictures to illustrate vertical, hide and ignore.

Resolve the incomplete topic above.

Here are some snippets from a project that contains four extended elevations. Some elevations traverse the same parts of the cave, and then head off along different passages.

thconfig map selections

#SOURCE DATA
#===========
source INDEXTeManaNui.th

#SELECT MAPS (Select which surveys/maps to output)
#======================================================
select TeMananuiPlan  # the whole cave

#Extended Elevation Control
#==========================
#Select only ONE Map ElevExt at a time, and 
#uncomment the ONE CORRESPONDING input Extend-*.th line in INDEXTeManaNui.th 

# select PyramidElevEXT               #uncomment ONLY one
select BladeRunnerOldBoldElevEXT    #uncomment ONLY one
# select BladeRunnerSalisburyElevEXT  #uncomment ONLY one
# select PharoahsNilePETNElevEXT      #uncomment ONLY one
...
input ../LayoutMapThisCave.thc       
input ./LayoutMapThisCaveElev.thc 

#SPECIFY OUTPUT COORDINATE SYSTEM
#=================================
# Recommended if you have one or more coordinate systems defined in source surveys or surfaces
# Often required if you also export atlas
cs EPSG:2193  #NZ Transverse Mercator 2000

#MAP/ATLAS 2D IMAGE OUTPUTS
#==========================
export map   -projection extended  \
  -layout LayoutMapThisCave \
  -layout LayoutMapThisCaveElev       \    
  -output ../Outputs/TeManaNuiCaveElevEXTMap.pdf  

Cave Survey INDEXTeManaNui.th

This example follows the convention that maps are defined outside of the survey definitions (but inside of the survey files). If you place maps inside the survey definitions, then you will need to remove the @TeManNuiCave bit.
This file includes inputs to the extended centreline file and definition of the extended elevation maps (in much the same way as it references plan and projected elevation elements as well - these are not shown).

survey TeManaNuiCave -title "Te Mana Nui Cave" 
#===============================================
  centreline
	cs <epsg number>
	fix gpsEntrance x y z dx dy dz
	equate gpsEntrance 19.1@19
  endcentreline
  
	#Input Surveys
	#=============
	input 01-BladeRunner.th
	...
	input input 19-Sphinx.th
	
	#Connect Surveys
	#===============
  centreline
    equate 11@01 21.0@21
	...
  endcentreline
  
  #Extended Elevation Control
  #==========================
  #Must only be ONE of following statements uncommented, 
  # and it must match selection in thconfig-TeManaNui.th
  # Files below contain extended elevation statements to make this survey 
  # match current extended elevation drawing
  
  # input Extend-PyramidElevEXT.th              #uncomment ONLY one
  input Extend-BladeRunnerOldBoldElevEXT.th   #uncomment ONLY one
  # input Extend-BladeRunnerSalisburyElevEXT.th #uncomment ONLY one
  # input Extend-PharoahsNilePETNElevEXT.th     #uncomment ONLY one
  
endsurvey TeManaNuiCave

 map PyramidElevEXT \
   -title "Pyramid Passage Te Mana Nui Cave Extended Elevation" \
  -projection extended
  
  18-OldBoldSideElevEXT@TeManaNuiCave
  20-ExhaustElevEXT@TeManaNuiCave
  22-PyramidElevEXT@TeManaNuiCave 
  ...
  28-CairnElevEXT@TeManaNuiCave
  endmap
  
map BladeRunnerOldBoldElevEXT \
   -title "Te Mana Nui Cave Downstream Extended Elevation" \
  -projection extended
   01-BladeRunnerElevEXT@TeManaNuiCave
   02-MainStreamElevEXT@TeManaNuiCave
   ...
   11-OldBoldExtElevEXT@TeManaNuiCave
   
   19-SphinxElevEXT@TeManaNuiCave  # This happens to be a separate cave
endmap

# etc for all other ElevEXT maps.

Extended Control: File Extend-BladeRunnerOldBoldElevEXT.th

Here is part of one of the four files referred to in the above two sections. It should give you a feel for how it works.

# filename: Extend-BladeRunnerOldBoldElevEXT.th
	# This file is called from within the TeManaNuiCave survey in INDEXTeManaNui.th

	# collect extend statements from all centrelines as prelude to 'changing'
	# them so they can be treated as a 'drawing property' instead of a 'survey property'
    # Placing extend statements in block within target survey only works if you purge ALL extend statements before 'extend start' in a centreline, and purge all 'in-line' extend statements in centrelines

centreline 
station-names []@01  #01-BladeRunner.th
  extend start 11
  extend left  12 #out to dripline
  extend right 11 10 #Head upstream from Main TMN Entrance
  extend right 10 9  #will not autogenerate backwards thru survey, so enumerating all
  extend right 9 8
  ...
  extend right 2 1
  extend right 1 0a
  extend right 0a 0
endcentreline  

centreline 
station-names []@02  #02-MainStream.th
  extend left  0 1 # 0@02 = 0@01 Head upstream from Blade Maiden
  extend right 1 2

  extend left 2 2a
  extend vertical 2a 2b
  extend hide 2a 2c #short leg at btm Blade Maiden

  extend right 2    3 # continue upstream to 4
  extend right 3    4
  extend right 4    5
  
  extend hide  5    6
  extend hide  6    7 # will not autogenerate, so must enumerate to end of branch
  extend hide  7    8 
  ...
  extend hide 45   46 
  extend hide 46   47 
endcentreline 
  
centreline 
station-names []@04  #04-Waterfall.th
  extend right 5 83
  extend left  83 84
  extend right 84 85
  extend right 85  86  # automatically continues to 97, but if so, offsets at 67-97 randomly, so enumerate all
  extend right  86   87
  ...
  extend right  95   96
  extend right  96   97
station-names [] []
  extend right 97@04 1@08
endcentreline

centreline
station-names []@201 #201-SOHeaven.th
  extend ignore 97 201.1 
  extend hide 201.1 
  extend left 97 201.3
  extend left 201.3 201.4 #automatically continues
  # but is connected 2b@02 to 201.15@201 and offsets randomly, until key statements put in place
  extend left 201.4 201.5
  ...
  extend left 201.13 201.14
  extend ignore 201.14 201.15 # this is key part 2 that made it work

  extend left 201.15 201.16
  extend left 201.16 201.17
  ...
  extend left 201.30 201.31 
  extend left 201.31 201.32 
endcentreline
  
centreline
station-names []@08 #08-OldBold.th
  extend right  1    2 # will not automatically continue for some reason, so enumerate
  extend right  2    3
  ...
  extend right 29   30 
  extend right 30   31 # Pyramid Passage survey 18 not needing ignoring or hiding, for some reason
  extend right 31   32 
  ...
  extend right 53   54 
endcentreline  

# centreline
  # station-names []@11 #11-OldBoldExt.th
  # # commented out as this centreline propagates perfectly by default
# endcentreline

centreline
# Create link between top end OldANDBold and Sphinx Valley Cave to enable connection of extended elevations
  date 2016
  flags approximate # makes dashed with our customisation
  flags duplicate   # ensures distance not counted anywhere, and makes yellow with our customisation
  data nosurvey from to
  75@11 19.2a@19
endcentreline  

centreline #Sphinx Valley cave
station-names [] @19 #19-Sphinx.th
  extend right 19.2a 19.2
  # Now explicitly hide the surface stations to avoid need to hide via symbol-hide statements
  # extend hide 19.e 19.0 #hiding survey legs insufficient to hide stations if there are splays present, so just hide all from each station
  ## extend hide 19.0 19.4
  extend hide 19.0
  extend hide 19.4
  ...
  extend hide 19.11
  extend hide 19.12  
endcentreline 
  • extend.txt
  • Last modified: 8 weeks ago
  • by brucemutton