Class EllipsoidToRadiusTransform

Object

FormattableObject

AbstractMathTransform

EllipsoidToRadiusTransform

All Implemented Interfaces:

Serializable, Parameterized, Lenient­Comparable, Printable, Math­Transform

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 Ellipsoid­To­Centric­Transform.

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 Default­Ellipsoid.get­Geocentric­Radius(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 Ellipsoid­To­Centric­Transform when the source coordinate system is spherical (Ellipsoid­To­Centric­Transform.Target­Type.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:

• Default­Ellipsoid.get­Geocentric­Radius(double)
• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
protected final double	eccentricity­Squared	The square of the eccentricity.

Constructor Summary

Constructors

Constructor	Description
Ellipsoid­To­Radius­Transform(Ellipsoid surface)	Creates a transform for an ellipsoid having a semi-major axis length of 1.

Method Summary

Modifier and Type	Method	Description
static Math­Transform	create­Geodetic­Conversion(Math­Transform­Factory factory, Ellipsoid surface)	Creates a transform for the given ellipsoid.
protected Contextual­Parameters	get­Contextual­Parameters()	Returns the parameters used for creating the complete conversion.
Parameter­Descriptor­Group	get­Parameter­Descriptors()	Returns a description of the internal parameters of this Ellipsoid­To­Radius­Transform transform.
Parameter­Value­Group	get­Parameter­Values()	Returns a copy of internal parameter values of this Ellipsoid­To­Radius­Transform transform.
final int	get­Source­Dimensions()	Gets the dimension of input points, which is 2.
final int	get­Target­Dimensions()	Gets the dimension of output points, which is 3.
Math­Transform	inverse()	Returns the inverse of this transform.
Matrix	transform(double[] src­Pts, int src­Off, double[] dst­Pts, int dst­Off, boolean derivate)	Converts the (λ,Ω) spherical coordinates to (λ,Ω,R), and optionally returns the derivative at that location.
void	transform(double[] src­Pts, int src­Off, double[] dst­Pts, int dst­Off, int num­Pts)	Converts the (λ,Ω) spherical coordinates to (λ,Ω,R) in a sequence of coordinate tuples.
protected void	try­Concatenate(Transform­Joiner context)	If the transform after this transform is dropping the third coordinate, removes this transform.

Methods inherited from class AbstractMathTransform

derivative, equals, format­To, get­Domain, hash­Code, is­Identity, transform, transform, transform, transform, try­Concatenate

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 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. Ellipsoid­To­Radius­Transform 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, Ellipsoid­To­Radius­Transform instances need to be concatenated with the following affine transforms:

• Normalization before Ellipsoid­To­Radius­Transform:
  • Conversion of spherical latitudes from degrees to radians
• Denormalization after Ellipsoid­To­Radius­Transform:
  • Multiplication of R by the semi-minor axis length

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

Parameters:

surface - the ellipsoid of the spherical coordinates for which to add a radius.

See Also:

• create­Geodetic­Conversion(Math­Transform­Factory, 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 Ellipsoid­To­Radius­Transform 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:

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.

Overrides:

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

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 Ellipsoid­To­Radius­Transform 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:

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()
• Single­Operation.get­Parameter­Values()

getParameterDescriptors

@Debug
public ParameterDescriptorGroup getParameterDescriptors()

Returns a description of the internal parameters of this Ellipsoid­To­Radius­Transform transform.

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.

Specified by:

get­Source­Dimensions in interface Math­Transform

Specified by:

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

Returns:

always 2.

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()

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 Abstract­Math­Transform

Parameters:

src­Pts - the array containing the source coordinates (cannot be null).

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

dst­Pts - the array into which the transformed coordinates is returned. May be the same as 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 cannot 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 (λ,Ω) 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 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 as 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 cannot be transformed.

inverse

public MathTransform inverse()

Returns the inverse of this transform. The inverse transform drops the radius.

Specified by:

inverse in interface Math­Transform

Overrides:

inverse in class Abstract­Math­Transform

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 Transform­Joiner to move the operations applied on the longitude value if this move can simplify the chain of transforms.

Overrides:

try­Concatenate in class Abstract­Math­Transform

Parameters:

context - information about the neighbor transforms, and the object where to set the result.

Throws:

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

See Also:

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