org.geotoolkit.referencing.datum
Class DefaultEllipsoid

Object
  FormattableObject
      AbstractIdentifiedObject
          DefaultEllipsoid

All Implemented Interfaces:

Serializable, Formattable, LenientComparable, Ellipsoid, IdentifiedObject

@Immutable
public class DefaultEllipsoid
extends AbstractIdentifiedObject
implements Ellipsoid

Geometric figure that can be used to describe the approximate shape of the earth. In mathematical terms, it is a surface formed by the rotation of an ellipse about its minor axis. An ellipsoid requires two defining parameters:

• semi-major axis and inverse flattening, or
• semi-major axis and semi-minor axis.

Since:

1.2

Version:

3.19

Author:

Martin Desruisseaux (IRD, Geomatys), Cédric Briançon (Geomatys)

See Also:

Serialized Form

Module:

referencing/geotk-referencing (download)

View source code for this class

Field Summary

static DefaultEllipsoid	CLARKE_1866 Clarke 1866 ellipsoid (EPSG:7008).
static DefaultEllipsoid	GRS80 GRS 1980 ellipsoid (EPSG:7019), also called "International 1979".
static DefaultEllipsoid	INTERNATIONAL_1924 International 1924 ellipsoid (EPSG:7022).
static DefaultEllipsoid	SPHERE A sphere with a radius of 6371000 metres.
static DefaultEllipsoid	WGS72 WGS 1972 ellipsoid (EPSG:7043).
static DefaultEllipsoid	WGS84 WGS 1984 ellipsoid (EPSG:7030) used in GPS systems.

Fields inherited from class FormattableObject

EPSG, GEOTIFF, INTERNAL, OGC, SINGLE_LINE

Fields inherited from interface IdentifiedObject

ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY

Constructor Summary

protected	DefaultEllipsoid(Ellipsoid ellipsoid) Constructs a new ellipsoid with the same values than the specified one.
protected	DefaultEllipsoid(Map<String,?> properties, double semiMajorAxis, double semiMinorAxis, double inverseFlattening, boolean ivfDefinitive, Unit<Length> unit) Constructs a new ellipsoid using the specified axis length.

Method Summary

static DefaultEllipsoid	castOrCopy(Ellipsoid object) Wraps an arbitrary ellipsoid into a Geotk implementation.
protected int	computeHashCode() Computes a hash value for this identified object.
static DefaultEllipsoid	createEllipsoid(Map<String,?> properties, double semiMajorAxis, double semiMinorAxis, Unit<Length> unit) Constructs a new ellipsoid using the specified axis length.
static DefaultEllipsoid	createEllipsoid(String name, double semiMajorAxis, double semiMinorAxis, Unit<Length> unit) Constructs a new ellipsoid using the specified axis length.
static DefaultEllipsoid	createFlattenedSphere(Map<String,?> properties, double semiMajorAxis, double inverseFlattening, Unit<Length> unit) Constructs a new ellipsoid using the specified axis length and inverse flattening value.
static DefaultEllipsoid	createFlattenedSphere(String name, double semiMajorAxis, double inverseFlattening, Unit<Length> unit) Constructs a new ellipsoid using the specified axis length and inverse flattening value.
boolean	equals(Object object, ComparisonMode mode) Compare this ellipsoid with the specified object for equality.
String	formatWKT(Formatter formatter) Formats the inner part of a Well Known Text (WKT) element.
Unit<Length>	getAxisUnit() Returns the linear unit of the semi-major and semi-minor axis values.
double	getEccentricity() The ratio of the distance between the center and a focus of the ellipse to the length of its semimajor axis.
double	getInverseFlattening() Returns the value of the inverse of the flattening constant.
double	getSemiMajorAxis() Length of the semi-major axis of the ellipsoid.
double	getSemiMinorAxis() Length of the semi-minor axis of the ellipsoid.
boolean	isIvfDefinitive() Indicates if the inverse flattening is definitive for this ellipsoid.
boolean	isSphere() true if the ellipsoid is degenerate and is actually a sphere.
double	orthodromicDistance(double x1, double y1, double x2, double y2) Returns the orthodromic distance between two geographic coordinates.
double	orthodromicDistance(Point2D P1, Point2D P2) Returns the orthodromic distance between two geographic coordinates.
static DefaultEllipsoid	wrap(Ellipsoid object) Deprecated. Renamed castOrCopy.

Methods inherited from class AbstractIdentifiedObject

equals, getAlias, getIdentifier, getIdentifiers, getName, getName, getRemarks, hashCode, nameMatches

Methods inherited from class FormattableObject

getDefaultIndentation, print, setDefaultIndentation, toString, toWKT, toWKT, toWKT

Methods inherited from class Object

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

Methods inherited from interface IdentifiedObject

getAlias, getIdentifiers, getName, getRemarks, toWKT

Field Detail

WGS84

public static final DefaultEllipsoid WGS84

WGS 1984 ellipsoid (EPSG:7030) used in GPS systems. The semi-major and semi-minor axis length are approximatively 6378137 and 6356752 metres respectively. This is the default ellipsoid for most org.geotoolkit packages.

See Also:

DefaultGeodeticDatum.WGS84

WGS72

public static final DefaultEllipsoid WGS72

WGS 1972 ellipsoid (EPSG:7043). The semi-major and semi-minor axis length are approximatively 6378135 and 6356751 metres respectively.

Since:

3.00

See Also:

DefaultGeodeticDatum.WGS72

GRS80

public static final DefaultEllipsoid GRS80

GRS 1980 ellipsoid (EPSG:7019), also called "International 1979". The semi-major and semi-minor axis length are approximatively 6378137 and 6356752 metres respectively. This ellipsoid is very close, but not identical, to WGS84.

Note: The NAD83 ellipsoid uses the same semi-axis length and units. The Web Map Server "CRS:83" authority code uses that NAD83 ellipsoid. The "IGNF:MILLER" authority code uses the GRS80 ellipsoid.

Since:

2.2

INTERNATIONAL_1924

public static final DefaultEllipsoid INTERNATIONAL_1924

International 1924 ellipsoid (EPSG:7022). The semi-major and semi-minor axis length are approximatively 6378388 and 6356912 metres respectively.

Note: The European Datum 1950 ellipsoid uses the same semi-axis length and units.

CLARKE_1866

public static final DefaultEllipsoid CLARKE_1866

Clarke 1866 ellipsoid (EPSG:7008). The semi-major and semi-minor axis length are approximatively 6378206 and 6356584 metres respectively.

Note: The NAD27 ellipsoid uses the same semi-axis length and units. The Web Map Server "CRS:27" authority code uses that NAD27 ellipsoid.

Since:

2.2

SPHERE

public static final DefaultEllipsoid SPHERE

A sphere with a radius of 6371000 metres. Spheres use a simpler algorithm for orthodromic distance computation, which may be faster and more robust.

Note: This ellipsoid is close to the GRS 1980 Authalic Sphere (EPSG:7048), which has a radius of 6371007 metres.

See Also:

DefaultGeodeticDatum.SPHERE

Constructor Detail

DefaultEllipsoid

protected DefaultEllipsoid(Ellipsoid ellipsoid)

Constructs a new ellipsoid with the same values than the specified one. This copy constructor provides a way to convert an arbitrary implementation into a Geotk one or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API. This constructor performs a shallow copy, i.e. the properties are not cloned.

Parameters:

ellipsoid - The ellipsoid to copy.

Since:

2.2

See Also:

castOrCopy(Ellipsoid)

DefaultEllipsoid

protected DefaultEllipsoid(Map<String,?> properties,
                           double semiMajorAxis,
                           double semiMinorAxis,
                           double inverseFlattening,
                           boolean ivfDefinitive,
                           Unit<Length> unit)

Constructs a new ellipsoid using the specified axis length. The properties map is given unchanged to the super-class constructor.

Parameters:

properties - Set of properties. Should contains at least "name".

semiMajorAxis - The equatorial radius.

semiMinorAxis - The polar radius.

inverseFlattening - The inverse of the flattening value.

ivfDefinitive - true if the inverse flattening is definitive.

unit - The units of the semi-major and semi-minor axis values.

See Also:

createEllipsoid(java.lang.String, double, double, javax.measure.unit.Unit), createFlattenedSphere(java.lang.String, double, double, javax.measure.unit.Unit)

Method Detail

createEllipsoid

public static DefaultEllipsoid createEllipsoid(String name,
                                               double semiMajorAxis,
                                               double semiMinorAxis,
                                               Unit<Length> unit)

Constructs a new ellipsoid using the specified axis length.

Parameters:

name - The ellipsoid name.

semiMajorAxis - The equatorial radius.

semiMinorAxis - The polar radius.

unit - The units of the semi-major and semi-minor axis values.

Returns:

An ellipsoid with the given axis length.

createEllipsoid

public static DefaultEllipsoid createEllipsoid(Map<String,?> properties,
                                               double semiMajorAxis,
                                               double semiMinorAxis,
                                               Unit<Length> unit)

Constructs a new ellipsoid using the specified axis length. The properties map is given unchanged to the super-class constructor.

Parameters:

properties - Set of properties. Should contains at least "name".

semiMajorAxis - The equatorial radius.

semiMinorAxis - The polar radius.

unit - The units of the semi-major and semi-minor axis values.

Returns:

An ellipsoid with the given axis length.

createFlattenedSphere

public static DefaultEllipsoid createFlattenedSphere(String name,
                                                     double semiMajorAxis,
                                                     double inverseFlattening,
                                                     Unit<Length> unit)

Constructs a new ellipsoid using the specified axis length and inverse flattening value.

Parameters:

name - The ellipsoid name.

semiMajorAxis - The equatorial radius.

inverseFlattening - The inverse flattening value.

unit - The units of the semi-major and semi-minor axis values.

Returns:

An ellipsoid with the given axis length.

createFlattenedSphere

public static DefaultEllipsoid createFlattenedSphere(Map<String,?> properties,
                                                     double semiMajorAxis,
                                                     double inverseFlattening,
                                                     Unit<Length> unit)

Constructs a new ellipsoid using the specified axis length and inverse flattening value. The properties map is given unchanged to the super-class constructor.

Parameters:

properties - Set of properties. Should contains at least "name".

semiMajorAxis - The equatorial radius.

inverseFlattening - The inverse flattening value.

unit - The units of the semi-major and semi-minor axis values.

Returns:

An ellipsoid with the given axis length.

castOrCopy

public static DefaultEllipsoid castOrCopy(Ellipsoid object)

Wraps an arbitrary ellipsoid into a Geotk implementation. This method is useful if orthodromic distance computation (for example) are desired. If the supplied ellipsoid is already an instance of DefaultEllipsoid or is null, then it is returned unchanged.

Parameters:

object - The object to get as a Geotk implementation, or null if none.

Returns:

A Geotk implementation containing the values of the given object (may be the given object itself), or null if the argument was null.

wrap

@Deprecated
public static DefaultEllipsoid wrap(Ellipsoid object)

Deprecated. Renamed castOrCopy.

Parameters:

object - The object to get as a Geotk implementation, or null if none.

Returns:

The given object as a Geotk implementation.

getAxisUnit

public Unit<Length> getAxisUnit()

Returns the linear unit of the semi-major and semi-minor axis values.

Specified by:

getAxisUnit in interface Ellipsoid

Returns:

The axis linear unit.

getSemiMajorAxis

public double getSemiMajorAxis()

Length of the semi-major axis of the ellipsoid. This is the equatorial radius in axis linear unit.

Specified by:

getSemiMajorAxis in interface Ellipsoid

Returns:

Length of semi-major axis.

getSemiMinorAxis

public double getSemiMinorAxis()

Length of the semi-minor axis of the ellipsoid. This is the polar radius in axis linear unit.

Specified by:

getSemiMinorAxis in interface Ellipsoid

Returns:

Length of semi-minor axis.

getEccentricity

public double getEccentricity()

The ratio of the distance between the center and a focus of the ellipse to the length of its semimajor axis. The eccentricity can alternately be computed from the equation: e=sqrt(2f-f²).

Returns:

The eccentricity of this ellipsoid.

getInverseFlattening

public double getInverseFlattening()

Returns the value of the inverse of the flattening constant. Flattening is a value used to indicate how closely an ellipsoid approaches a spherical shape. The inverse flattening is related to the equatorial/polar radius by the formula ivf = r_e/(r_e-r_p). For perfect spheres (i.e. if isSphere() returns true), the POSITIVE_INFINITY value is used.

Specified by:

getInverseFlattening in interface Ellipsoid

Returns:

The inverse flattening value.

isIvfDefinitive

public boolean isIvfDefinitive()

Indicates if the inverse flattening is definitive for this ellipsoid. Some ellipsoids use the IVF as the defining value, and calculate the polar radius whenever asked. Other ellipsoids use the polar radius to calculate the IVF whenever asked. This distinction can be important to avoid floating-point rounding errors.

Specified by:

isIvfDefinitive in interface Ellipsoid

Returns:

true if the inverse flattening is definitive, or false if the polar radius is definitive.

isSphere

public boolean isSphere()

true if the ellipsoid is degenerate and is actually a sphere. The sphere is completely defined by the semi-major axis, which is the radius of the sphere.

Specified by:

isSphere in interface Ellipsoid

Returns:

true if the ellipsoid is degenerate and is actually a sphere.

orthodromicDistance

public double orthodromicDistance(Point2D P1,
                                  Point2D P2)

Returns the orthodromic distance between two geographic coordinates. The orthodromic distance is the shortest distance between two points on a sphere's surface. The default implementation delegates the work to orthodromicDistance(double,double,double,double).

Parameters:

P1 - Longitude and latitude of first point (in decimal degrees).

P2 - Longitude and latitude of second point (in decimal degrees).

Returns:

The orthodromic distance (in the units of this ellipsoid).

orthodromicDistance

public double orthodromicDistance(double x1,
                                  double y1,
                                  double x2,
                                  double y2)

Returns the orthodromic distance between two geographic coordinates. The orthodromic distance is the shortest distance between two points on a sphere's surface. The orthodromic path is always on a great circle. This is different from the loxodromic distance, which is a longer distance on a path with a constant direction on the compass.

Parameters:

x1 - Longitude of first point (in decimal degrees).

y1 - Latitude of first point (in decimal degrees).

x2 - Longitude of second point (in decimal degrees).

y2 - Latitude of second point (in decimal degrees).

Returns:

The orthodromic distance (in the units of this ellipsoid's axis).

equals

public boolean equals(Object object,
                      ComparisonMode mode)

Compare this ellipsoid with the specified object for equality.

Specified by:

equals in interface LenientComparable

Overrides:

equals in class AbstractIdentifiedObject

Parameters:

object - The object to compare to this.

mode - STRICT for performing a strict comparison, or IGNORE_METADATA for comparing only properties relevant to transformations.

Returns:

true if both objects are equal.

computeHashCode

protected int computeHashCode()

Computes a hash value for this identified object. This method is invoked by AbstractIdentifiedObject.hashCode() when first needed.

Implementation specific feature
In the Geotk implementation, the name, identifiers and remarks are not used for hash code computation. Consequently two identified objects will return the same hash value if they are equal in the sense of equals(…, ComparisonMode.IGNORE_METADATA). This feature allows users to implement metadata-insensitive HashMap.

Overrides:

computeHashCode in class AbstractIdentifiedObject

Returns:

The hash code value. This value may change between different execution of the Geotk library.

formatWKT

public String formatWKT(Formatter formatter)

Formats the inner part of a Well Known Text (WKT) element.

Specified by:

formatWKT in interface Formattable

Overrides:

formatWKT in class FormattableObject

Parameters:

formatter - The formatter to use.

Returns:

The WKT element name, which is "SPHEROID".

See Also:

FormattableObject.toWKT(), FormattableObject.toString()