Class IndexedFacetDistance


  • public class IndexedFacetDistance
    extends java.lang.Object
    Computes the distance between the facets (segments and vertices) of two Geometrys using a Branch-and-Bound algorithm. The Branch-and-Bound algorithm operates over a traversal of R-trees built on the target and the query geometries.

    This approach provides the following benefits:

    • Performance is dramatically improved due to the use of the R-tree index and the pruning due to the Branch-and-Bound approach
    • The spatial index on the target geometry is cached which allow reuse in an repeated query situation.
    Using this technique is usually much more performant than using the brute-force Geometry.distance(Geometry) when one or both input geometries are large, or when evaluating many distance computations against a single geometry.

    This class is thread-safe.

    Author:
    Martin Davis
    • Constructor Detail

      • IndexedFacetDistance

        public IndexedFacetDistance​(Geometry geom)
        Creates a new distance-finding instance for a given target Geometry.

        Distances will be computed to all facets of the input geometry. The facets of the geometry are the discrete segments and points contained in its components. In the case of Lineal and Puntal inputs, this is equivalent to computing the conventional distance. In the case of Polygonal inputs, this is equivalent to computing the distance to the polygon boundaries.

        Parameters:
        geom - a Geometry, which may be of any type.
    • Method Detail

      • distance

        public static double distance​(Geometry g1,
                                      Geometry g2)
        Computes the distance between facets of two geometries.

        For geometries with many segments or points, this can be faster than using a simple distance algorithm.

        Parameters:
        g1 - a geometry
        g2 - a geometry
        Returns:
        the distance between facets of the geometries
      • isWithinDistance

        public static boolean isWithinDistance​(Geometry g1,
                                               Geometry g2,
                                               double distance)
        Tests whether the facets of two geometries lie within a given distance.
        Parameters:
        g1 - a geometry
        g2 - a geometry
        distance - the distance limit
        Returns:
        true if two facets lie with the given distance
      • nearestPoints

        public static Coordinate[] nearestPoints​(Geometry g1,
                                                 Geometry g2)
        Computes the nearest points of the facets of two geometries.
        Parameters:
        g1 - a geometry
        g2 - a geometry
        Returns:
        the nearest points on the facets of the geometries
      • distance

        public double distance​(Geometry g)
        Computes the distance from the base geometry to the given geometry.
        Parameters:
        g - the geometry to compute the distance to
        Returns:
        the computed distance
      • nearestLocations

        public GeometryLocation[] nearestLocations​(Geometry g)
        Computes the nearest locations on the base geometry and the given geometry.
        Parameters:
        g - the geometry to compute the nearest location to
        Returns:
        the nearest locations
      • nearestPoints

        public Coordinate[] nearestPoints​(Geometry g)
        Compute the nearest locations on the target geometry and the given geometry.
        Parameters:
        g - the geometry to compute the nearest point to
        Returns:
        the nearest points
      • isWithinDistance

        public boolean isWithinDistance​(Geometry g,
                                        double maxDistance)
        Tests whether the base geometry lies within a specified distance of the given geometry.
        Parameters:
        g - the geometry to test
        maxDistance - the maximum distance to test
        Returns:
        true if the geometry lies with the specified distance