Orbit, attitude, and solar geometry#

class space_pv_orbit.SolarGeometry(sun_vector_m: 'tuple[float, float, float]', sun_distance_m: 'float', sun_unit_vector: 'tuple[float, float, float]', illumination_fraction: 'float', cosine_aoi: 'float | None' = None)[source]#
Parameters:
sun_vector_m: tuple[float, float, float]#
sun_distance_m: float#
sun_unit_vector: tuple[float, float, float]#
illumination_fraction: float#
cosine_aoi: float | None#
space_pv_orbit.body_vector_to_reference(body_vector, quaternion_wxyz)[source]#
Parameters:
Return type:

ndarray

space_pv_orbit.cosine_incidence(panel_normal, sun_direction)[source]#
Return type:

float

space_pv_orbit.earth_occultation_fraction(spacecraft_position_m, sun_position_m, *, earth_radius_m=6378137.0, sun_radius_m=695700000.0)[source]#
Parameters:
Return type:

float

space_pv_orbit.quaternion_wxyz_to_matrix(quaternion_wxyz)[source]#

Rotation matrix for a normalized active quaternion in (w, x, y, z) order.

The repository convention is explicit: attitude quaternions used by this function rotate vectors from the spacecraft body frame into the stated inertial/reference frame. Mission connectors must convert source conventions before calling it.

Parameters:

quaternion_wxyz (tuple[float, float, float, float] | ndarray)

Return type:

ndarray

space_pv_orbit.solar_geometry(spacecraft_position_m, sun_position_m, *, panel_normal=None)[source]#
Return type:

SolarGeometry

space_pv_orbit.unit_vector(value)[source]#
Return type:

ndarray

Attitude#

space_pv_orbit.attitude.quaternion_wxyz_to_matrix(quaternion_wxyz)[source]#

Rotation matrix for a normalized active quaternion in (w, x, y, z) order.

The repository convention is explicit: attitude quaternions used by this function rotate vectors from the spacecraft body frame into the stated inertial/reference frame. Mission connectors must convert source conventions before calling it.

Parameters:

quaternion_wxyz (tuple[float, float, float, float] | ndarray)

Return type:

ndarray

Geometry#

class space_pv_orbit.geometry.SolarGeometry(sun_vector_m: 'tuple[float, float, float]', sun_distance_m: 'float', sun_unit_vector: 'tuple[float, float, float]', illumination_fraction: 'float', cosine_aoi: 'float | None' = None)[source]#
Parameters:

Astropy adapter#

space_pv_orbit.astropy_engine.geocentric_sun_positions_m(times)[source]#

Geocentric GCRS Sun positions using Astropy’s supported solar ephemeris path.

Parameters:

times (Sequence[datetime] | Sequence[str])

Return type:

ndarray

Skyfield / SGP4 adapter#

SPICE adapter#

space_pv_orbit.spice_engine.utc_to_ephemeris_seconds(timestamps)[source]#

Convert explicit UTC strings to SPICE ET using the loaded leap-second kernel.

SPICE errors for missing kernels or invalid dates propagate; no approximate UTC/TDB conversion is substituted. A loaded LSK is normally required.

Parameters:

timestamps (Sequence[str])

Return type:

ndarray

space_pv_orbit.spice_engine.frame_rotation_matrices(from_frame, to_frame, ets)[source]#

Return rotations mapping column vectors from one SPICE frame to another.

CK attitude frames require the relevant CK, FK, SCLK and time kernels, with coverage at every requested epoch. An unavailable transformation raises the original SPICE error. These are position rotations, not 6D state transforms.

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

Parameters:
  • from_frame (str)

  • to_frame (str)

  • ets (ArrayLike)

Return type:

ndarray

space_pv_orbit.spice_engine.transform_vectors(vectors, from_frame, to_frame, ets)[source]#

Rotate a fixed vector or a time-aligned (n, 3) array using SPICE attitude.

Parameters:
  • vectors (ArrayLike)

  • from_frame (str)

  • to_frame (str)

  • ets (ArrayLike)

Return type:

ndarray

Live tracking#

Timestamped WGS84 states from real GP elements, with explicit model limits.

class space_pv_orbit.tracking.GroundTrackSample(timestamp: 'datetime', longitude_deg: 'float', latitude_deg: 'float', altitude_m: 'float', speed_m_s: 'float', velocity_gcrs_m_s: 'tuple[float, float, float]', illumination_fraction: 'float')[source]#
Parameters:
space_pv_orbit.tracking.omm_epoch(omm)[source]#

Parse GP EPOCH; timezone-free OMM epochs are UTC per the GP contract.

Parameters:

omm (dict[str, object])

Return type:

datetime

space_pv_orbit.tracking.propagate_ground_track(omm, times, *, max_element_age_days=14, sun_positions_m=None)[source]#

Propagate OMM with SGP4 and transform to WGS84 geodetic coordinates.

Velocity and its magnitude are geocentric GCRS inertial quantities, not ground speed. Altitude is height above the WGS84 ellipsoid. Illumination reuses the finite-Sun/spherical-Earth occultation model and Astropy GCRS Sun vectors; it is an estimate, not measured PV output. Optional Sun vectors must be GCRS metres at the exact supplied timestamps.

Reject naive/unsorted timestamps, SGP4 errors and element sets farther than max_element_age_days from any requested time (including future epochs). This cutoff is a display policy, not an orbital accuracy guarantee.

Parameters:
Return type:

list[GroundTrackSample]