org.geotools.ct
Class MathTransformFactory

java.lang.Object
  org.geotools.ct.MathTransformFactory

Deprecated. Replaced by DefaultMathTransformFactory in the org.geotools.referencing.operation package.

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:

$Id: MathTransformFactory.java 17672 2006-01-19 00:25:55Z desruisseaux $

Author:

OpenGIS (www.opengis.org), Martin Desruisseaux

See Also:

CT_MathTransformFactory

Task:

REVISIT: Consider creating a set of package-privated methods in AbstractMathTransform (for example concatenante(MathTransformFactory, ...)) and moves some code in AbstractMathTransform's sub-classes. It would simplify MathTransformFactory but would introduces dependencies to the factory right inside the abstract math transform.

Constructor Summary

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

Method Summary

MathTransform2D	createAffineTransform(java.awt.geom.AffineTransform matrix) Deprecated. Creates an affine transform from a matrix.
MathTransform	createAffineTransform(Matrix matrix) Deprecated. Creates an affine transform from a matrix.
MathTransform	createConcatenatedTransform(MathTransform tr1, MathTransform tr2) Deprecated. Creates a transform by concatenating two existing transforms.
MathTransform	createFilterTransform(MathTransform transform, javax.media.jai.IntegerSequence outputDimensions) Deprecated. Creates a transform which retains only a subset of an other transform's outputs.
MathTransform	createFromWKT(java.lang.String text) Deprecated. Creates a math transform object from a Well-Known Text (WKT) string.
MathTransform	createIdentityTransform(int dimension) Deprecated. Creates an identity transform of the specified dimension.
MathTransform	createParameterizedTransform(Projection projection) Deprecated. Creates a transform from a projection.
MathTransform	createParameterizedTransform(java.lang.String classification, javax.media.jai.ParameterList parameters) Deprecated. Creates a transform from a classification name and parameters.
MathTransform	createPassThroughTransform(int firstAffectedOrdinate, MathTransform subTransform, int numTrailingOrdinates) Deprecated. Creates a transform which passes through a subset of ordinates to another transform.
MathTransform	createSubTransform(MathTransform transform, javax.media.jai.IntegerSequence inputDimensions, javax.media.jai.IntegerSequence outputDimensions) Deprecated. Reduces the number of input dimensions for the specified transform.
java.lang.String[]	getAvailableTransforms() Deprecated. Returns the classification names of every available transforms.
static MathTransformFactory	getDefault() Deprecated. Returns the default math transform factory.
MathTransformProvider	getMathTransformProvider(java.lang.String classification) Deprecated. Returns the provider for the specified classification.
Unit	getParameterUnit(java.lang.String parameter) Deprecated. Returns the unit for the specified parameter.

Methods inherited from class java.lang.Object

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

Constructor Detail

MathTransformFactory

public MathTransformFactory(MathTransformProvider[] providers)

Deprecated.

Construct a factory using the specified providers.

Method Detail

getDefault

public static MathTransformFactory getDefault()

Deprecated.

Returns the default math transform factory.

createIdentityTransform

public MathTransform createIdentityTransform(int dimension)

Deprecated.

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)

Deprecated.

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)

Deprecated.

Creates an affine transform from a matrix.

Parameters:

matrix - The matrix used to define the affine transform.

Returns:

The affine transform.

See Also:

CT_MathTransformFactory.createAffineTransform(org.opengis.pt.PT_Matrix)

createConcatenatedTransform

public MathTransform createConcatenatedTransform(MathTransform tr1,
                                                 MathTransform tr2)

Deprecated.

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.

See Also:

CT_MathTransformFactory.createConcatenatedTransform(org.opengis.ct.CT_MathTransform, org.opengis.ct.CT_MathTransform)

Task:

TODO: We could add one more optimisation: if one transform is a matrix and the other transform is a PassThroughTransform, and if the matrix as 0 elements for all rows matching the PassThrough sub-transform, then we can get ride of the whole PassThroughTransform object.

createPassThroughTransform

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

Deprecated.

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

See Also:

CT_MathTransformFactory.createPassThroughTransform(int, org.opengis.ct.CT_MathTransform), createSubTransform(org.geotools.ct.MathTransform, javax.media.jai.IntegerSequence, javax.media.jai.IntegerSequence)

createSubTransform

public MathTransform createSubTransform(MathTransform transform,
                                        javax.media.jai.IntegerSequence inputDimensions,
                                        javax.media.jai.IntegerSequence outputDimensions)
                                 throws org.opengis.referencing.FactoryException

Deprecated.

Reduces the number of input dimensions for the specified transform. The remaining output dimensions will be selected automatically according the specified input dimensions. For example if the supplied transform has (x, y, z) inputs and (longitude, latitude, height) outputs, then createSubTransform(transform, new IntegerSequence(0,1), null) will returns a transform with (x, y) inputs and (probably) (longitude, latitude) outputs. This method can be used in order to separate a concatenation of pass through transforms.

Parameters:

transform - The transform to reduces.

inputDimensions - The input dimension to keep. This sequence can contains any integers in the range 0 inclusive to transform.getDimSource() exclusive.

outputDimensions - An optional sequence in which to store output dimensions. If non-null, then this sequence will be filled with output dimensions selected by this method. The integers will be in the range 0 inclusive to transform.getDimTarget() exclusive.

Returns:

A transform expecting only the specified input dimensions. The following invariant should hold:

         subTransform.getDimSource() ==  inputDimensions.getNumElements();
         subTransform.getDimTarget() == outputDimensions.getNumElements();
         

Throws:

org.opengis.referencing.FactoryException - if the transform is not separable.

createFilterTransform

public MathTransform createFilterTransform(MathTransform transform,
                                           javax.media.jai.IntegerSequence outputDimensions)

Deprecated.

Creates a transform which retains only a subset of an other transform's outputs. The number and nature of inputs stay unchanged. For example if the supplied transform has (longitude, latitude, height) outputs, 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 may be see as a non-square matrix transform with less rows than columns, concatenated with transform. However, invoking createFilterTransfom(...) allows the optimization of some common cases.

Parameters:

transform - The transform to reduces.

outputDimensions - The output dimension to keep. This sequence can contains any integers in the range 0 inclusive to transform.getDimTarget() exclusive.

Returns:

The transform keeping only the specified output dimensions.

createParameterizedTransform

public MathTransform createParameterizedTransform(java.lang.String classification,
                                                  javax.media.jai.ParameterList parameters)
                                           throws MissingParameterException,
                                                  org.opengis.referencing.FactoryException

Deprecated.

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:

NoSuchClassificationException - if there is no transform for the specified classification.

MissingParameterException - if a parameter was required but not found.

org.opengis.referencing.FactoryException - if the math transform creation failed from some other reason.

See Also:

CT_MathTransformFactory.createParameterizedTransform(java.lang.String, org.opengis.ct.CT_Parameter[]), getAvailableTransforms()

createParameterizedTransform

public MathTransform createParameterizedTransform(Projection projection)
                                           throws MissingParameterException,
                                                  org.opengis.referencing.FactoryException

Deprecated.

Creates a transform from a projection. 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:

projection - The projection.

Returns:

The parameterized transform.

Throws:

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

MissingParameterException - if a parameter was required but not found.

org.opengis.referencing.FactoryException - if the math transform creation failed from some other reason.

getAvailableTransforms

public java.lang.String[] getAvailableTransforms()

Deprecated.

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

See Also:

createParameterizedTransform(java.lang.String, javax.media.jai.ParameterList)

getMathTransformProvider

public MathTransformProvider getMathTransformProvider(java.lang.String classification)
                                               throws NoSuchClassificationException

Deprecated.

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:

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

getParameterUnit

public Unit getParameterUnit(java.lang.String parameter)

Deprecated.

Returns the unit for the specified parameter. This method returns one of the following:

• If the specified parameter is a linear measure, then this method returns Unit.METRE. Other linear units are not authorized.
• If the specified parameter is an angular measure, then this method returns Unit.DEGREE. Other angular units are not authorized.
• Otherwise, this method may returns Unit.DIMENSIONLESS or null.

Parameters:

parameter - The parameter name (e.g. "false_easting" or "central_meridian").

Returns:

The parameter unit, or null.

createFromWKT

public MathTransform createFromWKT(java.lang.String text)
                            throws org.opengis.referencing.FactoryException

Deprecated.

Creates a math transform object from a Well-Known Text (WKT) string. WKT are part of Coordinate Transformation Services Specification.

Parameters:

text - The Well-Known Text.

Returns:

The math transform (never null).

Throws:

org.opengis.referencing.FactoryException - if the Well-Known Text can't be parsed, or if the math transform creation failed from some other reason.