Class NormalizedProjection
 All Implemented Interfaces:
Serializable
,Parameterized
,LenientComparable
,MathTransform
,MathTransform2D
 Direct Known Subclasses:
AlbersEqualArea
,AzimuthalEquidistant
,CassiniSoldner
,CylindricalEqualArea
,LambertAzimuthalEqualArea
,LambertConicConformal
,Mercator
,Mollweide
,ObliqueMercator
,ObliqueStereographic
,Orthographic
,PolarStereographic
,Polyconic
,SatelliteTracking
,Sinusoidal
,TransverseMercator
 On input, the
transform(…)
method expects (longitude, latitude) angles in radians, sometime premultiplied by other projectionspecific factors (see point #3 below). 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 semimajor axis length (a) of 1, sometime divided by other projectionspecific factors (see point #3 below). 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.  In addition to abovecited conversions, subclasses may opportunistically concatenate other linear operations
(scales and translations). They do that by changing the normalization and denormalization matrices shown below.
When such changes are applied, the
transform(…)
inputs are no longer angles in radians but some other derived values.
NormalizedProjection
respectively. Those matrices show only the basic parameters common to most projections.
Some projections will put more elements in those matrices.
NormalizedProjection
NormalizedProjection
does not store the above cited parameters (central meridian, scale factor, etc.)
on intent (except indirectly), in order to make clear that those parameters are not used by subclasses.
The ability to recognize two NormalizedProjection
s 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 CRSdependent units,
typically decimal degrees.
Serialization
Serialization of this class is appropriate for shortterm 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:
Defined in the sisreferencing
module

Nested Class Summary
Modifier and TypeClassDescriptionprotected static enum
Maps the parameters to be used for initializingNormalizedProjection
and its normalization / denormalization matrices. 
Field Summary
Modifier and TypeFieldDescriptionprotected final double
Ellipsoid eccentricity, equals tosqrt(eccentricitySquared)
.protected final double
The square of eccentricity: ℯ² = (a²b²)/a² where ℯ is the eccentricity, a is the semimajor axis length and b is the semiminor axis length.Fields inherited from class AbstractMathTransform2D
DIMENSION

Constructor Summary
ModifierConstructorDescriptionprotected
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 TypeMethodDescriptionprotected int
Computes a hash code value for thisNormalizedProjection
.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 final ContextualParameters
Returns the parameters used for creating the complete map projection.Returns a description of the nonlinear internal parameters of thisNormalizedProjection
.Returns a copy of nonlinear internal parameter values of thisNormalizedProjection
.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 insrcPts
at the given offset and stores the result inptDst
at the given offset.abstract Matrix
transform
(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate) Converts a single coordinate insrcPts
at the given offset and stores the result indstPts
at the given offset.protected MathTransform
tryConcatenate
(boolean applyOtherFirst, MathTransform other, MathTransformFactory factory) Concatenates or preconcatenates in an optimized way this projection with the given transform, if possible.Methods inherited from class AbstractMathTransform2D
createTransformedShape, derivative, getSourceDimensions, getTargetDimensions, transform
Methods inherited from class AbstractMathTransform
derivative, equals, formatTo, hashCode, isIdentity, transform, transform, transform, transform, transform
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
derivative, isIdentity, toWKT, transform, transform, transform, transform, transform

Field Details

eccentricity
protected final double eccentricityEllipsoid eccentricity, equals tosqrt(eccentricitySquared)
. Value 0 means that the ellipsoid is spherical. 
eccentricitySquared
protected final double eccentricitySquaredThe square of eccentricity: ℯ² = (a²b²)/a² where ℯ is the eccentricity, a is the semimajor axis length and b is the semiminor axis length.


Constructor Details

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 semimajor 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 semimajor axis length, semiminor axis length, scale factor (if present), central meridian, false easting and false northing values.
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
Theroles
map specifies which parameters to look for central meridian, scale factor, false easting, false northing and other values. All entries in theroles
map are optional. All descriptors in the map shall comply to the following constraints: Descriptors associated to
NormalizedProjection.ParameterRole.SEMI_MAJOR
,SEMI_MINOR
,FALSE_EASTING
andFALSE_NORTHING
shall have the same linear unit of measurement (usually metre).  Descriptors associated to angular measures (
NormalizedProjection.ParameterRole.CENTRAL_MERIDIAN
andLATITUDE_OF_CONFORMAL_SPHERE_RADIUS
) shall use degrees.
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 theroles
map, which must be the abovecited 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.
 On the normalization matrix (to be applied before


Method Details

createMapProjection
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:
Subclasses can override this method if they wish to use alternative implementations under some circumstances. For example many subclasses will replacereturn getContextualParameters().completeTransform(factory, this);
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:
FactoryException
 if an error occurred while creating a transform. See Also:

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:
getContextualParameters
in classAbstractMathTransform
 Returns:
 the parameter values for the sequence of normalize →
this
→ denormalize transforms, ornull
if unspecified.

getParameterValues
Returns a copy of nonlinear internal parameter values of thisNormalizedProjection
. The returned group contains at least theeccentricity
parameter value. Some subclasses add more nonlinear 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 nonlinear parameters in this class is highly implementation dependent. Most GIS applications will instead be interested in the contextual parameters. Specified by:
getParameterValues
in interfaceParameterized
 Overrides:
getParameterValues
in classAbstractMathTransform
 Returns:
 a copy of the internal parameter values for this normalized projection.
 See Also:

getParameterDescriptors
Returns a description of the nonlinear internal parameters of thisNormalizedProjection
. The returned group contains at least a descriptor for theeccentricity
parameter. Subclasses may add more parameters.This method is for inspecting the parameter values of this nonlinear kernel only, not for inspecting the contextual parameters. Inspecting the kernel parameter values is usually for debugging purpose only.
 Specified by:
getParameterDescriptors
in interfaceParameterized
 Overrides:
getParameterDescriptors
in classAbstractMathTransform
 Returns:
 a description of the internal parameters.
 See Also:

transform
public abstract Matrix transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate) throws ProjectionException Converts a single coordinate insrcPts
at the given offset and stores the result indstPts
at the given offset. In addition, opportunistically computes the transform derivative if requested.Normalization
The input coordinates are (λ,φ) (the variable names for longitude and latitude respectively) angles in radians, eventually premultiplied by projectionspecific factors. 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, apply the (false easting, false northing) offset and eventually other projectionspecific factors. This means that projections that implement this method are performed on a sphere or ellipse having a semimajor axis length of 1.Note 1: it is generally not necessary to know the projectionspecific additional factors applied by subclasses on the input and output values, becauseNormalizedProjection
should never be used directly.NormalizedProjection
instances are used only indirectly as a step in a concatenated transform that include the normalization and denormalization matrices documented in this class javadoc.Note 2: in Proj.4, the same standardization, described above, is handled bypj_fwd.c
, except for the projectionspecific additional factors.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 implementer responsibility to check the range. Specified by:
transform
in classAbstractMathTransform
 Parameters:
srcPts
 the array containing the source point coordinate, as (longitude, latitude) angles in radians.srcOff
 the offset of the single coordinate to be converted in the source array.dstPts
 the array into which the converted coordinate is returned (may be the same thansrcPts
). Coordinates will be expressed in a dimensionless unit, as a linear distance on a unit sphere or ellipse.dstOff
 the offset of the location of the converted coordinate that is stored in the destination array.derivate
true
for computing the derivative, orfalse
if not needed. Returns:
 the matrix of the projection derivative at the given source position,
or
null
if thederivate
argument isfalse
.  Throws:
ProjectionException
 if the coordinate can not be converted. See Also:

inverseTransform
protected abstract void inverseTransform(double[] srcPts, int srcOff, double[] dstPts, int dstOff) throws ProjectionException Inverse converts the single coordinate insrcPts
at the given offset and stores the result inptDst
at the given offset. The output coordinates 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 semimajor axis of 1. Additional projectionspecific factors may also need to be applied (see class javadoc).Note: in Proj.4, the same standardization, described above, is handled bypj_inv.c
, except for the projectionspecific additional factors. Parameters:
srcPts
 the array containing the source point coordinate, as linear distance on a unit sphere or ellipse.srcOff
 the offset of the point to be converted in the source array.dstPts
 the array into which the converted point coordinate is returned (may be the same thansrcPts
). Coordinates will be (longitude, latitude) angles in radians.dstOff
 the offset of the location of the converted point that is stored in the destination array. Throws:
ProjectionException
 if the point can not be converted.

inverse
Returns the inverse of this map projection. Subclasses do not need to override this method, as they should overrideinverseTransform(…)
instead. Specified by:
inverse
in interfaceMathTransform
 Specified by:
inverse
in interfaceMathTransform2D
 Overrides:
inverse
in classAbstractMathTransform2D
 Returns:
 the inverse of this map projection.

tryConcatenate
protected MathTransform tryConcatenate(boolean applyOtherFirst, MathTransform other, MathTransformFactory factory) throws FactoryException Concatenates or preconcatenates 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 returnsnull
. Overrides:
tryConcatenate
in classAbstractMathTransform
 Parameters:
applyOtherFirst
true
if the transformation order isother
followed bythis
, orfalse
if the transformation order isthis
followed byother
.other
 the other math transform to (pre)concatenate with this transform.factory
 the factory which is (indirectly) invoking this method, ornull
if none. Returns:
 the simplified (usually affine) transform, or
null
if no such optimization is available.  Throws:
FactoryException
 if an error occurred while combining the transforms. Since:
 0.8
 See Also:

computeHashCode
protected int computeHashCode()Computes a hash code value for thisNormalizedProjection
. Overrides:
computeHashCode
in classAbstractMathTransform
 Returns:
 the hash code value.

equals
Compares the given object with this transform for equivalence. The default implementation checks ifobject
is an instance of the same class thanthis
, 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 isComparisonMode.STRICT
orBY_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 interfaceLenientComparable
 Overrides:
equals
in classAbstractMathTransform
 Parameters:
object
 the object to compare with this map projection for equivalence.mode
 the strictness level of the comparison. Default toComparisonMode.STRICT
. Returns:
true
if the given object is equivalent to this map projection. See Also:
