org.deegree_impl.model.ct
Class MathTransformFactory

java.lang.Object
  org.deegree_impl.model.ct.MathTransformFactory

public class MathTransformFactory

extends java.lang.Object

Creates math transforms. MathTransformFactory is a low level factory that is used to create MathTransform objects. Many high level GIS applications will never need to use a MathTransformFactory directly; they can use a CoordinateTransformationFactory instead. However, the MathTransformFactory class is specified here, since it can be used directly by applications that wish to transform other types of coordinates (e.g. color coordinates, or image pixel coordinates).

A math transform is an object that actually does the work of applying formulae to coordinate values. The math transform does not know or care how the coordinates relate to positions in the real world. This lack of semantics makes implementing MathTransformFactory significantly easier than it would be otherwise. For example MathTransformFactory can create affine math transforms. The affine transform applies a matrix to the coordinates without knowing how what it is doing relates to the real world. So if the matrix scales Z values by a factor of 1000, then it could be converting meters into millimeters, or it could be converting kilometers into meters.

Because math transforms have low semantic value (but high mathematical value), programmers who do not have much knowledge of how GIS applications use coordinate systems, or how those coordinate systems relate to the real world can implement MathTransformFactory. The low semantic content of math transforms also means that they will be useful in applications that have nothing to do with GIS coordinates. For example, a math transform could be used to map color coordinates between different color spaces, such as converting (red, green, blue) colors into (hue, light, saturation) colors.

Since a math transform does not know what its source and target coordinate systems mean, it is not necessary or desirable for a math transform object to keep information on its source and target coordinate systems.

Version:

1.00

Author:

OpenGIS (www.opengis.org), Martin Desruisseaux

See Also:

CT_MathTransformFactory

Nested Class Summary

private class

MathTransformFactory.Export Wrap a MathTransformFactory for use with OpenGIS.

Field Summary

private static MathTransformFactory	DEFAULT The default math transform factory.
(package private) static WeakHashSet	pool A pool of math transform.
private MathTransformProvider[]	providers List of registered math transforms.

Constructor Summary

MathTransformFactory(MathTransformProvider[] providers)
Construct a factory using the specified providers.

Method Summary

private static boolean	areInverse(MathTransform tr1, MathTransform tr2) Tests if one math transform is the inverse of the other.
MathTransform2D	createAffineTransform(java.awt.geom.AffineTransform matrix) Creates an affine transform from a matrix.
MathTransform	createAffineTransform(Matrix matrix) Creates an affine transform from a matrix.
MathTransform	createConcatenatedTransform(MathTransform tr1, MathTransform tr2) Creates a transform by concatenating two existing transforms.
MathTransform	createIdentityTransform(int dimension) Creates an identity transform of the specified dimension.
MathTransform	createParameterizedTransform(Projection projection) Convenience method for creating a transform from a projection.
MathTransform	createParameterizedTransform(java.lang.String classification, ParameterList parameters) Creates a transform from a classification name and parameters.
MathTransform	createPassThroughTransform(int firstAffectedOrdinate, MathTransform subTransform, int numTrailingOrdinates) Creates a transform which passes through a subset of ordinates to another transform.
MathTransform	createSubMathTransform(int lower, int upper, MathTransform transform) Creates a transform which retains only a portion of an other transform.
MathTransformProvider	getAffineTransformProvider(int numRow, int numCol) Create a provider for affine transforms of the specified dimension.
java.lang.String[]	getAvailableTransforms() Returns the classification names of every available transforms.
static MathTransformFactory	getDefault() Returns the default math transform factory.
MathTransformProvider	getMathTransformProvider(java.lang.String classification) Returns the provider for the specified classification.
private static Matrix	getMatrix(MathTransform transform) Returns the underlying matrix for the specified transform, or null if the matrix is unavailable.
(package private) java.lang.Object	toOpenGIS(java.lang.Object adapters) Returns an OpenGIS interface for this transform factory.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT

private static MathTransformFactory DEFAULT

The default math transform factory. This factory will be constructed only when first needed.

pool

static final WeakHashSet pool

A pool of math transform. This pool is used in order to returns instance of existing math transforms when possible.

providers

private final MathTransformProvider[] providers

List of registered math transforms.

Constructor Detail

MathTransformFactory

public MathTransformFactory(MathTransformProvider[] providers)

Construct a factory using the specified providers.

Method Detail

getDefault

public static MathTransformFactory getDefault()

Returns the default math transform factory.

createIdentityTransform

public MathTransform createIdentityTransform(int dimension)

Creates an identity transform of the specified dimension.

Parameters:

dimension - The source and target dimension.

Returns:

The identity transform.

createAffineTransform

public MathTransform2D createAffineTransform(java.awt.geom.AffineTransform matrix)

Creates an affine transform from a matrix.

Parameters:

matrix - The matrix used to define the affine transform.

Returns:

The affine transform.

createAffineTransform

public MathTransform createAffineTransform(Matrix matrix)

Creates an affine transform from a matrix.

Parameters:

matrix - The matrix used to define the affine transform.

Returns:

The affine transform.

getMatrix

private static Matrix getMatrix(MathTransform transform)

Returns the underlying matrix for the specified transform, or null if the matrix is unavailable.

areInverse

private static boolean areInverse(MathTransform tr1,
                                  MathTransform tr2)

Tests if one math transform is the inverse of the other. This implementation can't detect every case. It just detect the case when tr2 is an instance of AbstractMathTransform.Inverse.

createConcatenatedTransform

public MathTransform createConcatenatedTransform(MathTransform tr1,
                                                 MathTransform tr2)

Creates a transform by concatenating two existing transforms. A concatenated transform acts in the same way as applying two transforms, one after the other. The dimension of the output space of the first transform must match the dimension of the input space in the second transform. If you wish to concatenate more than two transforms, then you can repeatedly use this method.

Parameters:

tr1 - The first transform to apply to points.

tr2 - The second transform to apply to points.

Returns:

The concatenated transform.

createPassThroughTransform

public MathTransform createPassThroughTransform(int firstAffectedOrdinate,
                                                MathTransform subTransform,
                                                int numTrailingOrdinates)

Creates a transform which passes through a subset of ordinates to another transform. This allows transforms to operate on a subset of ordinates. For example, if you have (latitidue,longitude,height) coordinates, then you may wish to convert the height values from feet to meters without affecting the latitude and longitude values.

Parameters:

firstAffectedOrdinate - Index of the first affected ordinate.

subTransform - The sub transform.

numTrailingOrdinates - Number of trailing ordinates to pass through. Affected ordinates will range from firstAffectedOrdinate inclusive to dimTarget-numTrailingOrdinates exclusive.

Returns:

A pass through transform with the following dimensions:

 Source: firstAffectedOrdinate + subTransform.getDimSource() + numTrailingOrdinates
 Target: firstAffectedOrdinate + subTransform.getDimTarget() + numTrailingOrdinates

createSubMathTransform

public MathTransform createSubMathTransform(int lower,
                                            int upper,
                                            MathTransform transform)

Creates a transform which retains only a portion of an other transform. For example if the source coordinate system has (longitude, latitude, height) values, then a sub-transform may be used to keep only the (longitude, latitude) part. In most cases, the created sub-transform is non-invertible since it loose informations.

This transform is a special case of a non-square matrix transform with less rows than columns. However, using a createSubMathTransfom(...) method makes it easier to optimize some common cases.

Parameters:

transform - The transform.

lower - Index of the first ordinate to keep.

upper - Index of the first ordinate. Must be greater than lower.

createParameterizedTransform

public MathTransform createParameterizedTransform(java.lang.String classification,
                                                  ParameterList parameters)
                                           throws java.util.NoSuchElementException,
                                                  MissingParameterException

Creates a transform from a classification name and parameters. The client must ensure that all the linear parameters are expressed in meters, and all the angular parameters are expressed in degrees. Also, they must supply "semi_major" and "semi_minor" parameters for cartographic projection transforms.

Parameters:

classification - The classification name of the transform (e.g. "Transverse_Mercator"). Leading and trailing spaces are ignored, and comparaison is case-insensitive.

parameters - The parameter values in standard units.

Returns:

The parameterized transform.

Throws:

java.util.NoSuchElementException - if there is no transform for the specified classification.

MissingParameterException - if a parameter was required but not found.

createParameterizedTransform

public MathTransform createParameterizedTransform(Projection projection)
                                           throws java.util.NoSuchElementException,
                                                  MissingParameterException

Convenience method for creating a transform from a projection.

Parameters:

projection - The projection.

Returns:

The parameterized transform.

Throws:

java.util.NoSuchElementException - if there is no transform for the specified projection.

MissingParameterException - if a parameter was required but not found.

getAvailableTransforms

public java.lang.String[] getAvailableTransforms()

Returns the classification names of every available transforms. The returned array may have a zero length, but will never be null.

getMathTransformProvider

public MathTransformProvider getMathTransformProvider(java.lang.String classification)
                                               throws java.util.NoSuchElementException

Returns the provider for the specified classification. This provider may be used to query parameter list for a classification name (e.g. getMathTransformProvider("Transverse_Mercator").getParameterList()), or the transform name in a given locale (e.g. getMathTransformProvider("Transverse_Mercator").getName(Locale#FRENCH))

Parameters:

classification - The classification name of the transform (e.g. "Transverse_Mercator"). It should be one of the name returned by getAvailableTransforms(). Leading and trailing spaces are ignored. Comparisons are case-insensitive.

Returns:

The provider for a math transform.

Throws:

java.util.NoSuchElementException - if there is no provider registered with the specified classification name.

getAffineTransformProvider

public MathTransformProvider getAffineTransformProvider(int numRow,
                                                        int numCol)
                                                 throws java.lang.IllegalArgumentException

Create a provider for affine transforms of the specified dimension. Created affine transforms will have a size of numRow × numCol.

Parameter	Description
Num_row	Number of rows in matrix
Num_col	Number of columns in matrix
elt_<r>_<c>	Element of matrix

For the element parameters, <r> and <c> should be substituted by printed decimal numbers. The values of r should be from 0 to (num_row-1), and the values of c should be from 0 to (num_col-1). Any undefined matrix elements are assumed to be zero for (r!=c), and one for (r==c). This corresponds to the identity transformation when the number of rows and columns are the same. The number of columns corresponds to one more than the dimension of the source coordinates and the number of rows corresponds to one more than the dimension of target coordinates. The extra dimension in the matrix is used to let the affine map do a translation.

Parameters:

numRow - The number of matrix's rows.

numCol - The number of matrix's columns.

Returns:

The provider for an affine transform.

Throws:

java.lang.IllegalArgumentException - if numRow or numCol is not a positive number.

toOpenGIS

final java.lang.Object toOpenGIS(java.lang.Object adapters)

Returns an OpenGIS interface for this transform factory. The returned object is suitable for RMI use. Note: The returned type is a generic Object in order to avoid too early class loading of OpenGIS interface.