org.geotools.referencing.operation.builder
Class MathTransformBuilder

java.lang.Object
  extended by org.geotools.referencing.operation.builder.MathTransformBuilder
Direct Known Subclasses:
AdvancedAffineBuilder, BursaWolfTransformBuilder, ProjectiveTransformBuilder, RubberSheetBuilder

public abstract class MathTransformBuilder
extends java.lang.Object

Provides a basic implementation for math transform builders. Math transform builders create MathTransform objects for transforming coordinates from a source CRS (Coordinate Reference System) to a target CRS using empirical parameters. Usually, one of those CRS is a geographic or projected one with a well known relationship to the earth. The other CRS is often an engineering or image one tied to some ship. For example a remote sensing image before georectification may be referenced by an image CRS.

Design note: It is technically possible to reference such remote sensing images with a CRS derived from the geographic or projected CRS, where the conversion from base is the math transform computed by this builder. Such approach is advantageous for coordinate operation factory implementations, since they can determine the operation just by inspection of the DerivedCRS instance. However this is conceptually incorrect since DerivedCRS can be related to an other CRS only through conversions, which by definition are accurate up to rounding errors. The operations created by math transform builders are rather transformations, which can't be used for DerivedCRS creation.

The math transform from source CRS to target CRS is calculated by MathTransformBuilder from a set of mapped positions in both CRS.

Subclasses must implement at least the getMinimumPointCount() and computeMathTransform() methods.

Since:
2.4
Version:
$Id: MathTransformBuilder.java 30641 2008-06-12 17:42:27Z acuster $
Author:
Jan Jezek, Martin Desruisseaux

Field Summary
protected  org.opengis.referencing.operation.MathTransformFactory mtFactory
          The factory to use for creating math transform instances.
 
Constructor Summary
MathTransformBuilder()
          Creates a builder with the default factories.
MathTransformBuilder(Hints hints)
          Creates a builder from the specified hints.
 
Method Summary
protected abstract  org.opengis.referencing.operation.MathTransform computeMathTransform()
          Calculates the math transform immediately.
 java.lang.Class<? extends org.opengis.referencing.cs.CoordinateSystem> getCoordinateSystemType()
          Returns the required coordinate system type.
 int getDimension()
          Returns the dimension for source and target CRS.
 Statistics getErrorStatistics()
          Returns statistics about the errors.
 java.util.List<MappedPosition> getMappedPositions()
          Returns the list of mapped positions.
 org.opengis.referencing.operation.MathTransform getMathTransform()
          Returns the calculated math transform.
abstract  int getMinimumPointCount()
          Returns the minimum number of points required by this builder.
 java.lang.String getName()
          Returns the name for the transformation to be created by this builder.
 org.opengis.referencing.crs.CoordinateReferenceSystem getSourceCRS()
          Returns the coordinate reference system for the source points.
 org.opengis.geometry.DirectPosition[] getSourcePoints()
          Returns the source points.
 org.opengis.referencing.crs.CoordinateReferenceSystem getTargetCRS()
          Returns the coordinate reference system for the target points.
 org.opengis.geometry.DirectPosition[] getTargetPoints()
          Returns the target points.
 org.opengis.referencing.operation.Transformation getTransformation()
          Returns the coordinate operation wrapping the calculated math transform.
 void printPoints(java.io.Writer out, java.util.Locale locale)
          Prints a table of all source and target points stored in this builder.
 void setMappedPositions(java.util.List<MappedPosition> positions)
          Set the list of mapped positions.
 void setSourcePoints(org.opengis.geometry.DirectPosition[] points)
          Convenience method setting the source points in mapped positions.
 void setTargetPoints(org.opengis.geometry.DirectPosition[] points)
          Convenience method setting the target points in mapped positions.
 java.lang.String toString()
          Returns a string representation of this builder.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

mtFactory

protected final org.opengis.referencing.operation.MathTransformFactory mtFactory
The factory to use for creating math transform instances.

Constructor Detail

MathTransformBuilder

public MathTransformBuilder()
Creates a builder with the default factories.


MathTransformBuilder

public MathTransformBuilder(Hints hints)
Creates a builder from the specified hints.

Method Detail

getName

public java.lang.String getName()
Returns the name for the transformation to be created by this builder.


getMinimumPointCount

public abstract int getMinimumPointCount()
Returns the minimum number of points required by this builder. This minimum depends on the algorithm used. For example affine transform builders require at least 3 points, while similar transform builders requires only 2 points.


getDimension

public int getDimension()
Returns the dimension for source and target CRS. The default value is 2.


getMappedPositions

public java.util.List<MappedPosition> getMappedPositions()
Returns the list of mapped positions.


setMappedPositions

public void setMappedPositions(java.util.List<MappedPosition> positions)
                        throws javax.vecmath.MismatchedSizeException,
                               org.opengis.geometry.MismatchedDimensionException,
                               org.opengis.geometry.MismatchedReferenceSystemException
Set the list of mapped positions.

Throws:
javax.vecmath.MismatchedSizeException - if the list doesn't have the expected number of points.
org.opengis.geometry.MismatchedDimensionException - if some points doesn't have the expected number of dimensions.
org.opengis.geometry.MismatchedReferenceSystemException - if CRS is not the same for all points.

getSourcePoints

public org.opengis.geometry.DirectPosition[] getSourcePoints()
Returns the source points. This convenience method extracts those points from the mapped positions.


setSourcePoints

public void setSourcePoints(org.opengis.geometry.DirectPosition[] points)
                     throws javax.vecmath.MismatchedSizeException,
                            org.opengis.geometry.MismatchedDimensionException,
                            org.opengis.geometry.MismatchedReferenceSystemException
Convenience method setting the source points in mapped positions.

Parameters:
points - The source points.
Throws:
javax.vecmath.MismatchedSizeException - if the list doesn't have the expected number of points.
org.opengis.geometry.MismatchedDimensionException - if some points doesn't have the expected number of dimensions.
org.opengis.geometry.MismatchedReferenceSystemException - if CRS is not the same for all points.

getTargetPoints

public org.opengis.geometry.DirectPosition[] getTargetPoints()
Returns the target points. This convenience method extracts those points from the mapped positions.


setTargetPoints

public void setTargetPoints(org.opengis.geometry.DirectPosition[] points)
                     throws javax.vecmath.MismatchedSizeException,
                            org.opengis.geometry.MismatchedDimensionException,
                            org.opengis.geometry.MismatchedReferenceSystemException
Convenience method setting the target points in mapped positions.

Parameters:
points - The target points.
Throws:
javax.vecmath.MismatchedSizeException - if the list doesn't have the expected number of points.
org.opengis.geometry.MismatchedDimensionException - if some points doesn't have the expected number of dimensions.
org.opengis.geometry.MismatchedReferenceSystemException - if CRS is not the same for all points.

printPoints

public void printPoints(java.io.Writer out,
                        java.util.Locale locale)
                 throws java.io.IOException
Prints a table of all source and target points stored in this builder.

Parameters:
out - The output device where to print all points.
locale - The locale, or null for the default.
Throws:
java.io.IOException - if an error occured while printing.

getSourceCRS

public org.opengis.referencing.crs.CoordinateReferenceSystem getSourceCRS()
                                                                   throws org.opengis.referencing.FactoryException
Returns the coordinate reference system for the source points. This method determines the CRS as below:

Throws:
org.opengis.referencing.FactoryException - if the CRS can't be created.

getTargetCRS

public org.opengis.referencing.crs.CoordinateReferenceSystem getTargetCRS()
                                                                   throws org.opengis.referencing.FactoryException
Returns the coordinate reference system for the target points. This method determines the CRS as below:

Throws:
org.opengis.referencing.FactoryException - if the CRS can't be created.

getCoordinateSystemType

public java.lang.Class<? extends org.opengis.referencing.cs.CoordinateSystem> getCoordinateSystemType()
Returns the required coordinate system type. The default implementation returns CoordinateSystem.class, which means that every kind of coordinate system is legal. Some subclasses will restrict to cartesian CS.


getErrorStatistics

public Statistics getErrorStatistics()
                              throws org.opengis.referencing.FactoryException
Returns statistics about the errors. The errors are computed as the distance between source points transformed by the math transform computed by this MathTransformBuilder, and the target points. Use Statistics.rms() for the Root Mean Squared error.

Throws:
org.opengis.referencing.FactoryException - If the math transform can't be created or used.

computeMathTransform

protected abstract org.opengis.referencing.operation.MathTransform computeMathTransform()
                                                                                 throws org.opengis.referencing.FactoryException
Calculates the math transform immediately.

Returns:
Math transform from MappedPosition.
Throws:
org.opengis.referencing.FactoryException - if the math transform can't be created.

getMathTransform

public final org.opengis.referencing.operation.MathTransform getMathTransform()
                                                                       throws org.opengis.referencing.FactoryException
Returns the calculated math transform. This method the math transform the first time it is requested.

Returns:
Math transform from MappedPosition.
Throws:
org.opengis.referencing.FactoryException - if the math transform can't be created.

getTransformation

public org.opengis.referencing.operation.Transformation getTransformation()
                                                                   throws org.opengis.referencing.FactoryException
Returns the coordinate operation wrapping the calculated math transform. The positional accuracy will be set to the Root Mean Square (RMS) of the differences between the source points transformed to the target CRS, and the expected target points.

Throws:
org.opengis.referencing.FactoryException

toString

public java.lang.String toString()
Returns a string representation of this builder. The default implementation returns a table containing all source and target points.

Overrides:
toString in class java.lang.Object


Copyright © 1996-2010 Geotools. All Rights Reserved.