Package org.apache.sis.geometry

Class WraparoundAdjustment

java.lang.Object
org.apache.sis.geometry.WraparoundAdjustment
public class WraparoundAdjustment extends Object
An envelope or position converter making them more compatible with a given domain of validity. For each axes having RangeMeaning.WRAPAROUND, this class can add or subtract an integer amount of periods (typically 360° of longitude) in attempt to move positions or envelopes inside a domain of validity specified at construction time.

WraparoundAdjustment instances are not thread-safe.

Since:
1.2
Version:
1.2

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final ImmutableEnvelope
    domainOfValidity
    The region inside which a given Area Of Interest (AOI) or Point Of Interest (POI) should be located.
    private final org.opengis.referencing.operation.MathTransform
    domainToInput
    A transform from the domainOfValidity CRS to the inputCRS if it was explicitly specified, or null otherwise.
    private org.opengis.metadata.extent.GeographicBoundingBox
    geographicDomain
    The geographic bounds of domainOfValidity, or null if not applicable.
    private boolean
    geographicDomainKnown
    Whether geographicDomain has been computed (result may be null).
    private org.opengis.referencing.crs.CoordinateReferenceSystem
    inputCRS
    Coordinate reference system of the last Area Of Interest (AOI) or Point Of Interest (POI).
    private org.opengis.referencing.operation.MathTransform
    inputToResult
    A transform from the inputCRS to any destination user space at caller choice.
    private org.opengis.referencing.operation.MathTransform
    inputToShiftable
    If the input envelopes or positions need to be converted to a (usually) geographic CRS, the transform to that CRS.
    private double[]
    periods
    The span (maximum - minimum) of wraparound axes, with 0 value for axes that are not wraparound.
    private final org.opengis.referencing.crs.CoordinateReferenceSystem
    resultCRS
    Coordinate reference system of results, or null if unspecified.
    private AbstractEnvelope
    shiftableDomain
    The domain of validity transformed to a CRS where wraparound axes exist, or null if not yet computed.
    private org.opengis.referencing.operation.MathTransform
    shiftableToResult
    The transform from the intermediate CRS to final objects, computed when first needed.

  • Constructor Summary

    Constructors
    Constructor
    Description
    WraparoundAdjustment(org.opengis.geometry.Envelope domain, org.opengis.referencing.crs.CoordinateReferenceSystem target)
    Creates a new instance for adjusting Area Of Interest (AOI) or Point Of Interest (POI) to the given domain.
    WraparoundAdjustment(org.opengis.geometry.Envelope domain, org.opengis.referencing.operation.MathTransform domainToInput, org.opengis.referencing.operation.MathTransform inputToResult)
    Creates a new instance with specified transforms from domain to the CRS of inputs, then to the CRS of outputs.

  • Method Summary

    Modifier and Type
    Method
    Description
    private org.opengis.referencing.operation.CoordinateOperation
    findOperation(org.opengis.referencing.crs.CoordinateReferenceSystem source, org.opengis.referencing.crs.CoordinateReferenceSystem target)
    Finds a coordinate operation from the given source CRS to target CRS.
    private boolean
    initialize(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Initializes this WraparoundAdjustment for an AOI or POI having the given coordinate reference system.
    org.opengis.geometry.DirectPosition
    shift(org.opengis.geometry.DirectPosition pointOfInterest)
    Computes a position with coordinates equivalent to the given pointOfInterest, but potentially shifted to interior of the domain of validity specified at construction time.
    GeneralEnvelope
    shift(org.opengis.geometry.Envelope areaOfInterest)
    Computes an envelope with coordinates equivalent to the given areaOfInterest, but potentially shifted for intersecting the domain of validity specified at construction time.
    private org.opengis.referencing.operation.MathTransform
    toResult(boolean isResultShifted)
    Returns the final transform to apply on the AOI or POI before to return it to the user.
    private void
    transformDomain(org.opengis.referencing.crs.CoordinateReferenceSystem target)
    Transforms domainOfValidity to a CRS where wraparound axes can be identified.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • domainOfValidity

      private final ImmutableEnvelope domainOfValidity
      The region inside which a given Area Of Interest (AOI) or Point Of Interest (POI) should be located. This domain is specified at construction time and does not change.

    • shiftableDomain

      private AbstractEnvelope shiftableDomain
      The domain of validity transformed to a CRS where wraparound axes exist, or null if not yet computed. For example if domainOfValidity is expressed in a projected CRS, then this envelope will be the same domain but converted to the base geographic CRS in order to allow identification of wraparound axes.

    • geographicDomain

      private org.opengis.metadata.extent.GeographicBoundingBox geographicDomain
      The geographic bounds of domainOfValidity, or null if not applicable.
      See Also:

    • geographicDomainKnown

      private boolean geographicDomainKnown
      Whether geographicDomain has been computed (result may be null).

    • inputCRS

      private org.opengis.referencing.crs.CoordinateReferenceSystem inputCRS
      Coordinate reference system of the last Area Of Interest (AOI) or Point Of Interest (POI). This is used for detecting when the input CRS changed.

    • resultCRS

      private final org.opengis.referencing.crs.CoordinateReferenceSystem resultCRS
      Coordinate reference system of results, or null if unspecified.

    • inputToResult

      private org.opengis.referencing.operation.MathTransform inputToResult
      A transform from the inputCRS to any destination user space at caller choice. Objects returned by shift(…) methods will be transformed by this transform after all computations have been finished. This is done in order to allow final transforms to be concatenated in a single step.

      This field should be considered final if domainToInput is non-null.

    • domainToInput

      private final org.opengis.referencing.operation.MathTransform domainToInput
      A transform from the domainOfValidity CRS to the inputCRS if it was explicitly specified, or null otherwise. If non-null, all input envelopes or positions will be assumed in the CRS which is the target of this transform. For performance reason, this assumption will not be verified.

    • inputToShiftable

      private org.opengis.referencing.operation.MathTransform inputToShiftable
      If the input envelopes or positions need to be converted to a (usually) geographic CRS, the transform to that CRS. Otherwise an identity transform. This is computed when first needed.

    • shiftableToResult

      private org.opengis.referencing.operation.MathTransform shiftableToResult
      The transform from the intermediate CRS to final objects, computed when first needed.
      See Also:

    • periods

      private double[] periods
      The span (maximum - minimum) of wraparound axes, with 0 value for axes that are not wraparound. Initially null and computed when first needed. The length of this array may be shorter than the CRS number of dimensions if all remaining axes are not wraparound axes.

  • Constructor Details

    • WraparoundAdjustment

      public WraparoundAdjustment(org.opengis.geometry.Envelope domain, org.opengis.referencing.crs.CoordinateReferenceSystem target)
      Creates a new instance for adjusting Area Of Interest (AOI) or Point Of Interest (POI) to the given domain. The results of shift(…) methods will be transformed (if needed) to the specified CRS.
      Parameters:
      domain - the region where a given area or point of interest should be located.
      target - the coordinate reference system of objects returned by shift(…) methods, or null for the same CRS than the domain CRS..

    • WraparoundAdjustment

      public WraparoundAdjustment(org.opengis.geometry.Envelope domain, org.opengis.referencing.operation.MathTransform domainToInput, org.opengis.referencing.operation.MathTransform inputToResult)
      Creates a new instance with specified transforms from domain to the CRS of inputs, then to the CRS of outputs. This constructor can be used when those transforms are known in advance; it avoids the cost of inferring them. With this constructor, WraparoundAdjustment does not verify if a coordinate operation is needed for a pair of CRS; it is caller's responsibility to ensure that input objects use the expected CRS.
      Example: in the context of GridGeometry, the domain argument may be the geospatial envelope of the grid and the inputToResult argument may be the "CRS to grid" transform. This configuration allows to compute grid coordinates having more chances to be inside the grid.
      Parameters:
      domain - the region where a given area (AOI) or point of interest (POI) should be located.
      domainToInput - if the AOI or POI will use a different CRS than domain, the transform from domain to the input CRS. Otherwise null for same CRS as the domain.
      inputToResult - a transform from the domain CRS to any user space at caller choice. If null, the results will be expressed in same CRS than the inputs.

  • Method Details

    • findOperation

      private org.opengis.referencing.operation.CoordinateOperation findOperation(org.opengis.referencing.crs.CoordinateReferenceSystem source, org.opengis.referencing.crs.CoordinateReferenceSystem target) throws org.opengis.referencing.operation.TransformException
      Finds a coordinate operation from the given source CRS to target CRS. This method is invoked by all codes that need to find a coordinate operation.
      Parameters:
      source - the source CRS of the desired coordinate operation.
      target - the target CRS of the desired coordinate operation.
      Returns:
      operation from source to target.
      Throws:
      org.opengis.referencing.operation.TransformException - if the operation cannot be computed.

    • initialize

      private boolean initialize(org.opengis.referencing.crs.CoordinateReferenceSystem crs) throws org.opengis.referencing.operation.TransformException
      Initializes this WraparoundAdjustment for an AOI or POI having the given coordinate reference system. If the given CRS is the same than the CRS given in last call to this method, then this method does nothing as this WraparoundAdjustment is assumed already initialized. Otherwise this method performs those steps:
      • If the given coordinate reference system is a projected CRS, replaces it by another CRS where wraparound axes can be identified.
      • Set shiftableDomain to an envelope in above CRS.
      • Set periods to an array with the periods of wraparound axes.
      • Set inputToResult to the final transform to apply in shift(…) methods.
      Returns:
      whether there is at least one wraparound axis.
      Throws:
      org.opengis.referencing.operation.TransformException

    • transformDomain

      private void transformDomain(org.opengis.referencing.crs.CoordinateReferenceSystem target) throws org.opengis.referencing.operation.TransformException
      Transforms domainOfValidity to a CRS where wraparound axes can be identified. This method should be invoked only when the caller detected at least one wraparound axis.

      If a domainToInput has been explicitly specified to the constructor, that transform is unconditionally used and the crs argument is ignored.

      Preconditions

      Throws:
      org.opengis.referencing.operation.TransformException

    • toResult

      private org.opengis.referencing.operation.MathTransform toResult(boolean isResultShifted) throws org.opengis.referencing.operation.TransformException
      Returns the final transform to apply on the AOI or POI before to return it to the user. If inputCRS is null, returns null for meaning "unknown transform".
      Throws:
      org.opengis.referencing.operation.TransformException

    • shift

      public GeneralEnvelope shift(org.opengis.geometry.Envelope areaOfInterest) throws org.opengis.referencing.operation.TransformException
      Computes an envelope with coordinates equivalent to the given areaOfInterest, but potentially shifted for intersecting the domain of validity specified at construction time. The dimensions that may be shifted are the ones having an axis with wraparound meaning. In order to perform this operation, the envelope may be temporarily converted to a geographic CRS and converted back to its original CRS.

      The coordinate reference system should be specified in the areaOfInterest. If not, then the CRS is assumed same as the CRS of the domain specified at construction time.

      This method does not intersect the area of interest with the domain of validity. It is up to the caller to compute that intersection after this method call, if desired.

      Parameters:
      areaOfInterest - the envelope to potentially shift toward domain of validity. If a shift is needed, then given envelope will be replaced by a new envelope; the given envelope will not be modified.
      Returns:
      envelope potentially expanded or shifted toward the domain of validity.
      Throws:
      org.opengis.referencing.operation.TransformException - if a coordinate conversion failed.
      See Also:

    • shift

      public org.opengis.geometry.DirectPosition shift(org.opengis.geometry.DirectPosition pointOfInterest) throws org.opengis.referencing.operation.TransformException
      Computes a position with coordinates equivalent to the given pointOfInterest, but potentially shifted to interior of the domain of validity specified at construction time. The dimensions that may be shifted are the ones having an axis with wraparound meaning. In order to perform this operation, the position may be temporarily converted to a geographic CRS and converted back to its original CRS.

      The coordinate reference system should be specified in the pointOfInterest. If not, then the CRS is assumed same as the CRS of the domain specified at construction time.

      Parameters:
      pointOfInterest - the position to potentially shift to domain of validity interior. If a shift is needed, then the given position will be replaced by a new position; the given position will not be modified.
      Returns:
      position potentially shifted to the domain of validity interior.
      Throws:
      org.opengis.referencing.operation.TransformException - if a coordinate conversion failed.