Class ContextualParameters
- All Implemented Interfaces:
Serializable
,Cloneable
,org.opengis.parameter.GeneralParameterValue
,org.opengis.parameter.ParameterValueGroup
Contextual parameters can be associated to the non-linear kernel step of the above-cited sequence. Since the parameter values of the non-linear kernel contains only normalized parameters (e.g. a map projection on an ellipsoid having a semi-major axis length of 1), Apache SIS needs contextual information for reconstructing the parameters of the complete transforms chain.
Usage in map projections
This object is used mostly for Apache SIS implementation of map projections, where the non-linear kernel is a normalized projection. The complete map projection (ignoring changes of axis order) is a chain of 3 transforms as shown below:ContextualParameters
is typically created and used as below:
- A
MathTransformProvider
instantiates a class from the map projection package. Note that different providers may instantiate the same map projection class. For example, both "Mercator (variant A)" and "Mercator (variant B)" methods instantiate the sameMercator
class, but with different ways to represent the parameters. - The map projection constructor fetches all parameters that it needs from the user supplied
Parameters
, initializes the projection, then saves the parameter values that it actually used in a newContextualParameters
instance. - The map projection constructor may keep only the non-linear parameters for itself,
and gives the linear parameters to the
normalizeGeographicInputs(…)
andMatrixSIS.convertAfter(…)
methods, which will create the matrices show above. The projection constructor is free to apply additional operations on the two affine transforms (normalize / denormalize) before or after the above-cited methods have been invoked. - After all parameter values have been set and the normalize / denormalize matrices defined,
the
completeTransform(…)
method will mark thisContextualParameters
object as unmodifiable and create the chain of transforms from (λ,φ) in angular degrees to (x,y) in metres. Note that conversions to other units and changes in axis order are not the purpose of this transforms chain – they are separated steps.
Serialization
Serialized instances of this class are not guaranteed to be compatible with future SIS versions. Serialization should be used only for short term storage or RMI between applications running the same SIS version.- Since:
- 0.6
- Version:
- 1.3
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enum
Whether a matrix is used for normalization or denormalization before or after a non-linear operation.private final class
Formats the Well Known Text for the transform or the inverse of the transform that would be built from the enclosingContextualParameters
. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate org.opengis.referencing.operation.Matrix
The affine transform to be applied before (normalize) and after (denormalize) the kernel operation.private final org.opengis.parameter.ParameterDescriptorGroup
The parameters that represents the sequence of transforms as a whole.private ContextualParameters
If the inverse coordinate operation can be described by anotherContextualParameters
instance, a reference to that instance.private boolean
false
if this parameter group is modifiable, ortrue
if it has been made unmodifiable (frozen) by a call tocompleteTransform(MathTransformFactory, MathTransform)
.private org.opengis.referencing.operation.Matrix
The affine transform to be applied before (normalize) and after (denormalize) the kernel operation.private static final long
For cross-version compatibility.private org.opengis.parameter.ParameterValue<?>[]
The parameter values. -
Constructor Summary
ConstructorsModifierConstructorDescriptionContextualParameters
(org.opengis.parameter.ParameterDescriptorGroup descriptor, int srcDim, int tgtDim) Creates a new group of parameters with the given descriptor.private
ContextualParameters
(org.opengis.parameter.ParameterDescriptorGroup desc, ContextualParameters forward, BiPredicate<Parameters, org.opengis.parameter.ParameterValue<?>> mapper) Creates a new and frozenContextualParameters
for the inverse operation. -
Method Summary
Modifier and TypeMethodDescriptionorg.opengis.parameter.ParameterValueGroup
Unsupported operation, sinceContextualParameters
groups do not contain sub-groups.(package private) final int
beforeFormat
(List<Object> transforms, int index, boolean inverse) Given a transformation chain, replaces the elements aroundtransforms.get(index)
transform by alternative objects to use when formatting WKT.clone()
Returns a modifiable clone of this parameter value group.org.opengis.referencing.operation.MathTransform
completeTransform
(org.opengis.referencing.operation.MathTransformFactory factory, org.opengis.referencing.operation.MathTransform kernel) Marks thisContextualParameter
as unmodifiable and creates the normalize →kernel
→ denormalize transforms chain.denormalizeGeographicOutputs
(double λ0) Appends a denormalization step after the non-linear kernel, which will convert input coordinates in the two first dimensions from radians to degrees.private void
Ensures that thisContextualParameters
instance is modifiable.boolean
Compares the given object with the parameters for equality.private void
freeze()
Marks this contextual parameter as unmodifiable.final org.opengis.parameter.ParameterDescriptorGroup
Returns the parameters for the normalize → non-linear kernel → denormalize sequence as a whole.final MatrixSIS
Returns the affine transforms to be applied before or after the non-linear kernel operation.List<org.opengis.parameter.ParameterValueGroup>
Unsupported operation, sinceContextualParameters
groups do not contain sub-groups.int
hashCode()
Returns a hash code value for this object.(package private) final ContextualParameters
inverse
(org.opengis.parameter.ParameterDescriptorGroup desc, BiPredicate<Parameters, org.opengis.parameter.ParameterValue<?>> mapper) Creates a new and frozenContextualParameters
for the inverse of this operation.private static MatrixSIS
Creates a matrix for a linear step of the transforms chain.normalizeGeographicInputs
(double λ0) Prepends a normalization step converting input coordinates in the two first dimensions from degrees to radians.org.opengis.parameter.ParameterValue<?>
Returns the parameter value of the given name.private org.opengis.parameter.ParameterNotFoundException
parameterNotFound
(String name) Returns the exception to thrown when the parameter of the given name has not been found.private MatrixSIS
toMatrixSIS
(org.opengis.referencing.operation.Matrix m) Returns the given matrix as an unmodifiable one if thisContextualParameters
instance is unmodifiable.private static void
Logs a warning about a non-invertible transform.List<org.opengis.parameter.GeneralParameterValue>
values()
Returns an unmodifiable list containing all parameters in this group.Methods inherited from class org.apache.sis.parameter.Parameters
booleanValue, cast, cast, castOrWrap, copy, doubleValue, doubleValue, doubleValueList, getDescriptors, getMandatoryValue, getMemberName, getOrCreate, getValue, getValueDomain, intValue, intValueList, isUnmodifiable, print, stringValue, toString, unmodifiable, unmodifiable
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
descriptor
private final org.opengis.parameter.ParameterDescriptorGroup descriptorThe parameters that represents the sequence of transforms as a whole. The parameter values may be used in the (de)normalization transforms, in the kernel, or both.- See Also:
-
normalize
private org.opengis.referencing.operation.Matrix normalizeThe affine transform to be applied before (normalize) and after (denormalize) the kernel operation. OnContextualParameters
construction, those affines are initially identity transforms, to be modified in-place by callers ofgetMatrix(MatrixRole)
or related methods. After thecompleteTransform(MathTransformFactory, MathTransform)
method has been invoked, those matrices are typically (but not necessarily) replaced by theLinearTransform
instances itself.- See Also:
-
denormalize
private org.opengis.referencing.operation.Matrix denormalizeThe affine transform to be applied before (normalize) and after (denormalize) the kernel operation. OnContextualParameters
construction, those affines are initially identity transforms, to be modified in-place by callers ofgetMatrix(MatrixRole)
or related methods. After thecompleteTransform(MathTransformFactory, MathTransform)
method has been invoked, those matrices are typically (but not necessarily) replaced by theLinearTransform
instances itself.- See Also:
-
values
private org.opengis.parameter.ParameterValue<?>[] valuesThe parameter values. Null elements in this array are empty slots available for adding new parameter values. The array length is the maximum number of parameters allowed, which is determined by thedescriptor
.This array is modifiable after construction, but is considered unmodifiable after
completeTransform(MathTransformFactory, MathTransform)
has been invoked.- See Also:
-
inverse
If the inverse coordinate operation can be described by anotherContextualParameters
instance, a reference to that instance. Otherwisenull
. -
isFrozen
private boolean isFrozenfalse
if this parameter group is modifiable, ortrue
if it has been made unmodifiable (frozen) by a call tocompleteTransform(MathTransformFactory, MathTransform)
.- See Also:
-
-
Constructor Details
-
ContextualParameters
public ContextualParameters(org.opengis.parameter.ParameterDescriptorGroup descriptor, int srcDim, int tgtDim) Creates a new group of parameters with the given descriptor. The method parameters shall describe the normalize → non-linear kernel → denormalize sequence as a whole. After construction, callers shall:- Set the relevant parameter values by calls to
parameter(…).setValue(…)
. - Modify the element values in normalization / denormalization affine transforms, optionally by calls to the convenience methods in this class.
- Get the complete transforms chain with a call
completeTransform(…)
- Parameters:
descriptor
- the parameter descriptor.srcDim
- number of source dimensions.tgtDim
- number of target dimensions.- Since:
- 1.0
- Set the relevant parameter values by calls to
-
ContextualParameters
private ContextualParameters(org.opengis.parameter.ParameterDescriptorGroup desc, ContextualParameters forward, BiPredicate<Parameters, org.opengis.parameter.ParameterValue<?>> mapper) Creates a new and frozenContextualParameters
for the inverse operation. An optionalmapper
can be specified for setting the parameter values. If the mapper is-non null, then it will be invoked for each new parameters. The first argument given to the mapper is theforward
operation, and the second argument is the parameter to configure. The return value is whether the parameter should be kept in the new operation.- Parameters:
desc
- descriptor of the inverse operation.forward
- the parameters created for the forward operation.mapper
- the function to invoke for setting parameter values, ornull
if the inverse operation uses the same parameter values.- See Also:
-
-
Method Details
-
linear
Creates a matrix for a linear step of the transforms chain. It is important that the matrices created here are instances ofMatrixSIS
, in order to allowgetMatrix(MatrixRole)
to return the reference to the (de)normalize matrices. -
inverse
final ContextualParameters inverse(org.opengis.parameter.ParameterDescriptorGroup desc, BiPredicate<Parameters, org.opengis.parameter.ParameterValue<?>> mapper) Creates a new and frozenContextualParameters
for the inverse of this operation. An optionalmapper
can be specified for setting the parameter values. If the mapper is-non null, then it will be invoked for each new parameters. The first argument given to the mapper will bethis
operation, and the second argument is the parameter to configure. The return value is whether the parameter should be kept in the new operation.This method caches the inverse operation. It is caller responsibility to ensure that all arguments given to this method are constants for a given
MathTransform
instance.- Parameters:
desc
- descriptor of the inverse operation.mapper
- the function to invoke for setting parameter values, ornull
if the inverse operation uses the same parameter values.- Returns:
- parameters for the inverse operation.
-
getDescriptor
public final org.opengis.parameter.ParameterDescriptorGroup getDescriptor()Returns the parameters for the normalize → non-linear kernel → denormalize sequence as a whole. This is the parameter descriptor of the operation method given to the constructor.The values for those parameters is given by the
values()
method. Those values may be used in the normalization / denormalization transforms, in the kernel, or both.Note: The definition of "kernel" is left to implementers. In the particular case of Apache SIS implementation of map projections, kernels are instances ofNormalizedProjection
. Other "kernels" in SIS areEllipsoidToCentricTransform
andMolodenskyTransform
.- Specified by:
getDescriptor
in interfaceorg.opengis.parameter.GeneralParameterValue
- Specified by:
getDescriptor
in interfaceorg.opengis.parameter.ParameterValueGroup
- Returns:
- the description of the parameters.
-
ensureModifiable
Ensures that thisContextualParameters
instance is modifiable.- Throws:
IllegalStateException
- if thisContextualParameter
has been made unmodifiable.
-
toMatrixSIS
Returns the given matrix as an unmodifiable one if thisContextualParameters
instance is unmodifiable. Note that if this instance is modifiable, then we must return a direct reference to the matrix, not a wrapper, because the caller may need to modify it. -
getMatrix
Returns the affine transforms to be applied before or after the non-linear kernel operation. Immediately after construction, those matrices are modifiable identity matrices. Callers can modify the matrix element values, typically by calls to theMatrixSIS.convertBefore(…)
method. Alternatively, the following methods can be invoked for applying some frequently used configurations: After thecompleteTransform(…)
method has been invoked, the matrices returned by this method are unmodifiable.Application to map projections: afterNormalizedProjection
construction, the matrices returned byprojection.getContextualParameters().getMatrix(…)
are initialized to the values shown below. Note that someNormalizedProjection
subclasses apply further modifications to those matrices.Initial matrix coefficients after NormalizedProjection
constructiongetMatrix(NORMALIZATION)
getMatrix(DENORMALIZATION)
- Parameters:
role
-NORMALIZATION
for fetching the normalization transform to apply before the kernel,DENORMALIZATION
for the denormalization transform to apply after the kernel, orINVERSE_*
for the inverse of the above-cited matrices.- Returns:
- the matrix for the requested normalization or denormalization affine transform.
- Since:
- 0.7
-
normalizeGeographicInputs
Prepends a normalization step converting input coordinates in the two first dimensions from degrees to radians. The normalization can optionally subtract the given λ₀ value (in degrees) from the longitude.Invoking this method is equivalent to concatenating the normalization matrix with the following matrix. This will have the effect of applying the conversion described above before any other operation:
- Parameters:
\u03bb0
- longitude of the central meridian, in degrees.- Returns:
- the normalization affine transform as a matrix. Callers can change that matrix directly if they want to apply additional normalization operations.
- Throws:
IllegalStateException
- if thisContextualParameter
has been made unmodifiable.
-
denormalizeGeographicOutputs
Appends a denormalization step after the non-linear kernel, which will convert input coordinates in the two first dimensions from radians to degrees. After this conversion, the denormalization can optionally add the given λ₀ value (in degrees) to the longitude.Invoking this method is equivalent to concatenating the denormalization matrix with the following matrix. This will have the effect of applying the conversion described above after the non-linear kernel operation:
- Parameters:
\u03bb0
- longitude of the central meridian, in degrees.- Returns:
- the denormalization affine transform as a matrix. Callers can change that matrix directly if they want to apply additional denormalization operations.
- Throws:
IllegalStateException
- if thisContextualParameter
has been made unmodifiable.
-
completeTransform
public org.opengis.referencing.operation.MathTransform completeTransform(org.opengis.referencing.operation.MathTransformFactory factory, org.opengis.referencing.operation.MathTransform kernel) throws org.opengis.util.FactoryException Marks thisContextualParameter
as unmodifiable and creates the normalize →kernel
→ denormalize transforms chain. This method shall be invoked only after the (de)normalization matrices have been set to their final values.The transforms chain created by this method does not include any step for changing axis order or for converting to units other than degrees or metres. Such steps, if desired, should be defined outside
ContextualParameters
. Efficient concatenation of those steps will happen "under the hood".- Parameters:
factory
- the factory to use for creating math transform instances.kernel
- the (usually non-linear) kernel. This is often aNormalizedProjection
.- Returns:
- the concatenation of normalize → the given kernel → denormalize transforms.
- Throws:
org.opengis.util.FactoryException
- if an error occurred while creating a math transform instance.- See Also:
-
freeze
private void freeze()Marks this contextual parameter as unmodifiable.- See Also:
-
parameter
public org.opengis.parameter.ParameterValue<?> parameter(String name) throws org.opengis.parameter.ParameterNotFoundException Returns the parameter value of the given name. Before the call tocompleteTransform(…)
, this method can be used for setting parameter values like below: After the call tocompleteTransform(…)
, the returned parameters are read-only.- Specified by:
parameter
in interfaceorg.opengis.parameter.ParameterValueGroup
- Parameters:
name
- the name of the parameter to search.- Returns:
- the parameter value for the given name.
- Throws:
org.opengis.parameter.ParameterNotFoundException
- if there is no parameter of the given name.
-
values
Returns an unmodifiable list containing all parameters in this group. Callers should not attempt to modify the parameter values in this list.- Specified by:
values
in interfaceorg.opengis.parameter.ParameterValueGroup
- Returns:
- all parameter values.
-
groups
Unsupported operation, sinceContextualParameters
groups do not contain sub-groups.- Specified by:
groups
in interfaceorg.opengis.parameter.ParameterValueGroup
- Parameters:
name
- ignored.- Returns:
- never returned.
-
addGroup
Unsupported operation, sinceContextualParameters
groups do not contain sub-groups.- Specified by:
addGroup
in interfaceorg.opengis.parameter.ParameterValueGroup
- Parameters:
name
- ignored.- Returns:
- never returned.
-
parameterNotFound
Returns the exception to thrown when the parameter of the given name has not been found. -
clone
Returns a modifiable clone of this parameter value group.- Specified by:
clone
in interfaceorg.opengis.parameter.GeneralParameterValue
- Specified by:
clone
in interfaceorg.opengis.parameter.ParameterValueGroup
- Overrides:
clone
in classParameters
- Returns:
- a clone of this parameter value group.
- See Also:
-
hashCode
public int hashCode()Returns a hash code value for this object. This value is implementation-dependent and may change in any future version. -
equals
Compares the given object with the parameters for equality. -
beforeFormat
Given a transformation chain, replaces the elements aroundtransforms.get(index)
transform by alternative objects to use when formatting WKT. The replacement is performed in-place in the given list.This method shall replace only the previous element and the few next elements that need to be changed as a result of the previous change. This method is not expected to continue the iteration after the changes that are of direct concern to this object.
This method is invoked (indirectly) only by
ConcatenatedTransform.getPseudoSteps()
in order to get theParameterValueGroup
of a map projection, or to format aProjectedCRS
WKT.- Parameters:
transforms
- the full chain of concatenated transforms.index
- the index of this transform in thetransforms
chain.inverse
- alwaysfalse
, except if we are formatting the inverse transform.- Returns:
- index of this transform in the
transforms
chain after processing. - See Also:
-
unexpectedException
Logs a warning about a non-invertible transform. This method may be invoked during WKT formatting. This error should never occur, but it still possible to recover from this error and let WKT formatting to continue, which can be useful for debugging.We pretend that the error come from
ConcatenatedTransform.formatTo(Formatter)
because this error should occurs only in the context of WKT formatting of a concatenated transform.
-