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

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

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

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