public class DefaultMathTransformFactory extends AbstractFactory implements MathTransformFactory, Parser
CRS
or MathTransforms
classes instead.
MathTransform
instances are created from parameter values.
The parameters expected by each operation available in a default Apache SIS installation is
listed here.
The set of parameters varies for each operation or projection, but the following can be considered typical:
Each descriptor has many aliases, and those aliases may vary between different projections.
For example the false easting parameter is usually called "false_easting"
by OGC, while EPSG uses various names like "False easting" or "Easting at
false origin".
"earth_radius"
, which copy its value to the "semi_major"
and
"semi_minor"
parameter values."inverse_flattening"
, which compute the "semi_minor"
value from
the "semi_major"
parameter value."standard_parallel"
expecting an array of type double[]
, which copy
its elements to the "standard_parallel_1"
and "standard_parallel_2"
parameter scalar values.The main purpose of those dynamic parameters is to support some less commonly used conventions without duplicating the most commonly used conventions. The alternative ways are used in netCDF files for example, which often use spherical models instead than ellipsoidal ones.
Parameters are flagged as either mandatory or optional. A parameter may be mandatory and still have a default value. In the context of this package, "mandatory" means that the parameter is an essential part of the projection defined by standards. Such mandatory parameters will always appears in any Well Known Text (WKT) formatting, even if not explicitly set by the user. For example the central meridian is typically a mandatory parameter with a default value of 0° (the Greenwich meridian).Optional parameters, on the other hand, are often non-standard extensions. They will appear in WKT formatting only if the user defined explicitly a value which is different than the default value.
OperationMethod
describes all the parameters expected for instantiating a particular kind of
math transform. The set of operation methods known to this factory can be obtained in two ways:
The default way is to scan the classpath. See MathTransformProvider
for indications about how to add
custom coordinate operation methods in a default Apache SIS installation.
OperationMethod
instances are thread-safe.
There is typically only one MathTransformFactory
instance for the whole application.MathTransformProvider
,
AbstractMathTransform
Defined in the sis-referencing
module
Modifier and Type | Class and Description |
---|---|
static class |
DefaultMathTransformFactory.Context
Source and target coordinate systems for which a new parameterized transform is going to be used.
|
Constructor and Description |
---|
DefaultMathTransformFactory()
Creates a new factory which will discover operation methods with a
ServiceLoader . |
DefaultMathTransformFactory(Iterable<? extends OperationMethod> methods)
Creates a new factory which will use the given operation methods.
|
Modifier and Type | Method and Description |
---|---|
MathTransform |
createAffineTransform(Matrix matrix)
Creates an affine transform from a matrix.
|
MathTransform |
createBaseToDerived(CoordinateReferenceSystem baseCRS,
ParameterValueGroup parameters,
CoordinateSystem derivedCS)
Deprecated.
|
MathTransform |
createConcatenatedTransform(MathTransform tr1,
MathTransform tr2)
Creates a transform by concatenating two existing transforms.
|
MathTransform |
createCoordinateSystemChange(CoordinateSystem source,
CoordinateSystem target)
Deprecated.
|
MathTransform |
createCoordinateSystemChange(CoordinateSystem source,
CoordinateSystem target,
Ellipsoid ellipsoid)
Creates a math transform that represent a change of coordinate system.
|
MathTransform |
createFromWKT(String text)
Creates a math transform object from a
Well
Known Text (WKT).
|
MathTransform |
createFromXML(String xml)
Deprecated.
|
MathTransform |
createParameterizedTransform(ParameterValueGroup parameters)
Deprecated.
Replaced by
createParameterizedTransform(ParameterValueGroup, Context)
where the Context argument can be null. |
MathTransform |
createParameterizedTransform(ParameterValueGroup parameters,
DefaultMathTransformFactory.Context context)
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 SingleOperation> type)
Returns a set of available methods for coordinate operations of the given type.
|
ParameterValueGroup |
getDefaultParameters(String method)
Returns the default parameter values for a math transform using the given operation method.
|
OperationMethod |
getLastMethodUsed()
Returns the operation method used by the latest call to a
create(…) constructor
in the currently running thread. |
OperationMethod |
getOperationMethod(String identifier)
Returns the operation method for the specified name or identifier.
|
void |
reload()
Notifies this factory that the elements provided by the
Iterable<OperationMethod> may have changed. |
MathTransform |
swapAndScaleAxes(MathTransform parameterized,
DefaultMathTransformFactory.Context context)
Given a transform between normalized spaces,
creates a transform taking in account axis directions, units of measurement and longitude rotation.
|
getVendor
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
getVendor
public DefaultMathTransformFactory()
ServiceLoader
.
The OperationMethod
implementations shall be listed in the following file:
META-INF/services/org.opengis.referencing.operation.OperationMethod
DefaultMathTransformFactory
parses the above-cited files in all JAR files in order to find all available
operation methods. By default, only operation methods that implement the MathTransformProvider
interface
can be used by the create(…)
methods in this class.reload()
public DefaultMathTransformFactory(Iterable<? extends OperationMethod> methods)
OperationMethod
constructions.
Note that by default, only operation methods that implement the MathTransformProvider
interface can be
used by the create(…)
methods in this class.
Requirements:
reload()
has been invoked.OperationMethod
instances should also implement MathTransformProvider
.OperationMethod
instances shall be thread-safe.Iterable
itself does not need to be thread-safe since all usages will be synchronized as below:
synchronized (methods) { for (OperationMethod method : methods) { // Use the method here. } }
methods
- the operation methods to use, stored by reference (not copied).public Set<OperationMethod> getAvailableMethods(Class<? extends SingleOperation> type)
type
argument can be used for filtering the kind of operations described by the returned
OperationMethod
s. The argument is usually (but not restricted to) one of the following types:
Transformation
for coordinate operations described by empirically derived parameters.Conversion
for coordinate operations described by definitions.Projection
for conversions from geodetic latitudes and longitudes to plane (map) coordinates.SingleOperation
for all coordinate operations.OperationMethod
elements than requested
if this MathTransformFactory
does not support filtering by the given type.getAvailableMethods
in interface MathTransformFactory
type
- SingleOperation.class
for fetching all operation methods,
Projection.class
for
fetching only map projection methods, etc.getDefaultParameters(String)
,
createParameterizedTransform(ParameterValueGroup, Context)
,
DefaultOperationMethod.getOperationType()
public OperationMethod getOperationMethod(String identifier) throws NoSuchIdentifierException
"EPSG:9807"
).
The search is case-insensitive. Comparisons against method names can be heuristic.
If more than one method match the given identifier, then the first (according iteration order) non-deprecated matching method is returned. If all matching methods are deprecated, the first one is returned.
identifier
- the name or identifier of the operation method to search.NoSuchIdentifierException
- if there is no operation method registered for the specified identifier.DefaultCoordinateOperationFactory.getOperationMethod(String)
public ParameterValueGroup getDefaultParameters(String method) throws NoSuchIdentifierException
method
argument is the name of any OperationMethod
instance returned by
getAvailableMethods
(SingleOperation.class)
.
A typical example is
"Transverse Mercator").
This function creates new parameter instances at every call.
Parameters are intended to be modified by the user before to be given to the
createParameterizedTransform(…)
method.
getDefaultParameters
in interface MathTransformFactory
method
- the case insensitive name of the coordinate operation method to search for.OperationMethod
identified by the given name.NoSuchIdentifierException
- if there is no method registered for the given name or identifier.getAvailableMethods(Class)
,
createParameterizedTransform(ParameterValueGroup, Context)
,
AbstractMathTransform.getParameterValues()
@Deprecated public MathTransform createParameterizedTransform(ParameterValueGroup parameters) throws NoSuchIdentifierException, FactoryException
createParameterizedTransform(ParameterValueGroup, Context)
where the Context
argument can be null.createParameterizedTransform
in interface MathTransformFactory
parameters
- the parameter values. The parameter group name
shall be the name of the desired operation method.NoSuchIdentifierException
- if there is no method for the given parameter group name.FactoryException
- if the object creation failed. This exception is thrown
if some required parameter has not been supplied, or has illegal value.public MathTransform createParameterizedTransform(ParameterValueGroup parameters, DefaultMathTransformFactory.Context context) throws NoSuchIdentifierException, FactoryException
getDefaultParameters(String)
, then to fill the parameter values.
Example:
ParameterValueGroup group = factory.getDefaultParameters("Transverse_Mercator"); group.parameter("semi_major").setValue(6378137.000); group.parameter("semi_minor").setValue(6356752.314); MathTransform mt = factory.createParameterizedTransform(group, null);Sometime the
"semi_major"
and "semi_minor"
parameter values are not explicitly provided,
but rather inferred from the geodetic
datum of the source Coordinate Reference System. If the given context
argument is non-null,
then this method will use those contextual information for:
"semi_major"
, "semi_minor"
, "src_semi_major"
,
"src_semi_minor"
, "tgt_semi_major"
or "tgt_semi_minor"
parameters values
from the ellipsoids associated to
the source or target CRS, if those parameters are not explicitly given and if they are relevant
for the coordinate operation method."semi_major"
, "semi_minor"
or other calculated values,
can be obtained by a call to DefaultMathTransformFactory.Context.getCompletedParameters()
after createParameterizedTransform(…)
returned. Note that the completed parameters may only have additional parameters compared to the given parameter
group; existing parameter values should not be modified.
The OperationMethod
instance used by this constructor can be obtained by a call to
getLastMethodUsed()
.
parameters
- the parameter values. The parameter group name
shall be the name of the desired operation method.context
- information about the context (for example source and target coordinate systems)
in which the new transform is going to be used, or null
if none.NoSuchIdentifierException
- if there is no method for the given parameter group name.FactoryException
- if the object creation failed. This exception is thrown
if some required parameter has not been supplied, or has illegal value.getDefaultParameters(String)
,
getAvailableMethods(Class)
,
getLastMethodUsed()
,
ParameterBuilder.createGroupForMapProjection(ParameterDescriptor...)
public MathTransform swapAndScaleAxes(MathTransform parameterized, DefaultMathTransformFactory.Context context) throws FactoryException
The given parameterized
transform shall expect
normalized input coordinates and
produce normalized output coordinates. See AxesConvention
for more
information about what Apache SIS means by "normalized".
Context.getMatrix(ContextualParameters.MatrixRole)
method.parameterized
- a transform for normalized input and output coordinates.context
- source and target coordinate systems in which the transform is going to be used.FactoryException
- if the object creation failed.AxesConvention.NORMALIZED
,
DefaultConversion.DefaultConversion(Map, OperationMethod, MathTransform, ParameterValueGroup)
@Deprecated public MathTransform createBaseToDerived(CoordinateReferenceSystem baseCRS, ParameterValueGroup parameters, CoordinateSystem derivedCS) throws NoSuchIdentifierException, FactoryException
createParameterizedTransform(ParameterValueGroup, Context)
."semi_major"
and "semi_minor"
parameters,
then it sets those values directly on the given parameters
instance – not on a clone – for
allowing the caller to get back the complete parameter values.
However this method only fills missing values, it never modify existing values.createBaseToDerived
in interface MathTransformFactory
baseCRS
- the source coordinate reference system.parameters
- the parameter values for the transform.derivedCS
- the target coordinate system.baseCRS
to derivedCS
,
including unit conversions and axis swapping.NoSuchIdentifierException
- if there is no transform registered for the coordinate operation method.FactoryException
- if the object creation failed. This exception is thrown
if some required parameter has not been supplied, or has illegal value.@Deprecated public MathTransform createCoordinateSystemChange(CoordinateSystem source, CoordinateSystem target) throws FactoryException
createCoordinateSystemChange(CoordinateSystem, CoordinateSystem, Ellipsoid)
source
- the source coordinate system.target
- the target coordinate system.FactoryException
- if the conversion can not be created.public MathTransform createCoordinateSystemChange(CoordinateSystem source, CoordinateSystem target, Ellipsoid ellipsoid) throws FactoryException
ellipsoid
argument is mandatory. In all other cases (including the case where both
coordinate systems are ellipsoidal), the ellipsoid argument is ignored and can be null
.
source
and target
because
this method should not be used for datum shifts. If the two given coordinate systems are ellipsoidal,
then they are assumed to use the same ellipsoid. If different ellipsoids are desired, then a
parameterized transform like "Molodensky",
"Geocentric translations", "Coordinate Frame Rotation" or
"Position Vector transformation" should be used instead.source
- the source coordinate system.target
- the target coordinate system.ellipsoid
- the ellipsoid of EllipsoidalCS
, or null
if none.FactoryException
- if the conversion can not be created.public MathTransform createAffineTransform(Matrix matrix) throws FactoryException
M
,
and output dimension is N
, 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 than M
, and 1
for i equals M
.createAffineTransform
in interface MathTransformFactory
matrix
- the matrix used to define the affine transform.FactoryException
- if the object creation failed.MathTransforms.linear(Matrix)
public MathTransform createConcatenatedTransform(MathTransform tr1, MathTransform tr2) throws FactoryException
The dimension of the output space of the first transform must match the dimension of the input space in the second transform. In order to concatenate more than two transforms, use this constructor repeatedly.
createConcatenatedTransform
in interface MathTransformFactory
tr1
- the first transform to apply to points.tr2
- the second transform to apply to points.FactoryException
- if the object creation failed.MathTransforms.concatenate(MathTransform, MathTransform)
public MathTransform createPassThroughTransform(int firstAffectedOrdinate, MathTransform subTransform, int numTrailingOrdinates) throws FactoryException
Source: firstAffectedOrdinate + subTransform.getSourceDimensions() + numTrailingOrdinates Target: firstAffectedOrdinate + subTransform.getTargetDimensions() + numTrailingOrdinates
createPassThroughTransform
in interface MathTransformFactory
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
from firstAffectedOrdinate
inclusive to dimTarget-numTrailingOrdinates
exclusive.FactoryException
- if the object creation failed.@Deprecated public MathTransform createFromXML(String xml) throws FactoryException
createFromXML
in interface MathTransformFactory
xml
- math transform encoded in XML format.FactoryException
- if the object creation failed.public MathTransform createFromWKT(String text) throws FactoryException
"org.apache.sis.io.wkt"
.createFromWKT
in interface Parser
createFromWKT
in interface MathTransformFactory
text
- math transform encoded in Well-Known Text format.null
).FactoryException
- if the Well-Known Text can not be parsed,
or if the math transform creation failed from some other reason.public OperationMethod getLastMethodUsed()
create(…)
constructor
in the currently running thread. Returns null
if not applicable.
Invoking getLastMethodUsed()
can be useful after a call to
createParameterizedTransform(…)
.
getLastMethodUsed
in interface MathTransformFactory
create(…)
constructor, or null
if unknown of unsupported.createParameterizedTransform(ParameterValueGroup, Context)
public void reload()
Iterable<OperationMethod>
may have changed.
This method performs the following steps:
Iterable
given at construction time is an instance of ServiceLoader
,
invokes its reload()
method.Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.