EarthLocation¶
-
class
astropy.coordinates.
EarthLocation
[source] [edit on github]¶ Bases:
astropy.units.quantity.Quantity
Location on the Earth.
Initialization is first attempted assuming geocentric (x, y, z) coordinates are given; if that fails, another attempt is made assuming geodetic coordinates (longitude, latitude, height above a reference ellipsoid). When using the geodetic forms, Longitudes are measured increasing to the east, so west longitudes are negative. Internally, the coordinates are stored as geocentric.
To ensure a specific type of coordinates is used, use the corresponding class methods (
from_geocentric
andfrom_geodetic
) or initialize the arguments with names (x
,y
,z
for geocentric;lon
,lat
,height
for geodetic). See the class methods for details.Notes
This class fits into the coordinates transformation framework in that it encodes a position on the
ITRS
frame. To get a properITRS
object from this object, use theitrs
property.Attributes Summary
ellipsoid
The default ellipsoid used to convert to geodetic coordinates. geocentric
Convert to a tuple with X, Y, and Z as quantities geodetic
Convert to geodetic coordinates for the default ellipsoid. height
Height of the location, for the default ellipsoid. info
Container for meta information like name, description, format. itrs
An ITRS
object with for the location of this object at the defaultobstime
.lat
Longitude of the location, for the default ellipsoid. latitude
Deprecated since version 2.0.
lon
Longitude of the location, for the default ellipsoid. longitude
Deprecated since version 2.0.
x
The X component of the geocentric coordinates. y
The Y component of the geocentric coordinates. z
The Z component of the geocentric coordinates. Methods Summary
from_geocentric
(x, y, z[, unit])Location on Earth, initialized from geocentric coordinates. from_geodetic
(lon, lat[, height, ellipsoid])Location on Earth, initialized from geodetic coordinates. get_gcrs
(obstime)GCRS position with velocity at obstime
as a GCRS coordinate.get_gcrs_posvel
(obstime)Calculate the GCRS position and velocity of this object at the requested obstime
.get_itrs
([obstime])Generates an ITRS
object with the location of this object at the requestedobstime
.get_site_names
()Get list of names of observatories for use with of_site
.gravitational_redshift
(obstime[, bodies, masses])Return the gravitational redshift at this EarthLocation. of_address
(address[, get_height, google_api_key])Return an object of this class for a given address by querying either the OpenStreetMap Nominatim tool [1] (default) or the Google geocoding API [2], which requires a specified API key. of_site
(site_name)Return an object of this class for a known observatory/site by name. to_geocentric
()Convert to a tuple with X, Y, and Z as quantities to_geodetic
([ellipsoid])Convert to geodetic coordinates. Attributes Documentation
-
ellipsoid
¶ The default ellipsoid used to convert to geodetic coordinates.
-
geocentric
¶ Convert to a tuple with X, Y, and Z as quantities
-
geodetic
¶ Convert to geodetic coordinates for the default ellipsoid.
-
height
¶ Height of the location, for the default ellipsoid.
-
info
¶ Container for meta information like name, description, format. This is required when the object is used as a mixin column within a table, but can be used as a general way to store meta information.
-
lat
¶ Longitude of the location, for the default ellipsoid.
-
latitude
¶ Deprecated since version 2.0: The latitude property is deprecated and may be removed in a future version. Use
lat
instead.Latitude of the location, for the default ellipsoid.
-
lon
¶ Longitude of the location, for the default ellipsoid.
-
longitude
¶ Deprecated since version 2.0: The longitude property is deprecated and may be removed in a future version. Use
lon
instead.Longitude of the location, for the default ellipsoid.
-
x
¶ The X component of the geocentric coordinates.
-
y
¶ The Y component of the geocentric coordinates.
-
z
¶ The Z component of the geocentric coordinates.
Methods Documentation
-
classmethod
from_geocentric
(x, y, z, unit=None)[source] [edit on github]¶ Location on Earth, initialized from geocentric coordinates.
Parameters: Raises: - astropy.units.UnitsError
If the units on
x
,y
, andz
do not match or an invalid unit is given.- ValueError
If the shapes of
x
,y
, andz
do not match.- TypeError
If
x
is not aQuantity
and no unit is given.
-
classmethod
from_geodetic
(lon, lat, height=0.0, ellipsoid=None)[source] [edit on github]¶ Location on Earth, initialized from geodetic coordinates.
Parameters: - lon :
Longitude
or float Earth East longitude. Can be anything that initialises an
Angle
object (if float, in degrees).- lat :
Latitude
or float Earth latitude. Can be anything that initialises an
Latitude
object (if float, in degrees).- height :
Quantity
or float, optional Height above reference ellipsoid (if float, in meters; default: 0).
- ellipsoid : str, optional
Name of the reference ellipsoid to use (default: ‘WGS84’). Available ellipsoids are: ‘WGS84’, ‘GRS80’, ‘WGS72’.
Raises: - astropy.units.UnitsError
If the units on
lon
andlat
are inconsistent with angular ones, or that onheight
with a length.- ValueError
If
lon
,lat
, andheight
do not have the same shape, or ifellipsoid
is not recognized as among the ones implemented.
Notes
For the conversion to geocentric coordinates, the ERFA routine
gd2gc
is used. See https://github.com/liberfa/erfa- lon :
-
get_gcrs
(obstime)[source] [edit on github]¶ GCRS position with velocity at
obstime
as a GCRS coordinate.Parameters: - obstime :
Time
The
obstime
to calculate the GCRS position/velocity at.
Returns: - gcrs :
GCRS
instance With velocity included.
- obstime :
-
get_gcrs_posvel
(obstime)[source] [edit on github]¶ Calculate the GCRS position and velocity of this object at the requested
obstime
.Parameters: - obstime :
Time
The
obstime
to calculate the GCRS position/velocity at.
Returns: - obsgeoloc :
CartesianRepresentation
The GCRS position of the object
- obsgeovel :
CartesianRepresentation
The GCRS velocity of the object
- obstime :
-
get_itrs
(obstime=None)[source] [edit on github]¶ Generates an
ITRS
object with the location of this object at the requestedobstime
.Parameters: Returns: - itrs :
ITRS
The new object in the ITRS frame
- itrs :
-
classmethod
get_site_names
()[source] [edit on github]¶ Get list of names of observatories for use with
of_site
.Note
When this function is called, it will first attempt to download site information from the astropy data server. If it cannot (i.e., an internet connection is not available), it will fall back on the list included with astropy (which is a limited and dated set of sites). If you think a site should be added, issue a pull request to the astropy-data repository .
Returns: - names : list of str
List of valid observatory names
See also
of_site
- Gets the actual location object for one of the sites names this returns.
-
gravitational_redshift
(obstime, bodies=['sun', 'jupiter', 'moon'], masses={})[source] [edit on github]¶ Return the gravitational redshift at this EarthLocation.
Calculates the gravitational redshift, of order 3 m/s, due to the requested solar system bodies.
Parameters: - obstime :
Time
The
obstime
to calculate the redshift at.- bodies : iterable, optional
The bodies (other than the Earth) to include in the redshift calculation. List elements should be any body name
get_body_barycentric
accepts. Defaults to Jupiter, the Sun, and the Moon. Earth is always included (because the class represents an Earth location).- masses : dict of str to Quantity, optional
The mass or gravitational parameters (G * mass) to assume for the bodies requested in
bodies
. Can be used to override the defaults for the Sun, Jupiter, the Moon, and the Earth, or to pass in masses for other bodies.
Returns: - redshift :
Quantity
Gravitational redshift in velocity units at given obstime.
- obstime :
-
classmethod
of_address
(address, get_height=False, google_api_key=None)[source] [edit on github]¶ Return an object of this class for a given address by querying either the OpenStreetMap Nominatim tool [1] (default) or the Google geocoding API [2], which requires a specified API key.
This is intended as a quick convenience function to get easy access to locations. If you need to specify a precise location, you should use the initializer directly and pass in a longitude, latitude, and elevation.
In the background, this just issues a web query to either of the APIs noted above. This is not meant to be abused! Both OpenStreetMap and Google use IP-based query limiting and will ban your IP if you send more than a few thousand queries per hour [2].
Warning
If the query returns more than one location (e.g., searching on
address='springfield'
), this function will use the first returned location.Parameters: - address : str
The address to get the location for. As per the Google maps API, this can be a fully specified street address (e.g., 123 Main St., New York, NY) or a city name (e.g., Danbury, CT), or etc.
- get_height : bool (optional)
This only works when using the Google API! See the
google_api_key
block below. Use the retrieved location to perform a second query to the Google maps elevation API to retrieve the height of the input address [3].- google_api_key : str (optional)
A Google API key with the Geocoding API and (optionally) the elevation API enabled. See [4] for more information.
Returns: - location : This class (a
EarthLocation
or subclass) The location of the input address.
References
[1] (1, 2, 3) https://nominatim.openstreetmap.org/ [2] (1, 2, 3, 4) https://developers.google.com/maps/documentation/geocoding/start [3] (1, 2) https://developers.google.com/maps/documentation/elevation/ [4] (1, 2) https://developers.google.com/maps/documentation/geocoding/get-api-key
-
classmethod
of_site
(site_name)[source] [edit on github]¶ Return an object of this class for a known observatory/site by name.
This is intended as a quick convenience function to get basic site information, not a fully-featured exhaustive registry of observatories and all their properties.
Additional information about the site is stored in the
.info.meta
dictionary of sites obtained using this method (see the examples below).Note
When this function is called, it will attempt to download site information from the astropy data server. If you would like a site to be added, issue a pull request to the astropy-data repository . If a site cannot be found in the registry (i.e., an internet connection is not available), it will fall back on a built-in list, In the future, this bundled list might include a version-controlled list of canonical observatories extracted from the online version, but it currently only contains the Greenwich Royal Observatory as an example case.
Parameters: - site_name : str
Name of the observatory (case-insensitive).
Returns: - site : This class (a
EarthLocation
or subclass) The location of the observatory.
See also
get_site_names
- the list of sites that this function can access
Examples
>>> from astropy.coordinates import EarthLocation >>> keck = EarthLocation.of_site('Keck Observatory') # doctest: +REMOTE_DATA >>> keck.geodetic # doctest: +REMOTE_DATA +FLOAT_CMP GeodeticLocation(lon=<Longitude -155.47833333 deg>, lat=<Latitude 19.82833333 deg>, height=<Quantity 4160. m>) >>> keck.info.meta # doctest: +REMOTE_DATA {'source': 'IRAF Observatory Database', 'timezone': 'US/Aleutian'}
-
to_geocentric
()[source] [edit on github]¶ Convert to a tuple with X, Y, and Z as quantities
-
to_geodetic
(ellipsoid=None)[source] [edit on github]¶ Convert to geodetic coordinates.
Parameters: - ellipsoid : str, optional
Reference ellipsoid to use. Default is the one the coordinates were initialized with. Available are: ‘WGS84’, ‘GRS80’, ‘WGS72’
Returns: Raises: - ValueError
if
ellipsoid
is not recognized as among the ones implemented.
Notes
For the conversion to geodetic coordinates, the ERFA routine
gc2gd
is used. See https://github.com/liberfa/erfa
-