ilog.views.maps.projection
Class IlvProjection

java.lang.Object
  ilog.views.maps.projection.IlvProjection

All Implemented Interfaces:

IlvPersistentObject, Serializable

Direct Known Subclasses:

IlvAzimuthalEquidistantProjection, IlvCassiniProjection, IlvConicProjection, IlvCylindricalEqualAreaProjection, IlvEckert4Projection, IlvEckert6Projection, IlvEquidistantCylindricalProjection, IlvGeographicProjection, IlvGnomonicProjection, IlvLambertAzimuthalEqualAreaProjection, IlvMercatorProjection, IlvMillerCylindricalProjection, IlvMollweideProjection, IlvObliqueMercatorProjection, IlvOrthographicProjection, IlvPolyconicProjection, IlvRobinsonProjection, IlvSinusoidalProjection, IlvStereographicProjection, IlvTransverseMercatorProjection, IlvWagner4Projection

public abstract class IlvProjection
extends Object
implements Serializable, IlvPersistentObject

All projections in the package inherit from this abstract class.
A map projection is a mathematical transformation between ellipsoidal coordinates (latitude/longitude) and planar coordinates.
The mapping of coordinates on spherical or ellipsoidal coordinates on a planar shape cannot be done without deformations. The aim of projections is to map the coordinates so that the deformations are minimal on the area of the map.

Since JViews 5.0, the datum of IlvProjection is now ignored. Datum conversions are now done when converting from one coordinate system from another.

See Also:

IlvProjectedCoordinateSystem, Serialized Form

Field Summary

static int	CONFORMAL Used to designate a projection that is Conformal.
static int	EQUAL_AREA Used to designate a projection that is Equal Area.
static int	NONE Used to designate a projection that is neither Conformal nor Equal Area.

Constructor Summary

protected	IlvProjection(boolean ellipsoidEnabled, boolean inverseEnabled, int property) Creates a new instance of the class IlvProjection.
protected	IlvProjection(IlvInputStream stream) Reads the object from an IlvInputStream.
protected	IlvProjection(IlvProjection source) Creates a new IlvProjection by copying an existing one.

Method Summary

protected void	addDescription(StringBuffer buffer) Converts the projection into a String (Evenden's format).
protected double	adjustLongitude(double lon) Reduces the longitude to -PI PI.
abstract IlvProjection	copy() Copies the object.
protected void	eForward(IlvCoordinate ll) Implements the projection for an ellipsoid.
protected void	eInverse(IlvCoordinate xy) Implements the inverse projection for an ellipsoid.
boolean	equals(Object obj) Compares the string representation of projections using the toString methods.
void	forward(IlvCoordinate ll) Converts the parameter IlvCoordinate representing a latitude and a longitude to Cartesian coordinates (x,y).
void	forward(IlvPoint ll) Converts the parameter IlvPoint representing a latitude and a longitude to Cartesian coordinates (x,y).
double	getCentralMeridian() Returns the central meridian of the projection.
double	getCentralParallel() Returns the central parallel of the projection.
IlvHorizontalDatum	getDatum() Deprecated. Since JViews 5.0, the datum is managed at the coordinate system level.
IlvEllipsoid	getEllipsoid() Returns the ellipsoid used for the projection.
double	getFalseEasting() Returns the false easting of the projection.
double	getFalseNorthing() Returns the false northing of the projection.
static IlvProjection	GetProjection(String description) Returns a projection from a string in Evenden's format.
int	getProperty() Returns the property of the projection.
IlvLinearUnit	getUnit() Returns the unit used to measure lengths in this projection.
IlvCoordinate	getXYOffset() Returns the false easting and the false northing.
void	inverse(IlvCoordinate xy) Converts the parameter IlvCoordinate representing Cartesian coordinates to a latitude and a longitude.
void	inverse(IlvPoint xy) Converts the IlvPoint representing Cartesian coordinates to a latitude and a longitude.
IlvPoint	inverse(MouseEvent e) Converts the coordinates of the MouseEvent to a latitude and a longitude expressed in radians.
boolean	isEllipsoidEnabled() Returns true if non-spherical ellipsoids can be used for the projection.
boolean	isGeocentric() Returns true if the projection uses geocentric latitudes.
boolean	isInverseEnabled() Returns true if the inverse function is supported by the projection.
boolean	isUsingLongitudeReduction() Returns true if the projection uses range reduction for longitudes.
void	setCentralMeridian(double lon) Sets the central meridian of the projection.
void	setCentralParallel(double lat) Sets the central parallel of the projection.
void	setDatum(IlvHorizontalDatum datum) Deprecated. Since JViews 5.0, the datum is managed at the coordinate system level.
void	setEllipsoid(IlvEllipsoid ellipsoid) Sets the ellipsoid used for the projection.
void	setFalseEasting(double falseEasting) Specifies the false easting of the projection.
void	setFalseNorthing(double falseNorthing) Specifies the false northing of the projection.
void	setGeocentric(boolean geoc) Specifies whether the projection uses geocentric or geodetic latitudes.
void	setLLCenter(double lon, double lat) Specifies the central meridian and the central parallel associated with the projection.
void	setUnit(IlvLinearUnit unit) Sets the unit of the projection.
void	setUsingLongitudeReduction(boolean use) Specifies whether the projection uses longitude reduction.
void	setXYOffset(IlvCoordinate center) Specifies the false easting and the false northing.
protected abstract void	sForward(IlvCoordinate ll) Implements the projection for a sphere.
protected void	sInverse(IlvCoordinate xy) Implements the inverse projection for a sphere.
void	write(IlvOutputStream stream) Writes the object to an IlvOutputStream.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NONE

public static final int NONE

Used to designate a projection that is neither Conformal nor Equal Area.

See Also:

getProperty(), Constant Field Values

CONFORMAL

public static final int CONFORMAL

Used to designate a projection that is Conformal.

See Also:

getProperty(), Constant Field Values

EQUAL_AREA

public static final int EQUAL_AREA

Used to designate a projection that is Equal Area.

See Also:

getProperty(), Constant Field Values

Constructor Detail

IlvProjection

protected IlvProjection(boolean ellipsoidEnabled,
                        boolean inverseEnabled,
                        int property)

Creates a new instance of the class IlvProjection.

Parameters:

ellipsoidEnabled - It is true if non-spherical ellipsoids can be used for the projection. Projections supporting non-spherical ellipsoids should implement the eForward function.

inverseEnabled - It is true if the projection implements an inverse function. Projections implementing an inverse function should implement the sInverse and the eInverse functions, if ellipsoids are supported.

property - The property of the projection (NONE, CONFORMAL, EQUAL_AREA).

IlvProjection

protected IlvProjection(IlvProjection source)

Creates a new IlvProjection by copying an existing one.

Parameters:

source - The graphic object that is copied.

Since:

JViews 3.0

IlvProjection

protected IlvProjection(IlvInputStream stream)
                 throws IlvReadFileException

Reads the object from an IlvInputStream.

Parameters:

stream - The input stream.

Throws:

IlvReadFileException - If the format is not correct.

Since:

JViews 3.0

Method Detail

copy

public abstract IlvProjection copy()

Copies the object.

Returns:

A copy of the object. This method copies the object by calling a constructor defined like this: public <CLASSNAME>(<CLASSNAME> source).

Since:

JViews 3.0

forward

public void forward(IlvPoint ll)
             throws IlvToleranceConditionException,
                    IlvUnsupportedProjectionFeature

Converts the parameter IlvPoint representing a latitude and a longitude to Cartesian coordinates (x,y).

Parameters:

ll - The longitude/latitude coordinates in radians (x = longitude, y = latitude).

Throws:

IlvToleranceConditionException - If the latitude or the longitude are not within the tolerated limits.

IlvUnsupportedProjectionFeature - If the projection does not support non-spherical ellipsoids and the ellipsoid used for the projection is not a sphere.

See Also:

IlvProjectionUtil.DegreeToRadian(double), IlvProjectionUtil.DMSToRadian(java.lang.String), isEllipsoidEnabled()

forward

public void forward(IlvCoordinate ll)
             throws IlvToleranceConditionException,
                    IlvUnsupportedProjectionFeature

Converts the parameter IlvCoordinate representing a latitude and a longitude to Cartesian coordinates (x,y). The longitude must be in the range [-PI ; PI]. The latitude must be in the range [-PI/2; PI/2]. If required, the function converts the latitude to a geocentric latitude. Then it centers the longitude and adjusts it. The forward projection is computed either by the sForward or the eForward methods depending on whether the ellipsoid is a sphere or not. The implementation of this method varies depending on the projection. Its result is then converted to the appropriate measurement unit.

Parameters:

ll - The longitude/latitude coordinates in radians (x = longitude, y = latitude).

Throws:

IlvToleranceConditionException - If the latitude or the longitude are not within the tolerated limits.

IlvUnsupportedProjectionFeature - If the projection does not support non-spherical ellipsoids and the ellipsoid used for the projection is not a sphere.

See Also:

isEllipsoidEnabled(), IlvProjectionUtil.DegreeToRadian(double), IlvProjectionUtil.DMSToRadian(java.lang.String)

inverse

public void inverse(IlvPoint xy)
             throws IlvUnsupportedProjectionFeature,
                    IlvToleranceConditionException

Converts the IlvPoint representing Cartesian coordinates to a latitude and a longitude.

Parameters:

xy - The Cartesian coordinates in the measurement unit of the projection.

Throws:

IlvUnsupportedProjectionFeature - If the inverse function is not supported by the projection.

IlvToleranceConditionException - If the values are not within the tolerated limits.

See Also:

IlvProjectionUtil.RadianToDegree(double), setUnit(ilog.views.maps.IlvLinearUnit)

inverse

public IlvPoint inverse(MouseEvent e)
                 throws IlvToleranceConditionException,
                        IlvUnsupportedProjectionFeature

Converts the coordinates of the MouseEvent to a latitude and a longitude expressed in radians.

If the component of the MouseEvent is an IlvManagerView, the method will apply the inverse transformer to the MouseEvent coordinates to get the manager coordinates.

Parameters:

e - The MouseEvent.

Throws:

IlvUnsupportedProjectionFeature - If the inverse function is not supported by the projection.

IlvToleranceConditionException - If the values are not within the tolerated limits.

See Also:

IlvProjectionUtil.RadianToDegree(double), setUnit(ilog.views.maps.IlvLinearUnit)

inverse

public void inverse(IlvCoordinate xy)
             throws IlvUnsupportedProjectionFeature,
                    IlvToleranceConditionException

Converts the parameter IlvCoordinate representing Cartesian coordinates to a latitude and a longitude. The x and y values are expressed in the measurement unit set for the projection (generally meters) unless another unit converter was set using the setUnit method. The longitude/latitude coordinates are in radians.

Parameters:

xy - The Cartesian coordinates in the measurement unit of the projection.

Throws:

IlvUnsupportedProjectionFeature - If the inverse function is not supported by the projection.

IlvToleranceConditionException - If the values are not within the tolerated limits.

See Also:

IlvProjectionUtil.RadianToDegree(double), setUnit(ilog.views.maps.IlvLinearUnit)

sForward

protected abstract void sForward(IlvCoordinate ll)
                          throws IlvToleranceConditionException

Implements the projection for a sphere.

This protected method should be implemented by the classes that extend the class IlvProjection. It is not called directly by the user, but by the IlvProjection.forward method if the ellipsoid associated with the projection is a sphere.

The method should convert the ll parameter to the projected coordinates. The various parameters associated with a projection, such as the measurement unit, the false easting or the central meridian, must not be taken into account in this method because they are processed by the calling method IlvProjection.forward. In this method, the sphere is assumed to be of radius 1.

Parameters:

ll - Longitude/latitude coordinates in radians.

Throws:

IlvToleranceConditionException - If the values are not within the tolerated limits.

eForward

protected void eForward(IlvCoordinate ll)
                 throws IlvToleranceConditionException,
                        IlvUnsupportedProjectionFeature

Implements the projection for an ellipsoid.

This protected method should be implemented by the classes that extend the class IlvProjection and that support non-spherical ellipsoids. It is not called directly by the user, but by the IlvProjection.forward method if the ellipsoid associated with the projection is not a sphere.

The method should convert the ll parameter to the projected coordinates.

The various parameters associated with a projection, such as the measurement unit, the false easting or the central meridian, must not be taken into account in this method because they are processed by the calling method IlvProjection.forward. In this method, the ellipsoid is assumed to have a semi-equatorial radius of 1.

The default implementation throws an IlvUnsupportedProjectionFeature exception.

Parameters:

ll - Longitude/latitude coordinates in radians.

Throws:

IlvToleranceConditionException - If the values are not within the tolerated limits.

IlvUnsupportedProjectionFeature - If the projection does not support non-spherical ellipsoids.

sInverse

protected void sInverse(IlvCoordinate xy)
                 throws IlvUnsupportedProjectionFeature,
                        IlvToleranceConditionException

Implements the inverse projection for a sphere.

This protected method should be implemented by the classes that extend the class IlvProjection and that support an inverse projection. It is not called directly by the user, but by the IlvProjection.inverse method if the ellipsoid associated with the projection is a sphere.

The method should convert the xy parameter to the corresponding latitude and longitude expressed in radians.

The various parameters associated with a projection, such as the measurement unit, the false easting or the central meridian, must not be taken into account in this method because they are processed by the calling method IlvProjection.inverse. In this method, the sphere is assumed to be of radius 1.

The default implementation throws an IlvUnsupportedProjectionFeature exception.

Parameters:

xy - Cartesian coordinates expressed in meters.

Throws:

IlvUnsupportedProjectionFeature - If the inverse function is not supported by the projection.

IlvToleranceConditionException - If the values not are within the tolerated limits.

See Also:

inverse(ilog.views.IlvPoint), isInverseEnabled()

eInverse

protected void eInverse(IlvCoordinate xy)
                 throws IlvUnsupportedProjectionFeature,
                        IlvToleranceConditionException

Implements the inverse projection for an ellipsoid.

This protected method should be implemented by the classes that extend the class IlvProjection and that support an inverse projection and non-spherical ellipsoids. It is not called directly by the user, but by the IlvProjection.inverse method if the ellipsoid associated with the projection is not a sphere.

The method should convert the xy parameter into the corresponding latitude and longitude expressed in radians for an ellipsoid of semi-equatorial radius of value 1.

The various parameters associated with a projection, such as the measurement unit, the false easting or the central meridian, must not be taken into account in this function because they are processed by the calling method IlvProjection.inverse. In this method, the ellipsoid is assumed to have a semi-equatorial radius of 1.

The default implementation throws an IlvUnsupportedProjectionFeature exception.

Parameters:

xy - Cartesian coordinates expressed in meters.

Throws:

IlvUnsupportedProjectionFeature - If the inverse function or non-spherical ellipsoids are not supported by the projection.

IlvToleranceConditionException - If the values are not within the tolerated limits.

See Also:

inverse(ilog.views.IlvPoint), isEllipsoidEnabled(), isInverseEnabled()

setEllipsoid

public void setEllipsoid(IlvEllipsoid ellipsoid)

Sets the ellipsoid used for the projection. By default, most of the projections use a spherical ellipsoid with a radius of 6370997 meters.

Parameters:

ellipsoid - The ellipsoid.

See Also:

IlvEllipsoid

getEllipsoid

public final IlvEllipsoid getEllipsoid()

Returns the ellipsoid used for the projection.

isGeocentric

public final boolean isGeocentric()

Returns true if the projection uses geocentric latitudes.

See Also:

setGeocentric(boolean)

setGeocentric

public final void setGeocentric(boolean geoc)

Specifies whether the projection uses geocentric or geodetic latitudes. By default, a projection uses geodetic latitudes.

Parameters:

geoc - If true, the projection uses geocentric latitudes. Otherwise, the projection uses geodetic latitudes.

See Also:

isGeocentric()

setLLCenter

public void setLLCenter(double lon,
                        double lat)

Specifies the central meridian and the central parallel associated with the projection. By default, the central parallel and the central meridian are set to 0.

Parameters:

lon - The central meridian in radians.

lat - The central parallel in radians.

See Also:

IlvProjectionUtil.DegreeToRadian(double), IlvProjectionUtil.DMSToRadian(java.lang.String)

setCentralMeridian

public final void setCentralMeridian(double lon)

Sets the central meridian of the projection.

Parameters:

lon - The central meridian in radian.

See Also:

setLLCenter(double, double)

getCentralMeridian

public final double getCentralMeridian()

Returns the central meridian of the projection.

setCentralParallel

public final void setCentralParallel(double lat)

Sets the central parallel of the projection.

Parameters:

lat - The central parallel in radians.

See Also:

setLLCenter(double, double)

getCentralParallel

public final double getCentralParallel()

Returns the central parallel of the projection.

setXYOffset

public final void setXYOffset(IlvCoordinate center)

Specifies the false easting and the false northing. The default value is (0, 0). The false easting is an offset that will be added to the x-coordinate of the projected data, and the false northing will be added to the y-coordinate of the projected data.

Parameters:

center - x is the false easting and y is the false northing. Both offsets should be expressed in meters.

getXYOffset

public final IlvCoordinate getXYOffset()

Returns the false easting and the false northing.

See Also:

setXYOffset(ilog.views.maps.IlvCoordinate)

setFalseNorthing

public final void setFalseNorthing(double falseNorthing)

Specifies the false northing of the projection.

Parameters:

falseNorthing - The offset that will be applied to the y-coordinate of the projected data. falseNorthing should be expressed in meters.

See Also:

setXYOffset(ilog.views.maps.IlvCoordinate)

getFalseNorthing

public final double getFalseNorthing()

Returns the false northing of the projection.

See Also:

getXYOffset()

setFalseEasting

public final void setFalseEasting(double falseEasting)

Specifies the false easting of the projection.

Parameters:

falseEasting - The offset that will be applied to the x-coordinate of the projected data. falseEasting should be expressed in meters.

See Also:

setXYOffset(ilog.views.maps.IlvCoordinate)

getFalseEasting

public final double getFalseEasting()

Returns the false easting of the projection.

See Also:

getXYOffset()

isUsingLongitudeReduction

public final boolean isUsingLongitudeReduction()

Returns true if the projection uses range reduction for longitudes.

See Also:

setUsingLongitudeReduction(boolean)

setUsingLongitudeReduction

public final void setUsingLongitudeReduction(boolean use)

Specifies whether the projection uses longitude reduction. By default, a projection uses range reduction. The normal geographic range for longitude is between 180E and 180W. By default, the internal range of longitude is reduced to this range. Setting the boolean flag to false disables internal range reduction. However this should be used with care in applications.

Parameters:

use - If true, the range reduction is enabled. Otherwise, it is disabled.

adjustLongitude

protected final double adjustLongitude(double lon)

Reduces the longitude to -PI PI.

Parameters:

lon - The longitude in radians.

Returns:

The adjusted longitude.

getUnit

public IlvLinearUnit getUnit()

Returns the unit used to measure lengths in this projection.

Since:

JViews 5.0

setUnit

public void setUnit(IlvLinearUnit unit)

Sets the unit of the projection.
The unit of the projection is the unit returned by the forward method of the projection, and also the unit of coordinates in input of the inverse method.
To express the projected coordinates of a projected coordinate system in different units from the projection unit, it's better to use the unit mechanism of the coordinate system.

Parameters:

unit - The unit.

Since:

JViews 5.0

See Also:

IlvProjectedCoordinateSystem

isEllipsoidEnabled

public final boolean isEllipsoidEnabled()

Returns true if non-spherical ellipsoids can be used for the projection.

isInverseEnabled

public final boolean isInverseEnabled()

Returns true if the inverse function is supported by the projection.

getProperty

public int getProperty()

Returns the property of the projection.

See Also:

NONE, CONFORMAL, EQUAL_AREA

addDescription

protected void addDescription(StringBuffer buffer)

Converts the projection into a String (Evenden's format).

Since:

JViews 7.5

GetProjection

public static IlvProjection GetProjection(String description)
                                   throws IlvBadProjectionParameter

Returns a projection from a string in Evenden's format.

Parameters:

description - A string defining a projection in Evenden's format.

Throws:

IlvBadProjectionParameter - If the string does not define a correct projection, or if a projection is not supported.

write

public void write(IlvOutputStream stream)
           throws IOException

Writes the object to an IlvOutputStream.

Specified by:

write in interface IlvPersistentObject

Parameters:

stream - The output stream.

Throws:

IOException - thrown when an exception occurs during the write operation for this object.

Since:

JViews 3.0

getDatum

public IlvHorizontalDatum getDatum()

Deprecated. Since JViews 5.0, the datum is managed at the coordinate system level.

Returns the horizontal datum of the projection. If the datum is not specified, the method returns a null pointer.

Since:

JViews 3.0

setDatum

public void setDatum(IlvHorizontalDatum datum)

Deprecated. Since JViews 5.0, the datum is managed at the coordinate system level.

Sets the horizontal datum of the projection.

Since:

JViews 3.0

equals

public boolean equals(Object obj)

Compares the string representation of projections using the toString methods.

Overrides:

equals in class Object

Since:

JViews 7.5

See Also:

Object.equals(java.lang.Object)