Karana.Frame

Karana.Frame#

Classes and modules related to the Frames layer.

Classes#

`ChainedFrameToFrame`	FrameToFrame class connecting arbitrary oframe/pframe Frame pairs
`EdgeFrameToFrame`	Base class for an edge FrameToFrame in the frames tree
`Frame`
`FrameContainer`
`FrameDumpOptions`
`FrameToFrame`	Represents a connection between two frames.
`OrientedChainedFrameToFrame`
`PrescribedFrameToFrame`	Base class for an edge FrameToFrame in the frames tree
`SpiceFrame`
`SpiceFrameToFrame`	Represents a connection between two frames.

Package Contents#

class Karana.Frame.ChainedFrameToFrame#

Bases: FrameToFrame

FrameToFrame class connecting arbitrary oframe/pframe Frame pairs

The oframe and pframe frames can be located anywhere in the frames tree.

See Coordinate Frames for more discussion on the frames layer.

class Karana.Frame.EdgeFrameToFrame#

Bases: FrameToFrame

Base class for an edge FrameToFrame in the frames tree

See Coordinate Frames for more discussion on the frames layer.

class Karana.Frame.Frame(name: str, fc: FrameContainer)#

Bases: Karana.Core.Base

static create(name: str, fc: FrameContainer) → Frame#

Creates a new frame with the given name. :param name:

The name of the frame to create.

Parameters:

fc –

The parent frames container

Returns:

The created frame.

container() → FrameContainer#: Get the reference to the container of the frame. :returns: The reference to the container of the frame.

dumpFrameTree(prefix: str = '', options: FrameDumpOptions = ...) → None#: Display the frame tree. The contents of the options struct can be

used to control the content and verbosity of the displayed output.

@param prefix the prefix for each output line @param options output content options

edge() → EdgeFrameToFrame#: Get the edge associated with this frame. :returns: The edge f2f.

frameToFrame(frame: Frame) → ChainedFrameToFrame#

Create a chained f2f between this frame and the target frame. This frame will be the o-frame and the target frame will become the p-frame. :param frame: The target frame. This will be the p-frame in the chained

frame to frame.

Returns:: The ChainedFrameToFrame connecting this frame (o-frame) and the target frame (p-frame).

getAncestor(other: Frame) → Frame#

Get the ancestor of this frame and another frame. :param other: The other frame.

Returns:: The common ancestor.

isAncestorOf(arg0: Frame, arg1: bool) → bool#

Check if this frame is an ancestor of another frame. :param other: The other frame to check against. :param strict: if false, a frame can be its own ancestor

Returns:: True if this frame is an ancestor of the other frame, false otherwise.

orientedFrameToFrame(frame: Frame) → OrientedChainedFrameToFrame#

Create an oriented chained f2f between this frame and the target frame. This frame will be the o-frame and the target frame will become the p-frame.

Note that it up to the user to ensure that the pframe is a true: descendant of the oframe. If not, there will be errors when trying to use this oriented chain.

Parameters:: frame – The target frame. This will be the p-frame in the chained frame to frame.
Returns:: The OrientedChainedFrameToFrame connecting this frame (o-frame) and the target frame (p-frame).

parent() → Frame#: Get the parent frame. :returns: The parent frame.

class Karana.Frame.FrameContainer(name: str)#

Bases: Karana.Core.LockingBase

static create(name: str) → FrameContainer#

Create a FrameContainer. :param root_frame_name: Name for the root frame

Returns:: The frame container.

edgeFrameToFrames() → list[EdgeFrameToFrame]#

Return a vector of all the EdgeFrameToFrames in the FrameContainer.

Returns:: List of all the edge elements.

frames() → list[Frame]#

Return a vector of all the frames in the FrameContainer.

Returns:: List of all the frame elements.

getAncestor(frame1: Frame, frame2: Frame) → Frame#

Gets the common ancestor of two frames. :param frame1: The first frame. :param frame2: The second frame.

Returns:: The common ancestor frame.

getEphemerisTime() → float#

Return the current ephemeris time

The ephemeris time is needed by Spice frames

Returns:: the current ephemeris time

isAncestorOf(arg0: Frame, arg1: Frame, arg2: bool) → bool#

Checks if one frame is an ancestor of another. :param oframe: The potential ancestor frame. :param pframe: The potential descendant frame. :param strict: If false, a frame can be its own ancestor

Returns:: True if oframe is an ancestor of pframe, false otherwise.

lookupFrame(name: str) → list[Frame]#

Return a vector of all Frames with the given name. :param name: name of the Frame instances to look up

Returns:: A vector of all the Frames with the given name.

root() → Frame#: Returns the root frame of the tree. :returns: The root frame.

setEphemerisTime(arg0: SupportsFloat) → None#

Set the ephemeris time

The ephemeris time is needed by Spice frames

Parameters:: ephemeris_time – the ephemeris time

showFramesGraph(*, port: int = 29623, label_map: collections.abc.Mapping[str | int, str] | None = None, title: str = 'Frame layer', buttons: list[Button] | None = None, coloring: Literal['type', 'valency'] = 'type', chains: bool = False, launch_client: bool = False) → GraphServer#

Visualize the frame tree as a graph.

self: FrameContainer
The frame container whose frames to display

port: int
Port to bind to. Use 0 to pick an arbitrary open port. Defaults to 29623.

label_map: Mapping[str | int, str] | None
Map indicating labels to use for frames in the visualization. Keys may be either frame ids or names. Frames without a label will be assigned a unique number as their label.

title: str
Title of the graph. Defaults to “Frame layer”.

buttons: list[Button]
Extra buttons to display, triggering callbacks on press.

coloring: Literal[“type”, “valency”]

How to color the nodes and edges in the visualization:
type: Color based on the type of the Frame or FrameToFrame valency: Color nodes based on number of connecting edges

Defaults to the “type” coloring.

chains: bool
Whether to also show edges for ChainedFrameToFrames. Defaults to False.

launch_client: bool
Automatically open the frontend in a local browser tab. Defaults to False.

GraphServer
Handle to the web server hosting the graph visualization

class Karana.Frame.FrameDumpOptions(type_string: bool = True, edge_type: bool = False, healthy_status: bool = False, id: bool = False)#

edge_ref_count: bool#

edge_type: bool#

healthy_status: bool#

id: bool#

ref_count: bool#

type_string: bool#

__repr__() → str#

class Karana.Frame.FrameToFrame#

Bases: Karana.Core.LockingBase

Represents a connection between two frames.

This class handles the transformation, velocity, and acceleration between two frames.

See Coordinate Frames for more discussion on the frames layer.

oframe() → Frame#: Get the oframe of the FrameToFrame. :returns: oframe.

oframeDerivRelRates() → Annotated[numpy.typing.NDArray[numpy.float64], [6, 1]]#

Return the transform rates for the oframe to pframe relative velocity

This method converts the spatial velocity of the pframe with respect to the oframe, into the minimal coordinate rates 6-vector for the relative transform. The minimal coordinates are the Karana::Math::RotationVector representation of the attitude part, and

the

relative position of the linear part.

Returns:: The coordinate rates as a 6-vector

pframe() → Frame#: Get the pframe of the FrameToFrame. :returns: pframe.

pframeObservedRelSpAccel() → Karana.Math.SpatialVector#

Return the pframe observed relative spatial acceleration between the oframe and pframe.

This is the spatial acceleration of the pframe with respect to the oframe, as observed from the pframe, and represented in pframe.

The resulting linear accel, p_a(o,p) is the derivative of p_R_o * o_v(o,p) vector, i.e. the time derivative of the pframe coordinate representation of the o_v(o,p) oframe/pframe translational velocity.

p_a(o,p) = p_R_o * [ o_a(o,p) + o_v(o,p) x w(o,p) ]

Note that the returned value is NOT p_a(p,o), which corresponds to f_to_f(pframe, oframe).relSpAccel(). To get p_a(p,o) you need to switch the roles of oframe and pframe and simply call pframe.relSpAccel(oframe).

Returns:: The pframe observed spatial acceleration vector.

pframeObservedRelSpVel() → Karana.Math.SpatialVector#

Return the pframe observed relative spatial velocity between the oframe and pframe.

This is the spatial velocity of the pframe with respect to the oframe, as observed from the pframe, and represented in the pframe.

The resulting linear velocity, p_v(o,p) is the derivative of p_l(o,p) = p_R_o * o_l(o,p) vector, i.e. the time derivative of the pframe coordinate representation of the oframe/pframe translational vector. Thus

p_v(o,p) = p_R_o * [ o_v(o,p) + o_l(o,p) x w(o,p) ]

Note that the returned value is NOT p_v(p,o) that corresponds to f_to_f(pframe, oframe).relSpVel() where the roles of oframe and pframe are switched, and the value would be the velocity of oframe with respect to pframe.

Returns:: The pframe observed spatial velocity vector.

relSpAccel() → Karana.Math.SpatialVector#

Get the relative acceleration between the oframe and pframe.

This is the spatial acceleration of the pframe with respect to the oframe, as observed from the oframe, and represented in the oframe.

The resulting linear accel, o_a(o,p) is the derivative of o_v(o,p) velocity, i.e. the time derivative of the oframe coordinate representation of the o_v(o,p) oframe/pframe translational velocity. The actual work is done by the accel cache callback, and this is a simple public wrapper for it.

Returns:: The spatial acceleration vector.

relSpVel() → Karana.Math.SpatialVector#

Get the relative velocity between the oframe and pframe.

This is the spatial velocity of the pframe with respect to the oframe, as observed from the oframe, and represented in the oframe.

The resulting linear velocity, o_v(o,p) is the derivative of o_l(o,p) vector, i.e. the time derivative of the oframe coordinate representation of the oframe/pframe translational vector. The actual work is done by the velocity cache callback, and this is a simple public wrapper for it.

Returns:: The spatial velocity vector.

relTransform() → Karana.Math.HomTran#

Get the relative homogeneous transformation between the oframe and pframe.

The actual work is done by the transform cache callback, and this is a simple public wrapper for it.

Returns:: The homogeneous transformation.

solveSpAccel(arg0: FrameToFrame, arg1: FrameToFrame, arg2: Karana.Math.SpatialVector) → Karana.Math.SpatialVector#

Solve for sub f_to_f’s relative spatial acceleration needed to achieve desired relative spatial acceleration

Denoting this as the A/C f_to_f, and the desired relative spatial acceleration as A, this method solves for the relative spatial acceleration required of the sub_f_to_f (which is assumed to be in the A/C path). It is required that sub_f_to_f be at one end or the other of the A/C f_to_f, i.e. it’s oframe is A, or that its pframe is C. The sub_f_to_f thus splits the A/C f_to_f path in two parts. The other_f_to_f is the f_to_f for the remaining half.

We pass in extra f_to_f’s to avoid the cost of lookups within this method.

Parameters:

sub_f_to_f – the sub f_to_f whose required spatial acceleration is to be computed
other_f_to_f – the f_to_f for the segment of oframe/pframe not covered by sub_f_to_f
A – the desired relative spatial acceleration for this f_to_f

Returns:

the relative spatial acceleration required for the sub f_to_f

solveSpVel(arg0: FrameToFrame, arg1: FrameToFrame, arg2: Karana.Math.SpatialVector) → Karana.Math.SpatialVector#

Solve for sub f_to_f’s relative spatial velocity needed to achieve desired relative spatial velocity

Denoting this as the A/C f_to_f, and the desired relative spatial velocity as V, this method solves for the relative spatial velocity required of the sub_f_to_f (which is assumed to be in the A/C path). It is required that sub_f_to_f be at one end or the other of the A/C f_to_f, i.e. it’s oframe is A, or that its pframe is C. The sub_f_to_f thus splits the A/C f_to_f path in two parts. The other_f_to_f is the f_to_f for the remaining half.

We pass in extra f_to_f’s to avoid the cost of lookups within this method.

Parameters:

sub_f_to_f – the sub f_to_f whose required spatial velocity is to be computed
other_f_to_f – the f_to_f for the segment of oframe/pframe not covered by sub_f_to_f
V – the desired relative spatial velocity for this f_to_f

Returns:

the relative spatial velocity required for the sub f_to_f

solveTransform(arg0: FrameToFrame, arg1: Karana.Math.HomTran) → Karana.Math.HomTran#

Solve for sub f_to_f’s transform needed to achieve desired relative transform

Denoting this as the A/C f_to_f, and the desired relative transform as desired_T, this method solves for the relative transform required of the sub_f_to_f (which is assumed to be in the A/C path). It is required that sub_f_to_f be at one end or the other of the A/C f_to_f, i.e. it’s oframe is A, or that its pframe is C.

Parameters:

sub_f_to_f – the sub f_to_f whose required transform is to be computed
T – the desired relative transform for this f_to_f

Returns:

the relative transform required for the sub f_to_f

subchainOrientation(arg0: FrameToFrame) → bool | None#

Check the relationship of a sub-chain FrameToFrame’s path with respect to the overall FrameToFrame path.

Return true if the sub-chain FrameToFrame’s path is contained in the FrameToFrame’s oframe/pframe path and oriented with the path, false if it has opposed orientation, and nullopt if it is not fully contained in the path.

Parameters:: sub_f_to_f – the sub-path FrameToFrame’s orientation to check
Returns:: null if not on path, and true if on the path and oriented

toOframeObserved(arg0: Annotated[numpy.typing.ArrayLike, numpy.float64, [3, 1]], arg1: Annotated[numpy.typing.ArrayLike, numpy.float64, [3, 1]]) → Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]#

Transform the 3-vector pframe observed derivative to oframe observed derivative

This method converts the pframe observed time derivative of a 3-vector into the oframe observed time derivative.

Usage: This method is used to change the observing frame for a 3-vector derivative to a new one. To do this, create a f_to_f FrameToFrame from the new observing frame to the original observing frame for the vector derivative, and pass in the vector, x, and its time derivative, xdot, as arguments to f_to_f.toOframeObserved(x, xdot). The returned value will be the time derivative vector in the new observing frame.

Parameters:

pframe_x – the pframe representation of the 3-vector whose time derivative is being taken
pframe_x_dot – the (original) pframe observed time derivative of pframe_x

Returns:

the (new) oframe observed time derivative of pframe_x

toPframeRelativeSpAccel(arg0: Karana.Math.SpatialVector) → Karana.Math.SpatialVector#

Transform the provided oframe relative spatial accel into pframe relative value

For this f_to_f, convert the hypothetical oframe relative spatial accel for the f_to_f into the corresponding pframe relative spatial accel as if we are taking the derivative of the pframe to the oframe vector quantities as observed from the pframe, and represented in the pframe. This method assumes that the relative transform and spatial velocity for the f_to_f are valid and uses them.

Note that when the hypothetical input spatial accel is the true value we will have the following equivalence:

toPframeRelativeSpAccel(relSpAccel()) ==

pframe()->frameToFrame(oframe())->relSpAccel()

Note that this method changes the acceleration vector from being oframe/pframe to being pframe/oframe, and thus is doing more than just changing the observing frame./

This method is handy for multibody state initialization, where we are trying to initialize the multibody acceleration coordinates based on some physical requirements on body/node spatial acceleration. This method can be use to convert these requirements into requirements on the relative spatial acceleration on hinges, and at which point the hinge fitUdot() method can be used to compute the Udot acceleration coordinates for the hinge that meet the requirements.

Parameters:: oframe_a – the hypothetical oframe relative spatial accel
Returns:: the corresponding pframe relative spatial accel

toPframeRelativeSpVel(arg0: Karana.Math.SpatialVector) → Karana.Math.SpatialVector#

Transform the hypothetical oframe deriv relative spatial velocity into pframe relative value

For this f_to_f, convert the hypothetical oframe derivative relative spatial velocity for the f_to_f into the corresponding pframe relative spatial velocity, i.e the derivative of the reversed pframe to the oframe vector quantities as observed from the pframe, and representing in the pframe. Thus this is computing B_alpha(B,A) from A_alpha(A, B). This method assumes that the relative transform for the f_to_f is valid and uses it.

Note that when the hypothetical input oframe relative spatial velocity is the true value we will have the following equivalence:

toPframeRelativeSpVel(relSpVel()) == pframe()->frameToFrame(oframe())->relSpVel()

Note that this method changes the velocity vector from being oframe/pframe to being pframe/oframe, and thus is doing more than just changing the observing frame./

This method is handy for state initialization, where we are trying to initialize the multibody velocity coordinates based on some physical requirements on body/node spatial velocities. This method can be use to convert these requirements into requirements on the relative spatial velocities for the hinge, and at which point the hinge fitU() method can be used to compute the U velocity coordinates for the hinge that meet the requirements.

Parameters:: oframe_v – the hypothetical oframe relative spatial velocity
Returns:: the corresponding pframe relative spatial velocity

class Karana.Frame.OrientedChainedFrameToFrame#: Bases: FrameToFrame

class Karana.Frame.PrescribedFrameToFrame(oframe: Frame, pframe: Frame)#

Bases: EdgeFrameToFrame

Base class for an edge FrameToFrame in the frames tree

See Coordinate Frames for more discussion on the frames layer.

static create(oframe: Frame, pframe: Frame) → PrescribedFrameToFrame#

Constructor for PrescribedFrameToFrame. :param oframe:

oframe of the PrescribedFrameToFrame.

Parameters:

pframe –

pframe of the PrescribedFrameToFrame.

Returns:

The PrescribedFrameToFrame object.

setRelSpAccel(arg0: Karana.Math.SpatialVector) → None#: Set the relative acceleration between the oframe and pframe.

setRelSpVel(arg0: Karana.Math.SpatialVector) → None#: Set the relative velocity between the oframe and pframe.

setRelTransform(arg0: Karana.Math.HomTran) → None#: Set the relative homogeneous transformation between the oframe and pframe.

class Karana.Frame.SpiceFrame(fc: FrameContainer, naif_body_id: SupportsInt, naif_frame_id: SupportsInt = 999999)#

Bases: Frame

static loadNaifKernel(path: os.PathLike | str | bytes) → None#: Method to load a NAIF kernel. :param path: path to the kernel

static lookupOrCreate(fc: FrameContainer, naif_body_id: SupportsInt, naif_frame_id: SupportsInt = 999999) → SpiceFrame#

Factory method to look up, or create a SpiceFrame

If the NAIF frame id is unspecified, then the default frame for the NAIF body is used.

Parameters:

fc – the FrameContainer
naif_body_id – the NAIF body id
naif_frame_id – the NAIF frame id

Returns:

a new SpiceFrame instance

class Karana.Frame.SpiceFrameToFrame(arg0: SpiceFrame, arg1: SpiceFrame)#

Bases: FrameToFrame

Represents a connection between two frames.

This class handles the transformation, velocity, and acceleration between two frames.

See Coordinate Frames for more discussion on the frames layer.

static lookupOrCreate(arg0: SpiceFrame, arg1: SpiceFrame) → SpiceFrameToFrame#

Factory method to look up or create a SpiceFrameToFrame

Parameters:

oframe – the SpiceFrame oframe
pframe – the SpiceFrame pframe

Returns:

a SpiceFrameToFrame instance