Class DomainDefinition

java.lang.Object
org.apache.sis.referencing.operation.transform.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:

The MathTransforms.getDomain(MathTransform) convenience method can be used when the default implementation is sufficient.
Since:
1.3
Version:
1.3
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static final class 
    The transform to apply on the envelope computed by a transform step in order to get an envelope in the units of the requested domain.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    The envelope to use for computing intersection, created only if needed.
    private org.opengis.geometry.Envelope
    Limits computed so far, or null if none.
    If the transform to evaluate is a step in the middle of a chain of transforms, the transform to apply on the envelope computed by the step in order to get an envelope in domain units.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Creates a new instance using default configuration.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    estimate(org.opengis.referencing.operation.MathTransform evaluated)
    Estimates the domain of the given math transform and intersects it with previously computed domains.
    (package private) final void
    estimateOnInverse(org.opengis.referencing.operation.MathTransform inverse)
    Estimates the domain using the inverse of a transform.
    (package private) final void
    estimateOnInverse(org.opengis.referencing.operation.MathTransform inverse, org.opengis.referencing.operation.MathTransform tail)
    Estimates the domain using the inverse of a transform and transform that domain using the given suffix.
    void
    intersect(org.opengis.geometry.Envelope domain)
    Sets the domain to the intersection of current domain with the specified envelope.
    (package private) final org.opengis.geometry.Envelope
    intersectOrTransform(org.opengis.geometry.Envelope domain, org.opengis.referencing.operation.MathTransform prefix)
    Transforms the given envelope, then either returns it or delegates to intersect(Envelope).
    Optional<org.opengis.geometry.Envelope>
    Returns the domain computed so far by this instance.
    Returns a string representation for debugging purposes.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Field Details

    • limits

      private org.opengis.geometry.Envelope limits
      Limits computed so far, or null if none.
    • intersection

      private GeneralEnvelope intersection
      The envelope to use for computing intersection, created only if needed.
    • stepToDomain

      private DomainDefinition.ToDomain stepToDomain
      If the transform to evaluate is a step in the middle of a chain of transforms, the transform to apply on the envelope computed by the step in order to get an envelope in domain units.
  • Constructor Details

    • DomainDefinition

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

    • estimate

      public void estimate(org.opengis.referencing.operation.MathTransform evaluated) throws org.opengis.referencing.operation.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:
      org.opengis.referencing.operation.TransformException - if the domain cannot be estimated.
    • estimateOnInverse

      final void estimateOnInverse(org.opengis.referencing.operation.MathTransform inverse) throws org.opengis.referencing.operation.TransformException
      Estimates the domain using the inverse of a transform. The input ranges of original transform is the output ranges of inverse transform. Using the inverse is convenient because ConcatenatedTransform.transform2 contains all transform steps down to the end of the chain. By contrast if we did not used inverse, we would have to concatenate ourselves all transform steps up to the beginning of the chain (because ConcatenatedTransform does not store information about what happened before) in order to convert the envelope provided by a step into the source units of the first step of the chain.
      Note: DomainDefinition.ToDomain records history and does concatenations, but it is for a corner case which would still exist in addition of the above if we didn't used inverse.
      Parameters:
      inverse - inverse of the transform for which to compute domain.
      Throws:
      org.opengis.referencing.operation.TransformException - if the domain cannot be estimated.
    • estimateOnInverse

      final void estimateOnInverse(org.opengis.referencing.operation.MathTransform inverse, org.opengis.referencing.operation.MathTransform tail) throws org.opengis.referencing.operation.TransformException
      Estimates the domain using the inverse of a transform and transform that domain using the given suffix. This method is invoked when the inverse transform is not the last step of a transform chain. The last steps shall be specified in the tail transform.
      Parameters:
      inverse - inverse of the transform for which to compute domain.
      tail - transform to use for transforming the domain envelope.
      Throws:
      org.opengis.referencing.operation.TransformException - if the domain cannot be estimated.
    • intersect

      public void intersect(org.opengis.geometry.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.
    • intersectOrTransform

      final org.opengis.geometry.Envelope intersectOrTransform(org.opengis.geometry.Envelope domain, org.opengis.referencing.operation.MathTransform prefix) throws org.opengis.referencing.operation.TransformException
      Transforms the given envelope, then either returns it or delegates to intersect(Envelope). If prefix was the only transform applied, then the transformed envelope is returned. Otherwise the transformed envelope is intersected with current domain and null is returned.

      This method behavior allows opportunistic implementation of AbstractMathTransform.Inverse.getDomain(DomainDefinition). When above-cited method is invoked directly by users, they should get the transformed envelope because there is no other transform queued in stepToDomain. But if above-cited method is invoked for a transform in the middle of a transforms chain, then the transformed envelope cannot be returned because it would not be in the CRS expected by method contract. But because that situation is specific to ConcatenatedTransform, it should be unnoticed by users.

      Parameters:
      domain - the domain to intersect with, or null if none.
      prefix - a transform to apply on the envelope before other transforms.
      Returns:
      the transformed envelope if prefix was the only transform applied, or null otherwise.
      Throws:
      org.opengis.referencing.operation.TransformException - if the envelope cannot be transformed to the domain of the first transform step.
    • result

      public Optional<org.opengis.geometry.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.