Package org.apache.lucene.spatial3d.geom

## Class PlanetModel

- java.lang.Object
- - org.apache.lucene.spatial3d.geom.PlanetModel

- All Implemented Interfaces:
    `SerializableObject`

      public class PlanetModel
      extends Object
      implements SerializableObject

  Holds mathematical constants associated with the model of a planet.
  WARNING: This API is experimental and might change in incompatible ways in the next release.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `PlanetModel.DocValueEncoder` | Utility class for encoding / decoding from lat/lon (decimal degrees) into sortable doc value numerics (integers)

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `double` | `a` | Semi-major axis
    `double` | `b` | Semi-minor axis
    `static PlanetModel` | `CLARKE_1866` | Planet model corresponding to Clarke 1866 ellipsoid
    `double` | `DECODE` | scalar value used to decode from integer back into double space
    `PlanetModel.DocValueEncoder` | `docValueEncoder` | utility class used to encode/decode from lat/lon (decimal degrees) into doc value integers
    `double` | `inverseScale` | The inverse of scale
    `double` | `inverseXYScaling` | The inverse of xyScaling
    `double` | `inverseXYScalingSquared` | The square of the inverse of xyScaling
    `double` | `inverseZScaling` | The inverse of zScaling
    `double` | `inverseZScalingSquared` | The square of the inverse of zScaling
    `int` | `MAX_ENCODED_VALUE` | Max encoded value
    `double` | `MAX_VALUE` | maximum magnitude value for *this* planet model
    `GeoPoint` | `MAX_X_POLE` | Max X pole
    `GeoPoint` | `MAX_Y_POLE` | Max Y pole
    `double` | `meanRadius` | The mean radius of the planet
    `int` | `MIN_ENCODED_VALUE` | Min encoded value
    `GeoPoint` | `MIN_X_POLE` | Min X pole
    `GeoPoint` | `MIN_Y_POLE` | Min Y pole
    `double` | `minimumPoleDistance` | Minimum surface distance between poles
    `GeoPoint` | `NORTH_POLE` | North pole
    `double` | `scale` | The scale of the planet
    `double` | `scaledFlattening` | The scaled flattening value
    `GeoPoint` | `SOUTH_POLE` | South pole
    `static PlanetModel` | `SPHERE` | Planet model corresponding to sphere.
    `double` | `squareRatio` | The square ratio
    `static PlanetModel` | `WGS84` | Planet model corresponding to WGS84 ellipsoid
    `double` | `xyScaling` | The x/y scaling factor
    `double` | `zScaling` | The z scaling factor

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `PlanetModel​(double semiMajorAxis, double semiMinorAxis)` | * Construct a Planet Model from the semi major axis, semi minor axis=.
    `PlanetModel​(InputStream inputStream)` | Deserialization constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `GeoPoint` | `bisection​(GeoPoint pt1, GeoPoint pt2)` | Compute a GeoPoint that's a bisection between two other GeoPoints.
    `GeoPoint` | `createSurfacePoint​(double x, double y, double z)` | Compute a GeoPoint that's based on (x,y,z) values, but is scaled to actually be on the planet surface.
    `GeoPoint` | `createSurfacePoint​(Vector vector)` | Compute a GeoPoint that's scaled to actually be on the planet surface.
    `double` | `decodeValue​(int x)` | Decodes a given integer back into the radian value according to the defined planet model
    `int` | `encodeValue​(double x)` | encode the provided value from double to integer space
    `boolean` | `equals​(Object o)` |
    `PlanetModel.DocValueEncoder` | `getDocValueEncoder()` | return reference to the DocValueEncoder used to encode/decode Geo3DDocValues
    `double` | `getMaximumMagnitude()` | Find the maximum magnitude of all points on the ellipsoid.
    `double` | `getMaximumXValue()` | Find the maximum x value.
    `double` | `getMaximumYValue()` | Find the maximum y value.
    `double` | `getMaximumZValue()` | Find the maximum z value.
    `double` | `getMeanRadius()` | return the calculated mean radius (in units provided by ab and c)
    `double` | `getMinimumMagnitude()` | Find the minimum magnitude of all points on the ellipsoid.
    `double` | `getMinimumXValue()` | Find the minimum x value.
    `double` | `getMinimumYValue()` | Find the minimum y value.
    `double` | `getMinimumZValue()` | Find the minimum z value.
    `int` | `hashCode()` |
    `boolean` | `isSphere()` | Does this planet model describe a sphere?
    `boolean` | `pointOnSurface​(double x, double y, double z)` | Check if point is on surface.
    `boolean` | `pointOnSurface​(Vector v)` | Check if point is on surface.
    `boolean` | `pointOutside​(double x, double y, double z)` | Check if point is outside surface.
    `boolean` | `pointOutside​(Vector v)` | Check if point is outside surface.
    `double` | `surfaceDistance​(GeoPoint pt1, GeoPoint pt2)` | Compute surface distance between two points.
    `GeoPoint` | `surfacePointOnBearing​(GeoPoint from, double dist, double bearing)` | Compute new point given original point, a bearing direction, and an adjusted angle (as would be computed by the surfaceDistance() method above).
    `String` | `toString()` |
    `void` | `write​(OutputStream outputStream)` | Serialize to output stream.

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

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

- - ### Field Detail

    - #### SPHERE

          public static final PlanetModel SPHERE

      Planet model corresponding to sphere.

    - #### WGS84

          public static final PlanetModel WGS84

      Planet model corresponding to WGS84 ellipsoid

    - #### CLARKE_1866

          public static final PlanetModel CLARKE_1866

      Planet model corresponding to Clarke 1866 ellipsoid

    - #### a

          public final double a

      Semi-major axis

    - #### b

          public final double b

      Semi-minor axis

    - #### xyScaling

          public final double xyScaling

      The x/y scaling factor

    - #### zScaling

          public final double zScaling

      The z scaling factor

    - #### inverseXYScaling

          public final double inverseXYScaling

      The inverse of xyScaling

    - #### inverseZScaling

          public final double inverseZScaling

      The inverse of zScaling

    - #### inverseXYScalingSquared

          public final double inverseXYScalingSquared

      The square of the inverse of xyScaling

    - #### inverseZScalingSquared

          public final double inverseZScalingSquared

      The square of the inverse of zScaling

    - #### scaledFlattening

          public final double scaledFlattening

      The scaled flattening value

    - #### squareRatio

          public final double squareRatio

      The square ratio

    - #### meanRadius

          public final double meanRadius

      The mean radius of the planet

    - #### scale

          public final double scale

      The scale of the planet

    - #### inverseScale

          public final double inverseScale

      The inverse of scale

    - #### NORTH_POLE

          public final GeoPoint NORTH_POLE

      North pole

    - #### SOUTH_POLE

          public final GeoPoint SOUTH_POLE

      South pole

    - #### MIN_X_POLE

          public final GeoPoint MIN_X_POLE

      Min X pole

    - #### MAX_X_POLE

          public final GeoPoint MAX_X_POLE

      Max X pole

    - #### MIN_Y_POLE

          public final GeoPoint MIN_Y_POLE

      Min Y pole

    - #### MAX_Y_POLE

          public final GeoPoint MAX_Y_POLE

      Max Y pole

    - #### minimumPoleDistance

          public final double minimumPoleDistance

      Minimum surface distance between poles

    - #### MAX_VALUE

          public final double MAX_VALUE

      maximum magnitude value for *this* planet model

    - #### DECODE

          public final double DECODE

      scalar value used to decode from integer back into double space

    - #### MAX_ENCODED_VALUE

          public final int MAX_ENCODED_VALUE

      Max encoded value

    - #### MIN_ENCODED_VALUE

          public final int MIN_ENCODED_VALUE

      Min encoded value

    - #### docValueEncoder

          public final PlanetModel.DocValueEncoder docValueEncoder

      utility class used to encode/decode from lat/lon (decimal degrees) into doc value integers

  - ### Constructor Detail

    - #### PlanetModel

          public PlanetModel​(double semiMajorAxis,
                             double semiMinorAxis)

      * Construct a Planet Model from the semi major axis, semi minor axis=.
      Parameters:
        `semiMajorAxis` - is the semi major axis (in meters) defined as 'a' in projection formulae.
        `semiMinorAxis` - is the semi minor axis (in meters) defined as 'b' in projection formulae.

    - #### PlanetModel

          public PlanetModel​(InputStream inputStream)
                      throws IOException

      Deserialization constructor.
      Parameters:
        `inputStream` - is the input stream.
      Throws:
        `IOException`

  - ### Method Detail

    - #### write

          public void write​(OutputStream outputStream)
                     throws IOException

      Description copied from interface: `SerializableObject`
      Serialize to output stream.
      Specified by:
        `write` in interface `SerializableObject`
      Parameters:
        `outputStream` - is the output stream to write to.
      Throws:
        `IOException`

    - #### isSphere

          public boolean isSphere()

      Does this planet model describe a sphere?
      Returns:
        true if so.

    - #### getMinimumMagnitude

          public double getMinimumMagnitude()

      Find the minimum magnitude of all points on the ellipsoid.
      Returns:
        the minimum magnitude for the planet.

    - #### getMaximumMagnitude

          public double getMaximumMagnitude()

      Find the maximum magnitude of all points on the ellipsoid.
      Returns:
        the maximum magnitude for the planet.

    - #### getMinimumXValue

          public double getMinimumXValue()

      Find the minimum x value.
      Returns:
        the minimum X value.

    - #### getMaximumXValue

          public double getMaximumXValue()

      Find the maximum x value.
      Returns:
        the maximum X value.

    - #### getMinimumYValue

          public double getMinimumYValue()

      Find the minimum y value.
      Returns:
        the minimum Y value.

    - #### getMaximumYValue

          public double getMaximumYValue()

      Find the maximum y value.
      Returns:
        the maximum Y value.

    - #### getMinimumZValue

          public double getMinimumZValue()

      Find the minimum z value.
      Returns:
        the minimum Z value.

    - #### getMaximumZValue

          public double getMaximumZValue()

      Find the maximum z value.
      Returns:
        the maximum Z value.

    - #### getMeanRadius

          public double getMeanRadius()

      return the calculated mean radius (in units provided by ab and c)

    - #### encodeValue

          public int encodeValue​(double x)

      encode the provided value from double to integer space

    - #### decodeValue

          public double decodeValue​(int x)

      Decodes a given integer back into the radian value according to the defined planet model

    - #### getDocValueEncoder

          public PlanetModel.DocValueEncoder getDocValueEncoder()

      return reference to the DocValueEncoder used to encode/decode Geo3DDocValues

    - #### pointOnSurface

          public boolean pointOnSurface​(Vector v)

      Check if point is on surface.
      Parameters:
        `v` - is the point to check.
      Returns:
        true if the point is on the planet surface.

    - #### pointOnSurface

          public boolean pointOnSurface​(double x,
                                        double y,
                                        double z)

      Check if point is on surface.
      Parameters:
        `x` - is the x coord.
        `y` - is the y coord.
        `z` - is the z coord.

    - #### pointOutside

          public boolean pointOutside​(Vector v)

      Check if point is outside surface.
      Parameters:
        `v` - is the point to check.
      Returns:
        true if the point is outside the planet surface.

    - #### pointOutside

          public boolean pointOutside​(double x,
                                      double y,
                                      double z)

      Check if point is outside surface.
      Parameters:
        `x` - is the x coord.
        `y` - is the y coord.
        `z` - is the z coord.

    - #### createSurfacePoint

          public GeoPoint createSurfacePoint​(Vector vector)

      Compute a GeoPoint that's scaled to actually be on the planet surface.
      Parameters:
        `vector` - is the vector.
      Returns:
        the scaled point.

    - #### createSurfacePoint

          public GeoPoint createSurfacePoint​(double x,
                                             double y,
                                             double z)

      Compute a GeoPoint that's based on (x,y,z) values, but is scaled to actually be on the planet surface.
      Parameters:
        `x` - is the x value.
        `y` - is the y value.
        `z` - is the z value.
      Returns:
        the scaled point.

    - #### bisection

          public GeoPoint bisection​(GeoPoint pt1,
                                    GeoPoint pt2)

      Compute a GeoPoint that's a bisection between two other GeoPoints.
      Parameters:
        `pt1` - is the first point.
        `pt2` - is the second point.
      Returns:
        the bisection point, or null if a unique one cannot be found.

    - #### surfaceDistance

          public double surfaceDistance​(GeoPoint pt1,
                                        GeoPoint pt2)

      Compute surface distance between two points.
      Parameters:
        `pt1` - is the first point.
        `pt2` - is the second point.
      Returns:
        the adjusted angle, when multiplied by the mean earth radius, yields a surface distance. This will differ from GeoPoint.arcDistance() only when the planet model is not a sphere. @see `GeoPoint.arcDistance(Vector)`

    - #### surfacePointOnBearing

          public GeoPoint surfacePointOnBearing​(GeoPoint from,
                                                double dist,
                                                double bearing)

      Compute new point given original point, a bearing direction, and an adjusted angle (as would be computed by the surfaceDistance() method above). The original point can be anywhere on the globe. The bearing direction ranges from 0 (due east at the equator) to pi/2 (due north) to pi (due west at the equator) to 3 pi/4 (due south) to 2 pi.
      Parameters:
        `from` - is the starting point.
        `dist` - is the adjusted angle.
        `bearing` - is the direction to proceed.
      Returns:
        the new point, consistent with the bearing direction and distance.

    - #### equals

          public boolean equals​(Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`