# Class EllipsoidToRadiusTransform

Object
FormattableObject
AbstractMathTransform
EllipsoidToRadiusTransform

All Implemented Interfaces:
  `Serializable`, `Parameterized`, `LenientComparable`, `Printable`, `MathTransform`

public class EllipsoidToRadiusTransform extends AbstractMathTransform implements Serializable
Conversion of spherical coordinates from (λ,Ω) to (λ,Ω,R) with points assumed to be on an ellipsoid surface. For each coordinate tuple, this transform copies the spherical longitude (λ) and the spherical latitude (Ω), then appends a R coordinate which is the distance from the sphere center to the ellipsoid surface at the spherical latitude Ω. Notes:

- For a biaxial ellipsoid, the spherical longitude is the same as the geodetic longitude. For this reason, the same symbol (λ) is reused.
- This transform does not convert the spherical latitude (Ω) to geodetic latitude (φ). That conversion is done by the inverse of `EllipsoidToCentricTransform`.

## Related operations

This transform is also named Spherical 2D to 3D conversion by Apache SIS. This transform is similar to Geographic 2D to 3D conversion (inverse of EPSG:9659 method), except that this spherical case sets R to a non-zero value that depends on the Ω value. By contrast, the geographic case unconditionally sets h to zero.

This transform is also related to the `DefaultEllipsoid​.getGeocentricRadius(double)` method, except that the latter expects geodetic latitudes while this transform expects geocentric latitudes.

## Purpose

This transform is used together with the inverse of `EllipsoidToCentricTransform` when the source coordinate system is spherical (`EllipsoidToCentricTransform​.TargetType​.SPHERICAL`). The conversion from spherical latitude (Ω) to geodetic latitude (φ) depends on R. When the latter is not specified, it is often assumed to be on the ellipsoid surface.

Since:
  1.5
See Also:
  - `DefaultEllipsoid​.getGeocentricRadius(double)`
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final double`
  `eccentricitySquared`
  The square of the eccentricity.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `EllipsoidToRadiusTransform(Ellipsoid surface)`
  Creates a transform for an ellipsoid having a semi-major axis length of 1.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static MathTransform`
  `createGeodeticConversion(MathTransformFactory factory, Ellipsoid surface)`
  Creates a transform for the given ellipsoid.
  `protected ContextualParameters`
  `getContextualParameters()`
  Returns the parameters used for creating the complete conversion.
  `ParameterDescriptorGroup`
  `getParameterDescriptors()`
  Returns a description of the internal parameters of this `EllipsoidToRadiusTransform` transform.
  `ParameterValueGroup`
  `getParameterValues()`
  Returns a copy of internal parameter values of this `EllipsoidToRadiusTransform` transform.
  `final int`
  `getSourceDimensions()`
  Gets the dimension of input points, which is 2.
  `final int`
  `getTargetDimensions()`
  Gets the dimension of output points, which is 3.
  `MathTransform`
  `inverse()`
  Returns the inverse of this transform.
  `Matrix`
  `transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate)`
  Converts the (λ,Ω) spherical coordinates to (λ,Ω,R), and optionally returns the derivative at that location.
  `void`
  `transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)`
  Converts the (λ,Ω) spherical coordinates to (λ,Ω,R) in a sequence of coordinate tuples.
  `protected void`
  `tryConcatenate(TransformJoiner context)`
  If the transform after this transform is dropping the third coordinate, removes this transform.

  ### Methods inherited from class AbstractMathTransform

  `derivative, equals, formatTo, getDomain, hashCode, isIdentity, transform, transform, transform, transform, tryConcatenate`

  ### Methods inherited from class FormattableObject

  `print, toString, toString, toWKT`

  ### Methods inherited from class Object

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

  ### Methods inherited from interface MathTransform

  `toWKT`

- ## Field Details

  - ### eccentricitySquared

    protected final double eccentricitySquared
    The square of the eccentricity. This is defined as ℯ² = (a²-b²)/a² where a is the semi-major axis length and b is the semi-minor axis length.

- ## Constructor Details

  - ### EllipsoidToRadiusTransform

    public EllipsoidToRadiusTransform(Ellipsoid surface)
    Creates a transform for an ellipsoid having a semi-major axis length of 1. `EllipsoidToRadiusTransform` instances expect input coordinates as below:
    1. Spherical longitudes in any unit (they will pass-through),
    2. Spherical latitudes in radians.
    Output coordinates are the same as the input coordinates, with the addition of the distance from sphere center to ellipsoid surface.

    #### Unit conversions

    For a complete chain of transforms, `EllipsoidToRadiusTransform` instances need to be concatenated with the following affine transforms:
    - Normalization before `EllipsoidToRadiusTransform`:
      - Conversion of spherical latitudes from degrees to radians
    - Denormalization after `EllipsoidToRadiusTransform`:
      - Multiplication of R by the semi-minor axis length
    After `EllipsoidToRadiusTransform` construction, the full conversion chain including the above affine transforms can be created by `getContextualParameters().completeTransform(factory, this)}`.
    Parameters:
      `surface` - the ellipsoid of the spherical coordinates for which to add a radius.
    See Also:
      - `createGeodeticConversion(MathTransformFactory, Ellipsoid)`

- ## Method Details

  - ### createGeodeticConversion

    public static MathTransform createGeodeticConversion(MathTransformFactory factory, Ellipsoid surface) throws FactoryException
    Creates a transform for the given ellipsoid. This factory method combines the `EllipsoidToRadiusTransform` instance with the steps needed for converting degrees to radians and expressing the results in units of the given ellipsoid.
    Parameters:
      `factory` - the factory to use for creating and concatenating the affine transforms.
      `surface` - the ellipsoid of the spherical coordinates for which to add a radius.
    Returns:
      the conversion from two-dimensional to three-dimensional spherical coordinates.
    Throws:
      `FactoryException` - 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.
    Overrides:
      `getContextualParameters` in class `AbstractMathTransform`
    Returns:
      the parameter values for the normalize → `this` → denormalize chain of transforms.

  - ### getParameterValues

    @Debug public ParameterValueGroup getParameterValues()
    Returns a copy of internal parameter values of this `EllipsoidToRadiusTransform` transform. 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:
      `getParameterValues` in interface `Parameterized`
    Overrides:
      `getParameterValues` in class `AbstractMathTransform`
    Returns:
      a copy of the internal parameter values for this transform.
    See Also:
      - `AbstractMathTransform​.getContextualParameters()`
      - `SingleOperation​.getParameterValues()`

  - ### getParameterDescriptors

    @Debug public ParameterDescriptorGroup getParameterDescriptors()
    Returns a description of the internal parameters of this `EllipsoidToRadiusTransform` transform.
    Specified by:
      `getParameterDescriptors` in interface `Parameterized`
    Overrides:
      `getParameterDescriptors` in class `AbstractMathTransform`
    Returns:
      a description of the internal parameters.
    See Also:
      - `DefaultOperationMethod​.getParameters()`

  - ### getSourceDimensions

    public final int getSourceDimensions()
    Gets the dimension of input points, which is 2.
    Specified by:
      `getSourceDimensions` in interface `MathTransform`
    Specified by:
      `getSourceDimensions` in class `AbstractMathTransform`
    Returns:
      always 2.
    See Also:
      - `DefaultOperationMethod​.getSourceDimensions()`

  - ### getTargetDimensions

    public final int getTargetDimensions()
    Gets the dimension of output points, which is 3.
    Specified by:
      `getTargetDimensions` in interface `MathTransform`
    Specified by:
      `getTargetDimensions` in class `AbstractMathTransform`
    Returns:
      always 3.
    See Also:
      - `DefaultOperationMethod​.getTargetDimensions()`

  - ### transform

    public Matrix transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate) throws TransformException
    Converts the (λ,Ω) spherical coordinates to (λ,Ω,R), and optionally returns the derivative at that location.
    Specified by:
      `transform` in 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 as `srcPts`. May be `null` if only the derivative matrix is desired.
      `dstOff` - 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:
      `TransformException` - if the point cannot be transformed or if a problem occurred while calculating the derivative.
    See Also:
      - `AbstractMathTransform​.derivative(DirectPosition)`
      - `AbstractMathTransform​.transform(DirectPosition, DirectPosition)`
      - `MathTransforms​.derivativeAndTransform(MathTransform, double[], int, double[], int)`

  - ### transform

    public void transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws TransformException
    Converts the (λ,Ω) spherical coordinates to (λ,Ω,R) in a sequence of coordinate tuples. This method performs the same conversion as `transform(double[], int, double[], int, boolean)`, but the formulas are repeated here for performance reasons.
    Specified by:
      `transform` in interface `MathTransform`
    Overrides:
      `transform` in 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 as `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.

  - ### inverse

    public MathTransform inverse()
    Returns the inverse of this transform. The inverse transform drops the radius.
    Specified by:
      `inverse` in interface `MathTransform`
    Overrides:
      `inverse` in class `AbstractMathTransform`
    Returns:
      the conversion from 3D to 2D spherical coordinates.

  - ### tryConcatenate

    protected void tryConcatenate(TransformJoiner context) throws FactoryException
    If the transform after this transform is dropping the third coordinate, removes this transform. Otherwise, allows `TransformJoiner` to move the operations applied on the longitude value if this move can simplify the chain of transforms.
    Overrides:
      `tryConcatenate` in class `AbstractMathTransform`
    Parameters:
      `context` - information about the neighbor transforms, and the object where to set the result.
    Throws:
      `FactoryException` - if an error occurred while combining the transforms.
    See Also:
      - `DefaultMathTransformFactory​.createConcatenatedTransform(MathTransform, MathTransform)`