Package com.github.micycle1.geoblitz

Class PointDistanceIndex

java.lang.Object
com.github.micycle1.geoblitz.PointDistanceIndex
public class PointDistanceIndex extends Object
Computes distances from query points (Coordinates) to the nearest indexed distance target extracted from one or two input geometries, using a spatial index for fast repeated queries.

Distance targets are extracted as:

  • Linear components (LineStrings), indexed as polyline facets, and
  • Point components (Points), indexed as singleton targets.

The indexed linear items are not individual segments; instead, each LineString is partitioned into contiguous “facets” (polyline chunks) consisting of N coordinates (and therefore N-1 segments). Each facet is inserted into an HPRtree using its envelope, and nearest-facet search is refined by an exact point-to-segment distance computation. This reduces index item count compared to segment-level indexing while keeping good query speed.

Point items are indexed as singleton facets and participate in nearest-distance queries, but do not affect signed-distance classification.

Signed vs unsigned distance

  • If a polygonal boundary is provided and a PointOnGeometryLocator is enabled, distance(Coordinate) returns a signed distance: negative for points in the Location.EXTERIOR of the sign geometry, and positive/zero for Location.INTERIOR/Location.BOUNDARY.
  • unsignedDistance(Coordinate) always returns a non-negative distance.

Inputs

  • boundary: must be Polygonal (Polygon/MultiPolygon) or a LinearRing. Its linear components are used as distance targets (e.g., polygon rings). Additionally, it may be used to determine the sign of distance(Coordinate).
  • obstacles: may be any Geometry. Its linear components (LineStrings) and point components (Points/MultiPoints) are extracted and used as distance targets.
Either boundary or obstacles may be null, but not both.
Author:
Michael Carleton

  • Constructor Summary

    Constructors
    Constructor
    Description
    PointDistanceIndex(org.locationtech.jts.geom.Geometry boundary)
    Constructs an index using only a boundary geometry.
    PointDistanceIndex(org.locationtech.jts.geom.Geometry boundary, org.locationtech.jts.algorithm.locate.PointOnGeometryLocator boundaryLocator, org.locationtech.jts.geom.Geometry obstacles, int facetCoordCount)
    Constructs an index with an explicitly supplied boundary locator.
    PointDistanceIndex(org.locationtech.jts.geom.Geometry boundary, org.locationtech.jts.geom.Geometry obstacles)
    Constructs an index from a boundary and an obstacles geometry.
    PointDistanceIndex(org.locationtech.jts.geom.Geometry boundary, org.locationtech.jts.geom.Geometry obstacles, int facetCoordCount)
    Constructs an index from a boundary and/or obstacles geometry, using an explicit facet size.

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    distance(double x, double y)
    Convenience overload of distance(Coordinate).
    double
    distance(org.locationtech.jts.geom.Coordinate p)
    Returns the (optionally) signed distance from the query coordinate to the nearest indexed linear component.
    double
    unsignedDistance(double x, double y)
    Convenience overload of unsignedDistance(Coordinate).
    double
    unsignedDistance(org.locationtech.jts.geom.Coordinate p)
    Returns the non-negative distance from the query coordinate to the nearest indexed linear component.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • PointDistanceIndex

      public PointDistanceIndex(org.locationtech.jts.geom.Geometry boundary)
      Constructs an index using only a boundary geometry.

      If boundary is non-null, signed distance is enabled using an YStripesPointInAreaLocator. Facet size defaults to 8 coordinates.

      Parameters:
      boundary - polygonal boundary used both as a distance target (via its rings) and to determine the sign of distance(Coordinate)
      Throws:
      IllegalArgumentException - if boundary is non-polygonal

    • PointDistanceIndex

      public PointDistanceIndex(org.locationtech.jts.geom.Geometry boundary, org.locationtech.jts.geom.Geometry obstacles)
      Constructs an index from a boundary and an obstacles geometry.

      If boundary is non-null, signed distance is enabled using an YStripesPointInAreaLocator. Facet size defaults to 8 coordinates.

      Parameters:
      boundary - polygonal boundary used for distance targets and (optionally) sign
      obstacles - any geometry; only linear components are used as distance targets
      Throws:
      IllegalArgumentException - if both inputs are null
      IllegalArgumentException - if boundary is non-polygonal

    • PointDistanceIndex

      public PointDistanceIndex(org.locationtech.jts.geom.Geometry boundary, org.locationtech.jts.geom.Geometry obstacles, int facetCoordCount)
      Constructs an index from a boundary and/or obstacles geometry, using an explicit facet size.

      If boundary is non-null, signed distance is enabled using an YStripesPointInAreaLocator.

      Parameters:
      boundary - polygonal boundary used for distance targets and (optionally) sign
      obstacles - any geometry; only linear components are used as distance targets
      facetCoordCount - number of coordinates per facet (must be >= 2)
      Throws:
      IllegalArgumentException - if both inputs are null
      IllegalArgumentException - if boundary is non-polygonal
      IllegalArgumentException - if facetCoordCount < 2

    • PointDistanceIndex

      public PointDistanceIndex(org.locationtech.jts.geom.Geometry boundary, org.locationtech.jts.algorithm.locate.PointOnGeometryLocator boundaryLocator, org.locationtech.jts.geom.Geometry obstacles, int facetCoordCount)
      Constructs an index with an explicitly supplied boundary locator.

      Passing a null boundaryLocator disables signed distance even if boundary is non-null, causing distance(Coordinate) to behave like unsignedDistance(Coordinate).

      Parameters:
      boundary - polygonal boundary used for distance targets and (optionally) sign
      boundaryLocator - locator used to compute sign; may be null to disable signed distance
      obstacles - any geometry; only linear components are used as distance targets
      facetCoordCount - number of coordinates per facet (must be >= 2)
      Throws:
      IllegalArgumentException - if both inputs are null
      IllegalArgumentException - if boundary is non-polygonal
      IllegalArgumentException - if facetCoordCount < 2

  • Method Details

    • distance

      public double distance(org.locationtech.jts.geom.Coordinate p)
      Returns the (optionally) signed distance from the query coordinate to the nearest indexed linear component.
      • If boundaryLocator is present: negative means the point is outside the boundary.
      • If boundaryLocator is absent: this equals unsignedDistance(Coordinate).
      Parameters:
      p - query coordinate
      Returns:
      signed distance, unsigned distance, or Double.NaN if no facets exist

    • distance

      public double distance(double x, double y)
      Convenience overload of distance(Coordinate).
      Parameters:
      x - query x
      y - query y
      Returns:
      signed distance, unsigned distance, or Double.NaN if no facets exist

    • unsignedDistance

      public double unsignedDistance(org.locationtech.jts.geom.Coordinate p)
      Returns the non-negative distance from the query coordinate to the nearest indexed linear component.

      This method uses the spatial index nearest-neighbour search and then computes the exact distance to segments within the chosen facet.

      Parameters:
      p - query coordinate
      Returns:
      distance >= 0, or Double.NaN if no facets exist

    • unsignedDistance

      public double unsignedDistance(double x, double y)
      Convenience overload of unsignedDistance(Coordinate).
      Parameters:
      x - query x
      y - query y
      Returns:
      distance >= 0, or Double.NaN if no facets exist