26.14 SDO_LRS.FIND_OFFSET

Format

SDO_LRS.FIND_OFFSET(
     geom_segment IN SDO_GEOMETRY, 
     point        IN SDO_GEOMETRY, 
     tolerance    IN NUMBER DEFAULT 1.0e-8 
     ) RETURN NUMBER;

or

SDO_LRS.FIND_OFFSET(
     geom_segment IN SDO_GEOMETRY, 
     dim_array    IN SDO_DIM_ARRAY, 
     point        IN SDO_GEOMETRY 
     [, point_dim_array  IN SDO_GEOMETRY] 
     ) RETURN NUMBER;

Description

Returns the signed offset (shortest distance) from a point to a geometric segment.

Parameters

geom_segment

Geometric segment (LRS segment) containing measure information.

point

Point whose shortest distance from geom_segment is to be returned.

tolerance

Tolerance value (see Tolerance and Tolerance Values with LRS Functions). The default value is 0.00000001.

dim_array

Dimensional information array corresponding to geom_segment, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Geometry Metadata Views).

point_dim_array

Dimensional information array corresponding to point, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Geometry Metadata Views).

Usage Notes

This function calls the SDO_LRS.PROJECT_PT function format that includes the offset output parameter: it passes in the geometric segment and point information, and it returns the SDO_LRS.PROJECT_PT offset parameter value. Thus, to find the offset of a point from a geometric segment, you can use either this function or the SDO_LRS.PROJECT_PT function with the offset parameter.

An exception is raised if geom_segment or point has an invalid geometry type or dimensionality, or if geom_segment and point are based on different coordinate systems.

For more information about offsets to a geometric segment, see Offset.

Examples

The following example returns the offset of point (9,3,NULL) from the geometric segment representing Route 1. (This example uses the definitions from the example in Example of LRS Functions.) As you can see from Example of LRS Functions, the point at (9,3,NULL) is on the right side along the segment, and therefore the offset has a negative value, as explained in Offset. The point at (9,3.NULL) is one distance unit away from the point at (9,4,NULL), which is on the segment.

-- Find the offset of point (9,3,NULL) from the road; should return -1.
SELECT  SDO_LRS.FIND_OFFSET(route_geometry, 
  SDO_GEOMETRY(3301, NULL, NULL, 
     SDO_ELEM_INFO_ARRAY(1, 1, 1), 
     SDO_ORDINATE_ARRAY(9, 3, NULL)) )
  FROM lrs_routes WHERE route_id = 1;

SDO_LRS.FIND_OFFSET(ROUTE_GEOMETRY,SDO_GEOMETRY(3301,NULL,NULL,SDO_ELEM_INFO_ARR
--------------------------------------------------------------------------------
                                                                              -1