org.deegree.model.csct.ct
Class MathTransformFactory

java.lang.Object
  org.deegree.model.csct.ct.MathTransformFactory

public class MathTransformFactory
extends 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, $Revision: 6259 $, $Date: 2007-03-20 10:15:15 +0100 (Di, 20 Mär 2007) $

Author:

OpenGIS (www.opengis.org), Martin Desruisseaux, last edited by: $Author: bezema $

See Also:

"org.opengis.ct.CT_MathTransformFactory"

Field Summary

(package private) static WeakHashSet

pool A pool of math transform.

Constructor Summary

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

Method Summary

MathTransform2D	createAffineTransform(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(String classification, javax.media.jai.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.
String[]	getAvailableTransforms() Returns the classification names of every available transforms.
static MathTransformFactory	getDefault() Returns the default math transform factory.
MathTransformProvider	getMathTransformProvider(String classification) Returns the provider for the specified classification.

Methods inherited from class java.lang.Object

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

Field Detail

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.

Constructor Detail

MathTransformFactory

public MathTransformFactory(MathTransformProvider[] providers)

Construct a factory using the specified providers.

Parameters:

providers -

Method Detail

getDefault

public static MathTransformFactory getDefault()

Returns the default math transform factory.

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(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.

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.

Returns:

createParameterizedTransform

public MathTransform createParameterizedTransform(String classification,
                                                  javax.media.jai.ParameterList parameters)
                                           throws 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:

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 NoSuchElementException,
                                                  MissingParameterException

Convenience method for creating a transform from a projection.

Parameters:

projection - The projection.

Returns:

The parameterized transform.

Throws:

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

MissingParameterException - if a parameter was required but not found.

getAvailableTransforms

public String[] getAvailableTransforms()

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

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(String classification)
                                               throws 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:

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

getAffineTransformProvider

public MathTransformProvider getAffineTransformProvider(int numRow,
                                                        int numCol)
                                                 throws 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:

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