Package noaa.coastwatch.util

Class EarthLocation

java.lang.Object
noaa.coastwatch.util.EarthLocation
All Implemented Interfaces:
Cloneable
public class EarthLocation extends Object implements Cloneable
An earth location represents a point using latitude and longitude in degrees. Unless otherwise specified, the latitude and longitude are geodetic relative to the WGS84 datum.
Since:
3.1.1
Author:
Peter Hollemans

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    D
    Format style code for integer degrees: '124 W'.
    static final int
    DD
    Format style code for 2-digit degrees: '124.36 W'.
    static final int
    DDDD
    Format style code for 4-digit degrees: '124.3600 W'.
    static final int
    DDMM
    Format style code for degrees, minutes: '124 21.60 W'.
    static final int
    DDMMSS
    Format style code for degrees, minutes, seconds: '124 21 36.00 W'.
    double
    lat
    The earth location latitude in degrees.
    static final int
    LAT
    Selection code for latitude.
    double
    lon
    The earth location longitude in degrees.
    static final int
    LON
    Selection code for longitude.
    static final int
    RAW
    Format style code for full precision degrees: '-124.360001453546473'.

  • Constructor Summary

    Constructors
    Constructor
    Description
    EarthLocation()
    Constructs a new earth location at the origin (0,0).
    EarthLocation(double lat, double lon)
    Constructs a new earth location from the specified parameters.
    EarthLocation(double lat, double lon, Datum datum)
    Constructs a new earth location from the specified parameters.
    EarthLocation(Datum datum)
    Constructs a new earth location at the origin (0,0) with the specified datum.

  • Method Summary

    Modifier and Type
    Method
    Description
    Object
    clone()
     
    void
    computeECF(double[] ecf)
    Converts this earth location to Earth-Centered-Fixed (ECF) coordinates as described in Datum.computeECF(double, double, double[]).
    boolean
    crossesAntiMeridian(EarthLocation loc)
    Determines if the shortest line segment joining this location to another crosses the anti-meridian line at +180/-180 longitude.
    static double
    distance(double latA, double lonA, double latB, double lonB)
    Calculates the great circle distance between two locations A and B.
    double
    distance(EarthLocation loc)
    Calculates the great circle distance from this location to another.
    double
    distanceProxy(double latA, double lonA, double latB, double lonB)
    Computes a distance proxy between two locations.
    double
    distanceProxy(EarthLocation loc)
    Calculates the great circle distance proxy from this location to another.
    static double
    distanceProxyToDistance(double distProxy)
    Converts a distance proxy to an actual distance.
    boolean
    equals(Object obj)
     
    String
    format()
    Formats this earth location to a string using the default format style.
    String
    format(int style)
    Formats this earth location to a string.
    static String
    formatSingle(double deg, int style, int select)
    Formats a single coordinate from an earth location to a string.
    String
    formatSingle(int select)
    Formats a single coordinate from this earth location coordinate to a string using the default format style.
    String
    formatSingle(int style, int select)
    Formats a single coordinate from this earth location to a string.
    double[]
    getCoords()
    Gets the coordinates as [lat, lon].
    Datum
    getDatum()
    Gets the location geodetic datum.
    static int
    getFormatStyle()
    Gets the default format style used by location formatting routines.
    boolean
    isEast(EarthLocation loc)
    Determines if this location is east of the specified location.
    boolean
    isNorth(EarthLocation loc)
    Determines if this location is north of the specified location.
    boolean
    isSouth(EarthLocation loc)
    Determines if this location is south of the specified location.
    boolean
    isValid()
    Checks if this earth location is valid.
    boolean
    isWest(EarthLocation loc)
    Determines if this location is west of the specified location.
    static double
    latRange(double lat)
    Returns a latitude in the range [-90..90].
    static double
    lonRange(double lon)
    Returns a longitude value in the range [-180..180).
    static void
    main(String[] argv)
    Tests this class.
    void
    markInvalid()
    Marks this location as invalid.
    void
    render(Graphics2D g, EarthImageTransform trans)
    Renders this earth location to a graphics context as a point.
    void
    setCoords(double lat, double lon)
    Sets the latitude and longitude coordinate values.
    void
    setDatum(Datum newDatum)
    Sets the location geodetic datum.
    static void
    setFormatStyle(int style)
    Sets the default format style used by location formatting methods.
    void
    shiftDatum(Datum newDatum)
    Sets the location geodetic datum and shifts the latitude and longitude coordinates so that they reflect the newly specified datum.
    String
    toString()
     
    EarthLocation
    translate(double latInc, double lonInc)
    Translates an earth location by the specified increments.

    Methods inherited from class java.lang.Object

    finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • D

      public static final int D
      Format style code for integer degrees: '124 W'.
      See Also:

    • DD

      public static final int DD
      Format style code for 2-digit degrees: '124.36 W'.
      See Also:

    • DDDD

      public static final int DDDD
      Format style code for 4-digit degrees: '124.3600 W'.
      See Also:

    • RAW

      public static final int RAW
      Format style code for full precision degrees: '-124.360001453546473'.
      See Also:

    • DDMM

      public static final int DDMM
      Format style code for degrees, minutes: '124 21.60 W'.
      See Also:

    • DDMMSS

      public static final int DDMMSS
      Format style code for degrees, minutes, seconds: '124 21 36.00 W'.
      See Also:

    • LAT

      public static final int LAT
      Selection code for latitude.
      See Also:

    • LON

      public static final int LON
      Selection code for longitude.
      See Also:

    • lat

      public double lat
      The earth location latitude in degrees. Latitudes have the range [-90..90].

    • lon

      public double lon
      The earth location longitude in degrees. Longitudes have the range [-180..180).

  • Constructor Details

    • EarthLocation

      public EarthLocation()
      Constructs a new earth location at the origin (0,0). The datum defaults to WGS84.

    • EarthLocation

      public EarthLocation(double lat, double lon)
      Constructs a new earth location from the specified parameters. If needed, the longitude value is adjusted to be in the range [-180..180). The datum defaults to WGS84.
      Parameters:
      lat - the latitude in degrees.
      lon - the longitude in degrees.

    • EarthLocation

      public EarthLocation(Datum datum)
      Constructs a new earth location at the origin (0,0) with the specified datum.
      Parameters:
      datum - the geodetic datum.

    • EarthLocation

      public EarthLocation(double lat, double lon, Datum datum)
      Constructs a new earth location from the specified parameters. If needed, the longitude value is adjusted to be in the range [-180..180). The datum defaults to WGS84.
      Parameters:
      lat - the latitude in degrees.
      lon - the longitude in degrees.
      datum - the geodetic datum.

  • Method Details

    • setDatum

      public void setDatum(Datum newDatum)
      Sets the location geodetic datum. No datum shift is performed.
      Parameters:
      newDatum - the location geodetic datum.
      See Also:

    • getDatum

      public Datum getDatum()
      Gets the location geodetic datum.
      Returns:
      the geodetic datum.

    • shiftDatum

      public void shiftDatum(Datum newDatum)
      Sets the location geodetic datum and shifts the latitude and longitude coordinates so that they reflect the newly specified datum.
      Parameters:
      newDatum - the new datum to convert to.

    • setFormatStyle

      public static void setFormatStyle(int style)
      Sets the default format style used by location formatting methods. The default format style is DDDD.
      Parameters:
      style - the location format style to use.

    • getFormatStyle

      public static int getFormatStyle()
      Gets the default format style used by location formatting routines.
      Returns:
      the current default location format style.
      See Also:

    • getCoords

      public double[] getCoords()
      Gets the coordinates as [lat, lon].

    • setCoords

      public void setCoords(double lat, double lon)
      Sets the latitude and longitude coordinate values. If needed, the longitude value is adjusted to be in the range [-180..180).
      Parameters:
      lat - the latitude in degrees.
      lon - the longitude in degrees.

    • distance

      public static double distance(double latA, double lonA, double latB, double lonB)

      Calculates the great circle distance between two locations A and B. The method uses a calculation for distance on a sphere.

      Haversine Formula (from R.W. Sinnott, "Virtues of the Haversine", Sky and Telescope, vol. 68, no. 2, 1984, p. 159):

         dlon = lon2 - lon1
   dlat = lat2 - lat1
   a = sin^2(dlat/2) + cos(lat1) * cos(lat2) * sin^2(dlon/2)
   c = 2 * arcsin(min(1,sqrt(a)))
   d = R * c
      Parameters:
      latA - the latitude of point A in degrees.
      lonA - the longitude of point A in degrees.
      latB - the latitude of point B in degrees.
      lonB - the longitude of point B in degrees.
      Returns:
      the distance between points in kilometres.
      See Also:

    • distance

      public double distance(EarthLocation loc)
      Calculates the great circle distance from this location to another.
      Parameters:
      loc - the location for which to calculate the distance.
      Returns:
      the distance between points in kilometres.
      See Also:

    • distanceProxyToDistance

      public static double distanceProxyToDistance(double distProxy)
      Converts a distance proxy to an actual distance.
      Parameters:
      distProxy - the distance proxy value from distanceProxy(EarthLocation).
      Returns:
      the distance in kilometres.
      Since:
      3.5.0

    • distanceProxy

      public double distanceProxy(double latA, double lonA, double latB, double lonB)
      Computes a distance proxy between two locations. The distance proxy can be used as measurement of the distance between two locations for the purposes of distance comparison, without the computational overhead of having to compute the actual distance.
      Parameters:
      latA - the latitude of point A in degrees.
      lonA - the longitude of point A in degrees.
      latB - the latitude of point B in degrees.
      lonB - the longitude of point B in degrees.
      Returns:
      the proxy for the distance between the two locations.
      Since:
      3.5.0

    • distanceProxy

      public double distanceProxy(EarthLocation loc)
      Calculates the great circle distance proxy from this location to another.
      Parameters:
      loc - the location for which to calculate the distance.
      Returns:
      the distance proxy between points in kilometres.
      Since:
      3.5.0
      See Also:

    • computeECF

      public void computeECF(double[] ecf)
      Converts this earth location to Earth-Centered-Fixed (ECF) coordinates as described in Datum.computeECF(double, double, double[]).
      Parameters:
      ecf - the output ECF coordinates in meters.
      Since:
      3.5.0

    • translate

      public EarthLocation translate(double latInc, double lonInc)
      Translates an earth location by the specified increments. If the translation causes the latitude to be outside the range [-90..90], the latitude and longitude are adjusted to travel over the pole and down the other side. If the translation causes the longitude to be outside the range [-180..180), the longitude is adjusted accordingly.
      Parameters:
      latInc - the latitude increment.
      lonInc - the longitude increment.
      Returns:
      the translated location.

    • isNorth

      public boolean isNorth(EarthLocation loc)
      Determines if this location is north of the specified location.
      Parameters:
      loc - the location to check.
      Returns:
      true if this location is north of the specified location or false if not.

    • isSouth

      public boolean isSouth(EarthLocation loc)
      Determines if this location is south of the specified location.
      Parameters:
      loc - the location to check.
      Returns:
      true if this location is south of the specified location or false if not.

    • isEast

      public boolean isEast(EarthLocation loc)
      Determines if this location is east of the specified location.
      Parameters:
      loc - the location to check.
      Returns:
      true if this location is east of the specified location or false if not.

    • isWest

      public boolean isWest(EarthLocation loc)
      Determines if this location is west of the specified location.
      Parameters:
      loc - the location to check.
      Returns:
      true if this location is west of the specified location or false if not.

    • crossesAntiMeridian

      public boolean crossesAntiMeridian(EarthLocation loc)
      Determines if the shortest line segment joining this location to another crosses the anti-meridian line at +180/-180 longitude.
      Parameters:
      loc - the earth location to check.
      Returns:
      true if the shortest line segment between this location and the specified location crosses the anti-meridian or false if not. If both locations are exactly on the anti-meridian, this method returns false. However if only one location is exactly on the antimeridian and the other is not, this method returns false if the location not on the anti-meridian has longitude in the range (-180, 0], or false if it has longitude in the range [0, 180).
      Since:
      3.5.1

    • formatSingle

      public static String formatSingle(double deg, int style, int select)
      Formats a single coordinate from an earth location to a string.
      Parameters:
      deg - the latitude or longitude value in degrees.
      style - the format style to use.
      select - the coordinate selection. Use LAT for latitude and LON for longitude.
      Returns:
      the formatted coordinate value.

    • formatSingle

      public String formatSingle(int style, int select)
      Formats a single coordinate from this earth location to a string.
      Parameters:
      style - the format style to use.
      select - the coordinate selection. Use LAT for latitude and LON for longitude.
      Returns:
      the formatted coordinate value.

    • formatSingle

      public String formatSingle(int select)
      Formats a single coordinate from this earth location coordinate to a string using the default format style.
      Parameters:
      select - the coordinate selection. Use LAT for latitude and LON for longitude.
      Returns:
      the formatted coordinate value.

    • format

      public String format(int style)
      Formats this earth location to a string. Both latitude and longitude are formatted.
      Parameters:
      style - the format style to use.
      Returns:
      the formatted coordinate values.

    • format

      public String format()
      Formats this earth location to a string using the default format style. Both latitude and longitude are formatted.
      Returns:
      the formatted coordinate values.

    • clone

      public Object clone()
      Overrides:
      clone in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • isValid

      public boolean isValid()
      Checks if this earth location is valid.
      Returns:
      true if the location is valid or false if not. An invalid earth location is normally used as a flag for a computation that has failed.
      See Also:

    • markInvalid

      public void markInvalid()
      Marks this location as invalid. Subsequent calls to check for validity will reflect the new state.
      Since:
      3.3.1
      See Also:

    • latRange

      public static double latRange(double lat)
      Returns a latitude in the range [-90..90].

    • lonRange

      public static double lonRange(double lon)
      Returns a longitude value in the range [-180..180).

    • render

      public void render(Graphics2D g, EarthImageTransform trans)
      Renders this earth location to a graphics context as a point.
      Parameters:
      g - the graphics context for drawing.
      trans - the earth image transform for converting Earth locations to image points.

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • main

      public static void main(String[] argv) throws Exception
      Tests this class.
      Parameters:
      argv - the array of command line parameters.
      Throws:
      Exception