Package org.apache.sis.referencing.operation

## Class CoordinateOperationContext

- Object
- - CoordinateOperationContext

- All Implemented Interfaces:
    `Serializable`

      public class CoordinateOperationContext
      extends Object
      implements Serializable

  Optional information about the context in which a requested coordinate operation will be used. The context can provide information such as:
  - The geographic area where the transformation will be used.
  - The desired accuracy. A coarser accuracy may allow SIS to choose a faster transformation method.
  While optional, those information can help `DefaultCoordinateOperationFactory` to choose the most suitable coordinate transformation between two CRS.
  Example: if a transformation from NAD27 to WGS84 is requested without providing context, then Apache SIS will return the transformation applicable to the widest North American surface. But if the user provides a context saying that he wants to transform coordinates in Texas, then Apache SIS may return another coordinate transformation with different Bursa-Wolf parameters more suitable to Texas, but not suitable to the rest of North-America.
  `CoordinateOperationContext` is part of the API used by SIS for implementing the late binding model. See package javadoc for a note on early binding versus late binding implementations.
  Since:
    0.7
  See Also:
    Serialized Form

  Defined in the `sis-referencing` module

  TODO:
    Should also take the country of a `Locale`. The EPSG database contains ISO2 and ISO3 identifiers that we can use.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `CoordinateOperationContext()` | Creates a new context with no area of interest and the best accuracy available.
    `CoordinateOperationContext​(Extent area, double accuracy)` | Creates a new context with the given area of interest and desired accuracy.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static CoordinateOperationContext` | `fromBoundingBox​(GeographicBoundingBox areaOfInterest)` | Creates an operation context for the given area of interest, which may be null or `undefined`.
    `Extent` | `getAreaOfInterest()` | Returns the spatiotemporal area of interest, or `null` if none.
    `double` | `getDesiredAccuracy()` | Returns the desired accuracy in metres.
    `void` | `setAreaOfInterest​(Extent area)` | Sets the spatiotemporal area of interest, or `null` if none.
    `void` | `setAreaOfInterest​(GeographicBoundingBox area)` | Sets the geographic component of the area of interest, or `null` if none.
    `void` | `setDesiredAccuracy​(double accuracy)` | Sets the desired accuracy in metres.

    - ### Methods inherited from class Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### CoordinateOperationContext

          public CoordinateOperationContext()

      Creates a new context with no area of interest and the best accuracy available.

    - #### CoordinateOperationContext

          public CoordinateOperationContext​(Extent area,
                                            double accuracy)

      Creates a new context with the given area of interest and desired accuracy.
      Parameters:
        `area` - the area of interest, or `null` if none.
        `accuracy` - the desired accuracy in metres, or 0 for the best accuracy available. See `getDesiredAccuracy()` for more details about what we mean by "best accuracy".

  - ### Method Detail

    - #### fromBoundingBox

          public static CoordinateOperationContext fromBoundingBox​(GeographicBoundingBox areaOfInterest)

      Creates an operation context for the given area of interest, which may be null or `undefined`. This is a convenience method for a frequently-used operation.
      Parameters:
        `areaOfInterest` - the area of interest, or `null` if none.
      Returns:
        the operation context, or `null` if the given bounding box was null, undefined or covers the whole world (in which case Apache SIS does not need that we specify a context).
      Since:
        1.0

    - #### getAreaOfInterest

          public Extent getAreaOfInterest()

      Returns the spatiotemporal area of interest, or `null` if none.
      Returns:
        the spatiotemporal area of interest, or `null` if none.
      See Also:
        `Extents​.getGeographicBoundingBox(Extent)`

    - #### setAreaOfInterest

          public void setAreaOfInterest​(Extent area)

      Sets the spatiotemporal area of interest, or `null` if none.
      Parameters:
        `area` - the spatiotemporal area of interest, or `null` if none.

    - #### setAreaOfInterest

          public void setAreaOfInterest​(GeographicBoundingBox area)

      Sets the geographic component of the area of interest, or `null` if none. This convenience method set the bounding box into the spatiotemporal `Extent`.

      The reverse operation can be done with `Extents​.getGeographicBoundingBox(getAreaOfInterest())`.

      Parameters:
        `area` - the geographic area of interest, or `null` if none.

    - #### getDesiredAccuracy

          public double getDesiredAccuracy()

      Returns the desired accuracy in metres. A value of 0 means to search for the most accurate operation.

      When searching for the most accurate operation, SIS considers only the operations specified by the authority. For example the Molodensky method is a better datum shift approximation than Abridged Molodensky. But if all coordinate operations defined by the authority use the Abridged Molodensky method, then SIS will ignore the Molodensky one.

      Returns:
        the desired accuracy in metres.

    - #### setDesiredAccuracy

          public void setDesiredAccuracy​(double accuracy)

      Sets the desired accuracy in metres. A value of 0 means to search for the most accurate operation. See `getDesiredAccuracy()` for more details about what we mean by "most accurate".
      Parameters:
        `accuracy` - the desired accuracy in metres.