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).

Documentation

The wheel ships its documentation inside the package, in gri_trajectory/docs/, so it is available wherever the package is installed:

• overview.md -- the protocol, each trajectory, legs, and traps
• api_summary.md -- every public class, method, and signature (generated)

Print the directory with python -c "import gri_trajectory, pathlib; print(pathlib.Path(gri_trajectory.__file__).parent / 'docs')". Every example in those files is run by the test suite.

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(dt)      # dt: seconds from traj.epoch_unix_s
vel = traj.velocity_at(dt)      # [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

epoch_unix_s: float                                   # absolute time of dt = 0
def position_at(dt: float = 0.0) -> Pos
def velocity_at(dt: float = 0.0) -> NDArray[np.floating]   # shape (3,), ECEF m/s
def state_at(dt: float = 0.0) -> Vel                  # position and velocity

dt is seconds relative to the trajectory's own epoch_unix_s, not an absolute time: convert with dt = unix_s - traj.epoch_unix_s. state_at() returns both in one call, which is cheaper 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.