org.geotools.referencing.operation.projection
Class MapProjection

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, 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:

• getParameterValues()
• transformNormalized(double, double, java.awt.geom.Point2D)
• inverseTransformNormalized(double, double, java.awt.geom.Point2D)

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

static class

MapProjection.AbstractProvider The base provider for MapProjections.

Field Summary

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.

Fields inherited from class Formattable

SINGLE_LINE

Constructor Summary

protected

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

Method Summary

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

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.