Coordinates

Contents

Coordinates Overview
Specifying Ground Locations
Different Coordinate Frames
Converting Between Coordinate Frames

Coordinates Overview 

The coordinate module provides the base classes and functions used for coordinate definitions and conversions. This includes the ability to define ground locations and different coordinate systems, in addition to defining the framework for conversions between these systems.

Specifying Ground Locations 

One of the primary objectives of Celest is to generate and schedule encounter times between a satellite and a ground location; this requires the definition of a ground location which is accomplished using the GroundLocation class.

The GroundLocation class can be imported via the following:

from celest.coordinates import GroundLocation

class GroundLocation(latitude, longitude, height, angular_unit, length_unit)

Bases: object

Specify an Earth bound location.

The GroundLocation class models the Earth with the WGS84 reference ellipsoid to provide accurate representations of ground locations.

Parameters

latitude (float) – The location’s latitude.
longitude (float) – The location’s longitude.
height (float, optional) – The location’s height above the WGS84 ellipsoid.
angular_unit (Unit) – Unit of the latitude and longitude measures.
length_unit (Unit) – Unit of the height measure.

property latitude: Quantity

property longitude: Quantity

property height: Quantity

property radius: Quantity

Return the location’s geocentric radius using WGS84.

Returns: Earth’s geocentric radius at the given location.
Return type: Quantity

Notes

The WGS84 Earth ellipsoid model is used as discussed in “Earth Radius by Latitude (WGS 84)” by Timur. 1

References

1: Timur. Earth Radius by Latitude (WGS 84). 2018. url: https://planetcalc.com/7721/.

property itrs_x: Quantity: Location’s x coordinate in the itrs frame.

property itrs_y: Quantity: Location’s y coordinate in the itrs frame.

property itrs_z: Quantity: Location’s z coordinate in the itrs frame.

Different Coordinate Frames 

Celest provides the ability to deal with different coordinate frames and their conversions. The supported frames are:

Roll-Pitch-Yaw Attitude Frame,
Azimuth-Elevation (Horizontal frame),
Geocentric Celestial Reference System (GCRS),
International Terrestrial Reference System (ITRS),
Local-Vertical-Local-Horizontal (LVLH), and
World Geodetic System 84 (WGS84).

Roll-Pitch-Yaw Attitude Frame

The Roll-Pitch-Yaw attitude frame is a 3-dimensional frame that defines satellite orientation. The roll, pitch, and yaw angles are the angles required to rotate the satellite from the lvlh frame to an orientation where the satellite’s nadir intersects the ground location. The role of the attitude frame is to define satellite orientation for ground target tracking during ground imaging encounters (for a nadir facing camera).

The attitude frame is calculated from the Satellite.attitude() method and requires both the satellite position and velocity.

The Attitude class can be imported via the following:

from celest.coordinates import Attitude

class Attitude(julian, roll, pitch, yaw, unit, location)

Bases: Position3d

Satellite attitude.

The attitude of a satellite is defined by the roll, pitch, and yaw angles that take the satellite from the lvlh frame to a ground-target-pointing orientation.

Parameters

julian (np.ndarray) – 1-D array containing time in the JD2000 epoch.
roll (np.ndarray) – 1-D array containing the coordinate data.
pitch (np.ndarray) – 1-D array containing the coordinate data.
yaw (np.ndarray) – 1-D array containing the coordinate data.
unit (Unit) – The unit of the angular data.
location (GroundLocation) – The ground location associated with the attitude data.

save_text_file(file_name)

Save data as a pretty text file.

Parameters: file_name (str) – Name of the text file for the saved data.
Return type: None

to_numpy(unit)

Convert coordinate data to NumPy array.

Parameters: unit (Unit) – The unit of the output array.
Returns: The spatial coordinate data in the specified unit.
Return type: np.ndarray

property location: GroundLocation

property pitch: Quantity

property roll: Quantity

property time: Quantity

property yaw: Quantity

Azimuth-Elevation (Horizontal Frame)

The Azimuth-Elevation frame (also known as the Horizontal or Altitude-Azimuth frame) is an observer centric frame that uses the observers local horizon to define two angular measures: azimuth and elevation. Azimuth is the angle in the plane of the observer’s local horizon between the desired target and North. Azimuth is measured as clockwise positive and lies in the range \([0, 360)\). Elevation is the angle of the desired target above and perpendicular to the observer’s local horizon. Elevation is measured as positive above the horizontal plane and lies in the range \([-90, 90]\). This frame is used extensively in the window generation workflow.

Since the Azimuth-Elevation frame is dependent on the observer’s location, conversions from frames such as the GCRS or ITRS frame requires passing in an observer’s location. For more information on initializing a ground location, refer to the Specifying Ground Locations section.

The AzEl class can be imported via the following:

from celest.coordinates import AzEl

class AzEl(julian, azimuth, elevation, unit, location)

Bases: Position2d

Coordinates in the horizontal system.

The horizontal system has its origin located at a ground location and has measures of azimith and elevation. Azimuth is defined as the angle of the satellite in the horizontal plane clockwise from north. Elevation is defined as the angle of the satellite above the horzontal plane.

Parameters

julian (np.ndarray) – 1-D array containing time in the J2000 epoch.
azimuth (np.ndarray) – 1-D array containing the coordinate data.
elevation (np.ndarray) – 1-D array containing the coordinate data.
unit (Unit) – The unit of the spatial data.
location (GroundLocation) – Origin of the azel coordinate frame.

save_text_file(file_name)

Save data as a pretty text file.

Parameters: file_name (str) – Name of the text file for the saved data.
Return type: None

to_numpy(unit)

Convert coordinate data to NumPy array.

Parameters: unit (Unit) – The unit of the output array.
Returns: The spatial coordinate data in the specified unit.
Return type: np.ndarray

property azimuth: Quantity

property elevation: Quantity

property location: GroundLocation

property time: Quantity

Geocentric Celestial Reference System (GCRS)

The GCRS class can be imported via the following:

from celest.coordinates import GCRS

class GCRS(julian, x, y, z, unit)

Bases: Position3d

Coordinates in the Geocentric Celestial Reference System.

Parameters

julian (np.ndarray) – 1-D array containing time in the JD2000 epoch.
x (np.ndarray) – 1-D array containing the coordinate data.
y (np.ndarray) – 1-D array containing the coordinate data.
z (np.ndarray) – 1-D array containing the coordinate data.
unit (Unit) – The unit of the spatial data.

save_text_file(file_name)

Save data as a pretty text file.

Parameters: file_name (str) – Name of the text file for the saved data.
Return type: None

to_numpy(unit)

Convert coordinate data to NumPy array.

Parameters: unit (Unit) – The unit of the output array.
Returns: The spatial coordinate data in the specified unit.
Return type: np.ndarray

property time: Quantity

property x: Quantity

property y: Quantity

property z: Quantity

International Terrestrial Reference System (ITRS)

The ITRS class can be imported via the following:

from celest.coordinates import ITRS

class ITRS(julian, x, y, z, unit)

Bases: Position3d

Coordinates in the Internation Terrestrial Reference System.

Parameters

julian (np.ndarray) – 1-D array containing time in the J2000 epoch.
x (np.ndarray) – 1-D array containing the coordinate data.
y (np.ndarray) – 1-D array containing the coordinate data.
z (np.ndarray) – 1-D array containing the coordinate data.
unit (Unit) – The unit of the spatial data.

save_text_file(file_name)

Save data as a pretty text file.

Parameters: file_name (str) – Name of the text file for the saved data.
Return type: None

to_numpy(unit)

Convert coordinate data to NumPy array.

Parameters: unit (Unit) – The unit of the output array.
Returns: The spatial coordinate data in the specified unit.
Return type: np.ndarray

property time: Quantity

property x: Quantity

property y: Quantity

property z: Quantity

Local-Vertical-Local-Horizontal (LVLH)

The Local-Vertical-Local-Horizontal (LVLH) frame (also known as the Hill frame) is a 3-dimensional frame oriented with respect to the satellite’s orbit. The origin is located at the satellite’s center of mass. The z-axis is aligned with the satellites geocentric radius vector and is positive towards the Earth’s surface. The x-axis lies in the orbital plane and is perpendicular to the z-axis; the axis is positive in the direction of the satellite’s motion. Lastly, the y-axis is perpendicular to the orbital plane to complete the right handed orthogonal set.

The LVLH frame is used as a basis for satellite attitude determination. That is, the satellite’s attitude is defined as the roll, pitch, and yaw angles required to rotate the satellite from the LVLH frame to it’s given orientation.

The LVLH class can be imported via the following:

from celest.coordinates import LVLH

class LVLH(julian, x, y, z, unit)

Bases: Position3d

Coordinates in the level-horizontal-level-vertical or Hill frame.

The local-vertical local-horizontal frame (also known as the Hill frame) is a body frame where the z-axis is algigned with the negative of the geocentric position vector, the y-axis is aligned with the negative orbit normal, and the x-axis completes the right handed triad.

Parameters

julian (np.ndarray) – 1-D array containing time in the JD2000 epoch.
x (np.ndarray) – 1-D array containing the coordinate data.
y (np.ndarray) – 1-D array containing the coordinate data.
z (np.ndarray) – 1-D array containing the coordinate data.
unit (Unit) – The unit of the spatial data.

save_text_file(file_name)

Save data as a pretty text file.

Parameters: file_name (str) – Name of the text file for the saved data.
Return type: None

to_numpy(unit)

Convert coordinate data to NumPy array.

Parameters: unit (Unit) – The unit of the output array.
Returns: The spatial coordinate data in the specified unit.
Return type: np.ndarray

property time: Quantity

property x: Quantity

property y: Quantity

property z: Quantity

World Geodetic System 84 (WGS84)

The World Geodetic System 84 (WGS84) is a reference ellipsoid used to model the Earth as an ellipsoid rather than a sphere. It is defined by three measures: latitude, longitude, and the location’s height above the reference ellipsoid. The WGS84 frame is used primarily in defining ground locations such as those used in satellite-to-ground encounters.

The WGS84 class can be imported via the following:

from celest.coordinates import WGS84

class WGS84(julian, latitude, longitude, height, angular_unit, length_unit)

Bases: Position3d

Coordinates in the WGS84 Earth ellipsoid model.

The World Geodetic System 84 (WGS84) is an Earth ellipsoid model with its origin located at the Earth’s center of mass. The WGS84 meridian of zero longitude is located at the IERS reference meridian with the parallel of zero latitude located at the WGS84 reference meridian plane. WGS84 is the standard model used by the Global Positioning System (GPS).

Parameters

julian (np.ndarray) – 1-D array containing time in the JD2000 epoch.
latitude (np.ndarray) – 1-D array containing the coordinate data.
longitude (np.ndarray) – 1-D array containing the coordinate data.
height (np.ndarray) – 1-D array containing the coordinate data.
angular_unit (Unit) – The unit of the latitude and longitude data.
length_unit (Unit) – The unit of the height data.

save_text_file(file_name)

Save data as a pretty text file.

Parameters: file_name (str) – Name of the text file for the saved data.
Return type: None

to_numpy(unit)

Convert coordinate data to NumPy array.

Parameters: unit (Unit) – The unit of the output array.
Returns: The spatial coordinate data in the specified unit.
Return type: np.ndarray

property height: Quantity

property latitude: Quantity

property longitude: Quantity

property time: Quantity

Converting Between Coordinate Frames 

Conversions between the different coordinate frames are accessible through the Coordinate class. However, there exist constraints on various conversions.

Since the Azimuth-Elevation frame is observer centric, conversions to this frane require a defined ground location to be passed in as a parameter to the conversion method.
Conversions from the Azimuth-Elevation frame are not supported.

For more information on using the coordinate conversions, refer to the tutorial on converting between frames found here.

Note

Velocity conversions can be handled much in the same way as position conversions. However, due to physical insignificance, velocity coordinates should not be converted into the WGS84 frame.

The Coordinate class can be imported via the following:

from celest.coordinates import Coordinate

class Coordinate(position)

Bases: object

Coordinate frame transformations.

Parameters: position ({ITRS, GCRS, WGS84}) – Input position.

convert_to(frame, location=None): Convert the current frame to frame.

Notes

Conversions between the AzEl, GCRS, ITRS, and WGS84 frames are supported except for conversions from the AzEl frame.

Examples

Let gcrs be an initialized GCRS frame. We can then convert to the ITRS frame:

>>> c = Coordinate(gcrs)
>>> itrs = c.convert_to(ITRS)

By specifying a ground location, we can convert to the AzEl frame:

>>> location = GroundLocation(43.6532, -79.3832, 76, u.deg, u.m)
>>> azel = c.convert_to(AzEl, location)

Coordinates

Coordinates Overview

Specifying Ground Locations

Different Coordinate Frames

Roll-Pitch-Yaw Attitude Frame

Azimuth-Elevation (Horizontal Frame)

Geocentric Celestial Reference System (GCRS)

International Terrestrial Reference System (ITRS)

Local-Vertical-Local-Horizontal (LVLH)

World Geodetic System 84 (WGS84)

Converting Between Coordinate Frames

Coordinates Overview 

Specifying Ground Locations 

Different Coordinate Frames 

Converting Between Coordinate Frames 