Class ContextualParameters

  • All Implemented Interfaces:
    Serializable, Cloneable, General­Parameter­Value, Parameter­Value­Group

    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:
    π/180 0 -λ0 (π/180) 0 π/180 0 0 0 1
    Map projection on a normalized ellipsoid
    a k0 0 FE 0 a k0 FN 0 0 1
    Contextual­Parameters is typically created and used as below:
    1. A Math­Transform­Provider 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 Contextual­Parameters instance.
    3. The map projection constructor may keep only the non-linear parameters for itself, and gives the linear parameters to the normalize­Geographic­Inputs(…) and Matrix­SIS​.convert­After(…) 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 complete­Transform(…) method will mark this Contextual­Parameters 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
    See Also:
    Normalized­Projection, Abstract­Math­Transform​.get­Contextual­Parameters(), Serialized Form

    Defined in the sis-referencing module

    • Constructor Detail

      • ContextualParameters

        public ContextualParameters​(OperationMethod method)
        Creates a new group of parameters for the given non-linear coordinate operation method. The method parameters shall describe the normalizenon-linear kerneldenormalize sequence as a whole. After construction, callers shall: See class javadoc for more information.
        Parameters:
        method - the non-linear operation method for which to define the parameter values.
      • ContextualParameters

        public ContextualParameters​(ParameterDescriptorGroup descriptor,
                                    int srcDim,
                                    int tgtDim)
        Creates a new group of parameters with the given descriptor. This constructor performs the same construction than Contextual­Parameters(Operation­Method) but without the need to specify an Operation­Method instance.
        Parameters:
        descriptor - the parameter descriptor.
        src­Dim - number of source dimensions.
        tgt­Dim - number of target dimensions.
        Since:
        1.0
    • Method Detail

      • 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 Matrix­SIS​.convert­Before(…) method. Alternatively, the following methods can be invoked for applying some frequently used configurations: After the complete­Transform(…) method has been invoked, the matrices returned by this method are unmodifiable.
        Application to map projections: after Normalized­Projection construction, the matrices returned by projection​.get­Contextual­Parameters()​.get­Matrix(…) are initialized to the values shown below. Note that some Normalized­Projection subclasses apply further modifications to those matrices.
        Initial matrix coefficients after Normalized­Projection construction
        getMatrix(NORMALIZATION) getMatrix(DENORMALIZATION)
        π/180 0 -λ0 (π/180) 0 π/180 0 0 0 1 a k0 0 FE 0 a k0 FN 0 0 1
        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:

        π/180 0 -λ0 (π/180) 0 π/180 0 0 0 1
        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:
        Illegal­State­Exception - if this Contextual­Parameter 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:

        180/π 0 λ0 0 180/π 0 0 0 1
        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:
        Illegal­State­Exception - if this Contextual­Parameter has been made unmodifiable.
      • completeTransform

        public MathTransform completeTransform​(MathTransformFactory factory,
                                               MathTransform kernel)
                                        throws FactoryException
        Marks this Contextual­Parameter 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 Contextual­Parameters. 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 Normalized­Projection.
        Returns:
        the concatenation of normalizethe given kerneldenormalize transforms.
        Throws:
        Factory­Exception - if an error occurred while creating a math transform instance.
        See Also:
        Normalized­Projection​.create­Map­Projection(Math­Transform­Factory)
      • parameter

        public ParameterValue<?> parameter​(String name)
                                    throws ParameterNotFoundException
        Returns the parameter value of the given name. Before the call to complete­Transform(…), this method can be used for setting parameter values like below:
        parameter("Scale factor").setValue(0.9996);   // Scale factor of Universal Transverse Mercator (UTM) projections.
        After the call to complete­Transform(…), the returned parameters are read-only.
        Specified by:
        parameter in interface Parameter­Value­Group
        Parameters:
        name - the name of the parameter to search.
        Returns:
        the parameter value for the given name.
        Throws:
        Parameter­Not­Found­Exception - if there is no parameter of the given name.
      • values

        public List<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 Parameter­Value­Group
        Returns:
        all parameter values.
      • 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:
        hash­Code 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.