Karana.Frame

Classes and modules related to the Frames layer.

Classes

ChainedFrame2Frame	Frame2Frame class connecting arbitrary oframe/pframe Frame pairs
EdgeFrame2Frame	Base class for an edge Frame2Frame in the frames tree
Frame
Frame2Frame	Represents a connection between two frames.
FrameContainer
OrientedChainedFrame2Frame
PrescribedFrame2Frame	Base class for an edge Frame2Frame in the frames tree
SpiceFrame
SpiceFrame2Frame	Represents a connection between two frames.
frameDumpOptions

Package Contents

class Karana.Frame.ChainedFrame2Frame

Bases: Frame2Frame

Frame2Frame class connecting arbitrary oframe/pframe Frame pairs

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

See The frames layer for more discussion on the frames layer.

class Karana.Frame.EdgeFrame2Frame

Bases: Frame2Frame

Base class for an edge Frame2Frame in the frames tree

See The frames layer 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.

Parameter name:

• The name of the frame to create.

Parameter 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.

edge() → EdgeFrame2Frame

Get the edge associated with this frame.

Returns:

The edge f2f.

frame2Frame(frame: Frame) → ChainedFrame2Frame

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.

Parameter frame:

The target frame. This will be the p-frame in the chained frame to frame.

Returns:

The ChainedFrame2Frame connecting this frame (o-frame) and the target frame (p-frame).

getAncestor(other: Frame) → Frame

Get the ancestor of this frame and another frame.

Parameter other:

The other frame.

Returns:

The common ancestor.

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

Check if this frame is an ancestor of another frame.

Parameter other:

The other frame to check against.

Parameter strict:

if false, a frame can be its own ancestor

Returns:

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

orientedFrame2Frame(frame: Frame) → OrientedChainedFrame2Frame

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.

Parameter frame:

The target frame. This will be the p-frame in the chained frame to frame.

Returns:

The OrientedChainedFrame2Frame connecting this frame (o-frame) and the target frame (p-frame).

parent() → Frame

Get the parent frame.

Returns:

The parent frame.

typeString() → str

Get the type string of the frame.

Returns:

The type string.

class Karana.Frame.Frame2Frame

Bases: Karana.Core.LockingBase

Represents a connection between two frames.

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

See The frames layer for more discussion on the frames layer.

oframe() → Frame

Get the oframe of the Frame2Frame.

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 wrt 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 postion of the linear part.

Returns:

The coordinate rates as a 6-vector

pframe() → Frame

Get the pframe of the Frame2Frame.

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 wrt 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 f2f(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 wrt 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 f2f(pframe, oframe).relSpVel() where the roles of oframe and pframe are switched, and the value would be the velocity of oframe wrt 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 wrt 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 wrt 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: Frame2Frame, arg1: Frame2Frame, arg2: Karana.Math.SpatialVector) → Karana.Math.SpatialVector

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

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

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

Parameter sub_f2f:

the sub f2f whose required spatial acceleration is to be computed

Parameter other_f2f:

the f2f for the segment of oframe/pframe not covered by sub_f2f

Parameter desired_A:

the desired relative spatial acceleration for this f2f

Returns:

the relative spatial acceleration required for the sub f2f

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

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

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

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

Parameter sub_f2f:

the sub f2f whose required spatial velocity is to be computed

Parameter other_f2f:

the f2f for the segment of oframe/pframe not covered by sub_f2f

Parameter desired_V:

the desired relative spatial velocity for this f2f

Returns:

the relative spatial velocity required for the sub f2f

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

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

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

Parameter sub_f2f:

the sub f2f whose required transform is to be computed

Parameter desired_T:

the desired relative transform for this f2f

Returns:

the relative transform required for the sub f2f

subchainOrientation(arg0: Frame2Frame) → bool | None

Check the relationship of a sub-chain f2f’s path wrt the overall f2f path

Return true if the subh-chain f2f’s path is contained in the f2f’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.

Parameter sub_f2f:

the sub-path Frame2Frame’s orientation to check

Returns:

null if not on path, and true if on the path and oriented

toPframeDerivSpAccel(arg0: Karana.Math.SpatialVector) → Karana.Math.SpatialVector

Transform the provided oframe deriv relative spatial accel into pframe deriv value

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

Note that toPframeDerivSpAccel(relSpAccel()) == pframe()->frame2Frame(oframe())->relSpAccel()

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

Parameter oframe_A:

the candidate oframe derivate relative spatial accel

Returns:

the corresponding pframe observed and represented spatial accel

toPframeDerivSpVel(arg0: Karana.Math.SpatialVector) → Karana.Math.SpatialVector

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

For this f2f, convert the candidate oframe derivate relative spatial velocity for the f2f into the relative spatial velocity as if we are taking the derivative of the pframe to the pframe vector quantities as observed from the pframe, and represented in the pframe. That is computing B_alpha(B,A) from A_alpha(A, B). This method assumes that the relative transform for the f2f is valid and uses it.

Note that toPframeDerivSpVel(relSpVel()) == pframe()->frame2Frame(oframe())->relSpVel()

This method is handy for state initialization, where we are trying to initialize the multibody velocity coordinates based on some physical reguirements 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 coordianates for the hinge that meet the requirements.

Parameter oframe_V:

the candidate oframe derivate relative spatial velocity

Returns:

the corresponding pframe observed and represented spatial velocity

class Karana.Frame.FrameContainer(name: str)

Bases: Karana.Core.LockingBase

static create(name: str) → FrameContainer

Create a FrameContainer.

Parameter root_frame_name:

Name for the root frame

Returns:

The frame container.

chainedFrame2Frames() → list[ChainedFrame2Frame]

Return a vector of all the ChainedFrame2Frames in the FrameContainer.

Returns:

List of all the chain elements.

edgeFrame2Frames() → list[EdgeFrame2Frame]

Return a vector of all the EdgeFrame2Frames 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.

Parameter frame1:

The first frame.

Parameter 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.

Parameter oframe:

The potential ancestor frame.

Parameter pframe:

The potential descendant frame.

Parameter 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.

Parameter 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

Parameter 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, log_level: str = 'warning', autorun: bool = True, 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 visualiztion:

type: Color based on the type of the Frame or Frame2Frame valency: Color nodes based on number of connecting edges

Defaults to the “type” coloring.

chains: bool

Whether to also show edges for ChainedFrame2Frames. Defaults to False.

log_level: str

Terminal verbosity level - defaults to “warning”.

autorun: bool

Automatically start the web server - defaults to True.

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.OrientedChainedFrame2Frame

Bases: Frame2Frame

class Karana.Frame.PrescribedFrame2Frame(oframe: Frame, pframe: Frame)

Bases: EdgeFrame2Frame

Base class for an edge Frame2Frame in the frames tree

See The frames layer for more discussion on the frames layer.

static create(oframe: Frame, pframe: Frame) → PrescribedFrame2Frame

Constructor for PrescribedFrame2Frame.

Parameter oframe:

• oframe of the PrescribedFrame2Frame.

Parameter pframe:

• pframe of the PrescribedFrame2Frame.

Returns:

The PrescribedFrame2Frame object.

setAccel(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.

Parameter 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.

Parameter fc:

the FrameContainer

Parameter naif_body_id:

the NAIF body id

Parameter naif_frame_id:

the NAIF frame id

Returns:

a new SpiceFrame instance

class Karana.Frame.SpiceFrame2Frame(arg0: SpiceFrame, arg1: SpiceFrame)

Bases: Frame2Frame

Represents a connection between two frames.

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

See The frames layer for more discussion on the frames layer.

static lookupOrCreate(arg0: SpiceFrame, arg1: SpiceFrame) → SpiceFrame2Frame

Factory method to look up or create a SpiceFrame2Frame

Parameter oframe:

the SpiceFrame oframe

Parameter pframe:

the SpiceFrame pframe

Returns:

a SpiceFrame2Frame instance

class Karana.Frame.frameDumpOptions(typeString: bool = True, edgeType: bool = False, lockStatus: bool = False, id: bool = False)

edgeRefCount: bool

edgeType: bool

id: bool

lockStatus: bool

refCount: bool

typeString: bool

__repr__() → str