Skip to content

API

Trajectory

Trajectory module.

This module defines the Trajectory abstract base class, which establishes the interface for all trajectory implementations in the PERSEO framework. A trajectory represents the path of a sensor through space over time, providing position, velocity, and acceleration vectors at arbitrary time points within its defined domain.

The Trajectory ABC specifies three core evaluation methods that all concrete implementations must provide:

  • position(time): Returns sensor position as (x, y, z) coordinates
  • velocity(time): Returns sensor velocity as (vx, vy, vz) components
  • acceleration(time): Returns sensor acceleration as (ax, ay, az) components

The abstract interface enables polymorphic use throughout PERSEO geometry computations, allowing different trajectory representations (e.g., cubic splines, Keplerian orbits, polynomial fits) to be used interchangeably in geocoding, pointing, and SAR processing.

Implementation tips

The concrete implementation of this class and its methods must support vectorized evaluation, with scalar times returning (3,) arrays and array times (N,) returning (N, 3) arrays. The domain property defines the valid time range [start, end]. Input query times can be checked to ensure they are within the domain bounds (using _is_time_valid) to avoid extrapolation outside the time domain.

Attributes

T module-attribute

Python
T = TypeVar('T', bound=np.generic)

__all__ module-attribute

Python
__all__ = ['Trajectory']

Classes

Trajectory

Bases: ABC, Generic[T]

Trajectory interface.

Attributes

domain abstractmethod property
Python
domain: tuple[T, T]

Trajectory time domain as a tuple of [start, end].

Methods:

position abstractmethod
Python
position(time: T | NDArray[T]) -> npt.NDArray[np.floating]

Retrieve position at given time.

Parameters:

Name Type Description Default
time T | NDArray[T]

evaluation time: scalar or array with shape (N,)

 required

Returns:

Type Description
NDArray[floating]

position with shape (3,) or (N, 3)
velocity abstractmethod
Python
velocity(time: T | NDArray[T]) -> npt.NDArray[np.floating]

Retrieve velocity at given time.

Parameters:

Name Type Description Default
time T | NDArray[T]

evaluation time: scalar or array with shape (N,)

 required

Returns:

Type Description
NDArray[floating]

velocity with shape (3,) or (N, 3)
acceleration abstractmethod
Python
acceleration(time: T | NDArray[T]) -> npt.NDArray[np.floating]

Retrieve acceleration at given time.

Parameters:

Name Type Description Default
time T | NDArray[T]

evaluation time: scalar or array with shape (N,)

 required

Returns:

Type Description
NDArray[floating]

acceleration with shape (3,) or (N, 3)
evaluate
Python
evaluate(time: T | NDArray[T]) -> tuple[npt.NDArray[np.floating], npt.NDArray[np.floating], npt.NDArray[np.floating]]

Evaluate position, velocity and acceleration at given time.

Parameters:

Name Type Description Default
time T | NDArray[T]

evaluation time: scalar or array with shape (N,)

 required

Returns:

Type Description
NDArray[floating]

position at given input times with shape (3,) or (N, 3)
NDArray[floating]

velocity at given input times with shape (3,) or (N, 3)
NDArray[floating]

acceleration at given input times with shape (3,) or (N, 3)

Cubic Spline Trajectory

Cubic Spline Trajectory module.

This module provides the CubicSplineTrajectory class, a concrete implementation of the Trajectory abstract base class that uses scipy's CubicSpline interpolator for continuous trajectory representation.

The CubicSplineTrajectory creates a twice-differentiable cubic spline that interpolates between recorded position and velocity state vectors. Extrapolation outside the time domain is not allowed.

The trajectory is initialized from three arrays of equal length:

  • times: Time axis (N,), either floats (relative times) or PreciseDateTime objects (absolute times)
  • positions: Position state vectors (N, 3) as [x, y, z] coordinates
  • velocities: Velocity state vectors (N, 3) as [vx, vy, vz] components

Attributes

T module-attribute

Python
T = TypeVar('T', bound=np.generic)

__all__ module-attribute

Python
__all__ = ['CubicSplineTrajectory']

Classes

CubicSplineTrajectory

Bases: Trajectory[T]

Trajectory based on a Cubic Spline interpolator.

Attributes

positions property
Python
positions: ndarray

Accessing trajectory positions vector.

velocities property
Python
velocities: ndarray

Accessing trajectory velocities vector.

times property
Python
times: ndarray

Accessing trajectory times vector.

domain property
Python
domain: tuple[T, T]

Trajectory time domain.

Methods:

__init__
Python
__init__(times: NDArray[T], positions: NDArray[floating], velocities: NDArray[floating]) -> None

Create a CubicSplineTrajectory from state vectors: times, positions and velocities.

Times must be of type T, either dates or floats.

Positions and velocities must be specified as (N, 3) arrays of floats.

CubicSplineTrajectory wraps scipy CubicSpline interpolator.

Extrapolation outside trajectory domain is not allowed.

Parameters:

Name Type Description Default
times NDArray[T]

time axis as numpy array of shape (N,)

 required
positions NDArray[floating]

positions as numpy array of shape (N, 3), with coordinates being x, y, z

 required
velocities NDArray[floating]

velocities as numpy array of shape (N, 3), with coordinates being x, y, z

 required
position
Python
position(time: T | NDArray[T]) -> npt.NDArray[np.floating]

Evaluate x, y, z position at given time.

Parameters:

Name Type Description Default
time T | NDArray[T]

time of the same type of the initialization times axis

 required

Returns:

Type Description
ndarray

position with shape (3,) or (N, 3) with coordinates being x, y, z
velocity
Python
velocity(time: T | NDArray[T]) -> npt.NDArray[np.floating]

Evaluate vx, vy, vz velocity at given time.

Parameters:

Name Type Description Default
time T | NDArray[T]

time of the same type of the initialization times axis

 required

Returns:

Type Description
ndarray

velocity with shape (3,) or (N, 3) with coordinates being x, y, z
acceleration
Python
acceleration(time: T | NDArray[T]) -> npt.NDArray[np.floating]

Evaluate ax, ay, az acceleration at given time.

Parameters:

Name Type Description Default
time T | NDArray[T]

time of the same type of the initialization times axis

 required

Returns:

Type Description
ndarray

acceleration with shape (3,) or (N, 3) with coordinates being x, y, z
evaluate
Python
evaluate(time: T | NDArray[T]) -> tuple[npt.NDArray[np.floating], npt.NDArray[np.floating], npt.NDArray[np.floating]]

Evaluate position, velocity and acceleration at given time.

Parameters:

Name Type Description Default
time T | NDArray[T]

evaluation time: scalar or array with shape (N,)

 required

Returns:

Type Description
NDArray[floating]

position at given input times with shape (3,) or (N, 3)
NDArray[floating]

velocity at given input times with shape (3,) or (N, 3)
NDArray[floating]

acceleration at given input times with shape (3,) or (N, 3)