astrix.spatial.location module

class Acceleration(vec, time, _xp)[source]

Bases: object

Acceleration vector(s) in ECEF coordinates (ax, ay, az) in m/s². Associated with a Time object for the time instances of the accelerations. Internal use only, typically created from Path objects. No data validation is performed.

Parameters:

  • vec (Array) – Acceleration vectors in ECEF coordinates (ax, ay, az) in m/s². Shape (n, 3).

  • time (Time) – Time object associated with the accelerations. Length must match number of acceleration vectors.

  • backend (BackendArg, optional) – Array backend to use (numpy, jax, etc.). Defaults to numpy.

  • _xp (Any)

classmethod from_data(vec, time, backend=None)[source]

Create an Acceleration object from acceleration vector array and Time object.

Return type:

Acceleration

Parameters:

  • vec (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str])

  • time (Time)

  • backend (str | Any | None)

convert_to(backend)[source]

Convert the Acceleration object to a different backend.

Return type:

Acceleration

Parameters:

backend (str | Any | None)

interp(time, method='linear', check_bounds=True)[source]

Interpolate the Acceleration to the given times using the specified method. Currently only ‘linear’ interpolation is supported.

Return type:

Acceleration

Parameters:

  • time (Time)

  • method (str)

  • check_bounds (bool)

rotate(rot)[source]
Return type:

Acceleration

Parameters:

rot (Rotation)

property backend: str
property magnitude: Any

Get the acceleration magnitude in m/s².

time: Time
property unit: Any

Get the unit acceleration vector.

vec: Any
class Location[source]

Bases: ABC

Abstract base class for location objects (Point, Path). ‘interp’ function is required for integration with other modules.

abstractmethod convert_to(backend)[source]
Return type:

Location

Parameters:

backend (str | Any | None)

property backend: str
property ecef: Any
property geodet: Any
abstract property is_singular: bool
property time: Time
class Path(point, backend=None)[source]

Bases: Location

Path of multiple Point objects with associated Time. Enables interpolation between points over time and calculation of velocity. Must have at least 2 points with associated Time.

Parameters:

  • point (Point | list of Point) – Point object or list of Point objects with associated Time. If a list is provided, all Points must have the same backend and associated Time.

  • backend (BackendArg, optional) – Array backend to use (numpy, jax, etc.). Defaults to numpy.

Examples

Instantiating a Path from a list of Points:

>>> from astrix import Point, Time, Path
>>> from datetime import datetime, timezone
>>> times = Time.from_datetime([
...     datetime(2025, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
...     datetime(2025, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
...     datetime(2025, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
... ])
>>> path = Path([
...     Point([1, 2, 0], time=times[0]),
...     Point([2, 3.8, 0.4], time=times[1]),
...     Point([3, 6.0, 1], time=times[2]),
... ])

Interpolate Path and get velocity:

>>> t_interp = Time.from_datetime(
...     datetime(2025, 1, 1, 12, 0, 1, 500000, tzinfo=timezone.utc)
... )
>>> path.interp(t_interp).ecef
array([[2.5, 4.9, 0.7]])
>>> vel = path.vel.interp(t_interp)
>>> vel.magnitude
array([2.48997992])
convert_to(backend)[source]

Convert the Path object to a different backend.

Return type:

Path

Parameters:

backend (str | Any | None)

downsample(dt_max)[source]

Downsample the Path to a maximum time step of dt_max seconds. Note: This function is not JIT-compatible due to data validation checks.

Return type:

Path

Parameters:

dt_max (float)

interp(time, method='linear', check_bounds=True)[source]

Interpolate the Path to the given times using the specified method.

Parameters:

  • time (Time) – Times to interpolate to.

  • method (str, optional) – Interpolation method. Currently only ‘linear’ is supported. Defaults to ‘linear’.

  • check_bounds (bool, optional) – Whether to check if the interpolation times are within the path time bounds. Defaults to True.

Returns:

Interpolated Point object at the given times.

Return type:

Point

time_at_alt(alt)[source]

Find the times when the Path crosses the given altitude (in metres). Uses linear interpolation between points to find the crossing times. Note: This function is not JIT-compatible due to data validation checks.

Return type:

Time

Parameters:

alt (float)

truncate(start_time=None, end_time=None)[source]

Truncate the Path to the given start and end times. If start_time or end_time is None, the Path is truncated to the start or end of the Path respectively.

Note: This function is not JIT-compatible due to data validation checks.

Return type:

Path

Parameters:

  • start_time (Time | None)

  • end_time (Time | None)

property acc: Acceleration

Calculate the acceleration from the Path using central differences.

property end_time: Time

Get the end time of the Path.

property is_singular: bool

Check if the Path object represents a single point. Always False for Path objects.

property points: Point

Get the list of Point objects that make up the Path.

property start_time: Time

Get the start time of the Path.

property vel: Velocity

Calculate the velocity from the Path using central differences.

class Point(ecef, time=Time invariant (n=1), backend=None)[source]

Bases: Location

Point(s) in ECEF coordinates, stored as (x, y, z) in metres. Can represent a single point or multiple points, and can be associated with a Time object for time instances of the points.

Parameters:

  • ecef (Array) – ECEF coordinates as (x, y, z) in metres. Shape (3,) or (1,3) for single points, (n, 3) for multiple points.

  • time (Time, optional) – Time object associated with the points. If provided, the length of time must match the number of points. Defaults to TIME_INVARIANT for static points.

  • backend (BackendArg, optional) – Array backend to use (numpy, jax, etc.). Defaults to numpy.

Examples

Single static point:

>>> from astrix import Point
>>> p1 = Point([-5047162.4, 2568329.79, -2924521.17])  # Brisbane ECEF (m)
>>> p1.geodet  # Convert to geodetic (lat, lon, alt)
array([[-27.47, 153.03, 0.0]])
>>> p2 = Point.from_geodet([-27.47, 153.03, 0])
>>> p2.ecef
array([[-5047162.4, 2568329.79, -2924521.17]])

Multiple static points:

>>> pts = Point([
...     [-5047162.4, 2568329.79, -2924521.17],  # Brisbane
...     [-2694045.0, -4293642.0, 3857878.0],  # San Francisco
... ])
>>> pt_bris = pts[0]
>>> len(pts)
2

Dynamic point with time:

>>> from datetime import datetime, timezone
>>> from astrix import Time
>>> times = Time.from_datetime([
...     datetime(2021, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
...     datetime(2021, 1, 1, 13, 0, 0, tzinfo=timezone.utc),
... ])
>>> pts_time = Point([
...     [-5047162.4, 2568329.79, -2924521.17],
...     [-2694045.0, -4293642.0, 3857878.0],
... ], time=times)
>>> pts_time.has_time
True
>>> pts_time.is_singular
False

Notes

  • When associating a Time object, the length of the Time must match the number of points.

  • Use Path objects for interpolating between multiple points over time.

classmethod from_geodet(geodet, time=Time invariant (n=1), backend=None)[source]

Create a Point object from geodetic coordinates (lat, lon, alt). Latitude and longitude are in degrees, altitude is in meters.

Return type:

Point

Parameters:

  • geodet (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str])

  • time (Time)

  • backend (str | Any | None)

classmethod from_list(points)[source]

Create a Point object from a list of Point objects.

Return type:

Point

Parameters:

points (list[Point])

convert_to(backend)[source]

Convert the Point object to a different backend.

Return type:

Point

Parameters:

backend (str | Any | None)

property has_time: bool

Check if the Point has associated Time.

property is_singular: bool

Check if the Point object represents a single point.

class Velocity(vec, time, _xp)[source]

Bases: object

Velocity vector(s) in ECEF coordinates (vx, vy, vz) in m/s. Associated with a Time object for the time instances of the velocities. Internal use only, typically created from Path objects. No data validation is performed.

Parameters:

  • vec (Array) – Velocity vectors in ECEF coordinates (vx, vy, vz) in m/s. Shape (n, 3).

  • time (Time) – Time object associated with the velocities. Length must match number of velocity vectors.

  • backend (BackendArg, optional) – Array backend to use (numpy, jax, etc.). Defaults to numpy.

  • _xp (Any)

Examples

Velocity objects are typically created from Path objects.

>>> from astrix import Point, Time, Path
>>> from datetime import datetime, timezone
>>> times = Time.from_datetime([
...     datetime(2025, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
...     datetime(2025, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
...     datetime(2025, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
... ])
>>> path = Path([
...     Point([1, 2, 0], time=times[0]),
...     Point([2, 3.8, 0.4], time=times[1]),
...     Point([3, 6.0, 1], time=times[2]),
... ])
>>> vel = path.vel
>>> vel.magnitude
array([1.91049732, 2.29128785, 2.6925824])
classmethod from_data(vec, time, backend=None)[source]

Create a Velocity object from velocity vector array and Time object.

Return type:

Velocity

Parameters:

  • vec (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str])

  • time (Time)

  • backend (str | Any | None)

convert_to(backend)[source]

Convert the Velocity object to a different backend.

Return type:

Velocity

Parameters:

backend (str | Any | None)

interp(time, method='linear', check_bounds=True)[source]

Interpolate the Velocity to the given times using the specified method. Currently only ‘linear’ interpolation is supported.

Return type:

Velocity

Parameters:

  • time (Time)

  • method (str)

  • check_bounds (bool)

rotate(rot)[source]
Return type:

Velocity

Parameters:

rot (Rotation)

property acc: Acceleration

Calculate the acceleration from the velocity using central differences.

property backend: str
property magnitude: Any

Get the velocity magnitude in m/s.

time: Time
property unit: Any

Get the unit velocity vector.

vec: Any