ST_PerpPoints function

The ST_PerpPoints function takes a curve or multicurve and a point as input parameters and returns the perpendicular projection of the given point on the curve or multicurve.

The point with the smallest distance between the given point and the perpendicular point is returned. If two or more such perpendicular projected points are equidistant from the given point, they are all returned. If no perpendicular point can be constructed, then an empty point is returned.

If the given curve or multicurve has Z or M coordinates, the Z or M coordinate of the resulting points are computed by interpolation on the given curve or multicurve.

If the given curve or point is empty, then an empty point is returned. If the given curve or point is null , then null is returned.

This function can also be called as a method.

Syntax

Parameters

curve: A value of type ST_Curve, ST_MultiCurve, or one of their subtypes that represents the curve or multicurve in which the perpendicular projection of the point is returned.
point: A value of type ST_Point that represents the point that is perpendicular projected onto curve.

Return type

db2gse.ST_MultiPoint

Examples

Example 1

This example illustrates the use of the ST_PerpPoints function to find points that are perpendicular to the linestring stored in the following table. The ST_LineString function is used in the INSERT statement to create the linestring.

SET CURRENT FUNCTION PATH=CURRENT FUNCTION PATH, db2gse
CREATE TABLE sample_lines (id INTEGER, line ST_LineString)

INSERT INTO sample_lines (id, line)
  VALUES (1, ST_LineString('linestring (0 10, 0 0, 10 0, 10 10)' , 0) )

Example 2

This example finds the perpendicular projection on the linestring of a point with coordinates (5, 0). The ST_AsText function is used to convert the returned value (a multipoint) to its well-known text representation.

SELECT CAST(ST_AsText(ST_PerpPoints(line,ST_Point(5,0)))
  AS VARCHAR(50)) PERP
  FROM sample_lines

Results:

PERP
----------------------------------------
MULTIPOINT(5.00000000 0.00000000)

Example 3

This example finds the perpendicular projections on the linestring of a point with coordinates (5, 5). In this case, there are three points on the linestring that are equidistant to the given location. Therefore, a multipoint that consists of all three points is returned.

SELECT  CAST(ST_AsText(ST_PerpPoints(line, ST_Point(5,5)))
  AS VARCHAR160)) PERP
  FROM sample_lines

Results:

PERP
--------------------------------------------------------------------------------
MULTIPOINT(0.00000000 5.00000000,5.00000000 0.00000000,10.00000000 5.00000000)

Example 4

This example finds the perpendicular projections on the linestring of a point with coordinates (5, 10). In this case there are three different perpendicular points that can be found. However, the ST_PerpPoints function only returns those points that are closest to the given point. Thus, a multipoint that consists of only the two closest points is returned. The third point is not included.

SELECT CAST(ST_AsText(ST_PerpPoints(line,ST_Point(5, 10)))
  AS VARCHAR(80) ) PERP
  FROM sample_lines

Results:

PERP
------------------------------------------------------------
MULTIPOINT(0.00000000 10.00000000, 10.00000000 10.00000000 )

Example 5

This example finds the perpendicular projection on the linestring of a point with coordinates (5, 15).

SELECT CAST(ST_AsText(ST_PerpPoints(line,ST_Point('point(5 15)',0)))
  AS VARCHAR(80)) PERP
  FROM sample_lines

Results:

PERP
------------------------------------
MULTIPOINT ( 5.00000000 0.00000000 )

Example 6

In this example, the specified point with coordinates (15 15) has no perpendicular projection on the linestring. Therefore, an empty geometry is returned.

SELECT CAST(ST_AsText(ST_PerpPoints(line,ST_Point(15,15)))
  AS VARCHAR(80)) PERP
  FROM sample_lines

Results:

PERP
----------------------------------------------
MULTIPOINT EMPTY