FormattableObject
AbstractMathTransform
AbstractMathTransform2D
UnitaryProjection
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
Object
@Immutable public abstract class UnitaryProjection
Base class for conversion services between ellipsoidal and cartographic projections. This conversion works on a normalized spaces, where angles are express 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 normalize affine transform.
On output, the transform method returns
(easting, northing) values on a sphere or ellipse having a semi-major
axis length of 1. The multiplication by the scale factor and the false easting/northing offsets
are applied by the denormalize affine transform.
UnitaryProjection does not expose publicly the above cited parameters (central meridian,
scale factor, etc.) on intend, in order to make clear that those parameters are not used
by subclasses. This separation removes ambiguity when testing for equivalence. The ability to recognize two UnitaryProjections 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 UnitaryProjection.Parameters where all angles are in decimal degrees.
Note: 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.
| referencing/geotk-referencing (download) | View source code for this class |
| Nested Class Summary | |
|---|---|
protected static class |
UnitaryProjection.Parameters
Parameters that determine the affine transforms to be applied before and after the UnitaryProjection. |
| Field Summary | |
|---|---|
protected double |
excentricity
Ellipsoid excentricity, equal to sqrt(excentricitySquared). |
protected double |
excentricitySquared
The square of excentricity: e² = (a²-b²)/a² where e is the excentricity, a is the semi major axis length and b is the semi minor axis length. |
| Fields inherited from class FormattableObject |
|---|
EPSG, GEOTIFF, INTERNAL, OGC, SINGLE_LINE |
| Constructor Summary | |
|---|---|
protected |
UnitaryProjection(UnitaryProjection.Parameters parameters)
Constructs a new map projection from the supplied parameters. |
| Method Summary | |
|---|---|
protected int |
computeHashCode()
Computes a hash code value for this unitary projection. |
boolean |
equals(Object object,
ComparisonMode mode)
Compares the given object with this transform for equivalence. |
protected void |
finish()
Must be invoked by subclass constructors after they finished their work. |
ParameterValueGroup |
getParameterValues()
Returns a copy of the parameter values for this projection. |
protected UnitaryProjection.Parameters |
getUnmarshalledParameters()
The parameters used for creating this projection. |
MathTransform2D |
inverse()
Returns the inverse of this map projection. |
protected abstract void |
inverseTransform(double[] srcPts,
int srcOff,
double[] dstPts,
int dstOff)
Converts the coordinate in srcPts at the given offset and stores the result
in ptDst at the given offset. |
static void |
resetWarnings()
Resets the warning status of all projections in the current JVM. |
protected double |
rollLongitude(double x)
Ensures that the specified longitude stay within its valid range. |
protected abstract void |
transform(double[] srcPts,
int srcOff,
double[] dstPts,
int dstOff)
Converts the coordinate in srcPts at the given offset and stores the result
in dstPts at the given offset. |
void |
transform(double[] srcPts,
int srcOff,
double[] dstPts,
int dstOff,
int numPts)
Converts a list of coordinate point ordinal values. |
protected double |
unrollLongitude(double x)
Ensures that the given longitude added to the central meridian will stay in the [-180 … 180]° range. |
| Methods inherited from class AbstractMathTransform2D |
|---|
getParameterDescriptors, getSourceDimensions, getTargetDimensions, transform |
| Methods inherited from class AbstractMathTransform |
|---|
createTransformedShape, derivative, derivative, ensureNonNull, equals, formatWKT, getName, hashCode, isIdentity, rollLongitude, transform, transform, transform, transform |
| Methods inherited from class FormattableObject |
|---|
getDefaultIndentation, print, setDefaultIndentation, toString, toWKT, toWKT, toWKT |
| Methods inherited from class Object |
|---|
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
| Methods inherited from interface MathTransform2D |
|---|
createTransformedShape, derivative |
| Methods inherited from interface MathTransform |
|---|
derivative, isIdentity, toWKT, transform, transform, transform, transform |
| Field Detail |
|---|
protected final double excentricity
sqrt(excentricitySquared).
Value 0 means that the ellipsoid is spherical.
protected final double excentricitySquared
| Constructor Detail |
|---|
protected UnitaryProjection(UnitaryProjection.Parameters parameters)
finish() when they have finished their work.
parameters - The parameters of the projection to be created.| Method Detail |
|---|
protected final void finish()
rollLongitude().
protected final double rollLongitude(double x)
This method should be invoked before the forward transform begin its calculation.
x - The longitude to roll.
MapProjection.ROLL_LONGITUDEprotected final double unrollLongitude(double x)
This method should be invoked after the inverse transform finished its calculation.
x - The longitude to unroll.
rollLongitude(double)
public void transform(double[] srcPts,
int srcOff,
double[] dstPts,
int dstOff,
int numPts)
throws TransformException
transform(double[],int,double[],int) in a loop. If a geographic coordinate is
outside the range of valid values, a warning may be logged. Whatever this check is done
or not depends on factors like whatever warnings have been previously logged, for which
projections, and if the user invoked resetWarnings().
Note:
We do not override the methods working on arrays of floating point values because
they are typically never invoked. In most pratical cases, a unitary projection is
always concatenated with other transforms (usually affine) that already converted
the values from single to double precision (or conversely). If nevertheless those
methods are invoked, the default AbstractMathTransform implementation
will delegate to this method anyway, at the cost of using a temporary buffer.
transform in interface MathTransformtransform in class AbstractMathTransformsrcPts - The array containing the source point coordinates.srcOff - The offset to the first point to be converted in the source array.dstPts - The array into which the converted point coordinates are returned.
May be the same than srcPts.dstOff - The offset to the location of the first converted point that is
stored in the destination array.numPts - The number of point objects to be converted.
TransformException - if a point can't be converted.
protected abstract void transform(double[] srcPts,
int srcOff,
double[] dstPts,
int dstOff)
throws ProjectionException
srcPts at the given offset and stores the result
in dstPts at the given offset. The input ordinates are (longitude,
latitude) angles in radians, 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
sin and cos. If this assumption is not applicable
to a particular subclass, then it is implementor's responsibility to check the range.
Input coordinate shall have the central meridian removed from the longitude before this method is invoked. After this method is invoked, the output coordinate shall be multiplied by the global scale factor and the (false easting, false northing) offset shall be applied. This means that projections that implement this method are performed on a sphere or ellipse having a semi-major axis length of 1.
In PROJ.4, the same standardization,
described above, is handled by pj_fwd.c. Therefore when porting projections
from PROJ.4, the forward transform equations can be used directly here with minimal
change.
transform in class AbstractMathTransformsrcPts - The array containing the source point coordinate, as (longitude,
latitude) angles in radians.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 than srcPts). Ordinates will be in a dimensionless unit,
as a linear distance on a unit sphere or ellipse.dstOff - The offset of the location of the converted point that is
stored in the destination array.
ProjectionException - if the point can't be converted.
protected abstract void inverseTransform(double[] srcPts,
int srcOff,
double[] dstPts,
int dstOff)
throws ProjectionException
srcPts at the given offset and stores the result
in ptDst at the given offset. The output ordinates are (longitude,
latitude) angles in radians, usually in the range [-π..π] and
[-π/2..π/2] respectively.
Input coordinate shall have the (false easting,
false northing) removed and the result divided
by the global scale factor before this method is invoked. After this method is invoked,
the output coordinate shall have the central meridian
added to the longitude in ptDst. This means that projections that implement this
method are performed on a sphere or ellipse having a semi-major axis of 1.
In PROJ.4, the same standardization,
described above, is handled by pj_inv.c. Therefore when porting projections
from PROJ.4, the inverse transform equations can be used directly here with minimal
change.
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 than srcPts). Ordinates will be (longitude,
latitude) angles in radians.dstOff - The offset of the location of the converted point that is
stored in the destination array.
ProjectionException - if the point can't be converted.public MathTransform2D inverse()
inverse in interface MathTransforminverse in interface MathTransform2Dinverse in class AbstractMathTransform2Dpublic static void resetWarnings()
UnitaryProjection
instance may log a warning the first time they are given coordinates outside their area of
validity. Subsequent coordinates outside the area of validity are silently projected in order
to avoid flowing the log with warnings. In case of suspicion, this method may be invoked in
order to force all projections to log again their first out-of-bounds coordinates.
Multi-threading
Calls to this method have immediate effect in the invoker thread. The effect in other
threads may be delayed by some arbitrary amount of time. This method works only on a
"best effort" basis.
CRS.reset(String)protected final UnitaryProjection.Parameters getUnmarshalledParameters()
getUnmarshalledParameters in class AbstractMathTransform2Dnull if none.public ParameterValueGroup getParameterValues()
sqrt(1 - e²), which is
consistent with the definition of UnitaryProjection.
getParameterValues in interface ParameterizedgetParameterValues in class AbstractMathTransformSingleOperation.getParameterValues()protected int computeHashCode()
computeHashCode in class AbstractMathTransform
public boolean equals(Object object,
ComparisonMode mode)
object is an instance of the same class than this, then compares
the excentricity.
If this method returns true, then for any given identical source position, the
two compared unitary projections shall compute the same target position. Many of the
projection parameters used for creating the unitary projections
are irrelevant and don't need to be known. Those projection parameters will be compared
only if the comparison mode is 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 unitary 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.
equals in interface LenientComparableequals in class AbstractMathTransformobject - The object to compare with this unitary projection for equivalence.mode - The strictness level of the comparison. Default to STRICT.
true if the given object is equivalent to this unitary projection.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||