# Class CoordinateOperationContext

Object
CoordinateOperationContext

All Implemented Interfaces:
  `Localized`

public class CoordinateOperationContext extends Object implements Localized
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.

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

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

Since:
  0.7
"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
  `void`
  `addAreaOfInterest(Envelope area)`
  Adds the geographic, vertical and temporal elements of an envelope as areas of interest.
  `void`
  `addAreaOfInterest(GeographicBoundingBox area)`
  Adds a geographic element of the area of interest.
  `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.
  `DirectPosition`
  `getConstantCoordinates()`
  Returns coordinate values that may be considered as constant, or `null` if none.
  `double`
  `getDesiredAccuracy()`
  Returns the desired accuracy in metres.
  `Locale`
  `getLocale()`
  Returns the locale for error messages.
  `Filter`
  `getLogFilter()`
  Returns a filter which will receive warnings, or `null` if none.
  `void`
  `setAreaOfInterest(Extent area)`
  Sets the spatiotemporal area of interest, or `null` if none.
  `void`
  `setAreaOfInterest(GeographicBoundingBox area)`
  Sets the geographic element of the area of interest, or `null` if none.
  `void`
  `setConstantCoordinates(DirectPosition coordinates)`
  Sets coordinate values that may be considered as constant.
  `void`
  `setDesiredAccuracy(double accuracy)`
  Sets the desired accuracy in metres.
  `void`
  `setLocale(Locale locale)`
  Sets the locale for error messages.
  `void`
  `setLogFilter(Filter logFilter)`
  Specifies a filter which will receive warnings, or `null` if none.

  ### 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 element of the area of interest, or `null` if none. This convenience method sets the given bounding box into the spatiotemporal `Extent`.

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

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

  - ### addAreaOfInterest

    public void addAreaOfInterest(GeographicBoundingBox area)
    Adds a geographic element of the area of interest. The given area is added to the list returned by `Extent​.getGeographicElements()`. If the list contains two or more elements, `DefaultCoordinateOperationFactory` will use the union of all elements.
    Parameters:
      `area` - the geographic area of interest to add, or `null` if none.
    Since:
      1.6

  - ### addAreaOfInterest

    public void addAreaOfInterest(Envelope area)
    Adds the geographic, vertical and temporal elements of an envelope as areas of interest. The geographic element is added to the list returned by `Extent​.getGeographicElements()`, and likewise for vertical and temporal components. If the envelope cannot be transformed to the CRS expected by a component list, then the exception is reported to the log filter and eventually logged.
    Parameters:
      `area` - the envelope to add as an area of interest, or `null` if none.
    Since:
      1.6

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

  - ### getConstantCoordinates

    public DirectPosition getConstantCoordinates()
    Returns coordinate values that may be considered as constant, or `null` if none. This method is invoked when at least one coordinate in the target CRS cannot be computed from the coordinates in the source CRS. For example, if the source CRS has (x, y) axes and the target CRS has (x, y, t) axes, then this method is invoked for determining which value to assign to the t coordinate. All other coordinates will be ignored and can be NaN.

    #### Coordinate reference system

    If `DirectPosition​.getCoordinateReferenceSystem()` returns null, the default coordinate reference system is the target CRS of the requested coordinate operation. Otherwise, the CRS of the returned position should be one of the components of the target CRS. If the CRS is not recognized, the returned position may be ignored.
    Returns:
      coordinates to take as constants, or `null` if none.
    Since:
      1.6

  - ### setConstantCoordinates

    public void setConstantCoordinates(DirectPosition coordinates)
    Sets coordinate values that may be considered as constant. This position will be used if at least one coordinate in the target CRS cannot be computed from the coordinates in the source CRS.

    #### Allowed coordinate reference systems

    The Coordinate Reference System (CRS) of the given position is optional. If absent, it is assumed to be the target CRS of the coordinate operation. If present, it should be either the target CRS of the requested operation, or one of the components of the target CRS (if the latter is compound). If this condition does not hold, the position may be ignored (it will not be transformed).
    Parameters:
      `coordinates` - coordinate values that may be considered as constant, or `null` if none.
    Since:
      1.6

  - ### getLocale

    public Locale getLocale()
    Returns the locale for error messages. By default, this is the JVM default locale. Note that this locale has no incidence on the selection of coordinate operations. In particular, this locale does not determine a geographic area.
    Specified by:
      `getLocale` in interface `Localized`
    Returns:
      the locale for error messages.
    Since:
      1.6

  - ### setLocale

    public void setLocale(Locale locale)
    Sets the locale for error messages. Locale specified by this method are used on a best-effort basis only. Note that this locale has no incidence on the selection of coordinate operations. In particular, this locale does not determine a geographic area.
    Parameters:
      `locale` - the locale for error messages, or `null` for the JVM default locale.
    Since:
      1.6

  - ### getLogFilter

    public Filter getLogFilter()
    Returns a filter which will receive warnings, or `null` if none. If that filter returns `false` for a given log record, then that record will not be logged by `CoordinateOperationFinder`.
    Returns:
      a filter which will receive warnings, or `null` if none.
    Since:
      1.6

  - ### setLogFilter

    public void setLogFilter(Filter logFilter)
    Specifies a filter which will receive warnings, or `null` if none. If that filter returns `false` for a given log record, then that record will not be logged by `CoordinateOperationFinder`.

    #### Usage example

    This filter can be used as a way to redirect the logs to something else, such as data store listeners. In such case, the return value of the filter controls whether the record should be also logged with the usual loggers.
    Parameters:
      `logFilter` - a filter which will receive warnings, or `null` if none.
    Since:
      1.6