Karana.Frame

Classes and modules related to the Frames layer.

Classes

ChainedFrameToFrame	@class ChainedFrameToFrame FrameToFrame class connecting arbitrary
EdgeFrameToFrame	@class EdgeFrameToFrame Base class for an edge FrameToFrame in the
Frame
FrameContainer
FrameDumpOptions
FrameToFrame	@class FrameToFrame Represents a connection between two frames.
OrientedChainedFrameToFrame
PrescribedFrameToFrame	@class EdgeFrameToFrame Base class for an edge FrameToFrame in the
SpiceFrame
SpiceFrameToFrame	@class FrameToFrame Represents a connection between two frames.

Package Contents

class Karana.Frame.ChainedFrameToFrame

Bases: FrameToFrame

@class ChainedFrameToFrame 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

@class EdgeFrameToFrame 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.

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.

Parameter prefix:

the prefix for each output line

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

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

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.

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.

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

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

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

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.FrameDumpOptions(type_string: bool = True, edge_type: bool = False, current_status: bool = False, id: bool = False)

current_status: bool

edge_ref_count: bool

edge_type: bool

id: bool

ref_count: bool

type_string: bool

__repr__() → str

class Karana.Frame.FrameToFrame

Bases: Karana.Core.LockingBase

@class 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.

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.

Parameter sub_f_to_f:

the sub f_to_f whose required spatial acceleration is to be computed

Parameter other_f_to_f:

the f_to_f for the segment of oframe/pframe not covered by sub_f_to_f

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

Parameter sub_f_to_f:

the sub f_to_f whose required spatial velocity is to be computed

Parameter other_f_to_f:

the f_to_f for the segment of oframe/pframe not covered by sub_f_to_f

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

Parameter sub_f_to_f:

the sub f_to_f whose required transform is to be computed

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

Parameter 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

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

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

For this f_to_f, convert the candidate oframe derivative relative spatial accel for the f_to_f 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 f_to_f are valid and uses them.

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

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.

Parameter oframe_a:

the candidate oframe derivative 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 f_to_f, convert the candidate oframe derivative relative spatial velocity for the f_to_f 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 f_to_f is valid and uses it.

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

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.

Parameter oframe_v:

the candidate oframe derivative relative spatial velocity

Returns:

the corresponding pframe observed and represented spatial velocity

class Karana.Frame.OrientedChainedFrameToFrame

Bases: FrameToFrame

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

Bases: EdgeFrameToFrame

@class 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.

Parameter oframe:

• oframe of the PrescribedFrameToFrame.

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

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.SpiceFrameToFrame(arg0: SpiceFrame, arg1: SpiceFrame)

Bases: FrameToFrame

@class 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

Parameter oframe:

the SpiceFrame oframe

Parameter pframe:

the SpiceFrame pframe

Returns:

a SpiceFrameToFrame instance