Class DefaultMathTransformFactory.Context
java.lang.Object
org.apache.sis.referencing.operation.transform.DefaultMathTransformFactory.Context
- All Implemented Interfaces:
Serializable
- Direct Known Subclasses:
MathTransformContext
- Enclosing class:
- DefaultMathTransformFactory
Source and target coordinate systems for which a new parameterized transform is going to be used.
DefaultMathTransformFactory
uses this information for:
- Completing some parameters if they were not provided. In particular, the source ellipsoid can be used for providing values for the
"semi_major"
and"semi_minor"
parameters in map projections. - Swapping and scaling axes if the source or the target coordinate systems are not normalized.
OperationMethod
,
for example "Longitude rotation" (EPSG:9601) for changing the prime meridian.
Scope
Instances of this class should be short-lived (they exist only the time needed for creating aMathTransform
)
and should not be shared (because they provide no immutability guarantees).
This class is not thread-safe.- Since:
- 0.7
- Version:
- 1.3
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionNames of parameters which have been inferred from context.private org.opengis.parameter.ParameterValueGroup
The parameters actually used.private org.opengis.referencing.operation.OperationMethod
The provider that created the parameterizedMathTransform
instance, ornull
if this information does not apply.private static final long
For cross-version compatibility.private org.opengis.referencing.cs.CoordinateSystem
Coordinate system of the source or target points.private org.opengis.referencing.datum.Ellipsoid
The ellipsoid of the source or target ellipsoidal coordinate system, ornull
if it does not apply.private org.opengis.referencing.cs.CoordinateSystem
Coordinate system of the source or target points.private org.opengis.referencing.datum.Ellipsoid
The ellipsoid of the source or target ellipsoidal coordinate system, ornull
if it does not apply. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescription(package private) final RuntimeException
completeParameters
(DefaultMathTransformFactory factory, org.opengis.referencing.operation.OperationMethod method, org.opengis.parameter.ParameterValueGroup userParams) Completes the parameter group with information about source and target ellipsoid axis lengths, if available.private void
ensureCompatibleParameters
(boolean writable) If the parameters given by the user were not created bygetDefaultParameters(String)
or something equivalent, copies those parameters into the structure expected by the provider.private static boolean
ensureSet
(org.opengis.parameter.ParameterValue<?> parameter, double actual, double expected, javax.measure.Unit<?> unit, double tolerance) Ensures that a value is set in the given parameter.org.opengis.parameter.ParameterValueGroup
Returns the parameter values used for the math transform creation, including the parameters completed by the factory.private org.opengis.parameter.ParameterValue<?>
getContextualParameter
(String name) Gets a parameter for which to infer a value from the context.Returns the names of parameters that have been inferred from the context.org.opengis.referencing.operation.Matrix
Returns the matrix that represent the affine transform to concatenate before or after the parameterized transform.org.opengis.referencing.operation.OperationMethod
Returns the operation method used for the math transform creation.org.opengis.referencing.cs.CoordinateSystem
Returns the source coordinate system, ornull
if unspecified.org.opengis.referencing.datum.Ellipsoid
Returns the ellipsoid of the source ellipsoidal coordinate system, ornull
if it does not apply.org.opengis.referencing.cs.CoordinateSystem
Returns the target coordinate system, ornull
if unspecified.org.opengis.referencing.datum.Ellipsoid
Returns the ellipsoid of the target ellipsoidal coordinate system, ornull
if it does not apply.private static double
getValue
(org.opengis.parameter.ParameterValue<?> parameter, javax.measure.Unit<?> unit) Returns the value of the given parameter in the given unit, orNaN
if the parameter is not set.private RuntimeException
setEllipsoid
(org.opengis.referencing.datum.Ellipsoid ellipsoid, String semiMajor, String semiMinor, boolean inverseFlattening, RuntimeException failure) Completes the parameter group with information about source or target ellipsoid axis lengths, if available.void
setSource
(org.opengis.referencing.crs.GeodeticCRS crs) Sets the source coordinate system and related ellipsoid to the components of given CRS.void
setSource
(org.opengis.referencing.cs.CoordinateSystem cs) Sets the source coordinate system to the given value.void
setSource
(org.opengis.referencing.cs.EllipsoidalCS cs, org.opengis.referencing.datum.Ellipsoid ellipsoid) Deprecated.void
setTarget
(org.opengis.referencing.crs.GeodeticCRS crs) Sets the target coordinate system and related ellipsoid to the components of given CRS.void
setTarget
(org.opengis.referencing.cs.CoordinateSystem cs) Sets the target coordinate system to the given value.void
setTarget
(org.opengis.referencing.cs.EllipsoidalCS cs, org.opengis.referencing.datum.Ellipsoid ellipsoid) Deprecated.Replaced bysetTarget(GeodeticCRS)
.toString()
Returns a string representation of this context for debugging purposes.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
sourceCS
private org.opengis.referencing.cs.CoordinateSystem sourceCSCoordinate system of the source or target points. -
targetCS
private org.opengis.referencing.cs.CoordinateSystem targetCSCoordinate system of the source or target points. -
sourceEllipsoid
private org.opengis.referencing.datum.Ellipsoid sourceEllipsoid -
targetEllipsoid
private org.opengis.referencing.datum.Ellipsoid targetEllipsoid -
provider
private org.opengis.referencing.operation.OperationMethod providerThe provider that created the parameterizedMathTransform
instance, ornull
if this information does not apply. This field is used for transferring information betweencreateParameterizedTransform(…)
andswapAndScaleAxes(…)
. -
parameters
private org.opengis.parameter.ParameterValueGroup parametersThe parameters actually used.- See Also:
-
contextualParameters
Names of parameters which have been inferred from context.- See Also:
-
-
Constructor Details
-
Context
public Context()Creates a new context with all properties initialized tonull
.
-
-
Method Details
-
setSource
public void setSource(org.opengis.referencing.cs.CoordinateSystem cs) Sets the source coordinate system to the given value. The source ellipsoid is unconditionally set tonull
.- Parameters:
cs
- the coordinate system to set as the source (can benull
).
-
setSource
@Deprecated public void setSource(org.opengis.referencing.cs.EllipsoidalCS cs, org.opengis.referencing.datum.Ellipsoid ellipsoid) Deprecated.Replaced bysetSource(GeodeticCRS)
.Sets the source coordinate system and its associated ellipsoid to the given value.Design note: ellipsoidal coordinate systems and ellipsoids are associated indirectly, through a geodetic CRS. However, this method expects those two components to be given explicitly instead of inferring them from aCoordinateReferenceSystem
for making clear thatMathTransformFactory
does not perform any geodetic datum analysis. For coordinate operations that take datum changes in account (including change of prime meridian), seeDefaultCoordinateOperationFactory
. This policy helps to enforce a separation of concerns.- Parameters:
cs
- the coordinate system to set as the source, ornull
.ellipsoid
- the ellipsoid associated to the given coordinate system, ornull
.
-
setSource
public void setSource(org.opengis.referencing.crs.GeodeticCRS crs) Sets the source coordinate system and related ellipsoid to the components of given CRS. TheEllipsoid
, fetched from the geodetic datum, is often used together with anEllipsoidalCS
, but not necessarily. The geodetic CRS may also be associated with a spherical or Cartesian coordinate system, and the ellipsoid information may still be needed even with those non-ellipsoidal coordinate systems.This method is not for datum shifts. All datum information other than the ellipsoid are ignored.
- Parameters:
crs
- the coordinate system and ellipsoid to set as the source, ornull
.- Since:
- 1.3
-
setTarget
public void setTarget(org.opengis.referencing.cs.CoordinateSystem cs) Sets the target coordinate system to the given value. The target ellipsoid is unconditionally set tonull
.- Parameters:
cs
- the coordinate system to set as the target (can benull
).
-
setTarget
@Deprecated public void setTarget(org.opengis.referencing.cs.EllipsoidalCS cs, org.opengis.referencing.datum.Ellipsoid ellipsoid) Deprecated.Replaced bysetTarget(GeodeticCRS)
.Sets the target coordinate system and its associated ellipsoid to the given value.Design note: seesetSource(EllipsoidalCS, Ellipsoid)
.- Parameters:
cs
- the coordinate system to set as the source, ornull
.ellipsoid
- the ellipsoid associated to the given coordinate system, ornull
.
-
setTarget
public void setTarget(org.opengis.referencing.crs.GeodeticCRS crs) Sets the target coordinate system and related ellipsoid to the components of given CRS. TheEllipsoid
, fetched from the geodetic datum, is often used together with anEllipsoidalCS
, but not necessarily. The geodetic CRS may also be associated with a spherical or Cartesian coordinate system, and the ellipsoid information may still be needed even with those non-ellipsoidal coordinate systems.This method is not for datum shifts. All datum information other than the ellipsoid are ignored.
- Parameters:
crs
- the coordinate system and ellipsoid to set as the target, ornull
.- Since:
- 1.3
-
getSourceCS
public org.opengis.referencing.cs.CoordinateSystem getSourceCS()Returns the source coordinate system, ornull
if unspecified.- Returns:
- the source coordinate system, or
null
.
-
getSourceEllipsoid
public org.opengis.referencing.datum.Ellipsoid getSourceEllipsoid()Returns the ellipsoid of the source ellipsoidal coordinate system, ornull
if it does not apply. This information is valid only ifgetSourceCS()
returns an instance ofEllipsoidalCS
.- Returns:
- the ellipsoid of the source ellipsoidal coordinate system, or
null
if it does not apply.
-
getTargetCS
public org.opengis.referencing.cs.CoordinateSystem getTargetCS()Returns the target coordinate system, ornull
if unspecified.- Returns:
- the target coordinate system, or
null
.
-
getTargetEllipsoid
public org.opengis.referencing.datum.Ellipsoid getTargetEllipsoid()Returns the ellipsoid of the target ellipsoidal coordinate system, ornull
if it does not apply. This information is valid only ifgetTargetCS()
returns an instance ofEllipsoidalCS
.- Returns:
- the ellipsoid of the target ellipsoidal coordinate system, or
null
if it does not apply.
-
getMatrix
public org.opengis.referencing.operation.Matrix getMatrix(ContextualParameters.MatrixRole role) throws org.opengis.util.FactoryException Returns the matrix that represent the affine transform to concatenate before or after the parameterized transform. Therole
argument specifies which matrix is desired:NORMALIZATION
for the conversion from the source coordinate system to a normalized coordinate system, usually with (longitude, latitude) axis order in degrees or (easting, northing) in metres. This normalization needs to be applied before the parameterized transform.DENORMALIZATION
for the conversion from a normalized coordinate system to the target coordinate system, for example with (latitude, longitude) axis order. This denormalization needs to be applied after the parameterized transform.INVERSE_NORMALIZATION
andINVERSE_DENORMALIZATION
are also supported but rarely used.
DefaultMathTransformFactory.swapAndScaleAxes(MathTransform, Context)
. Users an override this method if they need to customize the normalization process.- Parameters:
role
- whether the normalization or denormalization matrix is desired.- Returns:
- the requested matrix, or
null
if thisContext
has no information about the coordinate system. - Throws:
org.opengis.util.FactoryException
- if an error occurred while computing the matrix.- See Also:
-
getMethodUsed
public org.opengis.referencing.operation.OperationMethod getMethodUsed()Returns the operation method used for the math transform creation. This is the same information thanDefaultMathTransformFactory.getLastMethodUsed()
but more stable (not affected by transforms created with other contexts).- Returns:
- the operation method used by the factory.
- Throws:
IllegalStateException
- ifDefaultMathTransformFactory.createParameterizedTransform(ParameterValueGroup, Context)
has not yet been invoked.- Since:
- 1.3
- See Also:
-
getContextualParameters
Returns the names of parameters that have been inferred from the context. The set of keys can contain any of"dim"
,"semi_major"
,"semi_minor"
,"src_semi_major"
,"src_semi_minor"
,"tgt_semi_major"
,"tgt_semi_minor"
and/or"inverse_flattening"
, depending on the operation method used. The parameters named in that set are included in the parameters returned bygetCompletedParameters()
.Associated boolean values
The associated boolean in the map tells whether the named parameter value is really contextual. The boolean isFALSE
if the user explicitly specified a value in the parameters given to theDefaultMathTransformFactory.createParameterizedTransform(ParameterValueGroup, Context)
method, and that value is different than the value inferred from the context. Such inconsistencies are also logged atLevel.WARNING
. In all other cases (no value specified by the user, or a value was specified but is consistent with the context), the associated boolean in the map isTRUE
.Mutability
The returned map is modifiable for making easier for callers to amend the contextual information. This map is not used byContext
except for information purposes (e.g. intoString()
). In particular, modifications of this map have no incidence on the createdMathTransform
.- Returns:
- names of parameters inferred from context.
- Since:
- 1.3
-
getCompletedParameters
public org.opengis.parameter.ParameterValueGroup getCompletedParameters()Returns the parameter values used for the math transform creation, including the parameters completed by the factory. The parameters inferred from the context are listed bygetContextualParameters()
.- Returns:
- the parameter values used by the factory.
- Throws:
IllegalStateException
- ifDefaultMathTransformFactory.createParameterizedTransform(ParameterValueGroup, Context)
has not yet been invoked.
-
ensureCompatibleParameters
If the parameters given by the user were not created bygetDefaultParameters(String)
or something equivalent, copies those parameters into the structure expected by the provider. The intent is to make sure that we have room for the parameters thatsetEllipsoids(…)
may write.A side effect of this method is that the copy operation may perform a check of parameter value validity. This may result in an
InvalidParameterNameException
orInvalidParameterValueException
to be thrown.- Parameters:
writable
-true
if this method should also check that the parameters group is editable.- Throws:
IllegalArgumentException
- if the copy cannot be performed because a parameter has a unrecognized name or an illegal value.
-
getContextualParameter
private org.opengis.parameter.ParameterValue<?> getContextualParameter(String name) throws org.opengis.parameter.ParameterNotFoundException Gets a parameter for which to infer a value from the context. The consistency flag is initially set toBoolean.TRUE
.- Parameters:
name
- name of the contextual parameter.- Returns:
- the parameter.
- Throws:
org.opengis.parameter.ParameterNotFoundException
- if the parameter was not found.
-
getValue
private static double getValue(org.opengis.parameter.ParameterValue<?> parameter, javax.measure.Unit<?> unit) Returns the value of the given parameter in the given unit, orNaN
if the parameter is not set.NOTE: Do not merge this function with
ensureSet(…)
. We keep those two methods separated in order to give tocreateParameterizedTransform(…)
a "all or nothing" behavior. -
ensureSet
private static boolean ensureSet(org.opengis.parameter.ParameterValue<?> parameter, double actual, double expected, javax.measure.Unit<?> unit, double tolerance) Ensures that a value is set in the given parameter.- If the parameter has no value, then it is set to the given value.
- If the parameter already has a value, then the parameter is left unchanged but its value is compared to the given one for consistency.
- Parameters:
parameter
- the parameter which must have a value.actual
- the current parameter value, orNaN
if none.expected
- the expected parameter value, derived from the ellipsoid.unit
- the unit ofvalue
.tolerance
- maximal difference (in unit ofunit
) for considering the two values as equivalent.- Returns:
true
if there is a mismatch between the actual value and the expected one.
-
setEllipsoid
private RuntimeException setEllipsoid(org.opengis.referencing.datum.Ellipsoid ellipsoid, String semiMajor, String semiMinor, boolean inverseFlattening, RuntimeException failure) Completes the parameter group with information about source or target ellipsoid axis lengths, if available. This method writes semi-major and semi-minor parameter values only if they do not already exists in the given parameters.- Parameters:
ellipsoid
- the ellipsoid from which to get axis lengths of flattening factor, ornull
.semiMajor
-"semi_major
,"src_semi_major
or"tgt_semi_major
parameter name.semiMinor
-"semi_minor
,"src_semi_minor
or"tgt_semi_minor
parameter name.inverseFlattening
-true
if this method can try to set the"inverse_flattening"
parameter.- Returns:
- the exception if the operation failed, or
null
if none. This exception is not thrown now because the caller may succeed in creating the transform anyway, or otherwise may produce a more informative exception.
-
completeParameters
final RuntimeException completeParameters(DefaultMathTransformFactory factory, org.opengis.referencing.operation.OperationMethod method, org.opengis.parameter.ParameterValueGroup userParams) throws org.opengis.util.FactoryException, IllegalArgumentException Completes the parameter group with information about source and target ellipsoid axis lengths, if available. This method writes semi-major and semi-minor parameter values only if they do not already exists in the given parameters.The given method and parameters are stored in the
provider
andparameters
fields respectively. The actual stored values may differ from the values given to this method.- Parameters:
factory
- the enclosing factory.method
- description of the transform to be created, ornull
if unknown.- Returns:
- the exception if the operation failed, or
null
if none. This exception is not thrown now because the caller may succeed in creating the transform anyway, or otherwise may produce a more informative exception. - Throws:
IllegalArgumentException
- if the operation fails because a parameter has a unrecognized name or an illegal value.org.opengis.util.FactoryException
- See Also:
-
toString
Returns a string representation of this context for debugging purposes. Current implementation write the name of source/target coordinate systems and ellipsoids. If contextual parameters have already been inferred, then their names are appended with inconsistent parameters (if any) written on a separated line.
-
setSource(GeodeticCRS)
.