MapProjection (Geotools modules 14-SNAPSHOT API)

Object
- Formattable
- - AbstractMathTransform
  - - MapProjection

All Implemented Interfaces:

Serializable, MathTransform, MathTransform2D

Direct Known Subclasses:

AlbersEqualArea, CassiniSoldner, EckertIV, EquidistantConic, EquidistantCylindrical, Krovak, LambertAzimuthalEqualArea, LambertConformal, Mercator, Mollweide, NewZealandMapGrid, ObliqueMercator, Orthographic, Polyconic, Robinson, Sinusoidal, Stereographic, TransverseMercator, WinkelTripel, WorldVanDerGrintenI
```
public abstract class MapProjection
extends AbstractMathTransform
implements MathTransform2D, Serializable
```
Base class for transformation services between ellipsoidal and cartographic projections. This base class provides the basic feature needed for all methods (no need to overrides methods). Subclasses must "only" implements the following methods:
NOTE:Serialization of this class is appropriate for short-term storage or RMI use, but will probably not be compatible with future version. For long term storage, WKT (Well Know Text) or XML (not yet implemented) are more appropriate.
Since:

2.0

Author:

André Gosselin, Martin Desruisseaux (PMO, IRD), Rueben Schulz

See Also:
Map projections on MathWorld, Map projections on the atlas of Canada, Serialized Form

Tutorial:

How to add new projections

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class MapProjection.AbstractProvider
The base provider for MapProjections.

Nested Classes
Modifier and Type	Class and Description
`static class`	`MapProjection.AbstractProvider` The base provider for `MapProjection`s.

Field Summary

Fields
Modifier and Type	Field and Description
`protected double`	`centralMeridian` Central longitude in radians.
`protected double`	`en0` Constant needed for the `mlfn method.`
`protected double`	`en1` Constant needed for the `mlfn method.`
`protected double`	`en2` Constant needed for the `mlfn method.`
`protected double`	`en3` Constant needed for the `mlfn method.`
`protected double`	`en4` Constant needed for the `mlfn method.`
`protected double`	`excentricity` Ellipsoid excentricity, equals 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.
`protected double`	`falseEasting` False easting, in metres.
`protected double`	`falseNorthing` False northing, in metres.
`protected double`	`globalScale` Global scale factor.
`protected boolean`	`invertible` Marks if the projection is invertible.
`protected boolean`	`isSpherical` `true` if this projection is spherical.
`protected double`	`latitudeOfOrigin` Latitude of origin in radians.
`protected static Logger`	`LOGGER` The projection package logger
`protected double`	`scaleFactor` The scale factor.
`protected double`	`semiMajor` Length of semi-major axis, in metres.
`protected double`	`semiMinor` Length of semi-minor axis, in metres.
`static boolean`	`SKIP_SANITY_CHECKS` A global variable use to disable the reciprocal distance checks made when assertions are enabled.

Fields inherited from class Formattable
SINGLE_LINE

Constructor Summary

Constructors
Modifier Constructor and Description

protected MapProjection(ParameterValueGroup values)
Constructs a new map projection from the suplied parameters.

Constructors
Modifier	Constructor and Description
`protected`	`MapProjection(ParameterValueGroup values)` Constructs a new map projection from the suplied parameters.

Method Summary

Methods
Modifier and Type	Method and Description
`protected boolean`	`checkReciprocal(Point2D point, Point2D target, boolean inverse)` Check if the transform of `point` is close enough to `target`.
`boolean`	`equals(Object object)` Compares the specified object with this map projection for equality.
`abstract ParameterDescriptorGroup`	`getParameterDescriptors()` Returns the parameter descriptors for this map projection.
`ParameterValueGroup`	`getParameterValues()` Returns the parameter values for this map projection.
`int`	`getSourceDimensions()` Returns the dimension of input points.
`int`	`getTargetDimensions()` Returns the dimension of output points.
`protected double`	`getToleranceForAssertions(double longitude, double latitude)` Maximal error (in metres) tolerated for assertions, if enabled.
`int`	`hashCode()` Returns a hash value for this map projection.
`protected double`	`inv_mlfn(double arg)` Calculates the latitude (`phi`) from a meridian distance.
`MathTransform2D`	`inverse()` Returns the inverse of this map projection.
`protected abstract Point2D`	`inverseTransformNormalized(double x, double y, Point2D ptDst)` Transforms the specified coordinate and stores the result in `ptDst`.
`protected double`	`mlfn(double phi, double sphi, double cphi)` Calculates the meridian distance.
`protected double`	`orthodromicDistance(Point2D source, Point2D target)` Returns the orthodromic distance between the two specified points using a spherical approximation.
`static void`	`resetWarnings()` Resets the warning status of all projections in the current JVM.
`void`	`transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)` Transforms a list of coordinate point ordinal values.
`void`	`transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts)` Transforms a list of coordinate point ordinal values.
`Point2D`	`transform(Point2D ptSrc, Point2D ptDst)` Transforms the specified `ptSrc` and stores the result in `ptDst`.
`protected abstract Point2D`	`transformNormalized(double lambda, double phi, Point2D ptDst)` Transforms the specified coordinate and stores the result in `ptDst`.

Methods inherited from class AbstractMathTransform
createTransformedShape, derivative, derivative, ensureNonNull, formatWKT, getName, isIdentity, needCopy, rollLongitude, transform, transform, transform

Methods inherited from class Formattable
cleanupThreadLocals, toString, toWKT, 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

- Field Detail
  - SKIP_SANITY_CHECKS
```
public static boolean SKIP_SANITY_CHECKS
```
    A global variable use to disable the reciprocal distance checks made when assertions are enabled. This allows tests to work in "real world" conditions, where users often ask for points that are way to far from the correct area of usage of projections
  - LOGGER
```
protected static final Logger LOGGER
```
    The projection package logger
  - excentricity
```
protected final double excentricity
```
    Ellipsoid excentricity, equals to sqrt(excentricitySquared). Value 0 means that the ellipsoid is spherical.
    
    See Also:
    excentricitySquared, isSpherical
  - excentricitySquared
```
protected final 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.
    
    See Also:
    excentricity, semiMajor, semiMinor, isSpherical
  - isSpherical
```
protected final boolean isSpherical
```
    true if this projection is spherical. Spherical model has identical semi major and semi minor axis length, and an excentricity zero.
    
    See Also:
    excentricity, semiMajor, semiMinor
  - semiMajor
```
protected final double semiMajor
```
    Length of semi-major axis, in metres. This is named 'a' or 'R' (Radius in spherical cases) in Snyder.
    
    See Also:
    excentricity, semiMinor
  - semiMinor
```
protected final double semiMinor
```
    Length of semi-minor axis, in metres. This is named 'b' in Snyder.
    
    See Also:
    excentricity, semiMajor
  - centralMeridian
```
protected double centralMeridian
```
    Central longitude in radians. Default value is 0, the Greenwich meridian. This is called 'lambda0' in Snyder.
    Consider this field as final. It is not final only because some classes need to modify it at construction time.
  - latitudeOfOrigin
```
protected double latitudeOfOrigin
```
    Latitude of origin in radians. Default value is 0, the equator. This is called 'phi0' in Snyder.
    Consider this field as final. It is not final only because some classes need to modify it at construction time.
  - scaleFactor
```
protected double scaleFactor
```
    The scale factor. Default value is 1. Named 'k' in Snyder.
    Consider this field as final. It is not final only because some classes need to modify it at construction time.
  - falseEasting
```
protected final double falseEasting
```
    False easting, in metres. Default value is 0.
  - falseNorthing
```
protected final double falseNorthing
```
    False northing, in metres. Default value is 0.
  - globalScale
```
protected double globalScale
```
    Global scale factor. Default value globalScale is equal to semiMajor×scaleFactor.
    Consider this field as final. It is not final only because some classes need to modify it at construction time.
  - en0
```
protected double en0
```
    Constant needed for the mlfn method. Setup at construction time.
  en1 protected double en1 Constant needed for the mlfn method. Setup at construction time. en2 protected double en2 Constant needed for the mlfn method. Setup at construction time. en3 protected double en3 Constant needed for the mlfn method. Setup at construction time. en4 protected double en4 Constant needed for the mlfn method. Setup at construction time. invertible protected boolean invertible Marks if the projection is invertible. The vast majority is, subclasses can override.
Constructor Detail MapProjection protected MapProjection(ParameterValueGroup values) throws ParameterNotFoundException Constructs a new map projection from the suplied parameters. Parameters: values - The parameter values in standard units. The following parameter are recognized: "semi_major" (mandatory: no default) "semi_minor" (mandatory: no default) "central_meridian" (default to 0°) "latitude_of_origin" (default to 0°) "scale_factor" (default to 1 ) "false_easting" (default to 0 ) "false_northing" (default to 0 ) Throws: ParameterNotFoundException - if a mandatory parameter is missing. Method Detail getParameterDescriptors public abstract ParameterDescriptorGroup getParameterDescriptors() Returns the parameter descriptors for this map projection. This is used for a providing a default implementation of getParameterValues(), as well as arguments checking. Overrides: getParameterDescriptors in class AbstractMathTransform Returns: The parameter descriptors for this math transform, or null. See Also: OperationMethod.getParameters() getParameterValues public ParameterValueGroup getParameterValues() Returns the parameter values for this map projection. Overrides: getParameterValues in class AbstractMathTransform Returns: A copy of the parameter values for this map projection. See Also: Operation.getParameterValues() getSourceDimensions public final int getSourceDimensions() Returns the dimension of input points. Specified by: getSourceDimensions in interface MathTransform Specified by: getSourceDimensions in class AbstractMathTransform Returns: The dimension of input points. getTargetDimensions public final int getTargetDimensions() Returns the dimension of output points. Specified by: getTargetDimensions in interface MathTransform Specified by: getTargetDimensions in class AbstractMathTransform Returns: The dimension of output points. orthodromicDistance protected double orthodromicDistance(Point2D source, Point2D target) Returns the orthodromic distance between the two specified points using a spherical approximation. This is used for assertions only. checkReciprocal protected boolean checkReciprocal(Point2D point, Point2D target, boolean inverse) throws ProjectionException Check if the transform of point is close enough to target. "Close enough" means that the two points are separated by a distance shorter than getToleranceForAssertions(double, double). This method is used for assertions with J2SE 1.4. Parameters: point - Point to transform, in decimal degrees if inverse is false. target - Point to compare to, in metres if inverse is false. inverse - true for an inverse transform instead of a direct one. Returns: true if the two points are close enough. Throws: ProjectionException inverseTransformNormalized protected abstract Point2D inverseTransformNormalized(double x, double y, Point2D ptDst) throws ProjectionException Transforms the specified coordinate and stores the result in ptDst. This method returns longitude as x values in the range [-PI..PI] and latitude as y values in the range [-PI/2..PI/2]. It will be checked by the caller, so this method doesn't need to performs this check. Input coordinates have the falseEasting and falseNorthing removed and are divided by globalScale before this method is invoked. After this method is invoked, the centralMeridian is added to the x results in ptDst. This means that projections that implement this method are performed on an ellipse (or sphere) with 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. In the equations of Snyder, falseEasting, falseNorthing and scaleFactor are usually not given. When implementing these equations here, you will not need to add the centralMeridian to the output longitude or remove the semiMajor (a or R). Parameters: x - The easting of the coordinate, linear distance on a unit sphere or ellipse. y - The northing of the coordinate, linear distance on a unit sphere or ellipse. ptDst - the specified coordinate point that stores the result of transforming ptSrc, or null. Ordinates will be in radians. Returns: the coordinate point after transforming x, y and storing the result in ptDst. Throws: ProjectionException - if the point can't be transformed. transformNormalized protected abstract Point2D transformNormalized(double lambda, double phi, Point2D ptDst) throws ProjectionException Transforms the specified coordinate and stores the result in ptDst. This method is usually (but not guaranteed) to be invoked with values of x in the range [-PI..PI] and values of y in the range [-PI/2..PI/2]. Values outside those ranges are accepted (sometime with a warning logged) on the assumption that most implementations use those values only in trigonometric functions like sin and cos. Coordinates have the centralMeridian removed from lambda before this method is invoked. After this method is invoked, the results in ptDst are multiplied by globalScale, and the falseEasting and falseNorthing are added. This means that projections that implement this method are performed on an ellipse (or sphere) with a semi-major axis 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. In the equations of Snyder, falseEasting, falseNorthing and scaleFactor are usually not given. When implementing these equations here, you will not need to remove the centralMeridian from lambda or apply the semiMajor (a or R). Parameters: lambda - The longitude of the coordinate, in radians. phi - The latitude of the coordinate, in radians. ptDst - the specified coordinate point that stores the result of transforming ptSrc, or null. Ordinates will be in a dimensionless unit, as a linear distance on a unit sphere or ellipse. Returns: the coordinate point after transforming (lambda, phi) and storing the result in ptDst. Throws: ProjectionException - if the point can't be transformed. transform public final Point2D transform(Point2D ptSrc, Point2D ptDst) throws ProjectionException Transforms the specified ptSrc and stores the result in ptDst. This method standardizes the source x coordinate by removing the centralMeridian, before invoking transformNormalized(x, y, ptDst). It also multiplies by globalScale and adds the falseEasting and falseNorthing to the point returned by the transformNormalized(...) call. Specified by: transform in interface MathTransform2D Overrides: transform in class AbstractMathTransform Parameters: ptSrc - the specified coordinate point to be transformed. Ordinates must be in decimal degrees. ptDst - the specified coordinate point that stores the result of transforming ptSrc, or null. Ordinates will be in metres. Returns: the coordinate point after transforming ptSrc and storing the result in ptDst. Throws: ProjectionException - if the point can't be transformed. See Also: MathTransform2D.transform(Point2D,Point2D) transform public final void transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws ProjectionException Transforms a list of coordinate point ordinal values. Ordinates must be (longitude,latitude) pairs in decimal degrees. Specified by: transform in interface MathTransform 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 than 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: ProjectionException - if a point can't be transformed. This method tries to transform every points even if some of them can't be transformed. Non-transformable points will have value Double.NaN. If more than one point can't be transformed, then this exception may be about an arbitrary point. transform public final void transform(float[] srcPts, int srcOff, float[] dstPts, int dstOff, int numPts) throws ProjectionException Transforms a list of coordinate point ordinal values. Ordinates must be (longitude,latitude) pairs in decimal degrees. 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 than 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: ProjectionException - if a point can't be transformed. This method tries to transform every points even if some of them can't be transformed. Non-transformable points will have value Float.NaN. If more than one point can't be transformed, then this exception may be about an arbitrary point. inverse public final MathTransform2D inverse() throws NoninvertibleTransformException Returns the inverse of this map projection. Specified by: inverse in interface MathTransform Specified by: inverse in interface MathTransform2D Overrides: inverse in class AbstractMathTransform Returns: The inverse transform. Throws: NoninvertibleTransformException - if the transform can't be inversed. getToleranceForAssertions protected double getToleranceForAssertions(double longitude, double latitude) Maximal error (in metres) tolerated for assertions, if enabled. When assertions are enabled, every direct projection is followed by an inverse projection, and the result is compared to the original coordinate. If a distance greater than the tolerance level is found, then an ProjectionException will be thrown. Subclasses should override this method if they need to relax the tolerance level. Parameters: longitude - The longitude in decimal degrees. latitude - The latitude in decimal degrees. Returns: The tolerance level for assertions, in meters. resetWarnings public static void resetWarnings() Resets the warning status of all projections in the current JVM. Every MapProjection 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's thread. The effect in other threads may be delayed by some arbitrary amount of time. This method works only on a "best effort" basis. Since: 2.5 See Also: CRS.reset(java.lang.String) hashCode public int hashCode() Returns a hash value for this map projection. Overrides: hashCode in class AbstractMathTransform equals public boolean equals(Object object) Compares the specified object with this map projection for equality. Overrides: equals in class AbstractMathTransform Parameters: object - The object to compare with this transform. Returns: true if the given object is a transform of the same class and if, given identical source position, the transformed position would be the equals. mlfn protected final double mlfn(double phi, double sphi, double cphi) Calculates the meridian distance. This is the distance along the central meridian from the equator to phi. Accurate to < 1e-5 meters when used in conjuction with typical major axis values. Parameters: phi - latitude to calculate meridian distance for. sphi - sin(phi). cphi - cos(phi). Returns: meridian distance for the given latitude. inv_mlfn protected final double inv_mlfn(double arg) throws ProjectionException Calculates the latitude (phi) from a meridian distance. Determines phi to TOL (1e-11) radians, about 1e-6 seconds. Parameters: arg - meridian distance to calulate latitude for. Returns: the latitude of the meridian distance. Throws: ProjectionException - if the itteration does not converge.

Class MapProjection

Nested Class Summary

Field Summary

Fields inherited from class Formattable

Constructor Summary

Method Summary

Methods inherited from class AbstractMathTransform

Methods inherited from class Formattable

Methods inherited from class Object

Methods inherited from interface MathTransform2D

Methods inherited from interface MathTransform

Field Detail

SKIP_SANITY_CHECKS

LOGGER

excentricity

excentricitySquared

isSpherical

semiMajor

semiMinor

centralMeridian

latitudeOfOrigin

scaleFactor

falseEasting

falseNorthing

globalScale

en0

en1

en2

en3

en4

invertible

Constructor Detail

MapProjection

Method Detail

getParameterDescriptors

getParameterValues

getSourceDimensions

getTargetDimensions

orthodromicDistance

checkReciprocal

inverseTransformNormalized

transformNormalized

transform

transform

transform

inverse

getToleranceForAssertions

resetWarnings

hashCode

equals

mlfn

inv_mlfn