SDO_LRS.LOCATE

Format

SDO_LRS.LOCATE_PT(
     geom_segment IN SDO_GEOMETRY, 
     measure      IN NUMBER 
     [, offset    IN NUMBER] 
     ) RETURN SDO_GEOMETRY;

or

SDO_LRS.LOCATE_PT(
     geom_segment IN SDO_GEOMETRY, 
     dim_array    IN SDO_DIM_ARRAY, 
     measure      IN NUMBER 
     [, offset    IN NUMBER] 
     ) RETURN SDO_GEOMETRY;

Description

Returns the point located at a specified distance from the start of a geometric segment.

Parameters

geom_segment: Geometric segment (LRS segment) containing measure information.
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).
measure: Distance to measure from the start point of geom_segment.
offset: Distance to measure perpendicularly from the point that is located at measure units from the start point of geom_segment. The default is 0 (that is, the point is on geom_segment).

Usage Notes

This function returns the referenced point. For example, on a highway, the point might represent the location of an accident.

The unit of measurement for offset is the same as for the coordinate system associated with geom_segment. For geodetic data, the default unit of measurement is meters.

With geodetic data using the WGS 84 coordinate system, this function can be used to return the longitude and latitude coordinates of any point on or offset from the segment.

An exception is raised if geom_segment has an invalid geometry type or dimensionality, or if the location is out of range.

The _3D format of this function (SDO_LRS.LOCATE_PT_3D) is available; however, the offset parameter is not available for SDO_LRS.LOCATE_PT_3D. For information about _3D formats of LRS functions, see 3D Formats of LRS Functions.

For more information about locating a point on a geometric segment, see Locating a Point on a Geometric Segment.

Examples

The following example creates a table for automobile accident data, inserts a record for an accident at the point at measure 9 and on (that is, offset 0) the geometric segment representing Route 1, and displays the data. (The accident table is deliberately oversimplified. This example also uses the route definition from the example in Example of LRS Functions.)

-- Create a table for accidents.
CREATE TABLE accidents (
  accident_id  NUMBER PRIMARY KEY,
  route_id  NUMBER,
  accident_geometry  SDO_GEOMETRY);
 
-- Insert an accident record.
DECLARE
geom_segment SDO_GEOMETRY;
 
BEGIN
 
SELECT  SDO_LRS.LOCATE_PT(a.route_geometry, 9, 0) into geom_segment
  FROM lrs_routes a WHERE a.route_name = 'Route1';
 
INSERT INTO accidents VALUES(1, 1, geom_segment);
 
END;
/
 
SELECT * from accidents;
 
ACCIDENT_ID   ROUTE_ID                                                          
----------- ----------                                                          
ACCIDENT_GEOMETRY(SDO_GTYPE, SDO_SRID, SDO_POINT(X, Y, Z), SDO_ELEM_INFO, SDO_OR
--------------------------------------------------------------------------------
          1          1                                                          
SDO_GEOMETRY(3301, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1, 1), SDO_ORDINATE_ARRAY(
9, 4, 9))