PlanetModel (Lucene 10.5.0 spatial3d API)
Description: declaration: package: org.apache.lucene.spatial3d.geom, class: PlanetModel

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

  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 Details

  - ### 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 Details

  - ### 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 Details

  - ### 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`