Module org.apache.sis.feature
Package org.apache.sis.coverage

# Class RegionOfInterest

Object
RegionOfInterest

All Implemented Interfaces:
  `Serializable`, `LenientComparable`

public class RegionOfInterest extends Object implements LenientComparable, Serializable
Region of interest (ROI) for an operation to apply on a coverage.

## Multi-threading

Instances of `RegionOfInterest` are immutable and thread-safe.

## Limitations

Current implementation supports two-dimensional regions only. This restriction will be relaxed progressively in future versions.

Current implementation defines ROI using a geometric shape only. Future versions may allow other ways such as mask rasters.

Since:
  1.2
See Also:
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `RegionOfInterest(Shape geometry, CoordinateReferenceSystem crs)`
  Creates a new region of interest from a two-dimensional shape.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final boolean`
  `equals(Object other)`
  Compares this region of interest with the given object for equality.
  `boolean`
  `equals(Object other, ComparisonMode mode)`
  Compares this region of interest with the given object for equality.
  `int`
  `hashCode()`
  Returns a hash code value for this region of interest.
  `Shape`
  `toShape2D(GridGeometry target)`
  Returns the clip geometry in coordinates of grid cells.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### RegionOfInterest

    public RegionOfInterest(Shape geometry, CoordinateReferenceSystem crs)
    Creates a new region of interest from a two-dimensional shape. If the given CRS is `null`, then it will be assumed the same CRS than the CRS of the coverage on which operations are applied.
    Parameters:
      `geometry` - the ROI as a geometry. Coordinates are in the CRS given by `crs`.
      `crs` - coordinate reference system of the region of interest, or `null`.

- ## Method Details

  - ### toShape2D

    public Shape toShape2D(GridGeometry target) throws TransformException
    Returns the clip geometry in coordinates of grid cells. The target space is specified by a `GridGeometry`.

    #### Limitations

    In current implementation, the grid geometry most be two-dimensional. This restriction will be relaxed progressively in future versions.
    Parameters:
      `target` - two-dimensional grid geometry of the target image.
    Returns:
      clip in pixel coordinates of given grid.
    Throws:
      `TransformException` - if ROI coordinates cannot be transformed to grid coordinates.

  - ### equals

    public final boolean equals(Object other)
    Compares this region of interest with the given object for equality.
    Specified by:
      `equals` in interface `LenientComparable`
    Overrides:
      `equals` in class `Object`
    Parameters:
      `other` - the other object to compare with this ROI.
    Returns:
      whether the given object is equal to this ROI?
    See Also:
      - `ComparisonMode​.STRICT`

  - ### equals

    public boolean equals(Object other, ComparisonMode mode)
    Compares this region of interest with the given object for equality.
    Specified by:
      `equals` in interface `LenientComparable`
    Parameters:
      `other` - the other object to compare with this ROI.
      `mode` - the comparison criterion.
    Returns:
      whether the given object is equal to this ROI?
    See Also:
      - `Utilities​.deepEquals(Object, Object, ComparisonMode)`

  - ### hashCode

    public int hashCode()
    Returns a hash code value for this region of interest.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      a hash code for this ROI.