Class GeohashReferenceSystem.Coder

java.lang.Object
org.apache.sis.referencing.gazetteer.ReferencingByIdentifiers.Coder
org.apache.sis.referencing.gazetteer.GeohashReferenceSystem.Coder
Enclosing class:
GeohashReferenceSystem

public class GeohashReferenceSystem.Coder extends ReferencingByIdentifiers.Coder
Conversions between direct positions and geohashes. Each Coder instance can read codes at arbitrary precision, but formats at the specified precision. The same Coder instance can be reused for reading or writing many geohashes.

Immutability and thread safety

This class is not thread-safe. A new instance must be created for each thread, or synchronization must be applied by the caller.
Since:
0.8
Version:
1.3
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private char[]
    A buffer of length length, created when first needed.
    private final double[]
    Temporary array for coordinate transformation, or null if not needed.
    private org.opengis.referencing.operation.CoordinateOperation
    Last coordinate operation used by encode(DirectPosition).
    private int
    Amount of letters or digits to format in the geohash.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Creates a new geohash coder/decoder initialized to the default precision.
  • Method Summary

    Modifier and Type
    Method
    Description
    Decodes the given geohash into a latitude and a longitude.
    encode(double φ, double λ)
    Encodes the given latitude and longitude into a geohash.
    encode(org.opengis.geometry.DirectPosition position)
    Encodes the given position into a geohash.
    encode(org.opengis.geometry.DirectPosition position, javax.measure.Quantity<?> precision)
    Encodes the given position into a geohash with the given precision.
    int
    Returns the length of geohashes strings to be encoded by the encode(DirectPosition) method.
    javax.measure.Quantity<javax.measure.quantity.Length>
    getPrecision(org.opengis.geometry.DirectPosition position)
    Returns an approximate precision of the geohashes formatted by this coder.
    Returns the reference system for which GeoHash identifiers will be encoded or decoded.
    void
    setHashLength(int length)
    Sets the length of geohashes strings to be encoded by the encode(DirectPosition) method.
    void
    setPrecision(javax.measure.Quantity<?> precision, org.opengis.geometry.DirectPosition position)
    Sets the desired precision of the identifiers formatted by this coder.
    private org.opengis.geometry.DirectPosition
    toGeographic(org.opengis.geometry.DirectPosition position)
    Transforms the given position to the GeohashReferenceSystem.normalizedCRS.

    Methods inherited from class org.apache.sis.referencing.gazetteer.ReferencingByIdentifiers.Coder

    recoverableException

    Methods inherited from class java.lang.Object

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

    • length

      private int length
      Amount of letters or digits to format in the geohash.
    • buffer

      private transient char[] buffer
      A buffer of length length, created when first needed.
    • lastOp

      private transient org.opengis.referencing.operation.CoordinateOperation lastOp
      Last coordinate operation used by encode(DirectPosition).
    • coordinates

      private final transient double[] coordinates
      Temporary array for coordinate transformation, or null if not needed.
  • Constructor Details

    • Coder

      protected Coder()
      Creates a new geohash coder/decoder initialized to the default precision.
  • Method Details

    • getReferenceSystem

      public final GeohashReferenceSystem getReferenceSystem()
      Returns the reference system for which GeoHash identifiers will be encoded or decoded.
      Specified by:
      getReferenceSystem in class ReferencingByIdentifiers.Coder
      Returns:
      the enclosing reference system.
      Since:
      1.3
    • getHashLength

      public int getHashLength()
      Returns the length of geohashes strings to be encoded by the encode(DirectPosition) method. The default value for GeohashReferenceSystem.Format.BASE32 is 12.
      Returns:
      the length of geohashes strings.
    • setHashLength

      public void setHashLength(int length)
      Sets the length of geohashes strings to be encoded by the encode(DirectPosition) method.
      Parameters:
      length - the new length of geohashes strings.
    • getPrecision

      public javax.measure.Quantity<javax.measure.quantity.Length> getPrecision(org.opengis.geometry.DirectPosition position)
      Returns an approximate precision of the geohashes formatted by this coder. Values are in units of ellipsoid axis length (typically metres). If the location is unspecified, then this method returns a value for the "worst case" scenario, which is at equator. The actual precision is sometimes (but not always) better for coordinates closer to a pole.
      Specified by:
      getPrecision in class ReferencingByIdentifiers.Coder
      Parameters:
      position - where to evaluate the precision, or null for equator.
      Returns:
      approximate precision of formatted geohashes.
      Since:
      1.3
    • setPrecision

      public void setPrecision(javax.measure.Quantity<?> precision, org.opengis.geometry.DirectPosition position) throws javax.measure.IncommensurableException
      Sets the desired precision of the identifiers formatted by this coder. The given value is converted to a string length.
      Specified by:
      setPrecision in class ReferencingByIdentifiers.Coder
      Parameters:
      precision - the desired precision in a linear or angular unit.
      position - location where the specified precision is desired, or null for the equator.
      Throws:
      javax.measure.IncommensurableException - if the given precision does not use linear or angular units.
      Since:
      1.3
    • encode

      public String encode(double φ, double λ) throws org.opengis.referencing.operation.TransformException
      Encodes the given latitude and longitude into a geohash. This method does not take in account the axis order and units of the coordinate reference system (CRS) given to the GeohashReferenceSystem constructor. For geohashing of coordinates in different CRS, use encode(DirectPosition) instead.
      Parameters:
      φ - latitude to encode, as decimal degrees in the [-90 … 90]° range.
      λ - longitude to encode, as decimal degrees in the [-180 … 180]° range.
      Returns:
      geohash encoding of the given longitude and latitude.
      Throws:
      org.opengis.referencing.operation.TransformException - if an error occurred while formatting the given coordinate.
    • encode

      public String encode(org.opengis.geometry.DirectPosition position) throws org.opengis.referencing.operation.TransformException
      Encodes the given position into a geohash. The default implementation transforms the given position to the coordinate reference system expected by the enclosing GeohashReferenceSystem, then delegates to encode(double, double).
      Specified by:
      encode in class ReferencingByIdentifiers.Coder
      Parameters:
      position - the coordinate to encode.
      Returns:
      geohash encoding of the given position.
      Throws:
      org.opengis.referencing.operation.TransformException - if an error occurred while transforming the given coordinate to a geohash reference.
    • encode

      public String encode(org.opengis.geometry.DirectPosition position, javax.measure.Quantity<?> precision) throws javax.measure.IncommensurableException, org.opengis.referencing.operation.TransformException
      Encodes the given position into a geohash with the given precision. This is equivalent to invoking setPrecision(Quantity, DirectPosition) before encode(DirectPosition), except that it is potentially more efficient.
      Overrides:
      encode in class ReferencingByIdentifiers.Coder
      Parameters:
      position - the coordinate to encode.
      precision - the desired precision in a linear or angular unit.
      Returns:
      geohash encoding of the given position.
      Throws:
      javax.measure.IncommensurableException - if the given precision does not use linear or angular units.
      org.opengis.referencing.operation.TransformException - if an error occurred while transforming the given coordinate to a geohash reference.
      Since:
      1.3
    • toGeographic

      private org.opengis.geometry.DirectPosition toGeographic(org.opengis.geometry.DirectPosition position) throws org.opengis.util.FactoryException, org.opengis.referencing.operation.TransformException
      Transforms the given position to the GeohashReferenceSystem.normalizedCRS. If the position does not specify a CRS, then it is assumed already normalized.
      Parameters:
      position - the position to transform.
      Returns:
      the transformed position.
      Throws:
      org.opengis.util.FactoryException
      org.opengis.referencing.operation.TransformException
    • decode

      public AbstractLocation decode(CharSequence geohash) throws org.opengis.referencing.operation.TransformException
      Decodes the given geohash into a latitude and a longitude. The axis order depends on the coordinate reference system of the enclosing GeohashReferenceSystem.
      Upcoming API change — generalization
      in a future SIS version, the type of returned element may be generalized to the org.opengis.referencing.gazetteer.Location interface. This change is pending GeoAPI revision.
      Specified by:
      decode in class ReferencingByIdentifiers.Coder
      Parameters:
      geohash - geohash string to decode.
      Returns:
      a new geographic coordinate for the given geohash.
      Throws:
      org.opengis.referencing.operation.TransformException - if an error occurred while parsing the given string.