org.apache.sis.referencing.operation.projection

Class NormalizedProjection

Object

FormattableObject

AbstractMathTransform

AbstractMathTransform2D

NormalizedProjection

All Implemented Interfaces:

Serializable, Parameterized, LenientComparable, MathTransform, MathTransform2D

Direct Known Subclasses:

AlbersEqualArea, CylindricalEqualArea, LambertConicConformal, Mercator, ObliqueStereographic, PolarStereographic, TransverseMercator

public abstract class NormalizedProjection
extends AbstractMathTransform2D
implements Serializable

Base class for conversion services between ellipsoidal and cartographic projections. This conversion works on a normalized spaces, where angles are expressed in radians and computations are performed for a sphere having a semi-major axis of 1. More specifically:

• On input, the transform(…) method expects (longitude, latitude) angles in radians. Longitudes have the central meridian (λ₀) removed before the transform method is invoked. The conversion from degrees to radians and the longitude rotation are applied by the normalization affine transform.
• On output, the transform(…) method returns (x, y) values on a sphere or ellipse having a semi-major axis length (a) of 1. The multiplication by the scale factor (k₀) and the translation by false easting (FE) and false northing (FN) are applied by the denormalization affine transform.

The normalization and denormalization steps are represented below by the matrices immediately on the left and right sides of Normalized­Projection respectively. Those matrices show only the basic parameters common to most projections. Some projections will put more elements in those matrices.

$$\left[\begin{array}{ccc}0& 1& 0\\ 1& 0& 0\\ 0& 0& 1\end{array}\right]$$

→

$$\left[\begin{array}{ccc}\pi /180& 0& -{\lambda }_0\cdot (\pi /180)\\ 0& \pi /180& 0\\ 0& 0& 1\end{array}\right]$$

→

NormalizedProjection

→

$$\left[\begin{array}{ccc}a\cdot k_0& 0& \mathrm{FE}\\ 0& a\cdot k_0& \mathrm{FN}\\ 0& 0& 1\end{array}\right]$$

Note: The first matrix on the left side is for swapping axes from (latitude, longitude) to (longitude, latitude) order. This matrix is shown here for completeness, but is not managed by this projection package. Axes swapping is managed at a higher level.

Normalized­Projection does not store the above cited parameters (central meridian, scale factor, etc.) on intend (except indirectly), in order to make clear that those parameters are not used by subclasses. The ability to recognize two Normalized­Projections as equivalent without consideration for the scale factor (among other) allow more efficient concatenation in some cases (typically some combinations of inverse projection followed by a direct projection).

All angles (either fields, method parameters or return values) in this class and subclasses are in radians. This is the opposite of Parameters where all angles are in CRS-dependent units, typically decimal degrees.

Serialization

Serialization of this class is appropriate for short-term storage or RMI use, but may not be compatible with future versions. For long term storage, WKT (Well Know Text) or XML are more appropriate.

Since:

0.6

See Also:

Contextual­Parameters, Map projections on MathWorld, Serialized Form

Defined in the sis-referencing module

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	NormalizedProjection.ParameterRole Maps the parameters to be used for initializing Normalized­Projection and its normalization / denormalization matrices.

Field Summary

Fields

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

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	NormalizedProjection(OperationMethod method, Parameters parameters, Map<NormalizedProjection.ParameterRole,? extends ParameterDescriptor<? extends Number>> roles) Constructs a new map projection from the supplied parameters.

Method Summary

Modifier and Type	Method and Description
protected int	computeHashCode() Computes a hash code value for this Normalized­Projection.
MathTransform	createMapProjection(MathTransformFactory factory) Returns the sequence of normalization → this → denormalization transforms as a whole.
boolean	equals(Object object, ComparisonMode mode) Compares the given object with this transform for equivalence.
protected ContextualParameters	getContextualParameters() Returns the parameters used for creating the complete map projection.
ParameterDescriptorGroup	getParameterDescriptors() Returns a description of the non-linear internal parameters of this Normalized­Projection.
ParameterValueGroup	getParameterValues() Returns a copy of non-linear internal parameter values of this Normalized­Projection.
MathTransform2D	inverse() Returns the inverse of this map projection.
protected abstract void	inverseTransform(double[] srcPts, int srcOff, double[] dstPts, int dstOff) Inverse converts the single coordinate in src­Pts at the given offset and stores the result in pt­Dst at the given offset.
abstract Matrix	transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate) Converts a single coordinate in src­Pts at the given offset and stores the result in dst­Pts at the given offset.
protected MathTransform	tryConcatenate(boolean applyOtherFirst, MathTransform other, MathTransformFactory factory) Concatenates or pre-concatenates in an optimized way this projection with the given transform, if possible.

Methods inherited from class AbstractMathTransform2D

create­Transformed­Shape, derivative, get­Source­Dimensions, get­Target­Dimensions, transform

Methods inherited from class AbstractMathTransform

derivative, equals, format­To, hash­Code, is­Identity, transform, 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

derivative, is­Identity, to­WKT, transform, transform, transform, transform, transform

Field Detail

eccentricity

protected final double eccentricity

Ellipsoid eccentricity, equals to sqrt(eccentricity­Squared). Value 0 means that the ellipsoid is spherical.

eccentricitySquared

protected final double eccentricitySquared

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

Constructor Detail

NormalizedProjection

protected NormalizedProjection(OperationMethod method,
                               Parameters parameters,
                               Map<NormalizedProjection.ParameterRole,? extends ParameterDescriptor<? extends Number>> roles)

Constructs a new map projection from the supplied parameters. This constructor applies the following operations on the contextual parameters:

• On the normalization matrix (to be applied before this transform):
  • Subtract the central meridian value.
  • Convert from degrees to radians.
• On the denormalization matrix (to be applied after this transform):
  • Scale by the semi-major axis length.
  • If a scale factor is present (not all map projections have a scale factor), apply that scale.
  • Translate by the false easting and false northing (after the scale).
• On the contextual parameters (not the parameters of this transform):
  • Store the values for semi-major axis length, semi-minor axis length, scale factor (if present), central meridian, false easting and false northing values.

In matrix form, this constructor creates the following matrices (subclasses are free to modify):

Initial matrix coefficients after construction

Normalization	Denormalization
$$\left[\begin{array}{ccc}\pi /180& 0& -{\lambda }_0\cdot (\pi /180)\\ 0& \pi /180& 0\\ 0& 0& 1\end{array}\right]$$	$$\left[\begin{array}{ccc}a\cdot k_0& 0& \mathrm{FE}\\ 0& a\cdot k_0& \mathrm{FN}\\ 0& 0& 1\end{array}\right]$$

Which parameters are considered

The roles map specifies which parameters to look for central meridian, scale factor, false easting, false northing and other values. All entries in the roles map are optional. All descriptors in the map shall comply to the following constraints:

• Descriptors associated to Normalized­Projection.Parameter­Role.SEMI_MAJOR, SEMI_MINOR, FALSE_EASTING and FALSE_NORTHING shall have the same linear unit of measurement (usually metre).
• Descriptors associated to angular measures (Normalized­Projection.Parameter­Role.CENTRAL_MERIDIAN and LATITUDE_OF_CONFORMAL_SPHERE_RADIUS) shall use degrees.

Note that users can still use units of their choice in the Parameters object given in argument to this constructor. But those values will be converted to the units of measurement specified by the parameter descriptors in the roles map, which must be the above-cited units.

Parameters:

method - description of the map projection parameters.

parameters - the parameters of the projection to be created.

roles - parameters to look for central meridian, scale factor, false easting, false northing and other values.

Method Detail

createMapProjection

public MathTransform createMapProjection(MathTransformFactory factory)
                                  throws FactoryException

Returns the sequence of normalization → this → denormalization transforms as a whole. The transform returned by this method expects (longitude, latitude) coordinates in degrees and returns (x,y) coordinates in metres. Conversion to other units and changes in axis order are not managed by the returned transform.

The default implementation is as below:

return getContextualParameters().completeTransform(factory, this);

Subclasses can override this method if they wish to use alternative implementations under some circumstances. For example many subclasses will replace this by a specialized implementation if they detect that the ellipsoid is actually spherical.

Parameters:

factory - the factory to use for creating the transform.

Returns:

the map projection from (λ,φ) to (x,y) coordinates.

Throws:

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

See Also:

Contextual­Parameters.complete­Transform(Math­Transform­Factory, Math­Transform)

getContextualParameters

protected final ContextualParameters getContextualParameters()

Returns the parameters used for creating the complete map projection. 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. Subclasses shall not use the values defined in the returned object for computation purpose, except at construction time.

Overrides:

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

Returns:

the parameters values for the sequence of normalize → this → denormalize transforms, or null if unspecified.

getParameterValues

@Debug
public ParameterValueGroup getParameterValues()

Returns a copy of non-linear internal parameter values of this Normalized­Projection. The returned group contains at least the eccentricity parameter value. Some subclasses add more non-linear parameters, but most of them do not because many parameters like the scale factor or the false easting/northing are handled by the (de)normalization affine transforms instead.

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 normalized projection.

See Also:

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

getParameterDescriptors

@Debug
public ParameterDescriptorGroup getParameterDescriptors()

Returns a description of the non-linear internal parameters of this Normalized­Projection. The returned group contains at least a descriptor for the eccentricity parameter. Subclasses may add more parameters.

This method is for inspecting the parameter values of this non-linear kernel only, not for inspecting the contextual parameters. Inspecting the kernel parameter values is usually for debugging purpose only.

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

transform

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

Converts a single coordinate in src­Pts at the given offset and stores the result in dst­Pts at the given offset. In addition, opportunistically computes the transform derivative if requested.

Normalization

The input ordinates are (λ,φ) (the variable names for longitude and latitude respectively) angles in radians. Input coordinate shall have the central meridian removed from the longitude by the caller before this method is invoked. After this method is invoked, the caller will need to multiply the output coordinate by the global scale factor and apply the (false easting, false northing) offset. This means that projections that implement this method are performed on a sphere or ellipse having a semi-major axis length of 1.

Note: in Proj.4, the same standardization, described above, is handled by pj_fwd.c.

Argument checks

The input longitude and latitude are usually (but not always) in the range [-π … π] and [-π/2 … π/2] respectively. However values outside those ranges are accepted on the assumption that most implementations use those values only in trigonometric functions like sine and cosine. If this assumption is not applicable to a particular subclass, then it is implementor's responsibility to check the range.

Specified by:

transform in class Abstract­Math­Transform

Parameters:

src­Pts - the array containing the source point coordinate, as (longitude, latitude) angles in radians.

src­Off - the offset of the single coordinate to be converted in the source array.

dst­Pts - the array into which the converted coordinate is returned (may be the same than src­Pts). Ordinates will be expressed in a dimensionless unit, as a linear distance on a unit sphere or ellipse.

dst­Off - the offset of the location of the converted coordinate that is stored in the destination array.

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

Returns:

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

Throws:

Projection­Exception - if the coordinate can not be converted.

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)

inverseTransform

protected abstract void inverseTransform(double[] srcPts,
                                         int srcOff,
                                         double[] dstPts,
                                         int dstOff)
                                  throws ProjectionException

Inverse converts the single coordinate in src­Pts at the given offset and stores the result in pt­Dst at the given offset. The output ordinates are (longitude, latitude) angles in radians, usually (but not necessarily) in the range [-π … π] and [-π/2 … π/2] respectively.

Normalization

Input coordinate shall have the (false easting, false northing) removed by the caller and the result divided by the global scale factor before this method is invoked. After this method is invoked, the caller will need to add the central meridian to the longitude in the output coordinate. This means that projections that implement this method are performed on a sphere or ellipse having a semi-major axis of 1.

Note: in Proj.4, the same standardization, described above, is handled by pj_inv.c.

Parameters:

src­Pts - the array containing the source point coordinate, as linear distance on a unit sphere or ellipse.

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

dst­Pts - the array into which the converted point coordinate is returned (may be the same than src­Pts). Ordinates will be (longitude, latitude) angles in radians.

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

Throws:

Projection­Exception - if the point can not be converted.

inverse

public MathTransform2D inverse()

Returns the inverse of this map projection. Subclasses do not need to override this method, as they should override inverse­Transform(…) instead.

Specified by:

inverse in interface Math­Transform

Specified by:

inverse in interface Math­Transform2D

Overrides:

inverse in class Abstract­Math­Transform2D

Returns:

the inverse of this map projection.

tryConcatenate

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

Concatenates or pre-concatenates in an optimized way this projection with the given transform, if possible. If transforms are concatenated in an (inverse projection) → (affine) → (projection) sequence where the (projection) and (inverse projection) steps are the inverse of each other, then in some particular case the sequence can be replaced by a single affine transform. If no such simplification is possible, this method returns null.

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 simplified (usually affine) transform, or null if no such optimization is available.

Throws:

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

Since:

0.8

See Also:

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

computeHashCode

protected int computeHashCode()

Computes a hash code value for this Normalized­Projection.

Overrides:

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

Returns:

the hash code value.

equals

public boolean equals(Object object,
                      ComparisonMode mode)

Compares the given object with this transform for equivalence. The default implementation checks if object is an instance of the same class than this, then compares the eccentricity.

If this method returns true, then for any given identical source position, the two compared map projections shall compute the same target position. Many of the contextual parameters used for creating the map projections are irrelevant and do not need to be known. Those projection parameters will be compared only if the comparison mode is Comparison­Mode.STRICT or BY_CONTRACT.

Example: a Mercator projection can be created in the 2SP case with a standard parallel value of 60°. The same projection can also be created in the 1SP case with a scale factor of 0.5. Nevertheless those two map projections applied on a sphere gives identical results. Considering them as equivalent allows the referencing module to transform coordinates between those two projections more efficiently.

Specified by:

equals in interface Lenient­Comparable

Overrides:

equals in class Abstract­Math­Transform

Parameters:

object - the object to compare with this map projection for equivalence.

mode - the strictness level of the comparison. Default to Comparison­Mode.STRICT.

Returns:

true if the given object is equivalent to this map projection.

See Also:

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