Module org.osgeo.proj
Package org.osgeo.proj

Class CoordinateOperationContext

Object
CoordinateOperationContext
All Implemented Interfaces:
Serializable, Cloneable
public class CoordinateOperationContext extends Object implements Cloneable, Serializable
Optional information about the context in which a coordinate operation will be used. When given to Proj.createCoordinateOperation(…) method, CoordinateOperationContext can modify the criterion by which PROJ will select the "best" coordinate operation. Some criterion are:

Limitations

CoordinateOperationContext is not thread-safe. It is only a temporary object for creating coordinate operations and rarely needs to be shared between different threads.
Since:
1.0
See Also:

  • Constructor Details

    • CoordinateOperationContext

      public CoordinateOperationContext()
      Creates a new context initialized to default value.

  • Method Details

    • setAuthority

      public void setAuthority(String name)
      Sets the authority to use for searching coordinate operations. Special values:
      • "" (empty string): coordinate operations from any authority will be searched, with the restrictions set in the "authority_to_authority_preference" database table.
      • "any": coordinate operations from any authority will be searched.
      Any other value will cause coordinate operations to be searched only in that authority name space. The default value is "default".
      Parameters:
      name - name of the new authority.
      Throws:
      NullPointerException - if name is null.

    • getAuthority

      public String getAuthority()
      Returns the authority to use for searching coordinate operations. This is the value given in last call to the setter, or the default value ("") if no value has been explicitly set.
      Returns:
      name of the current authority.

    • setAreaOfInterest

      public void setAreaOfInterest(double westBoundLongitude, double eastBoundLongitude, double southBoundLatitude, double northBoundLatitude)
      Sets the desired area of interest from the given latitude and longitude bounds. This convenience method creates an Extent from the given argument values, then delegates to setAreaOfInterest(Extent).

      Caution: Arguments are expected in the same order than they appear in the ISO 19115 specification. This is different than the order commonly found in Java world, which is rather (xmin, ymin, xmax, ymax).

      Parameters:
      westBoundLongitude - the minimal x value.
      eastBoundLongitude - the maximal x value.
      southBoundLatitude - the minimal y value.
      northBoundLatitude - the maximal y value.
      Throws:
      IllegalArgumentException - if (west bound > east bound) or (south bound > north bound). Note that NaN values are allowed.

    • setAreaOfInterest

      public void setAreaOfInterest(Extent extent)
      Sets the desired area of interest. The default value is null.
      Parameters:
      extent - the new area of interest, or null if unknown.

    • getAreaOfInterest

      public Extent getAreaOfInterest()
      Returns the desired area of interest, or null if none. This is the value given in last call to the setter, or the default value (null) if no value has been explicitly set. That value is not cloned.
      Returns:
      the desired area of interest, or null if unknown.

    • setDesiredAccuracy

      public void setDesiredAccuracy(double accuracy)
      Sets the desired accuracy (in metres). A value of 0 stands for the best accuracy available. The default value is 0.
      Parameters:
      accuracy - the desired accuracy (in metres), or 0 for the best accuracy available.
      Throws:
      IllegalArgumentException - if the given value is not finite and positive.

    • getDesiredAccuracy

      public double getDesiredAccuracy()
      Returns the desired accuracy (in metres). This is the value given in last call to the setter, or the default value (zero) if no value has been explicitly set.
      Returns:
      the desired accuracy (in metres), or 0 for the best accuracy available.

    • setSourceAndTargetCRSExtentUse

      public void setSourceAndTargetCRSExtentUse(SourceTargetCRSExtentUse use)
      Sets how source and target CRS extents should be used when considering if a transformation can be used. This parameter takes effect only if no area of interest is explicitly defined. The default is SourceTargetCRSExtentUse.DEFAULT.
      Parameters:
      use - the new policy about CRS extents use.

    • getSourceAndTargetCRSExtentUse

      public SourceTargetCRSExtentUse getSourceAndTargetCRSExtentUse()
      Returns how source and target CRS extents should be used when considering if a transformation can be used. This is the value given in last call to the setter, or the default value if no value has been explicitly set.
      Returns:
      the current policy about CRS extents use.

    • setSpatialCriterion

      public void setSpatialCriterion(SpatialCriterion criterion)
      Sets the spatial criterion to use when comparing the area of validity of coordinate operations with the area of interest / area of validity of source and target CRS. The default is SpatialCriterion.DEFAULT.
      Parameters:
      criterion - the new spatial criterion.

    • getSpatialCriterion

      public SpatialCriterion getSpatialCriterion()
      Returns the spatial criterion to use when comparing the area of validity of coordinate operations with the area of interest / area of validity of source and target CRS. This is the value given in last call to the setter, or the default value if no value has been explicitly set.
      Returns:
      the current spatial criterion.

    • setGridAvailabilityUse

      public void setGridAvailabilityUse(GridAvailabilityUse use)
      Sets how grid availability is used. The default is GridAvailabilityUse.DEFAULT.
      Parameters:
      use - the new policy about grid availability use.

    • getGridAvailabilityUse

      public GridAvailabilityUse getGridAvailabilityUse()
      Return how grid availability is used. This is the value given in last call to the setter, or the default value if no value has been explicitly set.
      Returns:
      the current policy about grid availability use.

    • setAllowUseIntermediateCRS

      public void setAllowUseIntermediateCRS(IntermediateCRSUse use)
      Set whether an intermediate pivot CRS can be used for researching coordinate operations between a source and target CRS. Concretely if in the database there is an operation from A to C (or C to A), and another one from C to B (or B to C), but no direct operation between A and B, setting this parameter to ALWAYS or IF_NO_DIRECT_TRANSFORMATION, allow chaining both operations.

      The PROJ 6.2 implementation is limited to researching one intermediate step. By default, with the IF_NO_DIRECT_TRANSFORMATION strategy, all potential C candidates will be used if there is no direct transformation.

      The default is IntermediateCRSUse.DEFAULT.

      Parameters:
      use - the new policy about intermediate pivot CRS use.

    • getAllowUseIntermediateCRS

      public IntermediateCRSUse getAllowUseIntermediateCRS()
      Return whether an intermediate pivot CRS can be used for researching coordinate operations between a source and target CRS. This is the value given in last call to the setter, or the default value if no value has been explicitly set.
      Returns:
      the current policy about intermediate pivot CRS use.

    • setDiscardSuperseded

      public void setDiscardSuperseded(boolean discard)
      Sets whether transformations that are superseded (but not deprecated) should be discarded. The default is true.
      Parameters:
      discard - the new policy about superseded transformations.

    • getDiscardSuperseded

      public boolean getDiscardSuperseded()
      Returns whether transformations that are superseded (but not deprecated) should be discarded. This is the value given in last call to the setter, or the default value (true) if no value has been explicitly set.
      Returns:
      the current policy about superseded transformations.

    • hashCode

      public int hashCode()
      Returns a hash code value for this context. This value does not need to be stable between different versions of this class.
      Overrides:
      hashCode in class Object
      Returns:
      an implementation-dependent hash code value.

    • equals

      public boolean equals(Object obj)
      Compares this context with the given object for equality.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to compare with this context.
      Returns:
      whether the given object is non-null and equal to this context.

    • clone

      public CoordinateOperationContext clone()
      Returns a shallow copy of this context. The cloned context will share the same extent instance than this context.
      Overrides:
      clone in class Object
      Returns:
      a shallow copy of this coordinate operation context.