astrix.spatial.ray module

class Ray(dir_rel, origin_rel=array([[0., 0., 0.]]), frame=Frame(name=ECEF, static_rot=True, static_loc=True, has_ref=False, time_bounds=(Time invariant (n=1), Time invariant (n=1)), backend=numpy), time=Time invariant (n=1), check=True, backend=None)[source]

Bases: object

A ray defined by an origin point, direction vector, reference frame, and optional time.

Parameters:

  • dir_rel (Array) – Nx3 array of ray direction vectors in local frame. Need not be normalised. E.g., (1, 0, 0) is a ray pointing along axis 1 of reference frame.

  • origin_rel (Array) – 1x3 or Nx3 array defining the ray origin(s) in local frame (meters). Typically (0,0,0) for camera reference frames, or ECEF coordinates for ECEF frame rays.

  • frame (Frame, optional) – Reference frame for the ray origin and direction.

  • time (Time, optional) – Time object associated with the rays. Must be same length as origin if provided. Defaults to TIME_INVARIANT.

  • check (bool, optional) – If True (default), validate non-zero direction vectors; disable for JIT paths.

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

Notes

  • For calculating metrics (e.g. az/el), the axis are assumed (1) forward, (2) right, (3) down (FRD frame).

  • Although stored in local coordiantes, rays are globally defined by their reference frame.

  • Monotonically increasing time is required for interpolation. But to prevent data-dependent control flow,

    this is not checked on initialization. Use Time.is_increasing to check if needed.

Examples

>>> from astrix import Point, Ray
>>> origin = Point([0.0, 0.0, 0.0])
>>> target = Point([1.0, 0.0, 0.0])
>>> ray = Ray.from_points(target, origin)
>>> ray.unit_rel
array([[1., 0., 0.]])
classmethod from_az_el(az_el, frame=Frame(name=ECEF, static_rot=True, static_loc=True, has_ref=False, time_bounds=(Time invariant (n=1), Time invariant (n=1)), backend=numpy), time=Time invariant (n=1), origin_rel=array([[0., 0., 0.]]), check=True, backend=None)[source]

Create a Ray object from origin points and heading/elevation angles.

Parameters:

  • az_el (Array) – Nx2 array of azimuth and elevation angles in degrees, relative to the reference frame.

  • frame (Frame, optional) – Reference frame for the ray origin and direction. Defaults to ECEF frame.

  • time (Time, optional) – Time object associated with the rays.

  • origin_rel (Array, optional) – Nx3 array of ray origin points in local frame coordinates. Defaults to (0,0,0), which is the reference frame origin.

  • check (bool, optional) – Whether to check input arrays for validity (not JIT compatible). Defaults to True.

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

Return type:

Ray

classmethod from_camera(pixel, camera, frame, backend=None)[source]

Create a Ray object from pixel coordinates and a camera model.

Parameters:

  • pixel (Pixel) – Pixel object defining the pixel coordinates and optional time.

  • camera (CameraLike) – Camera model defining the camera parameters and orientation.

  • frame (Frame) – Reference frame for the ray origin and direction.

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

Returns:

Ray object defined by the pixel coordinates and camera model.

Return type:

Ray

classmethod from_points(endpoint, origin, time=Time invariant (n=1), check=True, backend=None)[source]

Create a Ray object from origin and endpoint arrays in ECEF frame.

Parameters:

  • endpoint (Point) – End points (ECEF coordinates). Must be length N.

  • origin (Point) – Origin points (ECEF coordinates). Must be length N or 1.

  • time (Time, optional) – Time object associated with the rays. If TIME_INVARIANT, time is inferred from endpoint or origin when available.

  • check (bool, optional) – If True, validate geometry (non-zero directions). Disable for JIT compatibility. Defaults to True.

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

Returns:

Ray object defined by the origin and direction from origin to endpoint.

Return type:

Ray

classmethod from_target_frame(target, frame, check_bounds=True, backend=None)[source]

Create a Ray object from a reference frame and target point(s).

Parameters:

  • target (Point) – Target point(s) in ECEF coordinates. Must be length N or 1.

  • frame (Frame) – Reference frame for the ray origin and direction.

  • check_bounds (bool, optional) – If True, ensure target times fall within frame time ranges.

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

Returns:

Ray object defined by the frame origin and direction to the target point(s).

Return type:

Ray

convert_to(backend)[source]

Convert the Ray object to a different backend.

Return type:

Ray

Parameters:

backend (str | Any | None)

correct_refraction(alt=100000.0)[source]

Apply atmospheric refraction correction to the Ray object using Bennett’s formula. Altitude sets the exponential scale height (metres) for the correction.

Returns:

New Ray object with refraction-corrected direction vectors.

Return type:

Ray

Parameters:

alt (float)

Notes

  • Assumes standard atmospheric conditions.

interp(time, check_bounds=True)[source]

Interpolate the Ray origin and direction to the given times.

Parameters:

  • time (Time) – Times to interpolate to.

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

Returns:

Interpolated Ray object at the given times.

Return type:

Ray

project_to_cam(camera)[source]

Project the Ray object to pixel coordinates using a camera model.

Parameters:

camera (CameraLike) – Camera model defining the camera parameters and orientation.

Returns:

Pixel object defining the pixel coordinates and associated time.

Return type:

Pixel

Notes

  • The Ray must be defined in the same reference frame as the camera.

  • Rays that do not intersect the image plane will result in NaN pixel coordinates.

replace_frame(frame)[source]

Replace the reference frame of the Ray without changing origin or direction. Not a transformation, but direct replacement. Use with caution.

Parameters:

frame (Frame) – New reference frame for the ray.

Returns:

Ray object with the new reference frame.

Return type:

Ray

to_ecef()[source]

Convert the Ray object to ECEF coordinates.

Return type:

Ray

to_frame(frame)[source]

Convert the Ray object to a different reference frame.

Parameters:

frame (Frame) – Reference frame to convert the ray to.

Returns:

Ray object defined in the new reference frame.

Return type:

Ray

to_ned()[source]

Convert the Ray object to a local NED frame at the ray origin.

Return type:

Ray

property az_el

Return the azimuth and elevation angles from the forward axis in degrees.

property backend: str

Get the name of the array backend in use (e.g., ‘numpy’, ‘jax’).

property frame: Frame

Get the reference Frame of the ray.

property has_time: bool

Check if the Ray has associated Time.

property origin_points: Point

Get the ray origin point(s) as ECEF. Note: this involves a frame transformation. For repeated access, recommend converting the Ray to ECEF frame first using to_ecef().

property origin_rel: Any

Get the ray origin point(s) in the local frame coordinates. Typically zero for camera reference frames, or ECEF coordinates for ECEF frame rays.

property time: Time

Get the associated Time object, if any.

property total_angle: Any

Return the total angle from the forward axis in degrees.

property unit_ecef: Any

Get the unit direction vector(s) of the ray in ECEF frame. Note: this involves a frame transformation. For repeated access, recommend converting the Ray to ECEF frame first using to_ecef().

property unit_rel: Any

Get the unit direction vector(s) of the ray in the local frame coordinates.