Class EllipsoidToCentricTransform
Object
FormattableObject
AbstractMathTransform
EllipsoidToCentricTransform
- All Implemented Interfaces:
- Serializable,- Parameterized,- LenientComparable,- MathTransform
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:
 
- longitude (λ) relative to the prime meridian (usually Greenwich),
- latitude (φ),
- optionally height above the ellipsoid (h).
- In the Cartesian case:
     - distance from Earth center on the X axis (toward the intersection of prime meridian and equator),
- distance from Earth center on the Y axis (toward the intersection of 90°E meridian and equator),
- distance from Earth center on the Z axis (toward North pole).
 
MathTransform has been created:
 - EllipsoidToCentricTransforminstances 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.
- Transforms created by the createGeodeticConversion(…)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:
Defined in the sis-referencing module
- 
Nested Class SummaryNested ClassesModifier and TypeClassDescriptionstatic enumWhether the output coordinate system is Cartesian or Spherical.
- 
Field SummaryFieldsModifier and TypeFieldDescriptionprotected final doubleThe square of eccentricity: ℯ² = (a²-b²)/a² where a is the semi-major axis length and b is the semi-minor axis length.
- 
Constructor SummaryConstructorsConstructorDescriptionEllipsoidToCentricTransform(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 SummaryModifier and TypeMethodDescriptionprotected intComputes a hash value for this transform.static MathTransformcreateGeodeticConversion(MathTransformFactory factory, double semiMajor, double semiMinor, Unit<Length> unit, boolean withHeight, EllipsoidToCentricTransform.TargetType target) Creates a transform from geographic to geocentric coordinates.static MathTransformcreateGeodeticConversion(MathTransformFactory factory, Ellipsoid ellipsoid, boolean withHeight) Creates a transform from geographic to Cartesian geocentric coordinates (convenience method).derivative(DirectPosition point) Computes the derivative at the given location.booleanequals(Object object, ComparisonMode mode) Compares the specified object with this math transform for equality.protected ContextualParametersReturns the parameters used for creating the complete conversion.Returns a description of the internal parameters of thisEllipsoidToCentricTransformtransform.Returns a copy of internal parameter values of thisEllipsoidToCentricTransformtransform.final intGets the dimension of input points, which is 2 or 3.final intGets the dimension of output points, which is 3.Returns whether the target coordinate system is Cartesian or Spherical.inverse()Returns the inverse of this transform.protected voidinverseTransform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) Converts Cartesian coordinates (X,Y,Z) to ellipsoidal coordinates (λ,φ) or (λ,φ,h).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.voidtransform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) Converts the (λ,φ) or (λ,φ,h) geodetic coordinates to to (X,Y,Z) geocentric coordinates.protected MathTransformtryConcatenate(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 AbstractMathTransformequals, formatTo, getDomain, hashCode, isIdentity, transform, transform, transform, transformMethods inherited from class FormattableObjectprint, toString, toString, toWKTMethods inherited from class Objectclone, finalize, getClass, notify, notifyAll, wait, wait, waitMethods inherited from interface MathTransformtoWKT
- 
Field Details- 
eccentricitySquaredprotected final double eccentricitySquaredThe square of eccentricity: ℯ² = (a²-b²)/a² where a is the semi-major axis length and b is the semi-minor axis length.
 
- 
- 
Constructor Details- 
EllipsoidToCentricTransformpublic 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 specificallyEllipsoidToCentricTransforminstances expect input coordinates as below:- longitudes in radians relative to the prime meridian (usually Greenwich),
- latitudes in radians,
- optionally heights above the ellipsoid, in units of an ellipsoid having a semi-major axis length of 1.
 - distance from Earth center on the X axis (toward the intersection of prime meridian and equator),
- distance from Earth center on the Y axis (toward the intersection of 90°E meridian and equator),
- distance from Earth center on the Z axis (toward North pole).
 Geographic to geocentric conversionsFor converting geographic coordinates to geocentric coordinates,EllipsoidToCentricTransforminstances need to be concatenated with the following affine transforms:- Normalization before EllipsoidToCentricTransform:- Conversion of (λ,φ) from degrees to radians
- Division of (h) by the semi-major axis length
 
- Denormalization after EllipsoidToCentricTransform:- Multiplication of (X,Y,Z) by the semi-major axis length
 
 EllipsoidToCentricTransformconstruction, the full conversion chain including the above affine transforms can be created bygetContextualParameters().completeTransform(factory, this)}.- Parameters:
- semiMajor- the semi-major axis length.
- semiMinor- the semi-minor axis length.
- unit- the unit of measurement for the semi-axes and the ellipsoidal height.
- withHeight-- trueif source geographic coordinates include an ellipsoidal height (i.e. are 3-D), or- falseif they are only 2-D.
- target- whether the target coordinate shall be Cartesian or Spherical.
- See Also:
 
 
- 
- 
Method Details- 
createGeodeticConversionpublic 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 theEllipsoidToCentricTransforminstance 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: - longitudes in degrees relative to the prime meridian (usually Greenwich),
- latitudes in degrees,
- optionally heights above the ellipsoid, in units of the ellipsoid axis (usually metres).
 - distance from Earth center on the X axis (toward the intersection of prime meridian and equator),
- distance from Earth center on the Y axis (toward the intersection of 90°E meridian and equator),
- distance from Earth center on the Z axis (toward North pole).
 - Parameters:
- factory- the factory to use for creating and concatenating the affine transforms.
- semiMajor- the semi-major axis length.
- semiMinor- the semi-minor axis length.
- unit- the unit of measurement for the semi-axes and the ellipsoidal height.
- withHeight-- trueif source geographic coordinates include an ellipsoidal height (i.e. are 3-D), or- falseif they are only 2-D.
- target- whether the target coordinate shall be Cartesian or Spherical.
- Returns:
- the conversion from geographic to geocentric coordinates.
- Throws:
- FactoryException- if an error occurred while creating a transform.
 
- 
createGeodeticConversionpublic 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:
 The target type is assumed Cartesian because this is the most frequently used target.createGeodeticConversion(factory, ellipsoid.getSemiMajorAxis(), ellipsoid.getSemiMinorAxis(), ellipsoid.getAxisUnit(), withHeight, TargetType.CARTESIAN);- 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.
- withHeight-- trueif source geographic coordinates include an ellipsoidal height (i.e. are 3-D), or- falseif they are only 2-D.
- Returns:
- the conversion from geographic to Cartesian geocentric coordinates.
- Throws:
- FactoryException- if an error occurred while creating a transform.
 
- 
getContextualParametersReturns 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:
- getContextualParametersin class- AbstractMathTransform
- Returns:
- the parameter values for the sequence of
         normalize → this→ denormalize transforms.
 
- 
getParameterValuesReturns a copy of internal parameter values of thisEllipsoidToCentricTransformtransform. 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:
- getParameterValuesin interface- Parameterized
- Overrides:
- getParameterValuesin class- AbstractMathTransform
- Returns:
- a copy of the internal parameter values for this transform.
- See Also:
 
- 
getParameterDescriptorsReturns a description of the internal parameters of thisEllipsoidToCentricTransformtransform. The returned group contains parameter descriptors for the number of dimensions and the eccentricity.- Specified by:
- getParameterDescriptorsin interface- Parameterized
- Overrides:
- getParameterDescriptorsin class- AbstractMathTransform
- Returns:
- a description of the internal parameters.
- See Also:
 
- 
getSourceDimensionspublic final int getSourceDimensions()Gets the dimension of input points, which is 2 or 3.- Specified by:
- getSourceDimensionsin interface- MathTransform
- Specified by:
- getSourceDimensionsin class- AbstractMathTransform
- Returns:
- 2 or 3.
- See Also:
 
- 
getTargetDimensionspublic final int getTargetDimensions()Gets the dimension of output points, which is 3.- Specified by:
- getTargetDimensionsin interface- MathTransform
- Specified by:
- getTargetDimensionsin class- AbstractMathTransform
- Returns:
- always 3.
- See Also:
 
- 
getTargetTypeReturns whether the target coordinate system is Cartesian or Spherical.- Returns:
- whether the target coordinate system is Cartesian or Spherical.
 
- 
derivativeComputes the derivative at the given location. This method relaxes a little bit theMathTransformcontract by accepting two- or three-dimensional points even if the number of dimensions does not match thegetSourceDimensions()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:
- derivativein interface- MathTransform
- Overrides:
- derivativein class- AbstractMathTransform
- Parameters:
- point- the position where to evaluate the derivative.
- Returns:
- the derivative at the specified point (never null).
- Throws:
- TransformException- if the derivative cannot be evaluated at the specified point.
 
- 
transformpublic 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:
- transformin class- AbstractMathTransform
- Parameters:
- srcPts- the array containing the source coordinates (cannot be- null).
- srcOff- the offset to the point to be transformed in the source array.
- dstPts- the array into which the transformed coordinates is returned. May be the same than- srcPts. May be- nullif only the derivative matrix is desired.
- dstOff- the offset to the location of the transformed point that is stored in the destination array.
- derivate-- truefor computing the derivative, or- falseif not needed.
- Returns:
- the matrix of the transform derivative at the given source position,
         or nullif thederivateargument isfalse.
- Throws:
- TransformException- if the point cannot be transformed or if a problem occurred while calculating the derivative.
- See Also:
 
- 
transformpublic 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 thantransform(double[], int, double[], int, boolean), but the formulas are repeated here for performance reasons.- Specified by:
- transformin interface- MathTransform
- Overrides:
- transformin class- AbstractMathTransform
- Parameters:
- srcPts- the array containing the source point coordinates.
- srcOff- the offset to the first point to be transformed in the source array.
- dstPts- the array into which the transformed point coordinates are returned. May be the same than- srcPts.
- dstOff- the offset to the location of the first transformed point that is stored in the destination array.
- numPts- the number of point objects to be transformed.
- Throws:
- TransformException- if a point cannot be transformed.
 
- 
inverseTransformprotected 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 byinverse().- Parameters:
- srcPts- the array containing the source point coordinates.
- srcOff- the offset to the first point to be transformed in the source array.
- dstPts- the array into which the transformed point coordinates are returned. May be the same than- srcPts.
- dstOff- the offset to the location of the first transformed point that is stored in the destination array.
- numPts- the number of point objects to be transformed.
- Throws:
- TransformException- if the calculation does not converge.
 
- 
inverseReturns the inverse of this transform. The default implementation returns a transform that will delegate its work toinverseTransform(double[], int, double[], int, int).- Specified by:
- inversein interface- MathTransform
- Overrides:
- inversein class- AbstractMathTransform
- Returns:
- the conversion from (geo)centric to ellipsoidal coordinates.
 
- 
computeHashCodeprotected int computeHashCode()Computes a hash value for this transform. This method is invoked byAbstractMathTransform.hashCode()when first needed.- Overrides:
- computeHashCodein class- AbstractMathTransform
- Returns:
- the hash code value. This value may change between different execution of the Apache SIS library.
 
- 
equalsCompares the specified object with this math transform for equality.- Specified by:
- equalsin interface- LenientComparable
- Overrides:
- equalsin class- AbstractMathTransform
- Parameters:
- object- the object to compare with this transform.
- mode- the strictness level of the comparison. Default to- STRICT.
- Returns:
- trueif the given object is considered equals to this math transform.
- See Also:
 
- 
tryConcatenateprotected 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 intent is to handle the following sequence of operations defined in the EPSG database:- Inverse of Geographic 3D to 2D conversion (EPSG:9659)
- Geographic/geocentric conversions (EPSG:9602)
 EllipsoidToCentricTransforminstance allow the following optimizations:- Avoid computation of h value.
- Allow use of the more efficient AffineTransformbefore this transform instead of a transform based on a matrix of size 4×3.
 - Overrides:
- tryConcatenatein class- AbstractMathTransform
- Parameters:
- applyOtherFirst-- trueif the transformation order is- otherfollowed by- this, or- falseif the transformation order is- thisfollowed by- other.
- other- the other math transform to (pre-)concatenate with this transform.
- factory- the factory which is (indirectly) invoking this method, or- nullif none.
- Returns:
- the combined math transform, or nullif no optimized combined transform is available.
- Throws:
- FactoryException- if an error occurred while combining the transforms.
- See Also:
 
 
-