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

  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 Details

  - ### 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 Details

  - ### 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.