Module org.apache.sis.referencing
Package org.apache.sis.referencing.operation.transform

# Class DomainDefinition

Object
DomainDefinition

public class DomainDefinition extends Object
Specification about how to estimate a domain of validity for transforms. Contrarily to CRS domain of validity, this class estimates a domain based on mathematical behavior only, not on "real world" considerations. For example, the Mercator projection tends to infinity when approaching poles, so it is recommended to not use it above some latitude threshold, typically 80° or 84°. The exact limit is arbitrary. This is different than the domain of validity of CRS, which is often limited to a particular country. In general, the CRS domain of validity is much smaller than the domain computed by this class.

Current implementation does not yet provide ways to describe how a domain is decided. A future version may, for example, allows to specify a maximal deformation tolerated for map projections. In current implementation, the estimation can be customized by overriding the `estimate(MathTransform)` or `intersect(Envelope)` methods.

Each `DomainDefinition` instance should be used only once for an `AbstractMathTransform` instance, unless that transform is a chain of concatenated transforms (this case is handled automatically by Apache SIS). Usage example:

    AbstractMathTransform transform = …;
    transform.getDomain(new DomainDefinition()).ifPresent((domain) -> {
        // Do something here with the transform domain.
    });

The `MathTransforms​.getDomain(MathTransform)` convenience method can be used when the default implementation is sufficient.

Since:
  1.3
See Also:
  - `MathTransforms​.getDomain(MathTransform)`
  - `AbstractMathTransform​.getDomain(DomainDefinition)`
  - `CoordinateOperation​.getDomainOfValidity()`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DomainDefinition()`
  Creates a new instance using default configuration.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `estimate(MathTransform evaluated)`
  Estimates the domain of the given math transform and intersects it with previously computed domains.
  `void`
  `intersect(Envelope domain)`
  Sets the domain to the intersection of current domain with the specified envelope.
  `Optional<Envelope>`
  `result()`
  Returns the domain computed so far by this instance.
  `String`
  `toString()`
  Returns a string representation for debugging purposes.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### DomainDefinition

    public DomainDefinition()
    Creates a new instance using default configuration.

- ## Method Details

  - ### estimate

    public void estimate(MathTransform evaluated) throws TransformException
    Estimates the domain of the given math transform and intersects it with previously computed domains. The result can be obtained by a call to `result()`.

    The default implementation invokes `AbstractMathTransform​.getDomain(DomainDefinition)` if possible, or does nothing otherwise. The domain provided by the transform is given to `intersect(Envelope)`. Subclasses can override for modifying this behavior.

    Parameters:
      `evaluated` - the transform for which to estimate the domain.
    Throws:
      `TransformException` - if the domain cannot be estimated.

  - ### intersect

    public void intersect(Envelope domain)
    Sets the domain to the intersection of current domain with the specified envelope. The envelope coordinates shall be in units of the inputs of the first `MathTransform` given to `estimate(MathTransform)`. If that method is invoked recursively in a chain of transforms, callers are responsible for converting the envelope.
    Parameters:
      `domain` - the domain to intersect with.

  - ### result

    public Optional<Envelope> result()
    Returns the domain computed so far by this instance. The envelope is in units of the inputs of the transform given in the first call to `estimate(MathTransform)`.
    Returns:
      the domain of the transform being evaluated.

  - ### toString

    public String toString()
    Returns a string representation for debugging purposes.
    Overrides:
      `toString` in class `Object`
    Returns:
      string representation of current domain.