Class GeoLocation
java.lang.Object
com.kosherjava.zmanim.util.GeoLocation
- All Implemented Interfaces:
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 - 2025
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final int
Constant for a distance type calculation.private double
The elevation in Meters above sea level.private static final int
Constant for a final bearing type calculation.private static final long
constant for milliseconds in an hour (3,600,000)private static final int
Constant for an initial bearing type calculation.private double
The latitude, for example 40.096 for Lakewood, NJ.private String
The location name used for display, for example "Lakewood, NJ".private double
The longitude, for example -74.222 for Lakewood, NJ.private static final long
constant for milliseconds in a minute (60,000)private TimeZone
The location's time zone. -
Constructor Summary
ConstructorsConstructorDescriptionDefault GeoLocation constructor will set location to the Prime Meridian at Greenwich, England and a TimeZone of GMT.GeoLocation
(String name, double latitude, double longitude, double elevation, TimeZone timeZone) GeoLocation constructor with parameters for all required fields.GeoLocation
(String name, double latitude, double longitude, TimeZone timeZone) GeoLocation constructor with parameters for all required fields. -
Method Summary
Modifier and TypeMethodDescriptionclone()
An implementation of theObject.clone()
method that creates a deep copy of the object.boolean
int
Adjust the date for antimeridian crossover.double
Method to return the elevation in Meters above sea level.double
getGeodesicDistance
(GeoLocation location) Calculate geodesic distance in Meters between this Object and a second Object passed to this method using Thaddeus Vincenty's inverse formula See T Vincenty, "Direct and Inverse Solutions of Geodesics on the Ellipsoid with application of nested equations", Survey Review, vol XXII no 176, 1975double
getGeodesicFinalBearing
(GeoLocation location) Calculate the final geodesic bearing between this Object and a second Object passed to this method using Thaddeus Vincenty's inverse formula See T Vincenty, "Direct and Inverse Solutions of Geodesics on the Ellipsoid with application of nested equations", Survey Review, vol XXII no 176, 1975double
getGeodesicInitialBearing
(GeoLocation location) Calculate the initial geodesic bearing between this Object and a second Object passed to this method using Thaddeus Vincenty's inverse formula See T Vincenty, "Direct and Inverse Solutions of Geodesics on the Ellipsoid with application of nested equations", Survey Review, vol XXII no 176, 1975double
Method to return the latitude as adouble
, for example 40.096 for Lakewood, NJ.long
A method that will return the location's local mean time offset in milliseconds from local standard time.Method to return the location name (for display), for example "Lakewood, NJ".double
Method to return the longitude as adouble
, for example -74.222 for Lakewood, NJ.double
getRhumbLineBearing
(GeoLocation location) Returns the rhumb line bearing from the current location to the GeoLocation passed in.double
getRhumbLineDistance
(GeoLocation location) Returns the rhumb line distance from the current location to the GeoLocation passed in.Method to return the time zone.int
hashCode()
void
setElevation
(double elevation) Method to set the elevation in Meters above sea level.void
setLatitude
(double latitude) Method to set the latitude as adouble
, for example 40.096 for Lakewood, NJ.void
setLatitude
(int degrees, int minutes, double seconds, String direction) Method to set the latitude in degrees, minutes and seconds.void
setLocationName
(String name) Setter for the location name (for display), for example "Lakewood, NJ".void
setLongitude
(double longitude) Method to set the longitude as adouble
, for example -74.222 for Lakewood, NJvoid
setLongitude
(int degrees, int minutes, double seconds, String direction) Method to set the longitude in degrees, minutes and seconds.void
setTimeZone
(TimeZone timeZone) Method to set the TimeZone.toString()
toXML()
A method that returns an XML formattedString
representing the serializedObject
.private GeoLocation
vincentyDirectFormulaDestination
(double initialBearing, double distance) Calculate the destination point based on an initial bearing and distance in meters from the current location using Thaddeus Vincenty's direct formula.private double
vincentyInverseFormula
(GeoLocation location, int formula) Calculate geodesic distance in Meters between this Object and a second Object passed to this method using Thaddeus Vincenty's inverse formula See T Vincenty, "Direct and Inverse Solutions of Geodesics on the Ellipsoid with application of nested equations", Survey Review, vol XXII no 176, 1975
-
Field Details
-
latitude
-
longitude
-
locationName
The location name used for display, for example "Lakewood, NJ".- See Also:
-
timeZone
-
elevation
-
DISTANCE
-
INITIAL_BEARING
Constant for an initial bearing type calculation.- See Also:
-
FINAL_BEARING
-
MINUTE_MILLIS
-
HOUR_MILLIS
-
-
Constructor Details
-
GeoLocation
GeoLocation constructor with parameters for all required fields.- Parameters:
name
- The location name for display, for example "Lakewood, NJ".latitude
- the latitude as adouble
, for example 40.096 for Lakewood, NJ. Note: For latitudes south of the equator, a negative value should be used.longitude
- the longitude as adouble
, for example -74.222 for Lakewood, NJ. Note: For longitudes east of the Prime Meridian (Greenwich), a negative value should be used.timeZone
- theTimeZone
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, for example "Lakewood, NJ".latitude
- the latitude as adouble
, for example 40.096 for Lakewood, NJ. Note: For latitudes south of the equator, a negative value should be used.longitude
- double the longitude as adouble
, for example -74.222 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.timeZone
- theTimeZone
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 Details
-
getElevation
Method to return the elevation in Meters above sea level.- Returns:
- Returns the elevation in Meters.
- See Also:
-
setElevation
Method to set the elevation in Meters above sea level. -
setLatitude
Method to set the latitude as adouble
, for example 40.096 for Lakewood, NJ.- Parameters:
latitude
- The degrees of latitude to set. The values should be between -90° and 90°. For example 40.096 would be used for Lakewood, NJ. Note: For latitudes south of the equator, a negative value should be used. An IllegalArgumentException will be thrown if the value exceeds the limits.
-
setLatitude
Method to set the latitude in degrees, minutes and seconds. For example, set the degrees to 40, minutes to 5, seconds to 45.6 and direction to "N" for Lakewood, NJ.- 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, for example 5 would be used for Lakewood, NJ.seconds
- seconds of arc, for example 45.6 would be used for Lakewood, NJ.direction
- "N" for north and "S" for south, for example "N" would be used for Lakewood, NJ. An IllegalArgumentException will be thrown if the value is not "S" or "N".
-
getLatitude
Method to return the latitude as adouble
, for example 40.096 for Lakewood, NJ.- Returns:
- Returns the latitude.
-
setLongitude
Method to set the longitude as adouble
, for example -74.222 for Lakewood, NJ- Parameters:
longitude
- The degrees of longitude to set as adouble
between -180.0° and 180.0°. For example -74.222 would be used for Lakewood, NJ. Note: for longitudes east of the Prime Meridian (Greenwich) a negative value should be used.An IllegalArgumentException will be thrown if the value exceeds the limit.
-
setLongitude
Method to set the longitude in degrees, minutes and seconds. For example, set the degrees to 74, minutes to 13, seconds to 19.2 and direction to "W" for Lakewood, NJ.- Parameters:
degrees
- The degrees of longitude to set between 0° and 180°. For example 74 would be set for Lakewood, NJ. An IllegalArgumentException will be thrown if the value exceeds the limits.minutes
- minutes of arc. For example 13 would be set for Lakewood, NJ.seconds
- seconds of arc. For example 19.2 would be set for Lakewood, NJ.direction
- "E" for east of the Prime Meridian or "W"for west of it. For example, "W" would be set for Lakewood, NJ. An IllegalArgumentException will be thrown if the value is not E or W.
-
getLongitude
Method to return the longitude as adouble
, for example -74.222 for Lakewood, NJ.- Returns:
- Returns the longitude.
-
getLocationName
Method to return the location name (for display), for example "Lakewood, NJ".- Returns:
- Returns the location name.
-
setLocationName
Setter for the location name (for display), for example "Lakewood, NJ".- Parameters:
name
- The setter method for the display name.
-
getTimeZone
-
setTimeZone
Method to set the TimeZone. If this is ever set after the GeoLocation is set in theAstronomicalCalendar
, it is critical thatAstronomicalCalendar.getCalendar()
.setTimeZone(TimeZone)
be called in order for the AstronomicalCalendar to output times in the expected offset. This situation will arise if the AstronomicalCalendar is evercloned
.- Parameters:
timeZone
- The timeZone to set.
-
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 solarnoon
(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.222, is 0.778 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.
-
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
-
getGeodesicInitialBearing
Calculate the initial geodesic bearing between this Object and a second Object passed to this method using Thaddeus Vincenty's inverse formula See T Vincenty, "Direct and Inverse Solutions of Geodesics on the Ellipsoid with application of nested equations", Survey Review, vol XXII no 176, 1975- Parameters:
location
- the destination location- Returns:
- the initial bearing
-
getGeodesicFinalBearing
Calculate the final geodesic bearing between this Object and a second Object passed to this method using Thaddeus Vincenty's inverse formula See T Vincenty, "Direct and Inverse Solutions of Geodesics on the Ellipsoid with application of nested equations", Survey Review, vol XXII no 176, 1975- Parameters:
location
- the destination location- Returns:
- the final bearing
-
getGeodesicDistance
Calculate geodesic distance in Meters between this Object and a second Object passed to this method using Thaddeus Vincenty's inverse formula See T Vincenty, "Direct and Inverse Solutions of Geodesics on the Ellipsoid with application of nested equations", Survey Review, vol XXII no 176, 1975- Parameters:
location
- the destination location- Returns:
- the geodesic distance in Meters
- See Also:
-
vincentyDirectFormulaDestination
Calculate the destination point based on an initial bearing and distance in meters from the current location using Thaddeus Vincenty's direct formula. See T Vincenty, "Direct and Inverse Solutions of Geodesics on the Ellipsoid with application of nested equations", Survey Review, vol XXII no 176, 1975.- Parameters:
initialBearing
- the initialBearingdistance
- the distance in meters.- Returns:
- the GeoLocation containing the destination point. The Timezone is set to the origin point (current object).
-
vincentyInverseFormula
Calculate geodesic distance in Meters between this Object and a second Object passed to this method using Thaddeus Vincenty's inverse formula See T Vincenty, "Direct and Inverse Solutions of Geodesics on the Ellipsoid with application of nested equations", Survey Review, vol XXII no 176, 1975- Parameters:
location
- the destination locationformula
- This formula calculates initial bearing (INITIAL_BEARING
), final bearing (FINAL_BEARING
) and distance (DISTANCE
).- Returns:
- geodesic distance in Meters
-
getRhumbLineBearing
Returns the rhumb line bearing from the current location to the GeoLocation passed in.- Parameters:
location
- destination location- Returns:
- the bearing in degrees
-
getRhumbLineDistance
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
A method that returns an XML formattedString
representing the serializedObject
. 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.096°</Latitude> <Longitude>-74.222amp;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
.
-
equals
-
hashCode
-
toString
-
clone
An implementation of theObject.clone()
method that creates a deep copy of the object. Note: If theTimeZone
in the clone will be changed from the original, it is critical thatAstronomicalCalendar.getCalendar()
.setTimeZone(TimeZone)
is called after cloning in order for the AstronomicalCalendar to output times in the expected offset.
-