STLocateAlong

STLocateAlong — Returns (possibly offset) point geometry at supplied measure along linestring.

Function Specification.

Function [lrs].[STLocateAlong] (
                  @p_linestring geometry,
                  @p_measure    Float,
                  @p_offset     Float = 0.0,
                  @p_round_xy   int   = 3,
                  @p_round_zm   int   = 2
         )
Returns geometry

Description.

This function is identical to STFindPointByName and so is a synonym for it.

Given a measure, this function returns a geometry point at that measure.

If a non-zero/null value is suppied for @p_offset, the found point is offset (perpendicular to line) to the left (if @p_offset < 0) or to the right (if @p_offset > 0).

Computed point’s ordinate values are rounded to @p_round_xy/@p_round_zm decimal digits of precision.

Notes.

Supports LineStrings with CircularString elements.

Parameters.

    @p_linestring (geometry) - Linestring geometry with measures.
    @p_measure       (float) - Measure defining position of point to be located.
    @p_offset        (float) - Offset (distance) value left (negative) or right (positive) in STSrid units.
    @p_round_xy        (int) - Decimal degrees of precision to which calculated XY ordinates are rounded.
    @p_round_zm        (int) - Decimal degrees of precision to which calculated ZM ordinates are rounded.

Result.

The function returns the point at the provided measure optionally offset to left or right.

Example.

with data as (
select geometry::STGeomFromText('LINESTRING(-4 -4 0  1, 0  0 0  5.6, 10  0 0 15.61, 10 10 0 25.4)',0) as linestring
)
Select locateType, 
       sm,em,
       case when f.measureSegment is not null 
            then f.measureSegment.AsTextZM() 
            else null 
        end as measureSegment 
  from (
select 'SM 1.0/EM 1.0 => Start Point' as locateType,1.0 as sm,1.0 as em,  [lrs].[STLocateBetween](linestring,1.0,1.0,0,3,2) as measureSegment from data as a
union all
select 'SM 1.0/EM NULL => Whole Linestring',1.0,null,                     [lrs].[STLocateBetween](linestring,1.0,null,0,3,2) as measureSegment from data as a
union all
select 'SM NULL/EM 1 => Start Point',null,1.0,                            [lrs].[STLocateBetween](linestring,null,1.0,0,3,2) as measureSegment from data as a
union all
select 'SM NULL/EM 5.6 => Return 1s Segment',null,5.6,                    [lrs].[STLocateBetween](linestring,null,5.6,0.0,3,2) as measureSegment from data as a
union all
select 'SM 5.6/EM 5.6 => 1st Segment EP or 2nd SP',5.6,5.6,               [lrs].[STLocateBetween](linestring,5.6,5.6,0,3,2) as measureSegment from data as a
union all
select 'SM 2.0/EM 5.0 Within First Segment => New Segment',2.0,5.0,       [lrs].[STLocateBetween](linestring,2.0,5.0,0,3,2) as measureSegment from data as a
union all
select 'SM 2.0/EM 6.0 => Two New Segments',2.0,6.0,                       [lrs].[STLocateBetween](linestring,2,6,0,3,2) as measureSegment from data as a
union all
select 'SM 1.1/EM 25.4 => New 1st Segment, 2nd, New 3rd Segment',1.1,25.1,[lrs].[STLocateBetween](linestring,1.1,25.1,0,3,2) as measureSegment from data as a
union all
select 'SM 0.1/EM 30.0 => whole linestring',0.1,30.0,                     [lrs].[STLocateBetween](linestring,0.1,30.0,0,3,2) as measureSegment from data as a
) as f;
GO

measure offset fPoint
      1     -1 POINT (-0.707 0.707 NULL 1)
      1      0 POINT (-4 -4 0 1)
      1      1 POINT (0.707 -0.707 NULL 1)
      3     -1 POINT (-3.293 -1.879 NULL 3)
      3      0 POINT (-2.586 -2.586 NULL 3)
      3      1 POINT (-1.879 -3.293 NULL 3)
      5     -1 POINT (-1.879 -0.465 NULL 5)
      5      0 POINT (-1.172 -1.172 NULL 5)
      5      1 POINT (-0.465 -1.879 NULL 5)
      7     -1 POINT (1.4 1 NULL 7)
      7      0 POINT (1.4 0 NULL 7)
      7      1 POINT (1.4 -1 NULL 7)
      9     -1 POINT (3.4 1 NULL 9)
      9      0 POINT (3.4 0 NULL 9)
      9      1 POINT (3.4 -1 NULL 9)
     11     -1 POINT (5.4 1 NULL 11)
     11      0 POINT (5.4 0 NULL 11)
     11      1 POINT (5.4 -1 NULL 11)
     13     -1 POINT (7.4 1 NULL 13)
     13      0 POINT (7.4 0 NULL 13)
     13      1 POINT (7.4 -1 NULL 13)
     15     -1 POINT (9.4 1 NULL 15)
     15      0 POINT (9.4 0 NULL 15)
     15      1 POINT (9.4 -1 NULL 15)
     17     -1 POINT (9 1.39 NULL 17)
     17      0 POINT (10 1.39 NULL 17)
     17      1 POINT (11 1.39 NULL 17)
     19     -1 POINT (9 3.39 NULL 19)
     19      0 POINT (10 3.39 NULL 19)
     19      1 POINT (11 3.39 NULL 19)
     21     -1 POINT (9 5.39 NULL 21)
     21      0 POINT (10 5.39 NULL 21)
     21      1 POINT (11 5.39 NULL 21)
     23     -1 POINT (9 7.39 NULL 23)
     23      0 POINT (10 7.39 NULL 23)
     23      1 POINT (11 7.39 NULL 23)
     25     -1 POINT (9 9.39 NULL 25)
     25      0 POINT (10 9.39 NULL 25)
     25      1 POINT (11 9.39 NULL 25)
      1     -1 POINT (-0.707 0.707 NULL 1)
      1      0 POINT (-4 -4 0 1)
      1      1 POINT (0.707 -0.707 NULL 1)
      2     -1 POINT (-0.707 0.707 NULL 5.6)
      2      0 POINT (0 0 0 5.6)
      2      1 POINT (0.707 -0.707 NULL 5.6)
      3     -1 POINT (10 1 NULL 15.61)
      3      0 POINT (10 0 0 15.61)
      3      1 POINT (10 -1 NULL 15.61)
      4     -1 POINT (9 10 NULL 25.4)
      4      0 POINT (10 10 0 25.4)
      4      1 POINT (11 10 NULL 25.4)