Ground Location¶

Overview¶

A Ground Location is simply a location on a planet (or, more specifically, on the ellipsoid of a CelestialBody). The ground locations are usually defined with their geodetic positions (latitude, longitude and height on the ellipsoid) or with the cartesian coordinates fixed on the body fixed frame (e.g. ITRS, the Earth Fixed Coordinate System).

The GroundLocation class is a generalisation of the EarthLocation class in astropy and the code is mostly based on it. However, unlike the EarthLocation class which is bounded on the Earth, the GroundLocation can be anywhere, therefore an ellipsoid (e.g. Earth or Moon) should be explicitly specified. Otherwise, “Earth GRS80 Ellipsoid” is assumed as default.

A GroundLocation object can be initialised using a cartesian position vector (with length units) or with latitude, longitude and altitude / height values as seen in the examples below. The GeodeticLocation class ensures the latitude and longitude angles wrap correctly.

from astropy import units as u
from astropy.coordinates import Latitude, Longitude

from satmad.core.celestial_bodies_lib import MOON_ELLIPSOID_IAUWG2015
from satmad.core.ground_location import GeodeticLocation, GroundLocation

# Ground location on the Moon, defined with lat/lon
gnd_loc_moon = GroundLocation(10 * u.deg, 15 * u.deg, 150 * u.m, ellipsoid=MOON_ELLIPSOID_IAUWG2015)

# Ground location on the Earth with default ellipsoid, defined with GeodeticLocation
gnd_loc_earth = GroundLocation(GeodeticLocation(Longitude(10 * u.deg), Latitude(15 * u.deg), 150 * u.m))

# Ground location on the Earth with default ellipsoid, defined with cartesian position
gnd_loc_cart = GroundLocation.from_geocentric(5000 * u.km, 3600 * u.km, 1500 * u.km)

Once initialised, the GroundLocation object can yield its geodetic position with the geodetic parameter or to_geodetic() method. The result is a GeodeticLocation class.

Similarly, it can yield its geocentric cartesian position with the geocentric parameter or to_geocentric() method. This geocentric position is equal to the position in the Central Body Fixed frame, for example, ITRS for the Earth. The result is a three-element tuple of cartesian position. Perhaps more useful version of this is the to_body_fixed_coords() method, where the Geodetic Position is converted to a geocentric coordinates object as used by astropy (such as ITRS class for Earth). For this, one or more time values are to be provided, as well as a Celestial Body, whose internal body_fixed_coord is used to generate the resulting object. If there are no body-fixed coordinates are defined for the Celestial Body, then a TypeError will be raised.

import numpy as np

from astropy import units as u
from astropy.time import Time, TimeDelta

from satmad.core.celestial_bodies_lib import EARTH
from satmad.core.ground_location import GroundLocation

# Generate three time values, one day apart
time = Time("2020-04-10T00:00:00", scale="utc") + np.arange(1, 4) * TimeDelta(1, format="jd")

# Generate the Ground Location with the default Earth ellipsoid
gnd_loc = GroundLocation(10 * u.deg, 15 * u.deg, 150 * u.m, ellipsoid=EARTH.ellipsoid)

# Generate the ground locations in body fixed frame (in this instance ITRS)
gnd_loc_body_fixed = gnd_loc.to_body_fixed_coords(EARTH, obstime=time)

print(gnd_loc_body_fixed)

Reference/API¶

Ground and Earth Location classes. These are based on astropy.coordinates.EarthLocation class, but generalised to non-Earth cases.

class satmad.core.ground_location.GeodeticLocation(lon, lat, height)¶

height¶: Alias for field number 2

lat¶: Alias for field number 1

lon¶: Alias for field number 0

class satmad.core.ground_location.GroundLocation(*args, **kwargs)¶

Location on a Central Body (e.g. Earth or Moon).

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 ~astropy.coordinates.ITRS frame. To get a proper ~astropy.coordinates.ITRS object from this object, use the itrs property.

property ellipsoid¶: The default ellipsoid used to convert to geodetic coordinates.

classmethod from_geocentric(x, y, z, unit=None, ellipsoid=<satmad.core.celestial_body.CelestialBodyEllipsoid object>)¶

Location on Central Body (e.g. Earth or Moon), initialized from geocentric cartesian coordinates.

Parameters

x (~astropy.units.Quantity or array_like) – Cartesian coordinates. If not quantities, unit should be given.
y (~astropy.units.Quantity or array_like) – Cartesian coordinates. If not quantities, unit should be given.
z (~astropy.units.Quantity or array_like) – Cartesian coordinates. If not quantities, unit should be given.
unit (~astropy.units.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.
ellipsoid (CelestialBodyEllipsoid, optional) – Definition of the reference ellipsoid to use (default: ‘EARTH_ELLIPSOID_GRS80’).

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 ~astropy.units.Quantity and no unit is given.

classmethod from_geodetic(lon, lat, height=0.0, ellipsoid=<satmad.core.celestial_body.CelestialBodyEllipsoid object>)¶

Location on Central Body (e.g. Earth or Moon), initialized from geodetic coordinates.

Parameters

lon (~astropy.coordinates.Longitude or float) – Earth East longitude. Can be anything that initialises an ~astropy.coordinates.Angle object (if float, in degrees).
lat (~astropy.coordinates.Latitude or float) – Earth latitude. Can be anything that initialises an ~astropy.coordinates.Latitude object (if float, in degrees).
height (~astropy.units.Quantity or float, optional) – Height above reference ellipsoid (if float, in meters; default: 0).
ellipsoid (CelestialBodyEllipsoid, optional) – Definition of the reference ellipsoid to use (default: ‘EARTH_ELLIPSOID_GRS80’).

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 gd2gce is used. See https://github.com/liberfa/erfa

property geocentric¶: Convert to a tuple with X, Y, and Z as quantities

property geodetic¶: Convert to geodetic coordinates for the default ellipsoid.

property height¶: Height of the location, for the default ellipsoid.

property lat¶: Longitude of the location, for the default ellipsoid.

property lon¶: Longitude of the location, for the default ellipsoid.

to_body_fixed_coords(celestial_body, obstime=None)¶

Generates a Central Body Fixed object (e.g. ~astropy.coordinates.ITRS object) with the location of this object at the requested obstime.

The celestial_body object should have its body_fixed_coord defined, as the resulting object will be of this type. For example, if the celestial body is Earth, the resulting object is of the type ITRS.

Parameters

celestial_body (CelestialBody) – The Celestial Body where the object is defined.
obstime (~astropy.time.Time or None) – The obstime to apply to the new object, or if None, the default obstime will be used.

Returns

The new object in the body fixed frame

Return type

body_fixed

to_geocentric()¶: Convert to a tuple with X, Y, and Z as quantities

to_geodetic(ellipsoid=<satmad.core.celestial_body.CelestialBodyEllipsoid object>)¶

Convert to geodetic coordinates.

Parameters: ellipsoid (CelestialBodyEllipsoid, optional) – Definition of the reference ellipsoid to use (default: ‘EARTH_ELLIPSOID_GRS80’).
Returns: (lon, lat, height) – The tuple contains instances of ~astropy.coordinates.Longitude, ~astropy.coordinates.Latitude, and ~astropy.units.Quantity
Return type: tuple

Notes

For the conversion to geodetic coordinates, the ERFA routine gc2gde is used. See https://github.com/liberfa/erfa

property x¶: The X component of the geocentric coordinates.

property y¶: The Y component of the geocentric coordinates.

property z¶: The Z component of the geocentric coordinates.