public class ContextualParameters extends Parameters implements Serializable
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.
→ | Map projection on a normalized ellipsoid | → |
ContextualParameters
is typically created and used as below:
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.Parameters
, initializes the projection, then saves the parameter values that
it actually used in a new ContextualParameters
instance.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.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.
NormalizedProjection
,
AbstractMathTransform.getContextualParameters()
,
Serialized FormDefined in the sis-referencing
module
Modifier and Type | Class and Description |
---|---|
static class |
ContextualParameters.MatrixRole
Whether a matrix is used for normalization or denormalization
before or after a non-linear operation.
|
Constructor and Description |
---|
ContextualParameters(OperationMethod method)
Creates a new group of parameters for the given non-linear coordinate operation method.
|
Modifier and Type | Method and Description |
---|---|
ParameterValueGroup |
addGroup(String name)
Unsupported operation, since
ContextualParameters groups do not contain sub-groups. |
ContextualParameters |
clone()
Returns a modifiable clone of this parameter value group.
|
MathTransform |
completeTransform(MathTransformFactory factory,
MathTransform kernel)
Marks this
ContextualParameter as unmodifiable and creates the
normalize → kernel → denormalize transforms chain. |
MatrixSIS |
denormalizeGeographicOutputs(double λ0)
Appends a denormalization step after the non-linear kernel, which will convert input ordinates
in the two first dimensions from radians to degrees.
|
boolean |
equals(Object object)
Compares the given object with the parameters for equality.
|
ParameterDescriptorGroup |
getDescriptor()
Returns the parameters for the normalize → non-linear kernel →
denormalize sequence as a whole.
|
MatrixSIS |
getMatrix(ContextualParameters.MatrixRole role)
Returns the affine transforms to be applied before or after the non-linear kernel operation.
|
List<ParameterValueGroup> |
groups(String name)
Unsupported operation, since
ContextualParameters groups do not contain sub-groups. |
int |
hashCode()
Returns a hash code value for this object.
|
MatrixSIS |
normalizeGeographicInputs(double λ0)
Prepends a normalization step converting input ordinates in the two first dimensions from degrees to radians.
|
ParameterValue<?> |
parameter(String name)
Returns the parameter value of the given name.
|
List<GeneralParameterValue> |
values()
Returns an unmodifiable list containing all parameters in this group.
|
booleanValue, cast, cast, castOrWrap, copy, doubleValue, doubleValueList, getDescriptors, getMandatoryValue, getMemberName, getOrCreate, getValue, getValueDomain, intValue, intValueList, print, stringValue, toString, unmodifiable
public ContextualParameters(OperationMethod method)
parameter(…).setValue(…)
.completeTransform(…)
method
- the non-linear operation method for which to define the parameter values.public final ParameterDescriptorGroup getDescriptor()
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.
NormalizedProjection
.
Other "kernels" in SIS are EllipsoidToCentricTransform
and MolodenskyTransform
.getDescriptor
in interface GeneralParameterValue
getDescriptor
in interface ParameterValueGroup
public final MatrixSIS getMatrix(ContextualParameters.MatrixRole role)
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.
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.
getMatrix(NORMALIZATION) |
getMatrix(DENORMALIZATION) |
---|---|
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.public MatrixSIS normalizeGeographicInputs(double λ0)
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:
λ0
- longitude of the central meridian, in degrees.IllegalStateException
- if this ContextualParameter
has been made unmodifiable.public MatrixSIS denormalizeGeographicOutputs(double λ0)
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:
λ0
- longitude of the central meridian, in degrees.IllegalStateException
- if this ContextualParameter
has been made unmodifiable.public MathTransform completeTransform(MathTransformFactory factory, MathTransform kernel) throws FactoryException
ContextualParameter
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".
factory
- the factory to use for creating math transform instances.kernel
- the (usually non-linear) kernel.
This is often a NormalizedProjection
.FactoryException
- if an error occurred while creating a math transform instance.NormalizedProjection.createMapProjection(MathTransformFactory)
public ParameterValue<?> parameter(String name) throws ParameterNotFoundException
completeTransform(…)
,
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
completeTransform(…)
, the returned parameters are read-only.parameter
in interface ParameterValueGroup
name
- the name of the parameter to search.ParameterNotFoundException
- if there is no parameter of the given name.public List<GeneralParameterValue> values()
values
in interface ParameterValueGroup
public List<ParameterValueGroup> groups(String name)
ContextualParameters
groups do not contain sub-groups.groups
in interface ParameterValueGroup
name
- ignored.public ParameterValueGroup addGroup(String name)
ContextualParameters
groups do not contain sub-groups.addGroup
in interface ParameterValueGroup
name
- ignored.public ContextualParameters clone()
clone
in interface GeneralParameterValue
clone
in interface ParameterValueGroup
clone
in class Parameters
Parameters.copy(ParameterValueGroup, ParameterValueGroup)
public int hashCode()
Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.