=====Extended Elevations===== This page is inspired by Marco Corvi’s altervista web pages on [[http://marcocorvi.altervista.org/caving/tbe/m_04/m_044.htm|extended elevations in relation to loops]] and [[http://marcocorvi.altervista.org/caving/tbe/m_04/m_047.htm|importing Survex data (near bottom of page)]], and others who have asked and answered ‘extended’ questions on the [[https://www.mail-archive.com/search?q=extend&l=therion%40speleo.sk|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 ====A Survey Centreline Paradigm==== 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. ====A Drawing Paradigm==== **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. ====An Extended Elevation Paradigm==== 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 [[https://survex.com/docs/manual/extend.htm|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. ====Enumerating extend station sequence==== 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%). ====Summary of all extend options, for survey centrelines==== 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 **** id, a valid survey **** (pair of stations), or in the case of ignore, possibly a three station ****.\\ * For **direction** options, specifying a **** applies the option to ONLY to that leg, and specifying a **** applies the option to the leg(s) used to reach (create) that station, AND all subsequent **** within the centreline (**Control** options ''start'', ''hide'', and ''ignore'' apply only to or at the or specified).\\ * Note that Therion differs from Survex here. Survex applies the **** 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 * You can include multiple caves in the same extended elevation, or [[tips#how_to_export_correct_extended_elevation_from_zig-zag_centerline|straighten out zig-zag surveys]], by way of ''data nosurvey'' legs. ''extend start '' - 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 '' - 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 '' - extend this leg only, to the right, then continue extending subsequent legs, left or right, as per the leg immediately previous.\\ ''extend right '' - generate the leg creating this station to the right and continue generating all subsequent legs towards the right.\\ ''extend left or '' - same as for extend right, but extending left!\\ \\ ''extend normal '' - 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 '' - 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 '' - 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 '' - 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 '' - 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 '' - generate the leg creating this station vertically and continue generating all subsequent legs vertically, without any horizontal component.\\ \\ ''extend <0 – 200> '' - 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> '' - stretch or shrink the leg creating this station by the ratio and continue generating all subsequent legs with that ratio.\\ \\ ''extend ignore '' - where = station1 station2 station3. The map-connection break will occur at station2\\ ''extend ignore '' - 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 of .\\ * 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 '' - where 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 . A bug in this functionality was resolved with Therion version 094ac85 14Nov2019.\\ Try to avoid ''ignore''ing 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 [[breakingextend|Breaking extended elevations on specific stations]]. \\ ''extend hide '' - 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 '' - 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 needs to be enumerated, ie they don’t autogenerate if just a single is specified. Other times, they autogenerate nicely. * Don't miss Martin Sluka's [[tips#how_to_export_correct_extended_elevation_from_zig-zag_centerline|hot tip for obtaining realistic extended centrelines]] from zig-zagged survey data (uses ''data nosurvey'') * 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. ===Creating links between separate caves that are close to each other=== 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 ====Extended elevation scrap drawing considerations==== 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 '' where that 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 [[https://therion.speleo.sk/samples.doc/25.html|Extended elevation control sample]] equate scrap LoopConnectionAB -proj extended point 0 0 station -name -from -visibility off point 100 0 station -name -from -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 ” – 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. ====Extended Elevation Control File Examples==== 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 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