astro py:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- Astropy v1.1.1 »
- Astronomical Coordinate Systems (`astropy.coordinates`) »
- EarthLocation

# EarthLocation

class `astropy.coordinates.``EarthLocation`

  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` and `from_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 proper `ITRS` object from this object, use the `itrs` 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.
  `itrs` | An `ITRS` object with for the location of this object at the default `obstime`.
  `latitude` | Latitude of the location, for the default ellipsoid.
  `longitude` | 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 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_itrs`([obstime]) | Generates an `ITRS` object with the location of this object at the requested `obstime`.
  `get_site_names`() | Get list of names of observatories for use with `of_site`.
  `of_site`(site_name) | Return an object of this class for a known observatory/site by name.
  `to`(unit[, equivalencies]) | Returns a new `Quantity` object with the specified units.
  `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.

  `itrs`

    An `ITRS` object with for the location of this object at the default `obstime`.

  `latitude`

    Latitude of the location, for the default ellipsoid.

  `longitude`

    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)

    Location on Earth, initialized from geocentric coordinates.

    Parameters:

    x, y, z : `Quantity` or array-like

    > Cartesian coordinates. If not quantities, `unit` should be given.

    unit : `UnitBase` object or None

    > Physical unit of the coordinate values. If `x`, `y`, and/or `z` are quantities, they will be converted to this unit.

    Raises:

    astropy.units.UnitsError

    > If the units on `x`, `y`, and `z` do not match or an invalid unit is given.

    ValueError

    > If the shapes of `x`, `y`, and `z` do not match.

    TypeError

    > If `x` is not a `Quantity` and no unit is given.

  classmethod `from_geodetic`(lon, lat, height=0.0, ellipsoid=None)

    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` and `lat` are inconsistent with angular ones, or that on `height` with a length.

    ValueError

    > If `lon`, `lat`, and `height` do not have the same shape, or if `ellipsoid` 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

  `get_itrs`(obstime=None)

    Generates an `ITRS` object with the location of this object at the requested `obstime`.

    Parameters:

    obstime : `Time` or None

    > The `obstime` to apply to the new `ITRS`, or if None, the default `obstime` will be used.

    Returns:

    itrs : `ITRS`

    > The new object in the ITRS frame

  classmethod `get_site_names`()

    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.
  classmethod `of_site`(site_name)

    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.

    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
  `to`(unit, equivalencies=[])

    Returns a new `Quantity` object with the specified units.

    Parameters:

    unit : `UnitBase` instance, str

    > An object that represents the unit to convert to. Must be an `UnitBase` object or a string parseable by the `units` package.

    equivalencies : list of equivalence pairs, optional

    > A list of equivalence pairs to try if the units are not directly convertible. See Equivalencies. If not provided or `[]`, class default equivalencies will be used (none for `Quantity`, but may be set for subclasses) If `None`, no equivalencies will be applied at all, not even any set globally or within a context.

  `to_geocentric`()

    Convert to a tuple with X, Y, and Z as quantities

  `to_geodetic`(ellipsoid=None)

    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:

    (lon, lat, height) : tuple

    > The tuple contains instances of `Longitude`, `Latitude`, and `Quantity`

    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