org.apache.sis.referencing.operation.transform

Class EllipsoidToCentricTransform

Object

FormattableObject

AbstractMathTransform

EllipsoidToCentricTransform

All Implemented Interfaces:

Serializable, Parameterized, LenientComparable, MathTransform

public class EllipsoidToCentricTransform
extends AbstractMathTransform
implements Serializable

Transform from two- or three- dimensional ellipsoidal coordinates to (geo)centric coordinates. This transform is usually (but not necessarily) part of a conversion from geographic to Cartesian geocentric coordinates. Each input coordinates is expected to contain:

1. longitude (λ) relative to the prime meridian (usually Greenwich),
2. latitude (φ),
3. optionally height above the ellipsoid (h).

Output coordinates are as below:

• In the Cartesian case:
  1. distance from Earth center on the X axis (toward the intersection of prime meridian and equator),
  2. distance from Earth center on the Y axis (toward the intersection of 90°E meridian and equator),
  3. distance from Earth center on the Z axis (toward North pole).

The units of measurements depend on how the Math­Transform has been created:

• Ellipsoid­To­Centric­Transform instances created directly by the constructor expect (λ,φ) values in radians and compute (X,Y,Z) values in units of an ellipsoid having a semi-major axis length of 1. That constructor is reserved for subclasses only.
• Transforms created by the create­Geodetic­Conversion(…) static method expect (λ,φ) values in degrees and compute (X,Y,Z) values in units of the ellipsoid axes (usually metres).

Since:

0.7

See Also:

Serialized Form

Defined in the sis-referencing module

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	EllipsoidToCentricTransform.TargetType Whether the output coordinate system is Cartesian or Spherical.

Field Summary

Fields

Modifier and Type	Field and Description
protected double	eccentricitySquared The square of eccentricity: ℯ² = (a²-b²)/a² where a is the semi-major axis length and b is the semi-minor axis length.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	EllipsoidToCentricTransform(double semiMajor, double semiMinor, Unit<Length> unit, boolean withHeight, EllipsoidToCentricTransform.TargetType target) Creates a transform from angles in radians on ellipsoid having a semi-major axis length of 1.

Method Summary

Modifier and Type	Method and Description
protected int	computeHashCode() Computes a hash value for this transform.
static MathTransform	createGeodeticConversion(MathTransformFactory factory, double semiMajor, double semiMinor, Unit<Length> unit, boolean withHeight, EllipsoidToCentricTransform.TargetType target) Creates a transform from geographic to geocentric coordinates.
static MathTransform	createGeodeticConversion(MathTransformFactory factory, Ellipsoid ellipsoid, boolean withHeight) Creates a transform from geographic to Cartesian geocentric coordinates (convenience method).
Matrix	derivative(DirectPosition point) Computes the derivative at the given location.
boolean	equals(Object object, ComparisonMode mode) Compares the specified object with this math transform for equality.
protected ContextualParameters	getContextualParameters() Returns the parameters used for creating the complete conversion.
ParameterDescriptorGroup	getParameterDescriptors() Returns a description of the internal parameters of this Ellipsoid­To­Centric­Transform transform.
ParameterValueGroup	getParameterValues() Returns a copy of internal parameter values of this Ellipsoid­To­Centric­Transform transform.
int	getSourceDimensions() Gets the dimension of input points, which is 2 or 3.
int	getTargetDimensions() Gets the dimension of output points, which is 3.
EllipsoidToCentricTransform.TargetType	getTargetType() Returns whether the target coordinate system is Cartesian or Spherical.
MathTransform	inverse() Returns the inverse of this transform.
protected void	inverseTransform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) Converts Cartesian coordinates (X,Y,Z) to ellipsoidal coordinates (λ,φ) or (λ,φ,h).
Matrix	transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate) Converts the (λ,φ) or (λ,φ,h) geodetic coordinates to to (X,Y,Z) geocentric coordinates, and optionally returns the derivative at that location.
void	transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) Converts the (λ,φ) or (λ,φ,h) geodetic coordinates to to (X,Y,Z) geocentric coordinates.
protected MathTransform	tryConcatenate(boolean applyOtherFirst, MathTransform other, MathTransformFactory factory) If this transform expects three-dimensional inputs, and if the transform just before this one unconditionally sets the height to zero, then replaces this transform by a two-dimensional one.

Methods inherited from class AbstractMathTransform

equals, format­To, hash­Code, is­Identity, transform, transform, transform, transform

Methods inherited from class FormattableObject

print, to­String, to­String, to­WKT

Methods inherited from class Object

clone, finalize, get­Class, notify, notify­All, wait, wait, wait

Methods inherited from interface MathTransform

to­WKT

Field Detail

eccentricitySquared

protected final double eccentricitySquared

The square of eccentricity: ℯ² = (a²-b²)/a² where a is the semi-major axis length and b is the semi-minor axis length.

Constructor Detail

EllipsoidToCentricTransform

protected EllipsoidToCentricTransform(double semiMajor,
                                      double semiMinor,
                                      Unit<Length> unit,
                                      boolean withHeight,
                                      EllipsoidToCentricTransform.TargetType target)

Creates a transform from angles in radians on ellipsoid having a semi-major axis length of 1. More specifically Ellipsoid­To­Centric­Transform instances expect input coordinates as below:

1. longitudes in radians relative to the prime meridian (usually Greenwich),
2. latitudes in radians,
3. optionally heights above the ellipsoid, in units of an ellipsoid having a semi-major axis length of 1.

Output coordinates are as below, in units of an ellipsoid having a semi-major axis length of 1:

1. distance from Earth center on the X axis (toward the intersection of prime meridian and equator),
2. distance from Earth center on the Y axis (toward the intersection of 90°E meridian and equator),
3. distance from Earth center on the Z axis (toward North pole).

Geographic to geocentric conversions

For converting geographic coordinates to geocentric coordinates, Ellipsoid­To­Centric­Transform instances need to be concatenated with the following affine transforms:

• Normalization before Ellipsoid­To­Centric­Transform:
  • Conversion of (λ,φ) from degrees to radians
  • Division of (h) by the semi-major axis length
• Denormalization after Ellipsoid­To­Centric­Transform:
  • Multiplication of (X,Y,Z) by the semi-major axis length

After Ellipsoid­To­Centric­Transform construction, the full conversion chain including the above affine transforms can be created by get­Contextual­Parameters().complete­Transform(factory, this)}.

Parameters:

semi­Major - the semi-major axis length.

semi­Minor - the semi-minor axis length.

unit - the unit of measurement for the semi-axes and the ellipsoidal height.

with­Height - true if source geographic coordinates include an ellipsoidal height (i.e. are 3-D), or false if they are only 2-D.

target - whether the target coordinate shall be Cartesian or Spherical.

See Also:

create­Geodetic­Conversion(Math­Transform­Factory, double, double, Unit, boolean, Target­Type)

Method Detail

createGeodeticConversion

public static MathTransform createGeodeticConversion(MathTransformFactory factory,
                                                     double semiMajor,
                                                     double semiMinor,
                                                     Unit<Length> unit,
                                                     boolean withHeight,
                                                     EllipsoidToCentricTransform.TargetType target)
                                              throws FactoryException

Creates a transform from geographic to geocentric coordinates. This factory method combines the Ellipsoid­To­Centric­Transform instance with the steps needed for converting degrees to radians and expressing the results in units of the given ellipsoid.

Input coordinates are expected to contain:

1. longitudes in degrees relative to the prime meridian (usually Greenwich),
2. latitudes in degrees,
3. optionally heights above the ellipsoid, in units of the ellipsoid axis (usually metres).

Output coordinates are as below, in units of the ellipsoid axis (usually metres):

1. distance from Earth center on the X axis (toward the intersection of prime meridian and equator),
2. distance from Earth center on the Y axis (toward the intersection of 90°E meridian and equator),
3. distance from Earth center on the Z axis (toward North pole).

Parameters:

factory - the factory to use for creating and concatenating the affine transforms.

semi­Major - the semi-major axis length.

semi­Minor - the semi-minor axis length.

unit - the unit of measurement for the semi-axes and the ellipsoidal height.

with­Height - true if source geographic coordinates include an ellipsoidal height (i.e. are 3-D), or false if they are only 2-D.

target - whether the target coordinate shall be Cartesian or Spherical.

Returns:

the conversion from geographic to geocentric coordinates.

Throws:

Factory­Exception - if an error occurred while creating a transform.

createGeodeticConversion

public static MathTransform createGeodeticConversion(MathTransformFactory factory,
                                                     Ellipsoid ellipsoid,
                                                     boolean withHeight)
                                              throws FactoryException

Creates a transform from geographic to Cartesian geocentric coordinates (convenience method). Invoking this method is equivalent to the following:

createGeodeticConversion(factory,
        ellipsoid.getSemiMajorAxis(),
        ellipsoid.getSemiMinorAxis(),
        ellipsoid.getAxisUnit(),
        withHeight, TargetType.CARTESIAN);

The target type is assumed Cartesian because this is the most frequently used target.

Parameters:

factory - the factory to use for creating and concatenating the affine transforms.

ellipsoid - the semi-major and semi-minor axis lengths with their unit of measurement.

with­Height - true if source geographic coordinates include an ellipsoidal height (i.e. are 3-D), or false if they are only 2-D.

Returns:

the conversion from geographic to Cartesian geocentric coordinates.

Throws:

Factory­Exception - if an error occurred while creating a transform.

getContextualParameters

protected ContextualParameters getContextualParameters()

Returns the parameters used for creating the complete conversion. Those parameters describe a sequence of normalize → this → denormalize transforms, not including axis swapping. Those parameters are used for formatting Well Known Text (WKT) and error messages.

Overrides:

get­Contextual­Parameters in class Abstract­Math­Transform

Returns:

the parameters values for the sequence of normalize → this → denormalize transforms.

getParameterValues

@Debug
public ParameterValueGroup getParameterValues()

Returns a copy of internal parameter values of this Ellipsoid­To­Centric­Transform transform. The returned group contains parameter values for the number of dimensions and the eccentricity.

Note: this method is mostly for debugging purposes since the isolation of non-linear parameters in this class is highly implementation dependent. Most GIS applications will instead be interested in the contextual parameters.

Specified by:

get­Parameter­Values in interface Parameterized

Overrides:

get­Parameter­Values in class Abstract­Math­Transform

Returns:

a copy of the internal parameter values for this transform.

See Also:

Abstract­Math­Transform.get­Contextual­Parameters(), Abstract­Single­Operation.get­Parameter­Values()

getParameterDescriptors

@Debug
public ParameterDescriptorGroup getParameterDescriptors()

Returns a description of the internal parameters of this Ellipsoid­To­Centric­Transform transform. The returned group contains parameter descriptors for the number of dimensions and the eccentricity.

Specified by:

get­Parameter­Descriptors in interface Parameterized

Overrides:

get­Parameter­Descriptors in class Abstract­Math­Transform

Returns:

a description of the internal parameters.

See Also:

Default­Operation­Method.get­Parameters()

getSourceDimensions

public final int getSourceDimensions()

Gets the dimension of input points, which is 2 or 3.

Specified by:

get­Source­Dimensions in interface Math­Transform

Specified by:

get­Source­Dimensions in class Abstract­Math­Transform

Returns:

2 or 3.

See Also:

Default­Operation­Method.get­Source­Dimensions()

getTargetDimensions

public final int getTargetDimensions()

Gets the dimension of output points, which is 3.

Specified by:

get­Target­Dimensions in interface Math­Transform

Specified by:

get­Target­Dimensions in class Abstract­Math­Transform

Returns:

always 3.

See Also:

Default­Operation­Method.get­Target­Dimensions()

getTargetType

public final EllipsoidToCentricTransform.TargetType getTargetType()

Returns whether the target coordinate system is Cartesian or Spherical.

Returns:

whether the target coordinate system is Cartesian or Spherical.

derivative

public Matrix derivative(DirectPosition point)
                  throws TransformException

Computes the derivative at the given location. This method relaxes a little bit the Math­Transform contract by accepting two- or three-dimensional points even if the number of dimensions does not match the get­Source­Dimensions() value.

Rational: that flexibility on the number of dimensions is required for calculation of inverse transform derivative, because that calculation needs to inverse a square matrix with all terms in it before to drop the last row in the two-dimensional case.

Specified by:

derivative in interface Math­Transform

Overrides:

derivative in class Abstract­Math­Transform

Parameters:

point - the coordinate point where to evaluate the derivative.

Returns:

the derivative at the specified point (never null).

Throws:

Transform­Exception - if the derivative can not be evaluated at the specified point.

transform

public Matrix transform(double[] srcPts,
                        int srcOff,
                        double[] dstPts,
                        int dstOff,
                        boolean derivate)
                 throws TransformException

Converts the (λ,φ) or (λ,φ,h) geodetic coordinates to to (X,Y,Z) geocentric coordinates, and optionally returns the derivative at that location.

Specified by:

transform in class Abstract­Math­Transform

Parameters:

src­Pts - the array containing the source coordinate (can not be null).

src­Off - the offset to the point to be transformed in the source array.

dst­Pts - the array into which the transformed coordinate is returned. May be the same than src­Pts. May be null if only the derivative matrix is desired.

dst­Off - the offset to the location of the transformed point that is stored in the destination array.

derivate - true for computing the derivative, or false if not needed.

Returns:

the matrix of the transform derivative at the given source position, or null if the derivate argument is false.

Throws:

Transform­Exception - if the point can not be transformed or if a problem occurred while calculating the derivative.

See Also:

Abstract­Math­Transform.derivative(Direct­Position), Abstract­Math­Transform.transform(Direct­Position, Direct­Position), Math­Transforms.derivative­And­Transform(Math­Transform, double[], int, double[], int)

transform

public void transform(double[] srcPts,
                      int srcOff,
                      double[] dstPts,
                      int dstOff,
                      int numPts)
               throws TransformException

Converts the (λ,φ) or (λ,φ,h) geodetic coordinates to to (X,Y,Z) geocentric coordinates. This method performs the same conversion than transform(double[], int, double[], int, boolean), but the formulas are repeated here for performance reasons.

Specified by:

transform in interface Math­Transform

Overrides:

transform in class Abstract­Math­Transform

Parameters:

src­Pts - the array containing the source point coordinates.

src­Off - the offset to the first point to be transformed in the source array.

dst­Pts - the array into which the transformed point coordinates are returned. May be the same than src­Pts.

dst­Off - the offset to the location of the first transformed point that is stored in the destination array.

num­Pts - the number of point objects to be transformed.

Throws:

Transform­Exception - if a point can not be transformed.

inverseTransform

protected void inverseTransform(double[] srcPts,
                                int srcOff,
                                double[] dstPts,
                                int dstOff,
                                int numPts)
                         throws TransformException

Converts Cartesian coordinates (X,Y,Z) to ellipsoidal coordinates (λ,φ) or (λ,φ,h). This method is invoked by the transform returned by inverse().

Parameters:

src­Pts - the array containing the source point coordinates.

src­Off - the offset to the first point to be transformed in the source array.

dst­Pts - the array into which the transformed point coordinates are returned. May be the same than src­Pts.

dst­Off - the offset to the location of the first transformed point that is stored in the destination array.

num­Pts - the number of point objects to be transformed.

Throws:

Transform­Exception - if the calculation does not converge.

inverse

public MathTransform inverse()

Returns the inverse of this transform. The default implementation returns a transform that will delegate its work to inverse­Transform(double[], int, double[], int, int).

Specified by:

inverse in interface Math­Transform

Overrides:

inverse in class Abstract­Math­Transform

Returns:

the conversion from (geo)centric to ellipsoidal coordinates.

computeHashCode

protected int computeHashCode()

Computes a hash value for this transform. This method is invoked by Abstract­Math­Transform.hash­Code() when first needed.

Overrides:

compute­Hash­Code in class Abstract­Math­Transform

Returns:

the hash code value. This value may change between different execution of the Apache SIS library.

equals

public boolean equals(Object object,
                      ComparisonMode mode)

Compares the specified object with this math transform for equality.

Specified by:

equals in interface Lenient­Comparable

Overrides:

equals in class Abstract­Math­Transform

Parameters:

object - the object to compare with this transform.

mode - the strictness level of the comparison. Default to STRICT.

Returns:

true if the given object is considered equals to this math transform.

See Also:

Utilities.deep­Equals(Object, Object, Comparison­Mode)

tryConcatenate

protected MathTransform tryConcatenate(boolean applyOtherFirst,
                                       MathTransform other,
                                       MathTransformFactory factory)
                                throws FactoryException

If this transform expects three-dimensional inputs, and if the transform just before this one unconditionally sets the height to zero, then replaces this transform by a two-dimensional one. The intend is to handle the following sequence of operations defined in the EPSG database:

1. Inverse of Geographic 3D to 2D conversion (EPSG:9659)
2. Geographic/geocentric conversions (EPSG:9602)

Replacing the above sequence by a two-dimensional Ellipsoid­To­Centric­Transform instance allow the following optimizations:

• Avoid computation of h value.
• Allow use of the more efficient Affine­Transform before this transform instead than a transform based on a matrix of size 4×3.

Overrides:

try­Concatenate in class Abstract­Math­Transform

Parameters:

apply­Other­First - true if the transformation order is other followed by this, or false if the transformation order is this followed by other.

other - the other math transform to (pre-)concatenate with this transform.

factory - the factory which is (indirectly) invoking this method, or null if none.

Returns:

the combined math transform, or null if no optimized combined transform is available.

Throws:

Factory­Exception - if an error occurred while combining the transforms.

See Also:

Default­Math­Transform­Factory.create­Concatenated­Transform(Math­Transform, Math­Transform)