org.apache.lucene.geo3d

## Class Plane

- java.lang.Object
- - org.apache.lucene.geo3d.Vector
  - - org.apache.lucene.geo3d.Plane

- Direct Known Subclasses:
    SidedPlane

      public class Plane
      extends Vector

  We know about three kinds of planes. First kind: general plain through two points and origin Second kind: horizontal plane at specified height. Third kind: vertical plane with specified x and y value, through origin.
  WARNING: This API is experimental and might change in incompatible ways in the next release.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `double` | `D` Ax + By + Cz + D = 0
    `protected static Membership[]` | `NO_BOUNDS` An array with no bounds in it
    `protected static GeoPoint[]` | `NO_POINTS` An array with no points in it
    `protected static Plane` | `normalXPlane` A vertical plane normal to the X axis
    `protected static Plane` | `normalYPlane` A vertical plane normal to the Y axis
    `protected static Plane` | `normalZPlane` A vertical plane normal to the Z axis

    - ### Fields inherited from class org.apache.lucene.geo3d.Vector

      `MINIMUM_RESOLUTION, MINIMUM_RESOLUTION_CUBED, MINIMUM_RESOLUTION_SQUARED, x, y, z`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Plane(double x, double y)` Construct a vertical plane through a specified x, y and origin.
    `Plane(double A, double B, double C, double D)` Construct a plane with all four coefficients defined.
    `Plane(PlanetModel planetModel, double sinLat)` Construct a horizontal plane at a specified Z.
    `Plane(Vector v, double D)` Construct a plane with a specific vector, and D offset from origin.
    `Plane(Vector A, Vector B)` Construct a plane through two points and origin.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected static void` | `addPoint(Bounds boundsInfo, Membership[] bounds, GeoPoint point)` Add a point to boundsInfo if within a specifically bounded area.
    `double` | `arcDistance(PlanetModel planetModel, double x, double y, double z, Membership... bounds)` Compute arc distance from plane to a vector.
    `double` | `arcDistance(PlanetModel planetModel, GeoPoint v, Membership... bounds)` Compute arc distance from plane to a vector expressed with a `GeoPoint`.
    `static Plane` | `constructNormalizedXPlane(double y, double z, double DValue)` Construct a normalized plane through a y-z point and parallel to the X axis.
    `static Plane` | `constructNormalizedXPlane(Vector... planePoints)` Construct the most accurate normalized plane through an y-z point and including the X axis.
    `static Plane` | `constructNormalizedYPlane(double x, double z, double DValue)` Construct a normalized plane through an x-z point and parallel to the Y axis.
    `static Plane` | `constructNormalizedYPlane(Vector... planePoints)` Construct the most accurate normalized plane through an x-z point and including the Y axis.
    `static Plane` | `constructNormalizedZPlane(double x, double y)` Construct a normalized plane through an x-y point and including the Z axis.
    `static Plane` | `constructNormalizedZPlane(Vector... planePoints)` Construct the most accurate normalized plane through an x-y point and including the Z axis.
    `boolean` | `equals(Object o)`
    `double` | `evaluate(double x, double y, double z)` Evaluate the plane equation for a given point, as represented by a vector.
    `double` | `evaluate(Vector v)` Evaluate the plane equation for a given point, as represented by a vector.
    `boolean` | `evaluateIsZero(double x, double y, double z)` Evaluate the plane equation for a given point, as represented by a vector.
    `boolean` | `evaluateIsZero(Vector v)` Evaluate the plane equation for a given point, as represented by a vector.
    `GeoPoint[]` | `findIntersections(PlanetModel planetModel, Plane q, Membership... bounds)` Public version of findIntersections.
    `protected GeoPoint[]` | `findIntersections(PlanetModel planetModel, Plane q, Membership[] bounds, Membership[] moreBounds)` Find the intersection points between two planes, given a set of bounds.
    `GeoPoint` | `getSampleIntersectionPoint(PlanetModel planetModel, Plane q)` Find a sample point on the intersection between two planes and the world.
    `int` | `hashCode()`
    `GeoPoint[]` | `interpolate(GeoPoint start, GeoPoint end, double[] proportions)` Find points on the boundary of the intersection of a plane and the unit sphere, given a starting point, and ending point, and a list of proportions of the arc (e.g.
    `boolean` | `intersects(PlanetModel planetModel, Plane q, GeoPoint[] notablePoints, GeoPoint[] moreNotablePoints, Membership[] bounds, Membership... moreBounds)` Determine whether the plane intersects another plane within the bounds provided.
    `protected boolean` | `isNumericallyIdentical(Plane p)` Returns true if this plane and the other plane are identical within the margin of error.
    `double` | `linearDistance(PlanetModel planetModel, double x, double y, double z, Membership... bounds)` Compute linear distance from plane to a vector.
    `double` | `linearDistance(PlanetModel planetModel, GeoPoint v, Membership... bounds)` Compute linear distance from plane to a vector.
    `double` | `linearDistanceSquared(PlanetModel planetModel, double x, double y, double z, Membership... bounds)` Compute linear distance squared from plane to a vector.
    `double` | `linearDistanceSquared(PlanetModel planetModel, GeoPoint v, Membership... bounds)` Compute linear distance squared from plane to a vector.
    `protected static boolean` | `meetsAllBounds(double x, double y, double z, Membership[] bounds)` Check if a vector meets the provided bounds.
    `protected static boolean` | `meetsAllBounds(double x, double y, double z, Membership[] bounds, Membership[] moreBounds)` Check if a vector meets the provided bounds.
    `protected static boolean` | `meetsAllBounds(Vector p, Membership[] bounds)` Check if a vector meets the provided bounds.
    `protected static boolean` | `meetsAllBounds(Vector p, Membership[] bounds, Membership[] moreBounds)` Check if a vector meets the provided bounds.
    `protected static Vector` | `modify(GeoPoint start, double transX, double transY, double transZ, double sinRA, double cosRA, double sinHA, double cosHA)` Modify a point to produce a vector in translated/rotated space.
    `double` | `normalDistance(double x, double y, double z, Membership... bounds)` Compute normal distance from plane to a vector.
    `double` | `normalDistance(Vector v, Membership... bounds)` Compute normal distance from plane to a vector.
    `double` | `normalDistanceSquared(double x, double y, double z, Membership... bounds)` Compute normal distance squared from plane to a vector.
    `double` | `normalDistanceSquared(Vector v, Membership... bounds)` Compute normal distance squared from plane to a vector.
    `Plane` | `normalize()` Build a normalized plane, so that the vector is normalized.
    `void` | `recordBounds(PlanetModel planetModel, LatLonBounds boundsInfo, Membership... bounds)` Accumulate bounds information for this plane, intersected with the unit sphere.
    `void` | `recordBounds(PlanetModel planetModel, XYZBounds boundsInfo, Membership... bounds)` Accumulate (x,y,z) bounds information for this plane, intersected with the unit sphere.
    `protected static GeoPoint` | `reverseModify(Vector point, double transX, double transY, double transZ, double sinRA, double cosRA, double sinHA, double cosHA)` Reverse modify a point to produce a GeoPoint in normal space.
    `String` | `toString()`

    - ### Methods inherited from class org.apache.lucene.geo3d.Vector

      `computeDesiredEllipsoidMagnitude, computeDesiredEllipsoidMagnitude, dotProduct, dotProduct, isWithin, linearDistance, linearDistance, linearDistanceSquared, linearDistanceSquared, magnitude, magnitude, normalDistance, normalDistance, normalDistanceSquared, normalDistanceSquared, rotateXY, rotateXY, rotateXZ, rotateXZ, rotateZY, rotateZY, translate`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### NO_POINTS

          protected static final GeoPoint[] NO_POINTS

      An array with no points in it

    - #### NO_BOUNDS

          protected static final Membership[] NO_BOUNDS

      An array with no bounds in it

    - #### normalYPlane

          protected static final Plane normalYPlane

      A vertical plane normal to the Y axis

    - #### normalXPlane

          protected static final Plane normalXPlane

      A vertical plane normal to the X axis

    - #### normalZPlane

          protected static final Plane normalZPlane

      A vertical plane normal to the Z axis

    - #### D

          public final double D

      Ax + By + Cz + D = 0

  - ### Constructor Detail

    - #### Plane

          public Plane(double A,
               double B,
               double C,
               double D)

      Construct a plane with all four coefficients defined.
      Parameters:
        `A` - is A
        `B` - is B
        `C` - is C
        `D` - is D

    - #### Plane

          public Plane(Vector A,
               Vector B)

      Construct a plane through two points and origin.
      Parameters:
        `A` - is the first point (origin based).
        `B` - is the second point (origin based).

    - #### Plane

          public Plane(PlanetModel planetModel,
               double sinLat)

      Construct a horizontal plane at a specified Z.
      Parameters:
        `planetModel` - is the planet model.
        `sinLat` - is the sin(latitude).

    - #### Plane

          public Plane(double x,
               double y)

      Construct a vertical plane through a specified x, y and origin.
      Parameters:
        `x` - is the specified x value.
        `y` - is the specified y value.

    - #### Plane

          public Plane(Vector v,
               double D)

      Construct a plane with a specific vector, and D offset from origin.
      Parameters:
        `v` - is the normal vector.
        `D` - is the D offset from the origin.

  - ### Method Detail

    - #### constructNormalizedZPlane

          public static Plane constructNormalizedZPlane(Vector... planePoints)

      Construct the most accurate normalized plane through an x-y point and including the Z axis. If none of the points can determine the plane, return null.
      Parameters:
        `planePoints` - is a set of points to choose from. The best one for constructing the most precise plane is picked.
      Returns:
        the plane

    - #### constructNormalizedYPlane

          public static Plane constructNormalizedYPlane(Vector... planePoints)

      Construct the most accurate normalized plane through an x-z point and including the Y axis. If none of the points can determine the plane, return null.
      Parameters:
        `planePoints` - is a set of points to choose from. The best one for constructing the most precise plane is picked.
      Returns:
        the plane

    - #### constructNormalizedXPlane

          public static Plane constructNormalizedXPlane(Vector... planePoints)

      Construct the most accurate normalized plane through an y-z point and including the X axis. If none of the points can determine the plane, return null.
      Parameters:
        `planePoints` - is a set of points to choose from. The best one for constructing the most precise plane is picked.
      Returns:
        the plane

    - #### constructNormalizedZPlane

          public static Plane constructNormalizedZPlane(double x,
                                        double y)

      Construct a normalized plane through an x-y point and including the Z axis. If the x-y point is at (0,0), return null.
      Parameters:
        `x` - is the x value.
        `y` - is the y value.
      Returns:
        a plane passing through the Z axis and (x,y,0).

    - #### constructNormalizedYPlane

          public static Plane constructNormalizedYPlane(double x,
                                        double z,
                                        double DValue)

      Construct a normalized plane through an x-z point and parallel to the Y axis. If the x-z point is at (0,0), return null.
      Parameters:
        `x` - is the x value.
        `z` - is the z value.
        `DValue` - is the offset from the origin for the plane.
      Returns:
        a plane parallel to the Y axis and perpendicular to the x and z values given.

    - #### constructNormalizedXPlane

          public static Plane constructNormalizedXPlane(double y,
                                        double z,
                                        double DValue)

      Construct a normalized plane through a y-z point and parallel to the X axis. If the y-z point is at (0,0), return null.
      Parameters:
        `y` - is the y value.
        `z` - is the z value.
        `DValue` - is the offset from the origin for the plane.
      Returns:
        a plane parallel to the X axis and perpendicular to the y and z values given.

    - #### evaluate

          public double evaluate(Vector v)

      Evaluate the plane equation for a given point, as represented by a vector.
      Parameters:
        `v` - is the vector.
      Returns:
        the result of the evaluation.

    - #### evaluate

          public double evaluate(double x,
                        double y,
                        double z)

      Evaluate the plane equation for a given point, as represented by a vector.
      Parameters:
        `x` - is the x value.
        `y` - is the y value.
        `z` - is the z value.
      Returns:
        the result of the evaluation.

    - #### evaluateIsZero

          public boolean evaluateIsZero(Vector v)

      Evaluate the plane equation for a given point, as represented by a vector.
      Parameters:
        `v` - is the vector.
      Returns:
        true if the result is on the plane.

    - #### evaluateIsZero

          public boolean evaluateIsZero(double x,
                               double y,
                               double z)

      Evaluate the plane equation for a given point, as represented by a vector.
      Parameters:
        `x` - is the x value.
        `y` - is the y value.
        `z` - is the z value.
      Returns:
        true if the result is on the plane.

    - #### normalize

          public Plane normalize()

      Build a normalized plane, so that the vector is normalized.
      Overrides:
        `normalize` in class `Vector`
      Returns:
        the normalized plane object, or null if the plane is indeterminate.

    - #### arcDistance

          public double arcDistance(PlanetModel planetModel,
                           GeoPoint v,
                           Membership... bounds)

      Compute arc distance from plane to a vector expressed with a `GeoPoint`.
      See Also:
        `arcDistance(PlanetModel, double, double, double, Membership...)`

    - #### arcDistance

          public double arcDistance(PlanetModel planetModel,
                           double x,
                           double y,
                           double z,
                           Membership... bounds)

      Compute arc distance from plane to a vector.
      Parameters:
        `planetModel` - is the planet model.
        `x` - is the x vector value.
        `y` - is the y vector value.
        `z` - is the z vector value.
        `bounds` - are the bounds which constrain the intersection point.
      Returns:
        the arc distance.

    - #### normalDistance

          public double normalDistance(Vector v,
                              Membership... bounds)

      Compute normal distance from plane to a vector.
      Parameters:
        `v` - is the vector.
        `bounds` - are the bounds which constrain the intersection point.
      Returns:
        the normal distance.

    - #### normalDistance

          public double normalDistance(double x,
                              double y,
                              double z,
                              Membership... bounds)

      Compute normal distance from plane to a vector.
      Parameters:
        `x` - is the vector x.
        `y` - is the vector y.
        `z` - is the vector z.
        `bounds` - are the bounds which constrain the intersection point.
      Returns:
        the normal distance.

    - #### normalDistanceSquared

          public double normalDistanceSquared(Vector v,
                                     Membership... bounds)

      Compute normal distance squared from plane to a vector.
      Parameters:
        `v` - is the vector.
        `bounds` - are the bounds which constrain the intersection point.
      Returns:
        the normal distance squared.

    - #### normalDistanceSquared

          public double normalDistanceSquared(double x,
                                     double y,
                                     double z,
                                     Membership... bounds)

      Compute normal distance squared from plane to a vector.
      Parameters:
        `x` - is the vector x.
        `y` - is the vector y.
        `z` - is the vector z.
        `bounds` - are the bounds which constrain the intersection point.
      Returns:
        the normal distance squared.

    - #### linearDistance

          public double linearDistance(PlanetModel planetModel,
                              GeoPoint v,
                              Membership... bounds)

      Compute linear distance from plane to a vector. This is defined as the distance from the given point to the nearest intersection of this plane with the planet surface.
      Parameters:
        `planetModel` - is the planet model.
        `v` - is the point.
        `bounds` - are the bounds which constrain the intersection point.
      Returns:
        the linear distance.

    - #### linearDistance

          public double linearDistance(PlanetModel planetModel,
                              double x,
                              double y,
                              double z,
                              Membership... bounds)

      Compute linear distance from plane to a vector. This is defined as the distance from the given point to the nearest intersection of this plane with the planet surface.
      Parameters:
        `planetModel` - is the planet model.
        `x` - is the vector x.
        `y` - is the vector y.
        `z` - is the vector z.
        `bounds` - are the bounds which constrain the intersection point.
      Returns:
        the linear distance.

    - #### linearDistanceSquared

          public double linearDistanceSquared(PlanetModel planetModel,
                                     GeoPoint v,
                                     Membership... bounds)

      Compute linear distance squared from plane to a vector. This is defined as the distance from the given point to the nearest intersection of this plane with the planet surface.
      Parameters:
        `planetModel` - is the planet model.
        `v` - is the point.
        `bounds` - are the bounds which constrain the intersection point.
      Returns:
        the linear distance squared.

    - #### linearDistanceSquared

          public double linearDistanceSquared(PlanetModel planetModel,
                                     double x,
                                     double y,
                                     double z,
                                     Membership... bounds)

      Compute linear distance squared from plane to a vector. This is defined as the distance from the given point to the nearest intersection of this plane with the planet surface.
      Parameters:
        `planetModel` - is the planet model.
        `x` - is the vector x.
        `y` - is the vector y.
        `z` - is the vector z.
        `bounds` - are the bounds which constrain the intersection point.
      Returns:
        the linear distance squared.

    - #### interpolate

          public GeoPoint[] interpolate(GeoPoint start,
                               GeoPoint end,
                               double[] proportions)

      Find points on the boundary of the intersection of a plane and the unit sphere, given a starting point, and ending point, and a list of proportions of the arc (e.g. 0.25, 0.5, 0.75). The angle between the starting point and ending point is assumed to be less than pi.
      Parameters:
        `start` - is the start point.
        `end` - is the end point.
        `proportions` - is an array of fractional proportions measured between start and end.
      Returns:
        an array of points corresponding to the proportions passed in.

    - #### modify

          protected static Vector modify(GeoPoint start,
                      double transX,
                      double transY,
                      double transZ,
                      double sinRA,
                      double cosRA,
                      double sinHA,
                      double cosHA)

      Modify a point to produce a vector in translated/rotated space.
      Parameters:
        `start` - is the start point.
        `transX` - is the translation x value.
        `transY` - is the translation y value.
        `transZ` - is the translation z value.
        `sinRA` - is the sine of the ascension angle.
        `cosRA` - is the cosine of the ascension angle.
        `sinHA` - is the sine of the height angle.
        `cosHA` - is the cosine of the height angle.
      Returns:
        the modified point.

    - #### reverseModify

          protected static GeoPoint reverseModify(Vector point,
                               double transX,
                               double transY,
                               double transZ,
                               double sinRA,
                               double cosRA,
                               double sinHA,
                               double cosHA)

      Reverse modify a point to produce a GeoPoint in normal space.
      Parameters:
        `point` - is the translated point.
        `transX` - is the translation x value.
        `transY` - is the translation y value.
        `transZ` - is the translation z value.
        `sinRA` - is the sine of the ascension angle.
        `cosRA` - is the cosine of the ascension angle.
        `sinHA` - is the sine of the height angle.
        `cosHA` - is the cosine of the height angle.
      Returns:
        the original point.

    - #### findIntersections

          public GeoPoint[] findIntersections(PlanetModel planetModel,
                                     Plane q,
                                     Membership... bounds)

      Public version of findIntersections.
      Parameters:
        `planetModel` - is the planet model.
        `q` - is the plane to intersect with.
        `bounds` - are the bounds to consider to determine legal intersection points.
      Returns:
        the set of legal intersection points.

    - #### findIntersections

          protected GeoPoint[] findIntersections(PlanetModel planetModel,
                                     Plane q,
                                     Membership[] bounds,
                                     Membership[] moreBounds)

      Find the intersection points between two planes, given a set of bounds.
      Parameters:
        `planetModel` - is the planet model to use in finding points.
        `q` - is the plane to intersect with.
        `bounds` - is the set of bounds.
        `moreBounds` - is another set of bounds.
      Returns:
        the intersection point(s) on the unit sphere, if there are any.

    - #### recordBounds

          public void recordBounds(PlanetModel planetModel,
                          XYZBounds boundsInfo,
                          Membership... bounds)

      Accumulate (x,y,z) bounds information for this plane, intersected with the unit sphere. Updates min/max information, using max/min points found within the specified bounds.
      Parameters:
        `planetModel` - is the planet model to use in determining bounds.
        `boundsInfo` - is the xyz info to update with additional bounding information.
        `bounds` - are the surfaces delineating what's inside the shape.

    - #### recordBounds

          public void recordBounds(PlanetModel planetModel,
                          LatLonBounds boundsInfo,
                          Membership... bounds)

      Accumulate bounds information for this plane, intersected with the unit sphere. Updates both latitude and longitude information, using max/min points found within the specified bounds.
      Parameters:
        `planetModel` - is the planet model to use in determining bounds.
        `boundsInfo` - is the lat/lon info to update with additional bounding information.
        `bounds` - are the surfaces delineating what's inside the shape.

    - #### addPoint

          protected static void addPoint(Bounds boundsInfo,
                      Membership[] bounds,
                      GeoPoint point)

      Add a point to boundsInfo if within a specifically bounded area.
      Parameters:
        `boundsInfo` - is the object to be modified.
        `bounds` - is the area that the point must be within.
        `point` - is the point.

    - #### intersects

          public boolean intersects(PlanetModel planetModel,
                           Plane q,
                           GeoPoint[] notablePoints,
                           GeoPoint[] moreNotablePoints,
                           Membership[] bounds,
                           Membership... moreBounds)

      Determine whether the plane intersects another plane within the bounds provided.
      Parameters:
        `planetModel` - is the planet model to use in determining intersection.
        `q` - is the other plane.
        `notablePoints` - are points to look at to disambiguate cases when the two planes are identical.
        `moreNotablePoints` - are additional points to look at to disambiguate cases when the two planes are identical.
        `bounds` - is one part of the bounds.
        `moreBounds` - are more bounds.
      Returns:
        true if there's an intersection.

    - #### isNumericallyIdentical

          protected boolean isNumericallyIdentical(Plane p)

      Returns true if this plane and the other plane are identical within the margin of error.
      Parameters:
        `p` - is the plane to compare against.
      Returns:
        true if the planes are numerically identical.

    - #### meetsAllBounds

          protected static boolean meetsAllBounds(Vector p,
                               Membership[] bounds)

      Check if a vector meets the provided bounds.
      Parameters:
        `p` - is the vector.
        `bounds` - are the bounds.
      Returns:
        true if the vector describes a point within the bounds.

    - #### meetsAllBounds

          protected static boolean meetsAllBounds(double x,
                               double y,
                               double z,
                               Membership[] bounds)

      Check if a vector meets the provided bounds.
      Parameters:
        `x` - is the x value.
        `y` - is the y value.
        `z` - is the z value.
        `bounds` - are the bounds.
      Returns:
        true if the vector describes a point within the bounds.

    - #### meetsAllBounds

          protected static boolean meetsAllBounds(Vector p,
                               Membership[] bounds,
                               Membership[] moreBounds)

      Check if a vector meets the provided bounds.
      Parameters:
        `p` - is the vector.
        `bounds` - are the bounds.
        `moreBounds` - are an additional set of bounds.
      Returns:
        true if the vector describes a point within the bounds.

    - #### meetsAllBounds

          protected static boolean meetsAllBounds(double x,
                               double y,
                               double z,
                               Membership[] bounds,
                               Membership[] moreBounds)

      Check if a vector meets the provided bounds.
      Parameters:
        `x` - is the x value.
        `y` - is the y value.
        `z` - is the z value.
        `bounds` - are the bounds.
        `moreBounds` - are an additional set of bounds.
      Returns:
        true if the vector describes a point within the bounds.

    - #### getSampleIntersectionPoint

          public GeoPoint getSampleIntersectionPoint(PlanetModel planetModel,
                                            Plane q)

      Find a sample point on the intersection between two planes and the world.
      Parameters:
        `planetModel` - is the planet model.
        `q` - is the second plane to consider.
      Returns:
        a sample point that is on the intersection between the two planes and the world.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Vector`

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Vector`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Vector`

Copyright © 2000-2017 Apache Software Foundation. All Rights Reserved.