Frame#

class spacekernel.frames.Frame#

Bases: object

Abstract base class for reference frames and coordinate systems.

Manages frame registration, provides transformation graph utilities, and enables transformation of vectors between frames.

Frame.__class_getitem__(cls, str item)

Get a registered Frame instance by name.

Frame.__hash__(self)

Return a hash for the Frame instance.

Frame.is_frame(cls, str item)

Check if a frame with the given name is registered.

Frame.name

Frame.name: str Get the registered name of this frame.

Frame.get_route(cls, source, target)

Find a sequence of frames (route) from source to target frame.

Frame.transforms(self)

Return the dictionary of direct transforms from this frame.

Frame.transform_to(self, frame, time, r, v)

Transform position and velocity vectors to another frame.

Frame.register_transform(self, ...)

Register a direct transformation from this frame to a target frame.

Frame.remove_transform(self, Frame target_frame)

Remove the direct transformation from this frame to a target frame.
classmethod Frame.__class_getitem__(cls, str item: str) → Frame#

Get a registered Frame instance by name.

Parameters:
itemstr

The name of the frame (case-insensitive).

Returns:
Frame

The Frame instance associated with the given name.

Raises:
KeyError

If no Frame with the given name is registered.

Frame.__hash__(self) → int#

Return a hash for the Frame instance.

Returns:
int

The hash value.

classmethod Frame.is_frame(cls, str item: str) → bool#

Check if a frame with the given name is registered.

Parameters:
itemstr

Name of the frame.

Returns:
bool

True if the frame is registered, False otherwise.

Frame.name()#

Frame.name: str Get the registered name of this frame.

Returns:
str

The name of the frame, or ‘Unnamed’ if not registered.

classmethod Frame.get_route(cls, source: Frame | str, target: Frame | str) → list[Frame]#

Find a sequence of frames (route) from source to target frame.

Parameters:
sourceFrame or str

The starting frame or its name.

targetFrame or str

The target frame or its name.

Returns:
list of Frame

The list of frames forming the transformation path.

Raises:
ValueError

If no route is found between source and target frames.

Frame.transforms(self) → dict[Frame, Callable]#

Return the dictionary of direct transforms from this frame.

Returns:
dict of {Frame: Callable}

Keys are adjacent frames; values are functions to transform coordinates from this frame to the adjacent frame.

Frame.transform_to(self, frame: Frame | str, time: DatetimeLike, r: ndarray[double], v: ndarray[double]) → tuple[ndarray, 2]#

Transform position and velocity vectors to another frame.

Parameters:
frameFrame or str

Target frame or its name.

timeDatetimeLike

Time of the transformation.

rndarray

Position vector(s) in this frame.

vndarray

Velocity vector(s) in this frame.

Returns:
tuple of ndarray, 2

Transformed position and velocity vectors in the target frame.

Raises:
ValueError

If no route is found between the frames.

Frame.register_transform(self, Frame target_frame: Frame, transform: Callable) → None#

Register a direct transformation from this frame to a target frame.

Parameters:
target_frameFrame

The frame to which the transformation applies.

transformCallable

The transformation function to convert coordinates from this frame to the target frame. The callable should have the signature (time: Time, position: ndarray[(N, 3)], velocity: ndarray[(N, 3)]).

Returns:
None

Notes

  • Overwrites any existing transformation to the same target frame.

  • Useful for dynamically adding or replacing frame transformations at runtime.

Frame.remove_transform(self, Frame target_frame: Frame) → None#

Remove the direct transformation from this frame to a target frame.

Parameters:
target_frameFrame

The frame whose transformation should be removed.

Returns:
None
Raises:
KeyError

If no transformation to the target frame exists.

Notes

  • After removal, transformations to the target frame must be re-registered to be available again.