Module org.opengis.geoapi

Package org.opengis.referencing.datum

Interface Ellipsoid

All Superinterfaces:

IdentifiedObject

@UML(identifier="Ellipsoid",
     specification=ISO_19111)
public interface Ellipsoid
extends IdentifiedObject

Geometric figure that can be used to describe the approximate shape of a planet. For the Earth the ellipsoid is bi-axial with rotation about the polar axis. For other planet, the ellipsoid may be tri-axial. An ellipsoid requires two or three defining parameters:

• Semi-major axis.
• One of the following:
  • semi-minor axis, or
  • inverse flattening.
• Optionally a semi-median axis (for planetary applications).

For some applications, for example small-scale mapping in atlases, a spherical approximation of the geoid's surface is used, requiring only the radius of the sphere to be specified.

Since:

1.0

See Also:

• DatumAuthorityFactory.createEllipsoid(String)
• DatumFactory.createEllipsoid(Map, double, double, Unit)
• DatumFactory.createFlattenedSphere(Map, double, double, Unit)

Departure from OGC/ISO standard due to constraint of the Java language

ISO 19111 defines the union named secondDefiningParameter as being either semiMinorAxis or inverseFlattening. The union construct (defined in some languages like C/C++) does not exist in Java. GeoAPI changed the interface to require both ellipsoidal parameters (in addition to the semiMajorAxis parameter which is mandatory in any case), as was done in OGC 01-009. However, implementers could readily permit users to only provide one of the two parameters by creating a class which calculates the second parameter from the first. For precision, GeoAPI imports the isIvfDefinitive attribute from OGC 01-009 to enable the user to establish which of the two parameters was used to define the instance.

Field Summary

Fields inherited from interface org.opengis.referencing.IdentifiedObject

ALIAS_KEY, DOMAINS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY

Method Summary

Modifier and Type	Method	Description
javax.measure.Unit<javax.measure.quantity.Length>	getAxisUnit()	Returns the linear unit of the semi-major, semi-minor and semi-median axis values.
double	getInverseFlattening()	Returns the value of the inverse of the flattening constant.
double	getSemiMajorAxis()	Length of the semi-major axis of the ellipsoid.
default OptionalDouble	getSemiMedianAxis()	Length of the semi-median axis of a triaxial ellipsoid.
double	getSemiMinorAxis()	Length of the semi-minor axis of the ellipsoid.
boolean	isIvfDefinitive()	Indicates if the inverse flattening (IVF) is definitive for this ellipsoid.
default boolean	isSphere()	true if the ellipsoid is degenerate and is actually a sphere.

Methods inherited from interface org.opengis.referencing.IdentifiedObject

getAlias, getDomains, getIdentifiers, getName, getRemarks, toWKT

Method Details

getAxisUnit

@UML(identifier="getAxisUnit",
     specification=OGC_01009)
javax.measure.Unit<javax.measure.quantity.Length> getAxisUnit()

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

Returns:

the axis linear unit.

getSemiMajorAxis

@UML(identifier="semiMajorAxis",
     obligation=MANDATORY,
     specification=ISO_19111)
double getSemiMajorAxis()

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

Returns:

length of semi-major axis.

Unit:

Length

getSemiMedianAxis

@UML(identifier="semiMedianAxis",
     obligation=OPTIONAL,
     specification=ISO_19111)
default OptionalDouble getSemiMedianAxis()

Length of the semi-median axis of a triaxial ellipsoid. This parameter is not required for a biaxial ellipsoid. The default implementation returns an empty value.

Returns:

length of the semi-median axis of a triaxial ellipsoid.

Since:

3.1

getSemiMinorAxis

@UML(identifier="secondDefiningParameter.semiMinorAxis",
     obligation=CONDITIONAL,
     specification=ISO_19111)
double getSemiMinorAxis()

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

Returns:

length of semi-minor axis.

Unit:

Length

getInverseFlattening

@UML(identifier="secondDefiningParameter.inverseFlattening",
     obligation=CONDITIONAL,
     specification=ISO_19111)
double getInverseFlattening()

Returns the value of the inverse of the flattening constant. 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 Double.POSITIVE_INFINITY value is used.

Returns:

the inverse flattening value.

Unit:

Scale

isIvfDefinitive

@UML(identifier="CS_Ellipsoid.isIvfDefinitive",
     obligation=MANDATORY,
     specification=OGC_01009)
boolean isIvfDefinitive()

Indicates if the inverse flattening (IVF) 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.

Returns:

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

isSphere

@UML(identifier="secondDefiningParameter.isSphere",
     obligation=CONDITIONAL,
     specification=ISO_19111)
default 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.

Returns:

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