org.geotools.referencing.operation.projection
Class MapProjection

Object
  extended by Formattable
      extended by AbstractMathTransform
          extended by MapProjection
All Implemented Interfaces:
Serializable, MathTransform, MathTransform2D
Direct Known Subclasses:
AlbersEqualArea, EquidistantCylindrical, Krovak, LambertAzimuthalEqualArea, LambertConformal, Mercator, NewZealandMapGrid, ObliqueMercator, Orthographic, Stereographic, TransverseMercator

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

Nested Class Summary
static class MapProjection.AbstractProvider
          The base provider for MapProjections.
 
Field Summary
protected  double centralMeridian
          Central longitude in radians.
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 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
 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.
 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.
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
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
 

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.

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

getTargetDimensions

public final int getTargetDimensions()
Returns the dimension of output points.

Specified by:
getTargetDimensions in interface MathTransform
Specified by:
getTargetDimensions in class AbstractMathTransform

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
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
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()
Returns the inverse of this map projection.

Specified by:
inverse in interface MathTransform
Specified by:
inverse in interface MathTransform2D
Overrides:
inverse in class AbstractMathTransform

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.


Copyright © 1996-2009 Geotools. All Rights Reserved.