Class ContextualParameters

java.lang.Object
org.apache.sis.parameter.Parameters
org.apache.sis.referencing.operation.transform.ContextualParameters
All Implemented Interfaces:
Serializable, Cloneable, org.opengis.parameter.GeneralParameterValue, org.opengis.parameter.ParameterValueGroup

public class ContextualParameters extends Parameters implements Serializable
The parameters that describe a sequence of normalizenon-linear kerneldenormalize transforms as a whole. The normalize and denormalize steps must be affine transforms, while the non-linear kernel is arbitrary.
Note: actually there is nothing in this class which force the kernel to be non-linear. But this class is useless if the kernel is linear, because 3 linear steps can be efficiently concatenated in a single affine transform.

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:
Map projection on a normalized ellipsoid
ContextualParameters is typically created and used as below:
  1. 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 same Mercator class, but with different ways to represent the parameters.
  2. 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 new ContextualParameters instance.
  3. The map projection constructor may keep only the non-linear parameters for itself, and gives the linear parameters to the normalizeGeographicInputs(…) and MatrixSIS.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.
  4. After all parameter values have been set and the normalize / denormalize matrices defined, the completeTransform(…) method will mark this ContextualParameters 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 Classes
    Modifier and Type
    Class
    Description
    static 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 enclosing ContextualParameters.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private 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.
    If the inverse coordinate operation can be described by another ContextualParameters instance, a reference to that instance.
    private boolean
    false if this parameter group is modifiable, or true if it has been made unmodifiable (frozen) by a call to completeTransform(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

    Constructors
    Modifier
    Constructor
    Description
     
    ContextualParameters(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 frozen ContextualParameters for the inverse operation.
  • Method Summary

    Modifier and Type
    Method
    Description
    org.opengis.parameter.ParameterValueGroup
    Unsupported operation, since ContextualParameters 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 around transforms.get(index) transform by alternative objects to use when formatting WKT.
    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 this ContextualParameter as unmodifiable and creates the normalizekerneldenormalize transforms chain.
    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 this ContextualParameters instance is modifiable.
    boolean
    equals(Object object)
    Compares the given object with the parameters for equality.
    private void
    Marks this contextual parameter as unmodifiable.
    final org.opengis.parameter.ParameterDescriptorGroup
    Returns the parameters for the normalizenon-linear kerneldenormalize 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>
    groups(String name)
    Unsupported operation, since ContextualParameters groups do not contain sub-groups.
    int
    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 frozen ContextualParameters for the inverse of this operation.
    private static MatrixSIS
    linear(String name, Integer size)
    Creates a matrix for a linear step of the transforms chain.
    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
    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 this ContextualParameters instance is unmodifiable.
    private static void
    Logs a warning about a non-invertible transform.
    List<org.opengis.parameter.GeneralParameterValue>
    Returns an unmodifiable list containing all parameters in this group.

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:
    • descriptor

      private final org.opengis.parameter.ParameterDescriptorGroup descriptor
      The 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 normalize
      The affine transform to be applied before (normalize) and after (denormalize) the kernel operation. On ContextualParameters construction, those affines are initially identity transforms, to be modified in-place by callers of getMatrix(MatrixRole) or related methods. After the completeTransform(MathTransformFactory, MathTransform) method has been invoked, those matrices are typically (but not necessarily) replaced by the LinearTransform instances itself.
      See Also:
    • denormalize

      private org.opengis.referencing.operation.Matrix denormalize
      The affine transform to be applied before (normalize) and after (denormalize) the kernel operation. On ContextualParameters construction, those affines are initially identity transforms, to be modified in-place by callers of getMatrix(MatrixRole) or related methods. After the completeTransform(MathTransformFactory, MathTransform) method has been invoked, those matrices are typically (but not necessarily) replaced by the LinearTransform instances itself.
      See Also:
    • values

      private org.opengis.parameter.ParameterValue<?>[] values
      The 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 the descriptor.

      This array is modifiable after construction, but is considered unmodifiable after completeTransform(MathTransformFactory, MathTransform) has been invoked.

      See Also:
    • inverse

      private ContextualParameters inverse
      If the inverse coordinate operation can be described by another ContextualParameters instance, a reference to that instance. Otherwise null.
      See Also:
    • isFrozen

      private boolean isFrozen
      false if this parameter group is modifiable, or true if it has been made unmodifiable (frozen) by a call to completeTransform(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 normalizenon-linear kerneldenormalize sequence as a whole. After construction, callers shall: See class javadoc for more information.
      Parameters:
      descriptor - the parameter descriptor.
      srcDim - number of source dimensions.
      tgtDim - number of target dimensions.
      Since:
      1.0
    • ContextualParameters

      private ContextualParameters(org.opengis.parameter.ParameterDescriptorGroup desc, ContextualParameters forward, BiPredicate<Parameters,org.opengis.parameter.ParameterValue<?>> mapper)
      Creates a new and frozen ContextualParameters for the inverse operation. An optional mapper 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 the forward 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, or null if the inverse operation uses the same parameter values.
      See Also:
  • Method Details

    • linear

      private static MatrixSIS linear(String name, Integer size)
      Creates a matrix for a linear step of the transforms chain. It is important that the matrices created here are instances of MatrixSIS, in order to allow getMatrix(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 frozen ContextualParameters for the inverse of this operation. An optional mapper 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 be this 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, or null 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 normalizenon-linear kerneldenormalize 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 of NormalizedProjection. Other "kernels" in SIS are EllipsoidToCentricTransform and MolodenskyTransform.
      Specified by:
      getDescriptor in interface org.opengis.parameter.GeneralParameterValue
      Specified by:
      getDescriptor in interface org.opengis.parameter.ParameterValueGroup
      Returns:
      the description of the parameters.
    • ensureModifiable

      private void ensureModifiable() throws IllegalStateException
      Ensures that this ContextualParameters instance is modifiable.
      Throws:
      IllegalStateException - if this ContextualParameter has been made unmodifiable.
    • toMatrixSIS

      private MatrixSIS toMatrixSIS(org.opengis.referencing.operation.Matrix m)
      Returns the given matrix as an unmodifiable one if this ContextualParameters 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

      public final MatrixSIS getMatrix(ContextualParameters.MatrixRole role)
      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 the MatrixSIS.convertBefore(…) method. Alternatively, the following methods can be invoked for applying some frequently used configurations: After the completeTransform(…) method has been invoked, the matrices returned by this method are unmodifiable.
      Application to map projections: after NormalizedProjection construction, the matrices returned by projection.getContextualParameters().getMatrix(…) are initialized to the values shown below. Note that some NormalizedProjection subclasses apply further modifications to those matrices.
      Initial matrix coefficients after NormalizedProjection construction
      getMatrix(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, or INVERSE_* for the inverse of the above-cited matrices.
      Returns:
      the matrix for the requested normalization or denormalization affine transform.
      Since:
      0.7
    • normalizeGeographicInputs

      public MatrixSIS normalizeGeographicInputs(double λ0)
      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 this ContextualParameter has been made unmodifiable.
    • denormalizeGeographicOutputs

      public MatrixSIS 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. 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 this ContextualParameter 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 this ContextualParameter as unmodifiable and creates the normalizekerneldenormalize 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 a NormalizedProjection.
      Returns:
      the concatenation of normalizethe given kerneldenormalize 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 to completeTransform(…), this method can be used for setting parameter values like below: After the call to completeTransform(…), the returned parameters are read-only.
      Specified by:
      parameter in interface org.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

      public List<org.opengis.parameter.GeneralParameterValue> 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 interface org.opengis.parameter.ParameterValueGroup
      Returns:
      all parameter values.
    • groups

      public List<org.opengis.parameter.ParameterValueGroup> groups(String name)
      Unsupported operation, since ContextualParameters groups do not contain sub-groups.
      Specified by:
      groups in interface org.opengis.parameter.ParameterValueGroup
      Parameters:
      name - ignored.
      Returns:
      never returned.
    • addGroup

      public org.opengis.parameter.ParameterValueGroup addGroup(String name)
      Unsupported operation, since ContextualParameters groups do not contain sub-groups.
      Specified by:
      addGroup in interface org.opengis.parameter.ParameterValueGroup
      Parameters:
      name - ignored.
      Returns:
      never returned.
    • parameterNotFound

      private org.opengis.parameter.ParameterNotFoundException parameterNotFound(String name)
      Returns the exception to thrown when the parameter of the given name has not been found.
    • clone

      public ContextualParameters clone()
      Returns a modifiable clone of this parameter value group.
      Specified by:
      clone in interface org.opengis.parameter.GeneralParameterValue
      Specified by:
      clone in interface org.opengis.parameter.ParameterValueGroup
      Overrides:
      clone in class Parameters
      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.
      Overrides:
      hashCode in class Object
    • equals

      public boolean equals(Object object)
      Compares the given object with the parameters for equality.
      Overrides:
      equals in class Object
      Parameters:
      object - the object to compare with the parameters.
      Returns:
      true if the given object is equal to this one.
    • beforeFormat

      final int beforeFormat(List<Object> transforms, int index, boolean inverse)
      Given a transformation chain, replaces the elements around transforms.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 the ParameterValueGroup of a map projection, or to format a ProjectedCRS WKT.

      Parameters:
      transforms - the full chain of concatenated transforms.
      index - the index of this transform in the transforms chain.
      inverse - always false, except if we are formatting the inverse transform.
      Returns:
      index of this transform in the transforms chain after processing.
      See Also:
    • unexpectedException

      private static void unexpectedException(IllegalStateException e)
      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.