Class DefiningConversion

Object

FormattableObject

AbstractIdentifiedObject

AbstractCoordinateOperation

DefaultConversion

DefiningConversion

All Implemented Interfaces:

Serializable, Formattable, Parameterized, Deprecable, Lenient­Comparable, Printable, Identified­Object, Conversion, Coordinate­Operation, Single­Operation

public class DefiningConversion
extends DefaultConversion

Conversion used as a carrier of parameters (without CRSs) for defining a final conversion. Defining conversions are used during the construction of derived CRS, in which cases the source and target CRS are provided by the derived CRS itself. When those CRSs become available, the specialize(…) method can be invoked for creating a math transform from the parameters and assign the source and target CRS to the final conversion.

Since:

1.7

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	Defining­Conversion.Side­Processing	The preprocessing and post-processing steps to apply before and after a defining conversion.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	SIDE_PROCESSING_KEY	Key for a property specifying the preprocessing and post-processing steps to apply before and after the defining conversion.

Fields inherited from class AbstractIdentifiedObject

DEPRECATED_KEY, DOMAINS_KEY, LOCALE_KEY

Modifier and Type	Field	Description
static final String	DEPRECATED_KEY	Optional key which can be given to the constructor for specifying the object is deprecated.
static final String	DOMAINS_KEY	Key for the "domains" property to be given to the Object­Factory.create­Foo(Map, ...) methods.
static final String	LOCALE_KEY	Optional key which can be given to the constructor for specifying the locale to use for producing error messages.

Fields inherited from interface CoordinateOperation

COORDINATE_OPERATION_ACCURACY_KEY, DOMAIN_OF_VALIDITY_KEY, OPERATION_VERSION_KEY, SCOPE_KEY

Modifier and Type	Field	Description
static final String	COORDINATE_OPERATION_ACCURACY_KEY	Key for the "coordinate­Operation­Accuracy" property.
static final String	DOMAIN_OF_VALIDITY_KEY	Key for the "domain­Of­Validity" property.
static final String	OPERATION_VERSION_KEY	Key for the "operation­Version" property.
static final String	SCOPE_KEY	Key for the "scope" property.

Fields inherited from interface IdentifiedObject

ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY

Modifier and Type	Field	Description
static final String	ALIAS_KEY	Key for the "alias" property to be given to the object factory create­Foo(…) methods.
static final String	IDENTIFIERS_KEY	Key for the "identifiers" property to be given to the object factory create­Foo(…) methods.
static final String	NAME_KEY	Key for the "name" property to be given to the object factory create­Foo(…) methods.
static final String	REMARKS_KEY	Key for the "remarks" property to be given to the object factory create­Foo(…) methods.

Constructor Summary

Constructors

Constructor	Description
Defining­Conversion(Map<String,?> properties, Operation­Method method, Math­Transform transform, Parameter­Value­Group parameters)	Creates a defining conversion from the given transform and/or parameters.

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object object, Comparison­Mode mode)	Compares this coordinate operation with the specified object for equality.
Operation­Method	get­Method()	Returns a description of the operation method, including a list of expected parameter names.
Parameter­Descriptor­Group	get­Parameter­Descriptors()	Returns a description of the parameters.
Parameter­Value­Group	get­Parameter­Values()	Returns the parameter values.
Defining­Conversion.Side­Processing	get­Side­Processing()	Returns the preprocessing and post-processing steps to apply before and after the defining conversion.
Conversion	specialize(Coordinate­Reference­System source­CRS, Coordinate­Reference­System target­CRS, Math­Transform­Factory factory)	Returns a specialization of this conversion with non-null CRSs.

Methods inherited from class DefaultConversion

cast­Or­Copy, get­Standard­Type

Modifier and Type	Method	Description
static Default­Conversion	cast­Or­Copy(Conversion object)	Returns a SIS coordinate operation implementation with the values of the given arbitrary implementation.
Type	get­Standard­Type()	Returns the GeoAPI interface that defines the contract of this implementation class.

Methods inherited from class AbstractCoordinateOperation

cast­Or­Copy, format­To, get­Coordinate­Operation­Accuracy, get­Domain­Of­Validity, get­Interpolation­CRS, get­Linear­Accuracy, get­Math­Transform, get­Operation­Version, get­Scope, get­Source­CRS, get­Source­Epoch, get­Target­CRS, get­Target­Epoch, get­Wrap­Around­Changes, is­Defining­Conversion, transform

Modifier and Type	Method	Description
static Abstract­Coordinate­Operation	cast­Or­Copy(Coordinate­Operation object)	Returns a SIS coordinate operation implementation with the values of the given arbitrary implementation.
protected String	format­To(Formatter formatter)	Formats this coordinate operation in Well Known Text (WKT) version 2 format.
Collection<Positional­Accuracy>	get­Coordinate­Operation­Accuracy()	Returns an estimation of the impact of this operation on point accuracy.
Extent	get­Domain­Of­Validity()	Deprecated. Replaced by Abstract­Identified­Object.get­Domains() as of ISO 19111:2019.
Optional<Coordinate­Reference­System>	get­Interpolation­CRS()	Returns the CRS to be used for interpolations in a grid.
double	get­Linear­Accuracy()	Returns an estimation of positional accuracy in metres, or Na­N if unknown.
Math­Transform	get­Math­Transform()	Returns the object for transforming coordinates in the source CRS to coordinates in the target CRS.
String	get­Operation­Version()	Returns the version of the coordinate operation.
International­String	get­Scope()	Deprecated. Replaced by Abstract­Identified­Object.get­Domains() as of ISO 19111:2019.
Coordinate­Reference­System	get­Source­CRS()	Returns the source CRS, or null if unspecified.
Optional<Temporal>	get­Source­Epoch()	Returns the date at which source coordinate tuples are valid.
Coordinate­Reference­System	get­Target­CRS()	Returns the target CRS, or null if unspecified.
Optional<Temporal>	get­Target­Epoch()	Returns the date at which target coordinate tuples are valid.
Set<Integer>	get­Wrap­Around­Changes()	Returns the indices of target dimensions where "wrap around" may happen as a result of this coordinate operation.
boolean	is­Defining­Conversion()	Deprecated, for removal: This API element is subject to removal in a future version. Replaced by the Defining­Conversion class.
Abstract­Coordinate­Set	transform(Abstract­Coordinate­Set data)	Changes coordinates from being referenced to the source CRS and/or epoch to being referenced to the target CRS and/or epoch.

Methods inherited from class AbstractIdentifiedObject

cast­Or­Copy, equals, format­To, get­Alias, get­Description, get­Domains, get­Identifiers, get­Interface, get­Name, get­Remarks, hash­Code, is­Deprecated, is­Heuristic­Match­For­Name

Modifier and Type	Method	Description
static Abstract­Identified­Object	cast­Or­Copy(Identified­Object object)	Returns a SIS identified object implementation with the values of the given arbitrary implementation.
final boolean	equals(Object object)	Compares the specified object with this object for equality.
void	format­To(Formatter formatter, int flags, int width, int precision)	Formats the name or identifier of this object using the provider formatter.
Collection<Generic­Name>	get­Alias()	Returns alternative names by which this object is identified.
Optional<International­String>	get­Description()	Returns a narrative explanation of the role of this object.
Collection<Default­Object­Domain>	get­Domains()	Returns the usage of this CRS-related object.
Set<Reference­Identifier>	get­Identifiers()	Returns identifiers which references elsewhere the object's defining information.
final Class<? extends Identified­Object>	get­Interface()	Deprecated, for removal: This API element is subject to removal in a future version. Renamed Abstract­Identified­Object.get­Standard­Type() for integration with Lenient­Comparable.
Reference­Identifier	get­Name()	Returns the primary name by which this object is identified.
International­String	get­Remarks()	Returns comments on or information about this object, including data source information.
final int	hash­Code()	Returns a hash value for this identified object.
boolean	is­Deprecated()	Returns true if this object is deprecated.
boolean	is­Heuristic­Match­For­Name(String name)	Returns true if either the primary name or at least one alias matches the given string according heuristic rules.

Methods inherited from class FormattableObject

print, to­String, to­String, to­WKT

Modifier and Type	Method	Description
void	print()	Prints a string representation of this object to the standard output stream.
String	to­String()	Returns a Well Known Text (WKT) or an alternative text representation for this object.
String	to­String(Convention convention)	Returns a Well Known Text (WKT) for this object using the specified convention.
String	to­WKT()	Returns a strictly compliant Well Known Text (WKT) using the default convention, symbols and indentation.

Methods inherited from class Object

clone, finalize, get­Class, notify, notify­All, wait, wait, wait

Methods inherited from interface Conversion

get­Operation­Version, get­Source­CRS, get­Target­CRS

Modifier and Type	Method	Description
String	get­Operation­Version()	This attribute is declared in Coordinate­Operation but is not used in a conversion.
Coordinate­Reference­System	get­Source­CRS()	Returns the source CRS.
Coordinate­Reference­System	get­Target­CRS()	Returns the target CRS.

Methods inherited from interface IdentifiedObject

to­WKT

Modifier and Type	Method	Description
String	to­WKT()	Returns a Well Known Text (WKT) for this object.

Field Details

SIDE_PROCESSING_KEY

public static final String SIDE_PROCESSING_KEY

Key for a property specifying the preprocessing and post-processing steps to apply before and after the defining conversion. The associated value shall be an instance of Defining­Conversion.Side­Processing. Possible values are:

• Defining­Conversion.Side­Processing.NORMALIZED means that the conversion is defined between a pair of CRSs normalized in the sense of Axes­Convention.NORMALIZED: the source and target coordinate systems are right-handed and use predetermined units of measurement such as degrees and metres. The Defining­Conversion needs to be completed with unit conversions and axis order changes. These changes can be applied by Default­Conversion.specialize(…).
• Defining­Conversion.Side­Processing.NONE means that no preprocessing or post-processing steps shall be added.

The default value is Defining­Conversion.Side­Processing.NORMALIZED.

See Also:

• get­Side­Processing()
• Axes­Convention.NORMALIZED
• Constant Field Values

Constructor Details

DefiningConversion

public DefiningConversion(Map<String,?> properties,
 OperationMethod method,
 MathTransform transform,
 ParameterValueGroup parameters)

Creates a defining conversion from the given transform and/or parameters. This conversion has no source and target CRS since those elements are usually unknown at defining conversion construction time. The source and target CRS will become known later, at the derived CRS construction time.

The properties map given in argument follows the same rules as for the parent constructor, with the addition of the following properties:

Additional properties

Property name	Value type	Returned by
"sideProcessing"	DefiningConversion.SideProcessing	getSideProcessing()

Transform and parameters arguments

At least one of the transform or parameters argument must be non-null. If the caller supplies a transform argument, then by default it shall be a transform expecting normalized input coordinates and producing normalized output coordinates (see Axes­Convention for more information about what Apache SIS means by "normalized"). This default behavior can be disabled by setting the "sideProcessing" key to NONE.

If the caller cannot yet supply a Math­Transform, then it shall supply the parameter values needed for creating that transform, with the possible omission of "semi_major" and "semi_minor" values. The semi-major and semi-minor parameter values will be set automatically when the specialize(…) method will be invoked.

If both the transform and parameters arguments are non-null, then the latter should describe the parameters used for creating the transform. Those parameters will be stored for information purpose and can be given back by the Single­Operation.get­Parameter­Values() method.

Parameters:

properties - the properties to be given to the identified object.

method - the operation method.

transform - transform from positions in the source CRS to positions in the target CRS, or null.

parameters - the transform parameter values, or null.

Method Details

getSideProcessing

public DefiningConversion.SideProcessing getSideProcessing()

Returns the preprocessing and post-processing steps to apply before and after the defining conversion. If NORMALIZED, the source and target coordinate systems are right-handed and use predetermined units of measurement such as degrees and metres. Such conversion needs to be completed by a call to specialize(…).

If this method returns NONE, then this Defining­Conversion defines fully the conversion and no conversion step should be added.

Returns:

the preprocessing and post-processing steps to apply before and after the defining conversion.

See Also:

• SIDE_PROCESSING_KEY
• Axes­Convention.NORMALIZED

specialize

public Conversion specialize(CoordinateReferenceSystem sourceCRS,
 CoordinateReferenceSystem targetCRS,
 MathTransformFactory factory)
                      throws FactoryException

Returns a specialization of this conversion with non-null CRSs. This method should be invoked when more information become available about the conversion to create.

Overrides:

specialize in class Default­Conversion

Parameters:

source­CRS - the source CRS.

target­CRS - the target CRS.

factory - the factory to use for creating a transform from the parameters or for performing axis changes, or null for the default factory.

Returns:

conversion which declares the given CRSs as the source and target.

Throws:

Factory­Exception - if the creation of a Math­Transform from the parameter values failed.

getMethod

public OperationMethod getMethod()

Returns a description of the operation method, including a list of expected parameter names. The returned object does not contains any parameter value.

Specified by:

get­Method in interface Single­Operation

Returns:

a description of the operation method.

getParameterDescriptors

public ParameterDescriptorGroup getParameterDescriptors()

Returns a description of the parameters. The default implementation performs the following choice:

• If parameter values were specified explicitly at construction time, then the descriptor of those parameters is returned.
• Otherwise if this method can infer the parameter descriptor from the math transform, then that descriptor is returned.
• Otherwise fallback on the method parameters.

Note: the two parameter descriptions (from the Math­Transform or from the Operation­Method) should be very similar. If they differ, it should be only in minor details like remarks, default values or units of measurement.

Specified by:

get­Parameter­Descriptors in interface Parameterized

Returns:

a description of the parameters.

See Also:

• Default­Operation­Method.get­Parameters()
• Abstract­Math­Transform.get­Parameter­Descriptors()

getParameterValues

public ParameterValueGroup getParameterValues()

Returns the parameter values. The default implementation performs the following choice:

• If parameter values were specified explicitly at construction time, then they are returned as an unmodifiable parameter group.
• Otherwise if this method can infer the parameter values from the math transform, then those parameters are returned.
• Otherwise throw Unsupported­Implementation­Exception.

Specified by:

get­Parameter­Values in interface Parameterized

Specified by:

get­Parameter­Values in interface Single­Operation

Returns:

the parameter values.

Throws:

Unsupported­Operation­Exception - if the parameter values cannot be determined for the current math transform implementation.

See Also:

• Abstract­Math­Transform.get­Parameter­Values()

equals

public boolean equals(Object object,
 ComparisonMode mode)

Compares this coordinate operation with the specified object for equality. If the mode argument is Comparison­Mode.STRICT or BY_CONTRACT, then all available properties are compared including the domains and the accuracy.

Specified by:

equals in interface Lenient­Comparable

Overrides:

equals in class Abstract­Coordinate­Operation

Parameters:

object - the object to compare to this.

mode - the strictness level of the comparison.

Returns:

true if both objects are equal for the given comparison mode.

See Also:

• Abstract­Identified­Object.compute­Hash­Code()
• Utilities.deep­Equals(Object, Object, Comparison­Mode)