Class MathTransformBuilder
 Object

 MathTransformBuilder

 Direct Known Subclasses:
AdvancedAffineBuilder
,BursaWolfTransformBuilder
,ProjectiveTransformBuilder
,RubberSheetBuilder
public abstract class MathTransformBuilder extends 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 sinceDerivedCRS
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 forDerivedCRS
creation.MathTransformBuilder
from a set of mapped positions in both CRS.Subclasses must implement at least the
getMinimumPointCount()
andcomputeMathTransform()
methods. Since:
 2.4
 Author:
 Jan Jezek, Martin Desruisseaux


Field Summary
Fields Modifier and Type Field Description protected MathTransformFactory
mtFactory
The factory to use for creatingmath transform
instances.

Constructor Summary
Constructors Constructor Description MathTransformBuilder()
Creates a builder with the default factories.MathTransformBuilder(Hints hints)
Creates a builder from the specified hints.

Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description protected abstract MathTransform
computeMathTransform()
Calculates the math transform immediately.Class<? extends CoordinateSystem>
getCoordinateSystemType()
Returns the required coordinate system type.int
getDimension()
Statistics
getErrorStatistics()
Returns statistics about the errors.List<MappedPosition>
getMappedPositions()
Returns the list of mapped positions.MathTransform
getMathTransform()
Returns the calculated math transform.abstract int
getMinimumPointCount()
Returns the minimum number of points required by this builder.String
getName()
Returns the name for the transformation to be created by this builder.CoordinateReferenceSystem
getSourceCRS()
Returns the coordinate reference system for thesource points
.Position[]
getSourcePoints()
Returns the source points.CoordinateReferenceSystem
getTargetCRS()
Returns the coordinate reference system for thetarget points
.Position[]
getTargetPoints()
Returns the target points.Transformation
getTransformation()
Returns the coordinate operation wrapping the calculated math transform.void
printPoints(Writer out, Locale locale)
Prints a table of all source and target points stored in this builder.void
setMappedPositions(List<MappedPosition> positions)
Set the list of mapped positions.void
setSourcePoints(Position... points)
Convenience method setting the source points in mapped positions.void
setTargetPoints(Position... points)
Convenience method setting the target points in mapped positions.String
toString()
Returns a string representation of this builder.



Field Detail

mtFactory
protected final MathTransformFactory mtFactory
The factory to use for creatingmath 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 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()

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

setMappedPositions
public void setMappedPositions(List<MappedPosition> positions) throws IllegalArgumentException, MismatchedDimensionException, MismatchedReferenceSystemException
Set the list of mapped positions. Throws:
IllegalArgumentException
 if the list doesn't have the expected number of points.MismatchedDimensionException
 if some points doesn't have the expected number of dimensions.MismatchedReferenceSystemException
 if CRS is not the same for all points.

getSourcePoints
public Position[] getSourcePoints()
Returns the source points. This convenience method extracts those points from the mapped positions.

setSourcePoints
public void setSourcePoints(Position... points) throws IllegalArgumentException, MismatchedDimensionException, MismatchedReferenceSystemException
Convenience method setting the source points in mapped positions. Parameters:
points
 The source points. Throws:
IllegalArgumentException
 if the list doesn't have the expected number of points.MismatchedDimensionException
 if some points doesn't have the expected number of dimensions.MismatchedReferenceSystemException
 if CRS is not the same for all points.

getTargetPoints
public Position[] getTargetPoints()
Returns the target points. This convenience method extracts those points from the mapped positions.

setTargetPoints
public void setTargetPoints(Position... points) throws IllegalArgumentException, MismatchedDimensionException, MismatchedReferenceSystemException
Convenience method setting the target points in mapped positions. Parameters:
points
 The target points. Throws:
IllegalArgumentException
 if the list doesn't have the expected number of points.MismatchedDimensionException
 if some points doesn't have the expected number of dimensions.MismatchedReferenceSystemException
 if CRS is not the same for all points.

printPoints
public void printPoints(Writer out, Locale locale) throws 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, ornull
for the default. Throws:
IOException
 if an error occured while printing.

getSourceCRS
public CoordinateReferenceSystem getSourceCRS() throws FactoryException
Returns the coordinate reference system for thesource points
. This method determines the CRS as below: If at least one source points has a CRS, then this CRS is selected as the source one and returned.
 If no source point has a CRS, then this method creates an engineering CRS using the same coordinate system than the one used by the target CRS.
 Throws:
FactoryException
 if the CRS can't be created.

getTargetCRS
public CoordinateReferenceSystem getTargetCRS() throws FactoryException
Returns the coordinate reference system for thetarget points
. This method determines the CRS as below: If at least one target points has a CRS, then this CRS is selected as the target one and returned.
 If no target point has a CRS, then this method creates an engineering CRS using the same coordinate system than the one used by the source CRS.
 Throws:
FactoryException
 if the CRS can't be created.

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

getErrorStatistics
public Statistics getErrorStatistics() throws FactoryException
Returns statistics about the errors. The errors are computed as the distance between source points transformed by the math transform computed by thisMathTransformBuilder
, and the target points. UseStatistics.rms()
for the Root Mean Squared error. Throws:
FactoryException
 If the math transform can't be created or used.

computeMathTransform
protected abstract MathTransform computeMathTransform() throws FactoryException
Calculates the math transform immediately. Returns:
 Math transform from
MappedPosition
.  Throws:
FactoryException
 if the math transform can't be created.

getMathTransform
public final MathTransform getMathTransform() throws FactoryException
Returns the calculated math transform. This method the math transform the first time it is requested. Returns:
 Math transform from
MappedPosition
.  Throws:
FactoryException
 if the math transform can't be created.

getTransformation
public Transformation getTransformation() throws 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:
FactoryException

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

