libera_utils.geolocation#

Module for performing geolocation tasks

Functions

`angle_between`(v1, v2[, degrees])	Returns angle between vectors v1 and v2, in units of radians (default) or degrees.
`cartesian_to_planetographic`(cartesian_coords)	Convert cartesian coordinates in the ITRF93 frame to planetographic latitude and longitude.
`frame_transform`(from_frame, to_frame, et, ...)	Transform a position <x, y, z> vector between reference frames, optionally normalizing the result.
`get_earth_radii`()	Retrieve Earth radii values from SPICE
`sub_observer_point`(target, et, frame, ...[, ...])	Computes the cartesian coordinates of the sub-observer point at time et and the observer altitude above the point.
`sub_solar_point`(target, et, frame, observer, *)	Computes the cartesian coordinates of the subsolar point at ephemeris time et.
`surface_intercept_point`(sc_location, ...[, et])	Returns rectangular coordinates of the point of interception of a look direction from the spacecraft onto the Earth ellipsoid.
`target_position`(target, et, frame, observer, *)	Calculates the position and velocity of the target at ephemeris time et relative to observer in reference frame frame.

libera_utils.geolocation.angle_between(v1: ndarray, v2: ndarray, degrees: bool = False)#

Returns angle between vectors v1 and v2, in units of radians (default) or degrees. N is the number of vectors D is the dimension of the space

Parameters:

v1 (numpy.ndarray) – Vector(s) 1. May be shape (D,) or (N, D).
v2 (numpy.ndarray) – Vector(s) 2. May be shape (D,) or (N, D).
degrees (bool) – Specify True to return result in degrees. Default is False (returns radians).

Returns:

Angle between v1 and v2 in radians (optionally in degrees)

Return type:

float or numpy.ndarray

libera_utils.geolocation.cartesian_to_planetographic(cartesian_coords: ndarray, degrees: bool = True)#

Convert cartesian coordinates in the ITRF93 frame to planetographic latitude and longitude. Longitude runs 0-360 such that longitude appears to increase as the planet rotates when viewed by an observer and latitude is calculated from a surface normal vector rather than a line through the planet center. See https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Tutorials/pdf/individual_docs/17_frames_and_coordinate_systems.pdf for reference.

Parameters:

cartesian_coords (numpy.ndarray) – Rectangular coordinates in ITRF93 frame.
degrees (bool) – Default true. If False, returns angles in radians.

Returns:

Each coordinate is returned as (longitude, latitude, altitude).

Return type:

numpy.ndarray

libera_utils.geolocation.frame_transform(from_frame: SpiceFrame, to_frame: SpiceFrame, et: float, position: ndarray, normalize: bool = False) → ndarray#

Transform a position <x, y, z> vector between reference frames, optionally normalizing the result.

Parameters:

from_frame (spice_utils.SpiceFrame) – Reference frame of position
to_frame (spice_utils.SpiceFrame) – Reference frame of output
et (numpy.float64 or numpy.ndarray) – Ephemeris time(s) corresponding to position(s). For time-independent transformations, this can by any valid ephemeris time.
position (numpy.ndarray) – <x, y, z> vector or array of vectors in reference frame from_frame
normalize (bool, Optional) – Optionally normalize the output vector

Returns:

3d position vector(s) in reference frame to_frame

Return type:

numpy.ndarray

libera_utils.geolocation.get_earth_radii()#

Retrieve Earth radii values from SPICE

Returns:: (re, rp, flat) tuple of equatorial and polar ellipsoid radii and a flattening coefficient
Return type:: tuple

libera_utils.geolocation.sub_observer_point(target: SpiceBody, et: float, frame: SpiceFrame, observer: SpiceBody, *, abcorr: str = 'NONE', method: str = 'NEAR POINT/ELLIPSOID')#

Computes the cartesian coordinates of the sub-observer point at time et and the observer altitude above the point. Units in km.

Parameters:

target (spice_utils.SpiceBody) – Body on which the sub point will be calculated (usually a planetary body).
et (float or numpy.ndarray) – Ephemeris time of observation.
frame (spice_utils.SpiceFrame) – Reference frame for returned vectors.
observer (spice_utils.SpiceBody) – The object from which to calculate the sub point (e.g. a spacecraft). A-B correction is applied based on the distance between observer and sub observer point.
abcorr (str, Optional) – String delineating what kind of A-B light time correction to perform. Default is ‘NONE’.
method (str, Optional) – String specifying what kind of method to use to find the vector between the observer and the target. Default is NEAR POINT/ELLIPSOID, which uses the nearest point on the ellipsoid rather than drawing a line through the center of the ellipsoid.

Returns:

Cartesian point on the target body surface in the specified reference frame and also the euclidean distance between the observer and the sub point in order: [x, y, z], obs_alt

Return type:

numpy.ndarray, float

libera_utils.geolocation.sub_solar_point(target: SpiceBody, et: float, frame: SpiceFrame, observer: SpiceBody, *, abcorr='LT+S', method='NEAR POINT/ELLIPSOID')#

Computes the cartesian coordinates of the subsolar point at ephemeris time et.

Parameters:

target (spice_utils.SpiceBody) – Body on which the sub point will be calculated (usually a planetary body).
et (float or numpy.ndarray) – Ephemeris time of observation.
frame (spice_utils.SpiceFrame) – Reference frame for returned vectors.
observer (spice_utils.SpiceBody) – The object from which to calculate the subsolar point (e.g. a spacecraft). A-B correction is applied based on the distance between observer and subsolar point.
abcorr (str) – String delineating what kind of A-B lighttime correction to perform. Default is ‘LT+S’.
method (str) – String specifying what kind of method to use to find the vector between the observer and the target. Default is NEAR POINT/ELLIPSOID, which uses the nearest point on the ellipsoid rather than drawing a line through the center of the ellipsoid.

Returns:

Subsolar point on the ellipsoid surface in the specified reference frame, apparent epoch at that point (depending on specified light time correction), and vector from observer to subsolar point.

Return type:

numpy.ndarray, numpy.ndarray, numpy.ndarray

libera_utils.geolocation.surface_intercept_point(sc_location: ndarray, look_vector: ndarray, look_frame: SpiceFrame, et: float = None)#

Returns rectangular coordinates of the point of interception of a look direction from the spacecraft onto the Earth ellipsoid. If the look vector misses the planet, then the distance returned will be non-zero and the point returned is the point on the look_vector ray that is closest to the ellipsoid.

This routine assumes that the location of the spacecraft and the location of the instrument are the same because we don’t have ephemeris data for the instrument but we _do_ have ephemeris for the spacecraft. Over the scale of distances involved, the offset between spacecraft and instrument (meters) should be negligible in affecting the near-point calculation.

https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/npedln_c.html

Parameters:

sc_location (numpy.ndarray) – The location of the observing body (i.e. the spacecraft body) with respect to Earth
look_vector (numpy.ndarray) – Look direction unit vector (e.g. an instrument look direction)
look_frame (spice_utils.SpiceFrame) – Reference frame of look_vector
et (float or numpy.ndarray or None, Optional) – Ephemeris time (at spacecraft at photon detection time). Only required if look_frame is not ITRF93.

Returns:

(pnear, alt) Rectangular coordinates of nearest point to reference surface ellipsoid and distance between the line and the near point.

Return type:

tuple

libera_utils.geolocation.target_position(target: SpiceBody, et: float, frame: SpiceFrame, observer: SpiceBody, *, abcorr: str = 'NONE', normalize: bool = False)#

Calculates the position and velocity of the target at ephemeris time et relative to observer in reference frame frame. Also calculates the light travel time between target and observer at time et.

Parameters:

target (spice_utils.SpiceBody) – Target body for which to calculate position and velocity relative to observer
et (float or numpy.ndarray) – Ephemeris time(s)
frame (spice_utils.SpiceFrame) – Reference frame (unit vectors)
observer (spice_utils.SpiceBody) – The observer of the target. Resulting coordinates point from observer to target.
abcorr (str) – A scalar string that indicates the aberration corrections to apply to the database of the target body to account for one-way light time and stellar aberration. Default is ‘NONE’.
normalize (bool, Optional) – Return unit vectors for position and velocity (light time output is unchanged)

Returns:

(x: numpy.ndarray, v: numpy.ndarray, lt: numpy.ndarray) or (x: float, v: float, lt: float) Rectangular position and velocity vectors (x, y, z), (v_x, v_y, v_z) where position points from the planet center of mass location at et to the aberration-corrected location of the target. Light time (lt) between planetary body and target.

Return type:

tuple