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
Next revisionBoth sides next revision
extend [2019/12/21 09:58] – Difference from Survex with extend <option> station tarquinwjextend [2020/09/07 07:05] – simplify part 4 brucemutton
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**: 
 + 
 +''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>**.\\ 
 +  * 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
  
-  * They must be followed either by a valid survey **<station>** id, or a valid survey **<leg>** (pair of stations).\\ 
-  * Generally specifying a **<leg>** applies the option to ONLY that leg, and specifying a **<station>** applies the option to both the leg used to reach that station, and 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 [[tips#how_to_export_correct_extended_elevation_from_zig-zag_centerline|straighten out zig-zag surveys]], by way of ''data nosurvey'' legs.   * 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.\\ ''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\\ If extent normal is the first statement after extend start, then it will extend to the right.\\+''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.  \\ If extent reverse is the first statement after extend start, then it will extend to the left.\\+''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.
Line 56: Line 82:
 \\ \\
 ''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’.\\
- 
-*Important note:* with ''left'', ''right'', ''normal'', ''reverse'', ''vertical'' and ''hide'', Therion and Pocket Topo both apply the selected options to the leg before the station (in whichever direction Therion is traversing the centreline), as well as the ones following it - that is to say, it applies it to the leg that creates the station. Survex, on the other hand, applies the selected option to all legs after the selected station. This rare difference from Survex is by design. Because of this, and because it helps clarification too, it is a common 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 that station. This also avoids some bugs mentioned above. 
- 
-  extend left 3 4 
-  extend left 4 
- 
-//* 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 [[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'')   * 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'')
Line 96: 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.txt
  • Last modified: 2 months ago
  • by brucemutton