Class GeoLocation

  • All Implemented Interfaces:
    Cloneable

    public class GeoLocation
    extends Object
    implements Cloneable
    A class that contains location information such as latitude and longitude required for astronomical calculations. The elevation field may not be used by some calculation engines and would be ignored if set. Check the documentation for specific implementations of the AstronomicalCalculator to see if elevation is calculated as part of the algorithm.
    Author:
    © Eliyahu Hershfeld 2004 - 2018
    • Constructor Detail

      • GeoLocation

        public GeoLocation​(String name,
                           double latitude,
                           double longitude,
                           TimeZone timeZone)
        GeoLocation constructor with parameters for all required fields.
        Parameters:
        name - The location name for display use such as "Lakewood, NJ"
        latitude - the latitude in a double format such as 40.095965 for Lakewood, NJ. Note: For latitudes south of the equator, a negative value should be used.
        longitude - double the longitude in a double format such as -74.222130 for Lakewood, NJ. Note: For longitudes east of the Prime Meridian (Greenwich), a negative value should be used.
        timeZone - the TimeZone for the location.
      • GeoLocation

        public GeoLocation​(String name,
                           double latitude,
                           double longitude,
                           double elevation,
                           TimeZone timeZone)
        GeoLocation constructor with parameters for all required fields.
        Parameters:
        name - The location name for display use such as "Lakewood, NJ"
        latitude - the latitude in a double format such as 40.095965 for Lakewood, NJ. Note: For latitudes south of the equator, a negative value should be used.
        longitude - double the longitude in a double format such as -74.222130 for Lakewood, NJ. Note: For longitudes east of the Prime Meridian (Greenwich), a negative value should be used.
        elevation - the elevation above sea level in Meters. Elevation is not used in most algorithms used for calculating sunrise and set.
        timeZone - the TimeZone for the location.
      • GeoLocation

        public GeoLocation()
        Default GeoLocation constructor will set location to the Prime Meridian at Greenwich, England and a TimeZone of GMT. The longitude will be set to 0 and the latitude will be 51.4772 to match the location of the Royal Observatory, Greenwich . No daylight savings time will be used.
    • Method Detail

      • getElevation

        public double getElevation()
        Method to get the elevation in Meters.
        Returns:
        Returns the elevation in Meters.
      • setElevation

        public void setElevation​(double elevation)
        Method to set the elevation in Meters above sea level.
        Parameters:
        elevation - The elevation to set in Meters. An IllegalArgumentException will be thrown if the value is a negative.
      • setLatitude

        public void setLatitude​(double latitude)
        Method to set the latitude.
        Parameters:
        latitude - The degrees of latitude to set. The values should be between -90° and 90°. An IllegalArgumentException will be thrown if the value exceeds the limit. For example 40.095965 would be used for Lakewood, NJ. Note: For latitudes south of the equator, a negative value should be used.
      • setLatitude

        public void setLatitude​(int degrees,
                                int minutes,
                                double seconds,
                                String direction)
        Method to set the latitude in degrees, minutes and seconds.
        Parameters:
        degrees - The degrees of latitude to set between 0° and 90°. For example 40 would be used for Lakewood, NJ. An IllegalArgumentException will be thrown if the value exceeds the limit.
        minutes - minutes of arc
        seconds - seconds of arc
        direction - N for north and S for south. An IllegalArgumentException will be thrown if the value is not S or N.
      • getLatitude

        public double getLatitude()
        Returns:
        Returns the latitude.
      • setLongitude

        public void setLongitude​(double longitude)
        Method to set the longitude in a double format.
        Parameters:
        longitude - The degrees of longitude to set in a double format between -180° and 180°. An IllegalArgumentException will be thrown if the value exceeds the limit. For example -74.2094 would be used for Lakewood, NJ. Note: for longitudes east of the Prime Meridian (Greenwich) a negative value should be used.
      • setLongitude

        public void setLongitude​(int degrees,
                                 int minutes,
                                 double seconds,
                                 String direction)
        Method to set the longitude in degrees, minutes and seconds.
        Parameters:
        degrees - The degrees of longitude to set between 0° and 180°. As an example 74 would be set for Lakewood, NJ. An IllegalArgumentException will be thrown if the value exceeds the limits.
        minutes - minutes of arc
        seconds - seconds of arc
        direction - E for east of the Prime Meridian or W for west of it. An IllegalArgumentException will be thrown if the value is not E or W.
      • getLongitude

        public double getLongitude()
        Returns:
        Returns the longitude.
      • setLocationName

        public void setLocationName​(String name)
        Parameters:
        name - The setter method for the display name.
      • getLocalMeanTimeOffset

        public long getLocalMeanTimeOffset()
        A method that will return the location's local mean time offset in milliseconds from local standard time. The globe is split into 360°, with 15° per hour of the day. For a local that is at a longitude that is evenly divisible by 15 (longitude % 15 == 0), at solar noon (with adjustment for the equation of time) the sun should be directly overhead, so a user who is 1° west of this will have noon at 4 minutes after standard time noon, and conversely, a user who is 1° east of the 15° longitude will have noon at 11:56 AM. Lakewood, N.J., whose longitude is -74.2094, is 0.7906 away from the closest multiple of 15 at -75°. This is multiplied by 4 to yield 3 minutes and 10 seconds earlier than standard time. The offset returned does not account for the Daylight saving time offset since this class is unaware of dates.
        Returns:
        the offset in milliseconds not accounting for Daylight saving time. A positive value will be returned East of the 15° timezone line, and a negative value West of it.
        Since:
        1.1
      • getAntimeridianAdjustment

        public int getAntimeridianAdjustment()
        Adjust the date for antimeridian crossover. This is needed to deal with edge cases such as Samoa that use a different calendar date than expected based on their geographic location. The actual Time Zone offset may deviate from the expected offset based on the longitude. Since the 'absolute time' calculations are always based on longitudinal offset from UTC for a given date, the date is presumed to only increase East of the Prime Meridian, and to only decrease West of it. For Time Zones that cross the antimeridian, the date will be artificially adjusted before calculation to conform with this presumption. For example, Apia, Samoa with a longitude of -171.75 uses a local offset of +14:00. When calculating sunrise for 2018-02-03, the calculator should operate using 2018-02-02 since the expected zone is -11. After determining the UTC time, the local DST offset of UTC+14:00 should be applied to bring the date back to 2018-02-03.
        Returns:
        the number of days to adjust the date This will typically be 0 unless the date crosses the antimeridian
      • getRhumbLineBearing

        public double getRhumbLineBearing​(GeoLocation location)
        Returns the rhumb line bearing from the current location to the GeoLocation passed in.
        Parameters:
        location - destination location
        Returns:
        the bearing in degrees
      • getRhumbLineDistance

        public double getRhumbLineDistance​(GeoLocation location)
        Returns the rhumb line distance from the current location to the GeoLocation passed in.
        Parameters:
        location - the destination location
        Returns:
        the distance in Meters
      • toXML

        public String toXML()
        A method that returns an XML formatted String representing the serialized Object. Very similar to the toString method but the return value is in an xml format. The format currently used (subject to change) is:
           <GeoLocation>
                 <LocationName>Lakewood, NJ</LocationName>
                 <Latitude>40.0828&deg</Latitude>
                 <Longitude>-74.2094&deg</Longitude>
                 <Elevation>0 Meters</Elevation>
                 <TimezoneName>America/New_York</TimezoneName>
                 <TimeZoneDisplayName>Eastern Standard Time</TimeZoneDisplayName>
                 <TimezoneGMTOffset>-5</TimezoneGMTOffset>
                 <TimezoneDSTOffset>1</TimezoneDSTOffset>
           </GeoLocation>
         
        Returns:
        The XML formatted String.