extend

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
extend [2019/01/14 09:25]
brucemutton [Summary of all extend options, for survey centrelines] independent splay control
extend [2020/09/07 07:05] (current)
brucemutton simplify part 4
Line 2: Line 2:
 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.\\ 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 brings some clarity.  It is based on the above posts and my experiences so far, which suggest the current documentation leaves much unsaid. As you will see, there is still some mystery, and what works with one centreline may behave differently in anotherso if you can offer insights or corrections, please post on the forum, or edit this page.  Bruce Mutton April 2018+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 correctedas 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==== ====A Survey Centreline Paradigm====
Line 13: Line 16:
  
 ====An Extended Elevation Paradigm==== ====An Extended Elevation Paradigm====
-Centrelines for **extended elevations**, however, do not fit entirely within either paradigm 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!+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!
  
-Now, Therion development has placed extended elevation control functionality primarily inside centreline commands, and the standard approach is to interleave the extend control with survey distance, bearing and inclinometer readings for each particular survey trip.  In a large cave, this makes it very difficult set up a clear arrangement of extended centrelines, let alone accommodating half a dozen different extended elevations for the same cave.+Initially, Therion development has supported extended elevation control functionality interleaved with the survey data (distance, bearing and inclinometer readingsfor 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. 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 the extended elevation.
  
 ====Summary of all extend options, for survey centrelines==== ====Summary of all extend options, for survey centrelines====
-Descriptions of behaviour when separated out from the survey data, and included in their own separate centreline;\\ +Descriptions of extend options behaviour when separated out from the survey data, and included in their own separate centreline:\\ 
-''Extend'' options include ''start'', ''right'', ''left'', ''normal'', ''reverse'', ''vertical'',  ''ignore'', and ''hide''.+The options can be  divided into those that affect network generation **control** and those that affect **direction**:
  
-  * They must be followed either by a valid survey **<station>** id, or a valid survey **<leg>** (pair of stations).\\ +''Extend'' **control** options include ''start'', ''ignore'', and ''hide''
-  * Generally specifying a **<leg>** applies the option to ONLY that leg, and specifying a **<station>** applies the option to all subsequent **<legs>** within the centreline.  But there is an exception with hide, and perhaps ignore, so read the notes below carefully.\\ + 
-  * You can include multiple caves in the same extended elevation, or [[extend#how_to_export_correct_extended_elevation_from_zig-zag_centerline|straighten out zig-zag surveys]], by way of ''data nosurvey'' legs.+''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>**.\\ 
 +  * Generally specifying a **<leg>** applies the option to ONLY to that leg, and specifying a **<station>** applies the option to both the leg(s) used to reach (create) that station, and all subsequent **<legs>** within the centreline (but this might not apply for ''start'', ''hide'', and perhaps ''ignore'').\\ 
 +  * Note that Therion differs from Survex here.  Survex applies the **<station>** option only 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 <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 <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.\\ ''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 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.  But sometimes it continues generating all legs, as per the next entry below!\\ +''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>'' - continue generating all extended centreline legs from this station onwards, towards the right.  Usually this option will not work as described, unless it is preceded by one or two ''extend right <leg>'' statements.  And sometimes it can appear to extend the wrong way.  If this happens, use ''extend ... <leg>'' rather than ''extend ... <station>''\\+''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 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 [I’m not sure when this is particularly useful!  I tend to be explicit, and use right or left in preference to normal and reverse.]\\ +''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>''continue generating all extended centreline legs from this station onwards, in the same direction as the 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 <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>'' - continue generating all extended centreline legs from this station onwards, in the opposite direction to the 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 <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>'' - continue generating only the vertical components all extended centreline legs from this station onwards.\\+''extend vertical <station>''generate the leg creating this station vertically and continue generating all subsequent legs vertically, without any horizontal component.\\
 \\ \\
-''extend ignore <leg>'' - generation of extended centreline shall not take this leg, it will take the (an)other leg if possible.\\+''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\\ 
 +''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.\\
   * If the leg is 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 the leg is 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.   * 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.\\ 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 leg past a junction in the direction of generation.  The generation of extended centreline shall not take this leg. I have found this syntax unreliableand the following may offer an insight as to why. Marco Corvi says (if I understand correctly) this does not work where there are only three legs meeting at a junction ie the usual case.  So only for use where 4 or more legs meeting at junction(?). +''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 one instead.  The map-connection break will occur at <station>.  A bug in this functionality was resolved with Therion version 094ac85 14Nov2019.\\
-Also do not use this syntax where <station> IS the junction station, obviously that will have unpredictable results. \\+
 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). \\ 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). \\
 <del>''extend break''</del> 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”.\\ <del>''extend break''</del> 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 it’s generation.\\+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.\\
 \\ \\
-//There is a lot about ''extend ignore'' behaviour that I do not understand and cannot explain.  If anyone has insight or explanations for odd behaviourplease amend this page or post on the forum.// \\+For more details of how to use ''extend ignore'', see the article [[breakingextend|Breaking extended elevations on specific stations]]. 
 \\ \\
 ''extend hide <leg>'' - hides the centreline part of the specified leg only, but NOT its stations.  Stations that form the leg remain visible!  Does not hide subsequent stations or legs. \\ ''extend hide <leg>'' - hides the centreline part of the specified leg only, but NOT its stations.  Stations that form the leg remain visible!  Does not hide subsequent stations or legs. \\
-''extend hide <station>'' - hides [the stationandall leg centrelines (usually two of these) that emanate directly from THIS station.  Unlike with other extend options, it does not hide subsequent stations or legs. \\+''extend hide <station>'' - hides the station and all leg centrelines (usually two of these) that emanate directly from THIS station.  It may not hide subsequent stations or legs, something yet to verify. \\
 Note that the centreline generation is carried out as per normal, the stations and legs are just made ‘not visible’.\\ Note that the centreline generation is carried out as per normal, the stations and legs are just made ‘not visible’.\\
- 
-//* Something I don't understand with 'hide' above, stations are sometimes hidden, and sometimes not.// 
  
 ===General Tips=== ===General Tips===
-  * Remember to comment out all extend options in the trip survey files 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+  * 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.
- +
-  * Using this approach, splay shots cannot be controlled (because they have no unique name) independent of the survey legs that they are associated with ie extending a splay left when the legs at that station are extended right.  Somewhat contrary to the above point, it seems that you may be able to extend the splays 'in-line' with the survey data, in a trip survey file, so long as you take care not to try to also control the survey legs+
  
   * 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.   * 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.
-  * Often specifying one <leg> then in the next line specifying a <station> will stimulate the desired autogeneration. 
  
-  * Don't miss Martin Sluka's [[extend#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'')+  * 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'')
  
   * 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, or parts of caves that comprise a linear passage with one or two dead-end branches are easiest to generate extended centrelines for.
Line 91: Line 112:
 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 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 misclosure, 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 \\+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 \\ 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!\\ 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!\\
  
-Now most of 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.\\+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. 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]] The famous [[https://therion.speleo.sk/samples.doc/25.html|Extended elevation control sample]]
  • extend.1547454350.txt.gz
  • Last modified: 21 months ago
  • by brucemutton