Class DefaultOperationMethod

  • All Implemented Interfaces:
    Serializable, Deprecable, Lenient­Comparable, Identified­Object, Operation­Method

    public class DefaultOperationMethod
    extends AbstractIdentifiedObject
    implements OperationMethod
    Describes the algorithm and parameters used to perform a coordinate operation. An Operation­Method is a kind of metadata: it does not perform any coordinate operation (e.g. map projection) by itself, but tells us what is needed in order to perform such operation.

    The most important parts of an Operation­Method are its name and its group of parameter descriptors. The parameter descriptors do not contain any value, but tell us what are the expected parameters, together with their units of measurement.

    Example: An operation method named “Mercator (variant A)” (EPSG:9804) expects the following parameters:
    • Latitude of natural origin” in degrees. Default value is 0°.
    • Longitude of natural origin” in degrees. Default value is 0°.
    • Scale factor at natural origin” as a dimensionless number. Default value is 1.
    • False easting” in metres. Default value is 0 m.
    • False northing” in metres. Default value is 0 m.
    In Apache SIS implementation, the name is the only mandatory property. However it is recommended to provide also identifiers (e.g. “EPSG:9804” in the above example) since names can sometime be ambiguous or be spelled in different ways.
    Departure from the ISO 19111 standard
    The following properties are mandatory according ISO 19111, but may be missing under some conditions in Apache SIS:
    Relationship with other classes or interfaces
    Operation­Method describes parameters without providing any value (except sometime default values). When values have been assigned to parameters, the result is a Single­Operation. Note that there is different kinds of Single­Operation depending on the nature and accuracy of the coordinate operation. See get­Operation­Type() for more information.

    The interface performing the actual work of taking coordinates in the source CRS and calculating the new coordinates in the target CRS is Math­Transform. In order to allow Apache SIS to instantiate those Math­Transforms from given parameter values, Default­Operation­Method subclasses should implement the Math­Transform­Provider interface.

    Immutability and thread safety
    This class is immutable and thread-safe if all properties given to the constructor are also immutable and thread-safe. It is strongly recommended for all subclasses to be thread-safe, especially the Math­Transform­Provider implementations to be used with Default­Math­Transform­Factory.
    Since:
    0.5
    See Also:
    Default­Conversion, Default­Transformation, Math­Transform­Provider, Serialized Form

    Defined in the sis-referencing module

    • Constructor Detail

      • DefaultOperationMethod

        public DefaultOperationMethod​(MathTransform transform)
        Convenience constructor that creates an operation method from a math transform. The information provided in the newly created object are approximations, and usually acceptable only as a fallback when no other information are available.
        Parameters:
        transform - the math transform to describe.
      • DefaultOperationMethod

        protected DefaultOperationMethod​(OperationMethod method)
        Creates a new operation method with the same values than the specified one. This copy constructor provides a way to convert an arbitrary implementation into a SIS one or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.

        This constructor performs a shallow copy, i.e. the properties are not cloned.

        Parameters:
        method - the operation method to copy.
        See Also:
        cast­Or­Copy(Operation­Method)
    • Method Detail

      • castOrCopy

        public static DefaultOperationMethod castOrCopy​(OperationMethod object)
        Returns a SIS operation method implementation with the same values than the given arbitrary implementation. If the given object is null, then null is returned. Otherwise if the given object is already a SIS implementation, then the given object is returned unchanged. Otherwise a new SIS implementation is created and initialized to the attribute values of the given object.
        Parameters:
        object - the object to get as a SIS implementation, or null if none.
        Returns:
        a SIS implementation containing the values of the given object (may be the given object itself), or null if the argument was null.
      • redimension

        public static OperationMethod redimension​(OperationMethod method,
                                                  int sourceDimensions,
                                                  int targetDimensions)
        Returns an operation method with different dimensions, if we are allowed to change dimensionality. The need to change an Operation­Method dimensionality may occur in two contexts:
        • When the original method can work with any number of dimensions. Those methods do not know in advance the number of dimensions, which is fixed only after the actual Math­Transform instance has been created. Example: Affine conversion.
        • When a three-dimensional method can also be used in the two-dimensional case, typically by assuming that the ellipsoidal height is zero everywhere. Example: Molodensky transform.
        This redimension(…) implementation performs the following choice:
        • If the given method is an instance of Default­Operation­Method, then delegate to redimension(int, int) in order to allow subclasses to defines their own policy. For example the Molodensky method needs to override.
        • Otherwise for each dimension (source and target):
          • If the corresponding dimension of the given method is null, then set that dimension to the given value in a new Operation­Method.
          • Otherwise if the given value is not equal to the corresponding dimension in the given method, throw an Illegal­Argument­Exception.
        Parameters:
        method - the operation method to redimension, or null.
        source­Dimensions - the desired number of input dimensions.
        target­Dimensions - the desired number of output dimensions.
        Returns:
        the redimensioned operation method, or null if the given method was null, or method if no change is needed.
        Throws:
        Illegal­Argument­Exception - if the given dimensions are illegal for the given operation method.
      • redimension

        public OperationMethod redimension​(int sourceDimensions,
                                           int targetDimensions)
        Returns this operation method with different dimensions, if we are allowed to change dimensionality. See redimension(Operation­Method, int, int) for more information.

        The default implementation performs the following choice: for each dimension (source and target):

        • If the corresponding dimension of the given method is null, then set that dimension to the given value in a new Operation­Method.
        • Otherwise if the given value is not equal to the corresponding dimension in the given method, throw an Illegal­Argument­Exception.
        Subclasses should override this method if they can work with different number of dimensions. For example a Molodensky transform usually works in a three-dimensional space, but can also work in a two-dimensional space by assuming that the ellipsoidal height is zero everywhere.
        Parameters:
        source­Dimensions - the desired number of input dimensions.
        target­Dimensions - the desired number of output dimensions.
        Returns:
        the redimensioned operation method, or this if no change is needed.
        Throws:
        Illegal­Argument­Exception - if the given dimensions are illegal for this operation method.
        Since:
        0.6
      • getInterface

        public Class<? extends OperationMethod> getInterface()
        Returns the GeoAPI interface implemented by this class. The SIS implementation returns Operation­Method​.class.
        Note for implementers: Subclasses usually do not need to override this information since GeoAPI does not define Operation­Method sub-interface. Overriding possibility is left mostly for implementers who wish to extend GeoAPI with their own set of interfaces.
        Overrides:
        get­Interface in class Abstract­Identified­Object
        Returns:
        Operation­Method​.class or a user-defined sub-interface.
      • getOperationType

        public Class<? extends SingleOperation> getOperationType()
        Returns the base interface of the Coordinate­Operation instances that use this method. The base Coordinate­Operation interface is usually one of the following subtypes:
        • Transformation if the coordinate operation has some errors (typically of a few metres) because of the empirical process by which the operation parameters were determined. Those errors do not depend on the floating point precision or the accuracy of the implementation algorithm.
        • Conversion if the coordinate operation is theoretically of infinite precision, ignoring the limitations of floating point arithmetic (including rounding errors) and the approximations implied by finite series expansions.
        • Projection if the coordinate operation is a conversion (as defined above) converting geodetic latitudes and longitudes to plane (map) coordinates. This type can optionally be refined with one of the Cylindrical­Projection, Conic­Projection or Planar­Projection subtypes.
        In case of doubt, get­Operation­Type() can conservatively return the base type. The default implementation returns Single­Operation​.class, which is the most conservative return value.
        Returns:
        interface implemented by all coordinate operations that use this method.
        See Also:
        Default­Math­Transform­Factory​.get­Available­Methods(Class)
      • getFormula

        public Formula getFormula()
        Formula(s) or procedure used by this operation method. This may be a reference to a publication. Note that the operation method may not be analytic, in which case this attribute references or contains the procedure, not an analytic formula.
        Departure from the ISO 19111 standard: this property is mandatory according ISO 19111, but optional in Apache SIS.
        Specified by:
        get­Formula in interface Operation­Method
        Returns:
        the formula used by this method, or null if unknown.
        See Also:
        Default­Formula, Math­Transform­Provider