gri-trajectory

Platform and emitter motion models for geolocation simulation. A trajectory defines how an entity moves through space over time; all trajectories implement a common Trajectory protocol providing position, velocity, and combined state queries at any time instant.

This package was factored out of gri-geosim so the motion models can be reused without pulling in the full simulation stack (it depends only on gri-nsepoch, gri-pos, and gri-utils, plus numpy/scipy/sgp4).

Install

uv add gri-trajectory

Import and use

from gri_trajectory import StationaryTrajectory, Sgp4Trajectory, WaypointTrajectory
from gri_pos import Pos

traj = StationaryTrajectory(Pos.LLA(38.0, -77.0, 100.0))
pos = traj.position_at(time)    # always the same Pos
vel = traj.velocity_at(time)    # [0, 0, 0]

Available trajectories

Composing segmented paths

The legs submodule builds a SegmentedTrajectory from kinematic primitives (Straight, Turn, Climb, Hold):

from gri_trajectory import SegmentedTrajectory
from gri_trajectory.legs import Straight, Turn
from gri_pos import Vel

start = Vel.LLA(38.0, -77.0, 0.0, 10.0, 0.0, 0.0)   # east at 10 m/s
racetrack = SegmentedTrajectory.from_legs(
    start,
    [Straight(20.0), Turn(180.0, radius_m=50.0),
     Straight(20.0), Turn(180.0, radius_m=50.0)],
)

The placement submodule provides builders for positioning a point over a ground origin by look angle (sky_point, by slant range or target altitude) -- compose with the orbit constructors for an overhead collector.

Trajectory protocol

def position_at(time: Time) -> Pos
def velocity_at(time: Time) -> NDArray[np.floating]   # shape (3,), ECEF m/s
def state_at(time: Time) -> tuple[Pos, NDArray[np.floating]]

state_at() returns position and velocity in one call, which is more efficient than separate queries for some trajectory types.

Notes

• All positions are ECEF (XYZ) in meters; velocities are ECEF m/s, shape (3,).
• Sgp4Trajectory converts TEME to ECEF internally.
• KeplerianTrajectory is a two-body approximation (no J2, drag, or third-body); for high fidelity use Sgp4Trajectory with real TLE data.
• Downstream, gri-geosim's Platform and Emitter accept a Pos directly and wrap it in a StationaryTrajectory internally.

License

MIT -- see LICENSE.