org.apache.sis.referencing.operation.transform

Class DefaultMathTransformFactory

Object

AbstractFactory

DefaultMathTransformFactory

All Implemented Interfaces:

Parser, MathTransformFactory, Factory

public class DefaultMathTransformFactory
extends AbstractFactory
implements MathTransformFactory, Parser

Low level factory for creating math transforms. The objects created by this factory do not know what the source and target coordinate systems mean. Because of this low semantic value, high level GIS applications usually do not need to use this factory directly. They can use the static convenience methods in the CRS or Math­Transforms classes instead.

Standard parameters

Math­Transform 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:

• A semi-major and semi-minor axis length in metres.
• A central meridian and latitude of origin in decimal degrees.
• A scale factor, which default to 1.
• A false easting and false northing in metres, which default to 0.

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".

Dynamic parameters

A few non-standard parameters are defined for compatibility reasons, but delegates their work to standard parameters. Those dynamic parameters are not listed in the parameter values. Dynamic parameters are:

• "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.

Mandatory and optional parameters

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.

Operation methods discovery

Operation­Method 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:

• specified explicitely at construction time, or
• discovered by scanning the classpath.

The default way is to scan the classpath. See Math­Transform­Provider for indications about how to add custom coordinate operation methods in a default Apache SIS installation.

Thread safety

This class is safe for multi-thread usage if all referenced Operation­Method instances are thread-safe. There is typically only one Math­Transform­Factory instance for the whole application.

Since:

0.6

See Also:

Math­Transform­Provider, Abstract­Math­Transform

Defined in the sis-referencing module

Nested Class Summary

Nested Classes

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 Summary

Constructors

Constructor and Description
DefaultMathTransformFactory() Creates a new factory which will discover operation methods with a Service­Loader.
DefaultMathTransformFactory(Iterable<? extends OperationMethod> methods) Creates a new factory which will use the given operation methods.

Method Summary

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. Replaced by create­Parameterized­Transform(Parameter­Value­Group, Context).
MathTransform	createConcatenatedTransform(MathTransform tr1, MathTransform tr2) Creates a transform by concatenating two existing transforms.
MathTransform	createCoordinateSystemChange(CoordinateSystem source, CoordinateSystem target) Deprecated. Replaced by create­Coordinate­System­Change(Coordinate­System, Coordinate­System, Ellipsoid)
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 create­Parameterized­Transform(Parameter­Value­Group, 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<Operation­Method> 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.

Methods inherited from class AbstractFactory

get­Vendor

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Methods inherited from interface Factory

get­Vendor

Constructor Detail

DefaultMathTransformFactory

public DefaultMathTransformFactory()

Creates a new factory which will discover operation methods with a Service­Loader. The Operation­Method implementations shall be listed in the following file:

META-INF/services/org.opengis.referencing.operation.OperationMethod

Default­Math­Transform­Factory 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 Math­Transform­Provider interface can be used by the create(…) methods in this class.

See Also:

reload()

DefaultMathTransformFactory

public DefaultMathTransformFactory(Iterable<? extends OperationMethod> methods)

Creates a new factory which will use the given operation methods. The given iterable is stored by reference — its content is not copied — in order to allow deferred Operation­Method constructions. Note that by default, only operation methods that implement the Math­Transform­Provider interface can be used by the create(…) methods in this class.

Requirements:

• The given iterable should not contain duplicated elements.
• The given iterable shall be stable: all elements returned by the first iteration must also be returned by any subsequent iterations, unless reload() has been invoked.
• Operation­Method instances should also implement Math­Transform­Provider.
• All Operation­Method instances shall be thread-safe.
• The 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.
      }
  }

Parameters:

methods - the operation methods to use, stored by reference (not copied).

Method Detail

getAvailableMethods

public Set<OperationMethod> getAvailableMethods(Class<? extends SingleOperation> type)

Returns a set of available methods for coordinate operations of the given type. The type argument can be used for filtering the kind of operations described by the returned Operation­Methods. 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.
• Single­Operation for all coordinate operations.

The returned set may conservatively contain more Operation­Method elements than requested if this Math­Transform­Factory does not support filtering by the given type.

Specified by:

get­Available­Methods in interface Math­Transform­Factory

Parameters:

type - Single­Operation.class for fetching all operation methods, Projection.class for fetching only map projection methods, etc.

Returns:

methods available in this factory for coordinate operations of the given type.

See Also:

get­Default­Parameters(String), create­Parameterized­Transform(Parameter­Value­Group, Context), Default­Operation­Method.get­Operation­Type()

getOperationMethod

public OperationMethod getOperationMethod(String identifier)
                                   throws NoSuchIdentifierException

Returns the operation method for the specified name or identifier. The given argument shall be either a method name (e.g. "Transverse Mercator") or one of its identifiers (e.g. "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.

Parameters:

identifier - the name or identifier of the operation method to search.

Returns:

the coordinate operation method for the given name or identifier.

Throws:

No­Such­Identifier­Exception - if there is no operation method registered for the specified identifier.

See Also:

Default­Coordinate­Operation­Factory.get­Operation­Method(String)

getDefaultParameters

public ParameterValueGroup getDefaultParameters(String method)
                                         throws NoSuchIdentifierException

Returns the default parameter values for a math transform using the given operation method. The method argument is the name of any Operation­Method instance returned by get­Available­Methods(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 create­Parameterized­Transform(…) method.

Specified by:

get­Default­Parameters in interface Math­Transform­Factory

Parameters:

method - the case insensitive name of the coordinate operation method to search for.

Returns:

a new group of parameter values for the Operation­Method identified by the given name.

Throws:

No­Such­Identifier­Exception - if there is no method registered for the given name or identifier.

See Also:

get­Available­Methods(Class), create­Parameterized­Transform(Parameter­Value­Group, Context), Abstract­Math­Transform.get­Parameter­Values()

createParameterizedTransform

@Deprecated
public MathTransform createParameterizedTransform(ParameterValueGroup parameters)
                                           throws NoSuchIdentifierException,
                                                  FactoryException

Deprecated. Replaced by create­Parameterized­Transform(Parameter­Value­Group, Context) where the Context argument can be null.

Creates a transform from a group of parameters. The set of expected parameters varies for each operation.

Specified by:

create­Parameterized­Transform in interface Math­Transform­Factory

Parameters:

parameters - the parameter values. The parameter group name shall be the name of the desired operation method.

Returns:

the transform created from the given parameters.

Throws:

No­Such­Identifier­Exception - if there is no method for the given parameter group name.

Factory­Exception - if the object creation failed. This exception is thrown if some required parameter has not been supplied, or has illegal value.

createParameterizedTransform

public MathTransform createParameterizedTransform(ParameterValueGroup parameters,
                                         DefaultMathTransformFactory.Context context)
                                           throws NoSuchIdentifierException,
                                                  FactoryException

Creates a transform from a group of parameters. The set of expected parameters varies for each operation. The easiest way to provide parameter values is to get an initially empty group for the desired operation by calling get­Default­Parameters(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:

1. Inferring the "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.
2. Concatenating the parameterized transform with any other transforms required for performing units changes and ordinates swapping.

The complete group of parameters, including "semi_major", "semi_minor" or other calculated values, can be obtained by a call to Default­Math­Transform­Factory.Context.get­Completed­Parameters() after create­Parameterized­Transform(…) 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 Operation­Method instance used by this constructor can be obtained by a call to get­Last­Method­Used().

Parameters:

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.

Returns:

the transform created from the given parameters.

Throws:

No­Such­Identifier­Exception - if there is no method for the given parameter group name.

Factory­Exception - if the object creation failed. This exception is thrown if some required parameter has not been supplied, or has illegal value.

See Also:

get­Default­Parameters(String), get­Available­Methods(Class), get­Last­Method­Used(), Parameter­Builder.create­Group­For­Map­Projection(Parameter­Descriptor...)

swapAndScaleAxes

public MathTransform swapAndScaleAxes(MathTransform parameterized,
                             DefaultMathTransformFactory.Context context)
                               throws FactoryException

Given a transform between normalized spaces, creates a transform taking in account axis directions, units of measurement and longitude rotation. This method concatenates the given parameterized transform with any other transform required for performing units changes and ordinates swapping.

The given parameterized transform shall expect normalized input coordinates and produce normalized output coordinates. See Axes­Convention for more information about what Apache SIS means by "normalized".

Example: The most typical examples of transforms with normalized inputs/outputs are normalized map projections expecting (longitude, latitude) inputs in degrees and calculating (x, y) coordinates in metres, both of them with (East, North) axis orientations.

Controlling the normalization process

Users who need a different normalized space than the default one way find more convenient to override the Context.get­Matrix(Contextual­Parameters.Matrix­Role) method.

Parameters:

parameterized - a transform for normalized input and output coordinates.

context - source and target coordinate systems in which the transform is going to be used.

Returns:

a transform taking in account unit conversions and axis swapping.

Throws:

Factory­Exception - if the object creation failed.

Since:

0.7

See Also:

Axes­Convention.NORMALIZED, Default­Conversion.Default­Conversion(Map, Operation­Method, Math­Transform, Parameter­Value­Group)

createBaseToDerived

@Deprecated
public MathTransform createBaseToDerived(CoordinateReferenceSystem baseCRS,
                                           ParameterValueGroup parameters,
                                           CoordinateSystem derivedCS)
                                  throws NoSuchIdentifierException,
                                         FactoryException

Deprecated. Replaced by create­Parameterized­Transform(Parameter­Value­Group, Context).

Creates a transform from a base CRS to a derived CS using the given parameters. If this method needs to set the values of "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.

Specified by:

create­Base­To­Derived in interface Math­Transform­Factory

Parameters:

base­CRS - the source coordinate reference system.

parameters - the parameter values for the transform.

derived­CS - the target coordinate system.

Returns:

the parameterized transform from base­CRS to derived­CS, including unit conversions and axis swapping.

Throws:

No­Such­Identifier­Exception - if there is no transform registered for the coordinate operation method.

Factory­Exception - if the object creation failed. This exception is thrown if some required parameter has not been supplied, or has illegal value.

createCoordinateSystemChange

@Deprecated
public MathTransform createCoordinateSystemChange(CoordinateSystem source,
                                                    CoordinateSystem target)
                                           throws FactoryException

Deprecated. Replaced by create­Coordinate­System­Change(Coordinate­System, Coordinate­System, Ellipsoid)

Creates a math transform that represent a change of coordinate system.

Parameters:

source - the source coordinate system.

target - the target coordinate system.

Returns:

a conversion from the given source to the given target coordinate system.

Throws:

Factory­Exception - if the conversion can not be created.

Since:

0.7

createCoordinateSystemChange

public MathTransform createCoordinateSystemChange(CoordinateSystem source,
                                         CoordinateSystem target,
                                         Ellipsoid ellipsoid)
                                           throws FactoryException

Creates a math transform that represent a change of coordinate system. If exactly one argument is an ellipsoidal coordinate systems, then the 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.

Design note: this method does not accept separated ellipsoid arguments for 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.

Parameters:

source - the source coordinate system.

target - the target coordinate system.

ellipsoid - the ellipsoid of Ellipsoidal­CS, or null if none.

Returns:

a conversion from the given source to the given target coordinate system.

Throws:

Factory­Exception - if the conversion can not be created.

Since:

0.8

createAffineTransform

public MathTransform createAffineTransform(Matrix matrix)
                                    throws FactoryException

Creates an affine transform from a matrix. If the transform input dimension is 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.

Specified by:

create­Affine­Transform in interface Math­Transform­Factory

Parameters:

matrix - the matrix used to define the affine transform.

Returns:

the affine transform.

Throws:

Factory­Exception - if the object creation failed.

See Also:

Math­Transforms.linear(Matrix)

createConcatenatedTransform

public MathTransform createConcatenatedTransform(MathTransform tr1,
                                        MathTransform tr2)
                                          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. In order to concatenate more than two transforms, use this constructor repeatedly.

Specified by:

create­Concatenated­Transform in interface Math­Transform­Factory

Parameters:

tr1 - the first transform to apply to points.

tr2 - the second transform to apply to points.

Returns:

the concatenated transform.

Throws:

Factory­Exception - if the object creation failed.

See Also:

Math­Transforms.concatenate(Math­Transform, Math­Transform)

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.

Example: Giving (latitude, longitude, height) coordinates, a pass through transform can convert the height values from meters to feet without affecting the (latitude, longitude) values.

The resulting transform will have the following dimensions:

Source: firstAffectedOrdinate + subTransform.getSourceDimensions() + numTrailingOrdinates
Target: firstAffectedOrdinate + subTransform.getTargetDimensions() + numTrailingOrdinates

Specified by:

create­Pass­Through­Transform in interface Math­Transform­Factory

Parameters:

first­Affected­Ordinate - the lowest index of the affected ordinates.

sub­Transform - transform to use for affected ordinates.

num­Trailing­Ordinates - number of trailing ordinates to pass through. Affected ordinates will range from first­Affected­Ordinate inclusive to dim­Target-num­Trailing­Ordinates exclusive.

Returns:

a pass through transform.

Throws:

Factory­Exception - if the object creation failed.

createFromXML

@Deprecated
public MathTransform createFromXML(String xml)
                            throws FactoryException

Deprecated.

There is no XML format for math transforms.

Specified by:

create­From­XML in interface Math­Transform­Factory

Parameters:

xml - math transform encoded in XML format.

Throws:

Factory­Exception - if the object creation failed.

createFromWKT

public MathTransform createFromWKT(String text)
                            throws FactoryException

Creates a math transform object from a Well Known Text (WKT). If the given text contains non-fatal anomalies (unknown or unsupported WKT elements, inconsistent unit definitions, etc.), warnings may be reported in a logger named "org.apache.sis.io.wkt".

Specified by:

create­From­WKT in interface Parser

Specified by:

create­From­WKT in interface Math­Transform­Factory

Parameters:

text - math transform encoded in Well-Known Text format.

Returns:

the math transform (never null).

Throws:

Factory­Exception - if the Well-Known Text can not be parsed, or if the math transform creation failed from some other reason.

getLastMethodUsed

public OperationMethod getLastMethodUsed()

Returns the operation method used by the latest call to a create(…) constructor in the currently running thread. Returns null if not applicable.

Invoking get­Last­Method­Used() can be useful after a call to create­Parameterized­Transform(…).

Specified by:

get­Last­Method­Used in interface Math­Transform­Factory

Returns:

the last method used by a create(…) constructor, or null if unknown of unsupported.

See Also:

create­Parameterized­Transform(Parameter­Value­Group, Context)

reload

public void reload()

Notifies this factory that the elements provided by the Iterable<Operation­Method> may have changed. This method performs the following steps:

• Clears all caches.
• If the Iterable given at construction time is an instance of Service­Loader, invokes its reload() method.

This method is useful to sophisticated applications which dynamically make new plug-ins available at runtime, for example following changes of the application classpath.

See Also:

Default­Math­Transform­Factory(Iterable), Service­Loader.reload()