org.geotools.referencing.operation.projection
Class MapProjection

java.lang.Object
  org.geotools.referencing.wkt.Formattable
      org.geotools.referencing.operation.transform.AbstractMathTransform
          org.geotools.referencing.operation.projection.MapProjection

All Implemented Interfaces:

org.opengis.referencing.operation.MathTransform, org.opengis.referencing.operation.MathTransform2D, java.io.Serializable

Direct Known Subclasses:

AlbersEqualArea, EquidistantCylindrical, LambertConformal, Mercator, NewZealandMapGrid, ObliqueMercator, Orthographic, Stereographic, TransverseMercator

public abstract class MapProjection

extends AbstractMathTransform

implements org.opengis.referencing.operation.MathTransform2D, java.io.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

Version:

$Id: MapProjection.java 17587 2006-01-13 03:43:41Z desruisseaux $

Author:

Andr? Gosselin, Martin Desruisseaux, Rueben Schulz

See Also:

Map projections on MathWorld, Map projections on the atlas of Canada, Serialized Form

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 if this projection is spherical.
protected double	latitudeOfOrigin Latitude of origin in radians.
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.

Constructor Summary

protected

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

Method Summary

boolean	equals(java.lang.Object object) Compares the specified object with this map projection for equality.
abstract org.opengis.parameter.ParameterDescriptorGroup	getParameterDescriptors() Returns the parameter descriptors for this map projection.
org.opengis.parameter.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 assertion, if enabled.
int	hashCode() Returns a hash value for this map projection.
org.opengis.referencing.operation.MathTransform	inverse() Returns the inverse of this map projection.
protected abstract java.awt.geom.Point2D	inverseTransformNormalized(double x, double y, java.awt.geom.Point2D ptDst) Transforms the specified coordinate and stores the result in .
void	transform(double[] src, int srcOffset, double[] dest, int dstOffset, int numPts) Transforms a list of coordinate point ordinal values.
void	transform(float[] src, int srcOffset, float[] dest, int dstOffset, int numPts) Transforms a list of coordinate point ordinal values.
java.awt.geom.Point2D	transform(java.awt.geom.Point2D ptSrc, java.awt.geom.Point2D ptDst) Transforms the specified and stores the result in .
protected abstract java.awt.geom.Point2D	transformNormalized(double x, double y, java.awt.geom.Point2D ptDst) Transforms the specified coordinate and stores the result in .

Methods inherited from class org.geotools.referencing.operation.transform.AbstractMathTransform

createTransformedShape, derivative, derivative, ensureNonNull, formatWKT, getDimSource, getDimTarget, isIdentity, needCopy, rollLongitude, transform

Methods inherited from class org.geotools.referencing.wkt.Formattable

toString, toWKT, toWKT, toWKT

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.opengis.referencing.operation.MathTransform2D

createTransformedShape, derivative

Methods inherited from interface org.opengis.referencing.operation.MathTransform

derivative, isIdentity, toWKT, transform

Field Detail

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

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 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(org.opengis.parameter.ParameterValueGroup values)
                 throws org.opengis.parameter.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:

org.opengis.parameter.ParameterNotFoundException - if a mandatory parameter is missing.

Method Detail

getParameterDescriptors

public abstract org.opengis.parameter.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 .

See Also:

OperationMethod.getParameters()

getParameterValues

public org.opengis.parameter.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 org.opengis.referencing.operation.MathTransform

Specified by:

getSourceDimensions in class AbstractMathTransform

getTargetDimensions

public final int getTargetDimensions()

Returns the dimension of output points.

Specified by:

getTargetDimensions in interface org.opengis.referencing.operation.MathTransform

Specified by:

getTargetDimensions in class AbstractMathTransform

inverseTransformNormalized

protected abstract java.awt.geom.Point2D inverseTransformNormalized(double x,
                                                                    double y,
                                                                    java.awt.geom.Point2D ptDst)
                                                             throws ProjectionException

Transforms the specified coordinate and stores the result in . This method returns longitude as x values in the range and latitude as y values in the range . It will be checked by the caller, so this method doesn't need to performs this check.

Input coordinates are also guarenteed to have the falseEasting and falseNorthing removed and be divided by globalScale before this method is invoked. After this method is invoked, the centralMeridian is added to the results in . This means that projections that implement this method are performed on an ellipse (or sphere) with a semiMajor axis of 1.0.

In PROJ.4, the same standardization, described above, is handled by . 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 , or . Ordinates will be in radians.

Returns:

the coordinate point after transforming , and storing the result in .

Throws:

ProjectionException - if the point can't be transformed.

To Do:

The argument will be removed and the return type changed if RFE 4222792 is implemented efficiently in a future J2SE release (maybe J2SE 1.6?).

transformNormalized

protected abstract java.awt.geom.Point2D transformNormalized(double x,
                                                             double y,
                                                             java.awt.geom.Point2D ptDst)
                                                      throws ProjectionException

Transforms the specified coordinate and stores the result in . This method is guaranteed to be invoked with values of x in the range and values of y in the range .

Coordinates are also guaranteed to have the centralMeridian removed from x before this method is invoked. After this method is invoked, the results in 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 semiMajor axis of 1.0.

In PROJ.4, the same standardization, described above, is handled by . 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 x or apply the semiMajor ('a' or 'R').

Parameters:

x - The longitude of the coordinate, in radians.

y - The latitude of the coordinate, in radians.

ptDst - the specified coordinate point that stores the result of transforming , or . Ordinates will be in a dimensionless unit, as a linear distance on a unit sphere or ellipse.

Returns:

the coordinate point after transforming , and storing the result in .

Throws:

ProjectionException - if the point can't be transformed.

To Do:

The argument will be removed and the return type changed if RFE 4222792 is implemented efficiently in a future J2SE release (maybe J2SE 1.6?).

transform

public final java.awt.geom.Point2D transform(java.awt.geom.Point2D ptSrc,
                                             java.awt.geom.Point2D ptDst)
                                      throws ProjectionException

Transforms the specified and stores the result in .

This method standardizes the source 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 call.

Specified by:

transform in interface org.opengis.referencing.operation.MathTransform2D

Overrides:

transform in class AbstractMathTransform

Parameters:

ptSrc - the specified coordinate point to be transformed. Ordinates must be in degrees.

ptDst - the specified coordinate point that stores the result of transforming , or . Ordinates will be in metres.

Returns:

the coordinate point after transforming and storing the result in .

Throws:

ProjectionException - if the point can't be transformed.

See Also:

MathTransform2D.transform(Point2D,Point2D)

transform

public final void transform(double[] src,
                            int srcOffset,
                            double[] dest,
                            int dstOffset,
                            int numPts)
                     throws ProjectionException

Transforms a list of coordinate point ordinal values. Ordinates must be (longitude,latitude) pairs in degrees.

Specified by:

transform in interface org.opengis.referencing.operation.MathTransform

Throws:

ProjectionException - if a point can't be transformed. This method try 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[] src,
                            int srcOffset,
                            float[] dest,
                            int dstOffset,
                            int numPts)
                     throws ProjectionException

Transforms a list of coordinate point ordinal values. Ordinates must be (longitude,latitude) pairs in degrees.

Specified by:

transform in interface org.opengis.referencing.operation.MathTransform

Overrides:

transform in class AbstractMathTransform

Throws:

ProjectionException - if a point can't be transformed. This method try 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 org.opengis.referencing.operation.MathTransform inverse()

Returns the inverse of this map projection.

Specified by:

inverse in interface org.opengis.referencing.operation.MathTransform

Overrides:

inverse in class AbstractMathTransform

getToleranceForAssertions

protected double getToleranceForAssertions(double longitude,
                                           double latitude)

Maximal error (in metres) tolerated for assertion, 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 AssertionError will be thrown. Subclasses should override this method if they need to relax the tolerance level.

Parameters:

longitude - The longitude in degrees.

latitude - The latitude in degrees.

Returns:

The tolerance level for assertions, in meters.

hashCode

public int hashCode()

Returns a hash value for this map projection.

Overrides:

hashCode in class AbstractMathTransform

equals

public boolean equals(java.lang.Object object)

Compares the specified object with this map projection for equality.

Overrides:

equals in class AbstractMathTransform