Package org.locationtech.jts.operation.distance3d

Class Distance3DOp

java.lang.Object

org.locationtech.jts.operation.distance3d.Distance3DOp

public class Distance3DOp
extends java.lang.Object

Find two points on two 3D Geometrys which lie within a given distance, or else are the nearest points on the geometries (in which case this also provides the distance between the geometries).

3D geometries have vertex Z ordinates defined. 3D Polygons are assumed to lie in a single plane (which is enforced if not actually the case). 3D LineStrings and Points may have any configuration.

The distance computation also finds a pair of points in the input geometries which have the minimum distance between them. If a point lies in the interior of a line segment, the coordinate computed is a close approximation to the exact point.

The algorithms used are straightforward O(n^2) comparisons. This worst-case performance could be improved on by using Voronoi techniques or spatial indexes.

Version:

1.7

Field Summary

Fields

Modifier and Type	Field	Description
private Geometry[]	geom
private boolean	isDone
private double	minDistance
private GeometryLocation[]	minDistanceLocation
private double	terminateDistance

Constructor Summary

Constructors

Constructor	Description
Distance3DOp(Geometry g0, Geometry g1)	Constructs a DistanceOp that computes the distance and nearest points between the two specified geometries.
Distance3DOp(Geometry g0, Geometry g1, double terminateDistance)	Constructs a DistanceOp that computes the distance and nearest points between the two specified geometries.

Method Summary

Modifier and Type	Method	Description
private void	computeMinDistance()
private void	computeMinDistance(Geometry g0, Geometry g1, boolean flip)
private void	computeMinDistanceLineLine(LineString line0, LineString line1, boolean flip)
private void	computeMinDistanceLinePoint(LineString line, Point point, boolean flip)
private void	computeMinDistanceMultiMulti(Geometry g0, Geometry g1, boolean flip)
private void	computeMinDistanceOneMulti(Geometry g0, Geometry g1, boolean flip)
private void	computeMinDistanceOneMulti(PlanarPolygon3D poly, Geometry geom, boolean flip)
private void	computeMinDistancePointPoint(Point point0, Point point1, boolean flip)
private void	computeMinDistancePolygonLine(PlanarPolygon3D poly, LineString line, boolean flip)
private void	computeMinDistancePolygonPoint(PlanarPolygon3D polyPlane, Point point, boolean flip)
private void	computeMinDistancePolygonPolygon(PlanarPolygon3D poly0, Polygon poly1, boolean flip)	Computes distance between two polygons.
private void	computeMinDistancePolygonRings(PlanarPolygon3D poly, Polygon ringPoly, boolean flip)	Compute distance between a polygon and the rings of another.
double	distance()	Report the distance between the nearest points on the input geometries.
static double	distance(Geometry g0, Geometry g1)	Compute the distance between the nearest points of two geometries.
private Coordinate	intersection(PlanarPolygon3D poly, LineString line)
static boolean	isWithinDistance(Geometry g0, Geometry g1, double distance)	Test whether two geometries lie within a given distance of each other.
private int	mostPolygonalIndex()	Finds the index of the "most polygonal" input geometry.
GeometryLocation[]	nearestLocations()	Report the locations of the nearest points in the input geometries.
Coordinate[]	nearestPoints()	Report the coordinates of the nearest points in the input geometries.
static Coordinate[]	nearestPoints(Geometry g0, Geometry g1)	Compute the the nearest points of two geometries.
private static PlanarPolygon3D	polyPlane(Geometry poly)	Convenience method to create a Plane3DPolygon
private static Coordinate	segmentPoint(Coordinate p0, Coordinate p1, double d0, double d1)	Computes a point at a distance along a segment specified by two relatively proportional values.
private void	updateDistance(double dist, GeometryLocation loc0, GeometryLocation loc1, boolean flip)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

geom

private Geometry[] geom

terminateDistance

private double terminateDistance

minDistanceLocation

private GeometryLocation[] minDistanceLocation

minDistance

private double minDistance

isDone

private boolean isDone

Constructor Detail

Distance3DOp

public Distance3DOp(Geometry g0,
                    Geometry g1)

Constructs a DistanceOp that computes the distance and nearest points between the two specified geometries.

Parameters:

g0 - a Geometry

g1 - a Geometry

Distance3DOp

public Distance3DOp(Geometry g0,
                    Geometry g1,
                    double terminateDistance)

Constructs a DistanceOp that computes the distance and nearest points between the two specified geometries.

Parameters:

g0 - a Geometry

g1 - a Geometry

terminateDistance - the distance on which to terminate the search

Method Detail

distance

public static double distance(Geometry g0,
                              Geometry g1)

Compute the distance between the nearest points of two geometries.

Parameters:

g0 - a Geometry

g1 - another Geometry

Returns:

the distance between the geometries

isWithinDistance

public static boolean isWithinDistance(Geometry g0,
                                       Geometry g1,
                                       double distance)

Test whether two geometries lie within a given distance of each other.

Parameters:

g0 - a Geometry

g1 - another Geometry

distance - the distance to test

Returns:

true if g0.distance(g1) <= distance

nearestPoints

public static Coordinate[] nearestPoints(Geometry g0,
                                         Geometry g1)

Compute the the nearest points of two geometries. The points are presented in the same order as the input Geometries.

Parameters:

g0 - a Geometry

g1 - another Geometry

Returns:

the nearest points in the geometries

distance

public double distance()

Report the distance between the nearest points on the input geometries.

Returns:

the distance between the geometries, or 0 if either input geometry is empty

Throws:

java.lang.IllegalArgumentException - if either input geometry is null

nearestPoints

public Coordinate[] nearestPoints()

Report the coordinates of the nearest points in the input geometries. The points are presented in the same order as the input Geometries.

Returns:

a pair of Coordinates of the nearest points

nearestLocations

public GeometryLocation[] nearestLocations()

Report the locations of the nearest points in the input geometries. The locations are presented in the same order as the input Geometries.

Returns:

a pair of GeometryLocations for the nearest points

updateDistance

private void updateDistance(double dist,
                            GeometryLocation loc0,
                            GeometryLocation loc1,
                            boolean flip)

computeMinDistance

private void computeMinDistance()

mostPolygonalIndex

private int mostPolygonalIndex()

Finds the index of the "most polygonal" input geometry. This optimizes the computation of the best-fit plane, since it is cached only for the left-hand geometry.

Returns:

the index of the most polygonal geometry

computeMinDistanceMultiMulti

private void computeMinDistanceMultiMulti(Geometry g0,
                                          Geometry g1,
                                          boolean flip)

computeMinDistanceOneMulti

private void computeMinDistanceOneMulti(Geometry g0,
                                        Geometry g1,
                                        boolean flip)

computeMinDistanceOneMulti

private void computeMinDistanceOneMulti(PlanarPolygon3D poly,
                                        Geometry geom,
                                        boolean flip)

polyPlane

private static PlanarPolygon3D polyPlane(Geometry poly)

Convenience method to create a Plane3DPolygon

Parameters:

poly -

Returns:

computeMinDistance

private void computeMinDistance(Geometry g0,
                                Geometry g1,
                                boolean flip)

computeMinDistancePolygonPolygon

private void computeMinDistancePolygonPolygon(PlanarPolygon3D poly0,
                                              Polygon poly1,
                                              boolean flip)

Computes distance between two polygons. To compute the distance, compute the distance between the rings of one polygon and the other polygon, and vice-versa. If the polygons intersect, then at least one ring must intersect the other polygon. Note that it is NOT sufficient to test only the shell rings. A counter-example is a "figure-8" polygon A and a simple polygon B at right angles to A, with the ring of B passing through the holes of A. The polygons intersect, but A's shell does not intersect B, and B's shell does not intersect A.

Parameters:

poly0 -

poly1 -

geomIndex -

computeMinDistancePolygonRings

private void computeMinDistancePolygonRings(PlanarPolygon3D poly,
                                            Polygon ringPoly,
                                            boolean flip)

Compute distance between a polygon and the rings of another.

Parameters:

poly -

ringPoly -

geomIndex -

computeMinDistancePolygonLine

private void computeMinDistancePolygonLine(PlanarPolygon3D poly,
                                           LineString line,
                                           boolean flip)

intersection

private Coordinate intersection(PlanarPolygon3D poly,
                                LineString line)

computeMinDistancePolygonPoint

private void computeMinDistancePolygonPoint(PlanarPolygon3D polyPlane,
                                            Point point,
                                            boolean flip)

computeMinDistanceLineLine

private void computeMinDistanceLineLine(LineString line0,
                                        LineString line1,
                                        boolean flip)

computeMinDistanceLinePoint

private void computeMinDistanceLinePoint(LineString line,
                                         Point point,
                                         boolean flip)

computeMinDistancePointPoint

private void computeMinDistancePointPoint(Point point0,
                                          Point point1,
                                          boolean flip)

segmentPoint

private static Coordinate segmentPoint(Coordinate p0,
                                       Coordinate p1,
                                       double d0,
                                       double d1)

Computes a point at a distance along a segment specified by two relatively proportional values. The fractional distance along the segment is d0/(d0+d1).

Parameters:

p0 - start point of the segment

p1 - end point of the segment

d0 - proportional distance from start point to computed point

d1 - proportional distance from computed point to end point

Returns:

the computed point