Class DefaultConversion
- All Implemented Interfaces:
Serializable
,Formattable
,Parameterized
,Deprecable
,LenientComparable
,org.opengis.referencing.IdentifiedObject
,org.opengis.referencing.operation.Conversion
,org.opengis.referencing.operation.CoordinateOperation
,org.opengis.referencing.operation.SingleOperation
- Direct Known Subclasses:
DefaultProjection
This coordinate operation contains an operation method, usually with associated parameter values. In the SIS implementation, the parameter values can be either inferred from the math transform or explicitly provided at construction time in a defining conversion (see below).
Defining conversions
OperationMethod
instances are generally created for a pair of existing source
and target CRS. But Conversion
instances without those information may exist
temporarily while creating a derived or
projected CRS.
Those defining conversions have no source and target CRS since those elements are provided by the
derived or projected CRS themselves. This class provides a constructor for such defining conversions.
After the source and target CRS become known, we can invoke the specialize(…)
method for
creating a math transform from the parameters,
instantiate a new Conversion
of a more specific type
(ConicProjection
,
CylindricalProjection
or
PlanarProjection
) if possible,
and assign the source and target CRS to it.
Immutability and thread safety
This class is immutable and thus thread-safe if the property values (not necessarily the map itself) given to the constructor are also immutable. This means that unless otherwise noted in the javadoc,Conversion
instances created using only SIS factories and static constants can be shared
by many objects and passed between threads without synchronization.- Since:
- 0.6
- Version:
- 1.3
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final long
Serial number for inter-operability with different versions.Fields inherited from class org.apache.sis.referencing.operation.AbstractSingleOperation
parameters
Fields inherited from class org.apache.sis.referencing.operation.AbstractCoordinateOperation
coordinateOperationAccuracy, domainOfValidity, sourceCRS, targetCRS, transform
Fields inherited from class org.apache.sis.referencing.AbstractIdentifiedObject
DEPRECATED_KEY, LOCALE_KEY
Fields inherited from interface org.opengis.referencing.operation.CoordinateOperation
COORDINATE_OPERATION_ACCURACY_KEY, DOMAIN_OF_VALIDITY_KEY, OPERATION_VERSION_KEY, SCOPE_KEY
Fields inherited from interface org.opengis.referencing.IdentifiedObject
ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Constructs a new object in which every attributes are set to a null value.DefaultConversion
(Map<String, ?> properties, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, org.opengis.referencing.crs.CoordinateReferenceSystem interpolationCRS, org.opengis.referencing.operation.OperationMethod method, org.opengis.referencing.operation.MathTransform transform) Creates a coordinate conversion from the given properties.DefaultConversion
(Map<String, ?> properties, org.opengis.referencing.operation.OperationMethod method, org.opengis.referencing.operation.MathTransform transform, org.opengis.parameter.ParameterValueGroup parameters) Creates a defining conversion from the given transform and/or parameters.protected
DefaultConversion
(org.opengis.referencing.operation.Conversion operation) Creates a new coordinate operation with the same values than the specified one.(package private)
DefaultConversion
(org.opengis.referencing.operation.Conversion definition, org.opengis.referencing.crs.CoordinateReferenceSystem source, org.opengis.referencing.crs.CoordinateReferenceSystem target, org.opengis.referencing.operation.MathTransformFactory factory, org.opengis.referencing.operation.OperationMethod[] actual) Constructs a new conversion with the same values than the specified one, together with the specified source and target CRS. -
Method Summary
Modifier and TypeMethodDescriptionstatic DefaultConversion
castOrCopy
(org.opengis.referencing.operation.Conversion object) Returns a SIS coordinate operation implementation with the values of the given arbitrary implementation.private static void
ensureCompatibleDatum
(String param, org.opengis.referencing.crs.CoordinateReferenceSystem expected, org.opengis.referencing.crs.CoordinateReferenceSystem actual) Ensures that theactual
CRS uses a datum which is equal, ignoring metadata, to the datum of theexpected
CRS.Class
<? extends org.opengis.referencing.operation.Conversion> Returns the GeoAPI interface implemented by this class.<T extends org.opengis.referencing.operation.Conversion>
Tspecialize
(Class<T> baseType, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, org.opengis.referencing.operation.MathTransformFactory factory) Returns a specialization of this conversion with a more specific type, source and target CRS.private static org.opengis.referencing.operation.MathTransform
swapAndScaleAxes
(org.opengis.referencing.operation.MathTransform transform, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, int interpDim, boolean isSource, org.opengis.referencing.operation.MathTransformFactory factory) Concatenates to the given transform the operation needed for swapping and scaling the axes.Methods inherited from class org.apache.sis.referencing.operation.AbstractSingleOperation
afterUnmarshal, equals, getMethod, getParameterDescriptors, getParameterValues, setParameterValues
Methods inherited from class org.apache.sis.referencing.operation.AbstractCoordinateOperation
castOrCopy, checkDimensions, computeHashCode, computeTransientFields, formatTo, getCoordinateOperationAccuracy, getDomainOfValidity, getInterpolationCRS, getInterpolationCRS, getLinearAccuracy, getMathTransform, getOperationVersion, getParameterDescriptors, getScope, getSourceCRS, getTargetCRS, getWrapAroundChanges, isDefiningConversion
Methods inherited from class org.apache.sis.referencing.AbstractIdentifiedObject
castOrCopy, equals, formatTo, getAlias, getDescription, getIdentifiers, getName, getRemarks, hashCode, isDeprecated, isHeuristicMatchForName
Methods inherited from class org.apache.sis.io.wkt.FormattableObject
print, toString, toString, toWKT
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.opengis.referencing.operation.Conversion
getOperationVersion, getSourceCRS, getTargetCRS
Methods inherited from interface org.opengis.referencing.operation.CoordinateOperation
getCoordinateOperationAccuracy, getDomainOfValidity, getMathTransform, getScope
Methods inherited from interface org.opengis.referencing.IdentifiedObject
getAlias, getIdentifiers, getName, getRemarks, toWKT
Methods inherited from interface org.opengis.referencing.operation.SingleOperation
getMethod, getParameterValues
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerial number for inter-operability with different versions.- See Also:
-
-
Constructor Details
-
DefaultConversion
public DefaultConversion(Map<String, ?> properties, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, org.opengis.referencing.crs.CoordinateReferenceSystem interpolationCRS, org.opengis.referencing.operation.OperationMethod method, org.opengis.referencing.operation.MathTransform transform) Creates a coordinate conversion from the given properties. The properties given in argument follow the same rules than for the super-class constructor. The following table is a reminder of main (not all) properties:Recognized properties (non exhaustive list) Property name Value type Returned by "name" Identifier
orString
AbstractIdentifiedObject.getName()
"identifiers" Identifier
(optionally as array)AbstractIdentifiedObject.getIdentifiers()
"domainOfValidity" Extent
AbstractCoordinateOperation.getDomainOfValidity()
Relationship between datum
By definition, coordinate conversions do not change the datum. Consequently, the givensourceCRS
andtargetCRS
should use the same datum. If the datum is not the same, then the coordinate operation should probably be a transformation instead. However, Apache SIS does not enforce that condition, but we encourage users to follow it. The reason why SIS is tolerant is because some gray areas may exist about whether an operation should be considered as a conversion or a transformation.Example: converting time instants from a temporal CRS using the January 1st, 1950 epoch to another temporal CRS using the January 1st, 1970 epoch is a datum change, since the epoch is part of temporal datum definition. However, such operation does not have all the accuracy issues of transformations between geodetic datum (empirically determined, over-determined systems, stochastic nature of the parameters). Consequently, some users may consider sufficient to represent temporal epoch changes as conversions instead than transformations.Note that while Apache SIS accepts to constructDefaultConversion
instances with different source and target datum, it does not accept to use such instances for derived CRS construction.- Parameters:
properties
- the properties to be given to the identified object.sourceCRS
- the source CRS.targetCRS
- the target CRS, which shall use a datum equals (ignoring metadata) to the source CRS datum.interpolationCRS
- the CRS of additional coordinates needed for the operation, ornull
if none.method
- the coordinate operation method (mandatory in all cases).transform
- transform from positions in the source CRS to positions in the target CRS.
-
DefaultConversion
public DefaultConversion(Map<String, ?> properties, org.opengis.referencing.operation.OperationMethod method, org.opengis.referencing.operation.MathTransform transform, org.opengis.parameter.ParameterValueGroup parameters) Creates a defining conversion from the given transform and/or parameters. This conversion has no source and target CRS since those elements are usually unknown at defining conversion construction time. The source and target CRS will become known later, at the Derived CRS or Projected CRS construction time.The
properties
map given in argument follows the same rules than for the above constructor.Transform and parameters arguments
At least one of thetransform
orparameters
argument must be non-null. If the caller supplies atransform
argument, then it shall be a transform expecting normalized input coordinates and producing normalized output coordinates. SeeAxesConvention
for more information about what Apache SIS means by "normalized".If the caller cannot yet supply a
MathTransform
, then (s)he shall supply the parameter values needed for creating that transform, with the possible omission of"semi_major"
and"semi_minor"
values. The semi-major and semi-minor parameter values will be set automatically when thespecialize(…)
method will be invoked.If both the
transform
andparameters
arguments are non-null, then the latter should describe the parameters used for creating the transform. Those parameters will be stored for information purpose and can be given back by theAbstractSingleOperation.getParameterValues()
method.- Parameters:
properties
- the properties to be given to the identified object.method
- the operation method.transform
- transform from positions in the source CRS to positions in the target CRS, ornull
.parameters
- thetransform
parameter values, ornull
.- See Also:
-
DefaultConversion
DefaultConversion(org.opengis.referencing.operation.Conversion definition, org.opengis.referencing.crs.CoordinateReferenceSystem source, org.opengis.referencing.crs.CoordinateReferenceSystem target, org.opengis.referencing.operation.MathTransformFactory factory, org.opengis.referencing.operation.OperationMethod[] actual) throws org.opengis.util.FactoryException Constructs a new conversion with the same values than the specified one, together with the specified source and target CRS. While the source conversion can be an arbitrary one, it is typically a defining conversion.- Parameters:
definition
- the defining conversion.source
- the new source CRS.target
- the new target CRS.factory
- the factory to use for creating a transform from the parameters or for performing axis changes.actual
- an array of length 1 where to store the actual operation method used by the math transform factory.- Throws:
org.opengis.util.FactoryException
-
DefaultConversion
protected DefaultConversion(org.opengis.referencing.operation.Conversion operation) Creates a new coordinate operation with the same values than the specified one. This copy constructor provides a way to convert an arbitrary implementation into a SIS one or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.This constructor performs a shallow copy, i.e. the properties are not cloned.
- Parameters:
operation
- the coordinate operation to copy.- See Also:
-
DefaultConversion
private DefaultConversion()Constructs a new object in which every attributes are set to a null value. This is not a valid object. This constructor is strictly reserved to JAXB, which will assign values to the fields using reflection.
-
-
Method Details
-
castOrCopy
Returns a SIS coordinate operation implementation with the values of the given arbitrary implementation. This method performs the first applicable action in the following choices:- If the given object is
null
, then this method returnsnull
. - Otherwise if the given object is an instance of
Conversion
,Projection
,CylindricalProjection
,ConicProjection
orPlanarProjection
, then this method delegates to thecastOrCopy(…)
method of the corresponding SIS subclass. Note that if the given object implements more than one of the above-cited interfaces, then thecastOrCopy(…)
method to be used is unspecified. - Otherwise if the given object is already an instance of
DefaultConversion
, then it is returned unchanged. - Otherwise a new
DefaultConversion
instance is created using the copy constructor and returned. Note that this is a shallow copy operation, because the other properties contained in the given object are not recursively copied.
- Parameters:
object
- the object to get as a SIS implementation, ornull
if none.- Returns:
- a SIS implementation containing the values of the given object (may be the
given object itself), or
null
if the argument was null.
- If the given object is
-
getInterface
Returns the GeoAPI interface implemented by this class. The default implementation returnsConversion.class
. Subclasses implementing a more specific GeoAPI interface shall override this method.- Overrides:
getInterface
in classAbstractCoordinateOperation
- Returns:
- the conversion interface implemented by this class.
-
specialize
public <T extends org.opengis.referencing.operation.Conversion> T specialize(Class<T> baseType, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, org.opengis.referencing.operation.MathTransformFactory factory) throws org.opengis.util.FactoryException Returns a specialization of this conversion with a more specific type, source and target CRS. Thisspecialize(…)
method is typically invoked on defining conversion instances, when more information become available about the conversion to create.The given
baseType
argument can be one of the following values:Conversion.class
Projection.class
CylindricalProjection.class
ConicProjection.class
PlanarProjection.class
specialize(…)
method returns a conversion which implement at least the givenbaseType
interface, but may also implement a more specific GeoAPI interface ifspecialize(…)
has been able to infer the type from the operation method.- Type Parameters:
T
- compile-time type of thebaseType
argument.- Parameters:
baseType
- the base GeoAPI interface to be implemented by the conversion to return.sourceCRS
- the source CRS.targetCRS
- the target CRS.factory
- the factory to use for creating a transform from the parameters or for performing axis changes, ornull
for the default factory.- Returns:
- the conversion of the given type between the given CRS.
- Throws:
ClassCastException
- if a contradiction is found between the givenbaseType
, the defining conversion type and the method operation type.MismatchedDatumException
- if the given CRS do not use the same datum than the source and target CRS of this conversion.org.opengis.util.FactoryException
- if the creation of aMathTransform
from the parameter values, or a change of axis order or units failed.- See Also:
-
ensureCompatibleDatum
private static void ensureCompatibleDatum(String param, org.opengis.referencing.crs.CoordinateReferenceSystem expected, org.opengis.referencing.crs.CoordinateReferenceSystem actual) Ensures that theactual
CRS uses a datum which is equal, ignoring metadata, to the datum of theexpected
CRS.- Parameters:
param
- the parameter name, used only in case of error.expected
- the CRS containing the expected datum, ornull
.actual
- the CRS for which to check the datum, ornull
.- Throws:
MismatchedDatumException
- if the two CRS use different datum.
-
swapAndScaleAxes
private static org.opengis.referencing.operation.MathTransform swapAndScaleAxes(org.opengis.referencing.operation.MathTransform transform, org.opengis.referencing.crs.CoordinateReferenceSystem sourceCRS, org.opengis.referencing.crs.CoordinateReferenceSystem targetCRS, int interpDim, boolean isSource, org.opengis.referencing.operation.MathTransformFactory factory) throws org.opengis.util.FactoryException Concatenates to the given transform the operation needed for swapping and scaling the axes. The two coordinate systems must implement the same GeoAPI coordinate system interface. For example ifsourceCRS
uses aCartesianCS
, thentargetCRS
must use aCartesianCS
too.- Parameters:
transform
- the transform to which to concatenate axis changes.sourceCRS
- the first CRS of the pair for which to check for axes changes.targetCRS
- the second CRS of the pair for which to check for axes changes.interpDim
- the number of dimensions of the interpolation CRS, or 0 if none.isSource
-true
for pre-concatenating the changes, orfalse
for post-concatenating.factory
- the factory to use for performing axis changes.- Throws:
org.opengis.util.FactoryException
-