Class DefaultMathTransformFactory
- Object
-
- AbstractFactory
-
- ReferencingFactory
-
- DefaultMathTransformFactory
-
- All Implemented Interfaces:
Factory
,MathTransformFactory
,Factory
,RegistrableFactory
public class DefaultMathTransformFactory extends ReferencingFactory implements MathTransformFactory
Low level factory for creating math transforms. Many high level GIS applications will never need to use this factory directly; they can use a coordinate operation factory instead. However, theMathTransformFactory
interface 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 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.
- Since:
- 2.1
- Author:
- Martin Desruisseaux (IRD)
-
-
Field Summary
-
Fields inherited from class ReferencingFactory
LOGGER
-
Fields inherited from class AbstractFactory
hints, MAXIMUM_PRIORITY, MINIMUM_PRIORITY, NORMAL_PRIORITY, priority
-
-
Constructor Summary
Constructors Constructor Description DefaultMathTransformFactory()
Constructs a defaultmath transform
factory.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static void
cleanupThreadLocals()
Cleans up the thread local set in this thread.MathTransform
createAffineTransform(Matrix matrix)
Creates an affine transform from a matrix.MathTransform
createBaseToDerived(CoordinateReferenceSystem baseCRS, ParameterValueGroup parameters, CoordinateSystem derivedCS)
Creates a parameterized transform from a base CRS to a derived CS.MathTransform
createBaseToDerived(CoordinateReferenceSystem baseCRS, MathTransform projection, CoordinateSystem derivedCS)
Creates a transform from a base CRS to a derived CS.MathTransform
createConcatenatedTransform(MathTransform transform1, MathTransform transform2)
Creates a transform by concatenating two existing transforms.MathTransform
createFromWKT(String text)
Creates a math transform object from a Well Known Text (WKT).MathTransform
createFromXML(String xml)
Creates a math transform object from a XML string.MathTransform
createParameterizedTransform(ParameterValueGroup parameters)
Creates a transform from a group of parameters.MathTransform
createPassThroughTransform(int firstAffectedOrdinate, MathTransform subTransform, int numTrailingOrdinates)
Creates a transform which passes through a subset of ordinates to another transform.Set<OperationMethod>
getAvailableMethods(Class<? extends Operation> type)
Returns a set of available methods for math transforms.ParameterValueGroup
getDefaultParameters(String method)
Returns the default parameter values for a math transform using the given method.OperationMethod
getLastMethodUsed()
Returns the operation method used for the latest call tocreateParameterizedTransform
in the currently running thread.OperationMethod
getOperationMethod(String name)
Returns the operation method for the specified name.Citation
getVendor()
Returns the vendor responsible for creating this factory implementation.static void
main(String... args)
Dump to the standard output stream a list of available operation methods.void
scanForPlugins()
Scans for factory plug-ins on the application class path.-
Methods inherited from class ReferencingFactory
ensureNonNull
-
Methods inherited from class AbstractFactory
addImplementationHints, equals, getImplementationHints, getPriority, hashCode, onDeregistration, onRegistration, toString
-
-
-
-
Constructor Detail
-
DefaultMathTransformFactory
public DefaultMathTransformFactory()
Constructs a defaultmath transform
factory.
-
-
Method Detail
-
getVendor
public Citation getVendor()
Returns the vendor responsible for creating this factory implementation. Many implementations may be available for the same factory interface. The default implementation returns Geotools.- Specified by:
getVendor
in interfaceFactory
- Overrides:
getVendor
in classReferencingFactory
- Returns:
- The vendor for this factory implementation.
-
getAvailableMethods
public Set<OperationMethod> getAvailableMethods(Class<? extends Operation> type)
Returns a set of available methods for math transforms. For each element in this set, the operation method name must be known to thegetDefaultParameters(java.lang.String)
method in this factory. The set of available methods is implementation dependent.- Specified by:
getAvailableMethods
in interfaceMathTransformFactory
- Parameters:
type
-Operation.class
for fetching all operation methods, orProjection.class
for fetching only map projection methods.- Returns:
- All math transform methods available in this factory.
- See Also:
getDefaultParameters(java.lang.String)
,createParameterizedTransform(org.geotools.api.parameter.ParameterValueGroup)
-
getLastMethodUsed
public OperationMethod getLastMethodUsed()
Returns the operation method used for the latest call tocreateParameterizedTransform
in the currently running thread. Returnsnull
if not applicable.- Specified by:
getLastMethodUsed
in interfaceMathTransformFactory
- Returns:
- The last method used, or
null
if unknown of unsupported. - Since:
- 2.5
- See Also:
createParameterizedTransform(org.geotools.api.parameter.ParameterValueGroup)
-
getOperationMethod
public OperationMethod getOperationMethod(String name) throws NoSuchIdentifierException
Returns the operation method for the specified name.- Parameters:
name
- The case insensitive identifier code of the operation method to search for (e.g."Transverse_Mercator"
).- Returns:
- The operation method.
- Throws:
NoSuchIdentifierException
- if there is no operation method registered for the specified name.- Since:
- 2.2
-
getDefaultParameters
public ParameterValueGroup getDefaultParameters(String method) throws NoSuchIdentifierException
Returns the default parameter values for a math transform using the given method. The method argument is the name of any operation method returned by thegetAvailableMethods(java.lang.Class<? extends org.geotools.api.referencing.operation.Operation>)
method. A typical example is"Transverse_Mercator"
).This method creates new parameter instances at every call. It is intented to be modified by the user before to be passed to
createParameterizedTransform(parameters)
.- Specified by:
getDefaultParameters
in interfaceMathTransformFactory
- Parameters:
method
- The case insensitive name of the method to search for.- Returns:
- The default parameter values.
- Throws:
NoSuchIdentifierException
- if there is no transform registered for the specified method.- See Also:
getAvailableMethods(java.lang.Class<? extends org.geotools.api.referencing.operation.Operation>)
,createParameterizedTransform(org.geotools.api.parameter.ParameterValueGroup)
,AbstractMathTransform.getParameterValues()
-
createBaseToDerived
public MathTransform createBaseToDerived(CoordinateReferenceSystem baseCRS, ParameterValueGroup parameters, CoordinateSystem derivedCS) throws NoSuchIdentifierException, FactoryException
Creates a parameterized transform from a base CRS to a derived CS. If the"semi_major"
and"semi_minor"
parameters are not explicitly specified, they will be inferred from the ellipsoid and added toparameters
. In addition, this method performs axis switch as needed.The operation method used can be obtained by a call to
#getLastUsedMethod
.- Specified by:
createBaseToDerived
in interfaceMathTransformFactory
- Parameters:
baseCRS
- The source coordinate reference system.parameters
- The parameter values for the transform.derivedCS
- the target coordinate system.- Returns:
- The parameterized transform.
- Throws:
NoSuchIdentifierException
- if there is no transform registered for the method.FactoryException
- if the object creation failed. This exception is thrown if some required parameter has not been supplied, or has illegal value.
-
createBaseToDerived
public MathTransform createBaseToDerived(CoordinateReferenceSystem baseCRS, MathTransform projection, CoordinateSystem derivedCS) throws FactoryException
Creates a transform from a base CRS to a derived CS. This method expects a "raw" transform without unit conversion or axis switch, typically a map projection working on (longitude, latitude) axes in degrees and (x, y) axes in metres. This method inspects the coordinate systems and prepend or append the unit conversions and axis switchs automatically.- Parameters:
baseCRS
- The source coordinate reference system.projection
- The "raw" base to derived transform.derivedCS
- the target coordinate system.- Returns:
- The parameterized transform.
- Throws:
FactoryException
- if the object creation failed. This exception is thrown if some required parameter has not been supplied, or has illegal value.- Since:
- 2.5
-
createParameterizedTransform
public MathTransform createParameterizedTransform(ParameterValueGroup parameters) throws NoSuchIdentifierException, FactoryException
Creates a transform from a group of parameters. The method name is inferred from the parameter group name. Example:ParameterValueGroup p = factory.getDefaultParameters("Transverse_Mercator"); p.parameter("semi_major").setValue(6378137.000); p.parameter("semi_minor").setValue(6356752.314); MathTransform mt = factory.createParameterizedTransform(p);
- Specified by:
createParameterizedTransform
in interfaceMathTransformFactory
- Parameters:
parameters
- The parameter values.- Returns:
- The parameterized transform.
- Throws:
NoSuchIdentifierException
- if there is no transform registered for the method.FactoryException
- if the object creation failed. This exception is thrown if some required parameter has not been supplied, or has illegal value.- See Also:
getDefaultParameters(java.lang.String)
,getAvailableMethods(java.lang.Class<? extends org.geotools.api.referencing.operation.Operation>)
,#getLastUsedMethod
-
createAffineTransform
public MathTransform createAffineTransform(Matrix matrix) throws FactoryException
Creates an affine transform from a matrix. If the transform's input dimension isM
, and output dimension isN
, then the matrix will have size[N+1][M+1]
. The +1 in the matrix dimensions allows the matrix to do a shift, as well as a rotation. The[M][j]
element of the matrix will be the j'th ordinate of the moved origin. The[i][N]
element of the matrix will be 0 for i less thanM
, and 1 for i equalsM
.- Specified by:
createAffineTransform
in interfaceMathTransformFactory
- Parameters:
matrix
- The matrix used to define the affine transform.- Returns:
- The affine transform.
- Throws:
FactoryException
- if the object creation failed.
-
createConcatenatedTransform
public MathTransform createConcatenatedTransform(MathTransform transform1, MathTransform transform2) throws FactoryException
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.
- Specified by:
createConcatenatedTransform
in interfaceMathTransformFactory
- Parameters:
transform1
- The first transform to apply to points.transform2
- The second transform to apply to points.- Returns:
- The concatenated transform.
- Throws:
FactoryException
- if the object creation failed.
-
createPassThroughTransform
public MathTransform createPassThroughTransform(int firstAffectedOrdinate, MathTransform subTransform, int numTrailingOrdinates) throws FactoryException
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 (Lat,Lon,Height) coordinates, then you may wish to convert the height values from meters to feet without affecting the (Lat,Lon) values.- Specified by:
createPassThroughTransform
in interfaceMathTransformFactory
- Parameters:
firstAffectedOrdinate
- The lowest index of the affected ordinates.subTransform
- Transform to use for affected ordinates.numTrailingOrdinates
- Number of trailing ordinates to pass through. Affected ordinates will range fromfirstAffectedOrdinate
inclusive todimTarget-numTrailingOrdinates
exclusive.- Returns:
- A pass through transform with the following dimensions:
Source: firstAffectedOrdinate + subTransform.getSourceDimensions() + numTrailingOrdinates Target: firstAffectedOrdinate + subTransform.getTargetDimensions() + numTrailingOrdinates
- Throws:
FactoryException
- if the object creation failed.
-
createFromXML
public MathTransform createFromXML(String xml) throws FactoryException
Creates a math transform object from a XML string. The default implementation always throws an exception, since this method is not yet implemented.- Specified by:
createFromXML
in interfaceMathTransformFactory
- Parameters:
xml
- Math transform encoded in XML format.- Returns:
- The math transform (never
null
). - Throws:
FactoryException
- if the object creation failed.
-
createFromWKT
public MathTransform createFromWKT(String text) throws FactoryException
Creates a math transform object from a Well Known Text (WKT).- Specified by:
createFromWKT
in interfaceMathTransformFactory
- Parameters:
text
- Math transform encoded in Well-Known Text format.- Returns:
- The math transform (never
null
). - Throws:
FactoryException
- if the Well-Known Text can't be parsed, or if the math transform creation failed from some other reason.
-
scanForPlugins
public void scanForPlugins()
Scans for factory plug-ins on the application class path. This method is needed because the application class path can theoretically change, or additional plug-ins may become available. Rather than re-scanning the classpath on every invocation of the API, the class path is scanned automatically only on the first invocation. Clients can call this method to prompt a re-scan. Thus this method need only be invoked by sophisticated applications which dynamically make new plug-ins available at runtime.
-
main
public static void main(String... args)
Dump to the standard output stream a list of available operation methods. This method can be invoked from the command line. It provides a mean to verify which transforms were found in the classpath. The syntax is:
java org.geotools.referencing.operation.DefaultMathTransformFactory <options> <method>
where options are:
-projections
List only projections -conversions
List only conversions -all
List the parameters for all transforms -encoding
<code>Set the character encoding -locale
<language>Set the language for the output (e.g. "fr" for French) and <method> is the optional name of an operation method (e.g.
"Affine"
,"EPSG:9624"
or just"9624"
for the affine transform method).Note for Windows users: If the output contains strange symbols, try to supply an "
-encoding
" argument. Example:java org.geotools.referencing.operation.DefaultMathTransformFactory -encoding Cp850
The codepage number (850 in the previous example) can be obtained from the DOS commande line using the "
chcp
" command with no arguments.- Parameters:
args
- Command line arguments.
-
cleanupThreadLocals
public static void cleanupThreadLocals()
Cleans up the thread local set in this thread. They can prevent web applications from proper shutdown
-
-