Karana.KUtils.vizutils

Classes and functions associated with visualizing forces.

Classes

NodeForceVisualizer	Helper to visualize the force on a Node.
SpringForceVisualizer	Helper to visualize forces generated by contact.
SpringModelProtocol	A protocol for classes representing a spring model between a pair of nodes.
Axes3d	Create a 3d axes visualization.
ContactForceVisualizer	Visualize the contact forces created by a PenaltyContact KModel.
FrameToFrameRateType	Enums for the frame to frame rate vector types for visualization
FrameToFrameVectorVisualizer	Visualize a vector that spans the two frames in a FrameToFrame.
ScaledVectorVisualizer	A scaled version of VectorVisualizer.
VectorVisualizer	Visualize a vector using a frame and a function.

Functions

computeSphereSweptHull(positions, *[, sphere_radius, ...])	Compute a sphere-swept convex hull.
createBodyHullPartSpec(→ Karana.Scene.ScenePartSpec)	Create a ScenePartSpec for a convex hull over a body's nodes.
visualizeFrameToFrameRates(→ ScaledVectorVisualizer)	Visualize the frame_to_frame vel/accel values
visualizeInterBodyForce(→ ScaledVectorVisualizer)	Visualize the interbody force on a node.
visualizeInterBodyTorque(→ ScaledVectorVisualizer)	Visualize the interbody torque on a node.
visualizeNodeForce(→ ScaledVectorVisualizer)	Visualize the force of a node.
visualizeNodeTorque(→ ScaledVectorVisualizer)	Visualize the torque on a node.

Package Contents

class Karana.KUtils.vizutils.NodeForceVisualizer(name: str, scene: Karana.Scene.ProxyScene, force_scale: float | collections.abc.Callable[[float], float] = 0.01, radius: float = 0.01, color: Karana.Scene.Color = Color.WHITE, auto_update: bool = True)

Helper to visualize the force on a Node.

The force is visualized as an arrow emanating from the point where the force is applied. The arrow’s length scales based on the magnitude of the force.

Unless constructed with auto_update=True, the update method must be called periodically to update the arrow.

name

setNode(node: Karana.Dynamics.Node | None, update: bool = True)

Set the external force node to visualize.

Parameters:

• node (Node | None) – The node to visualize the force of, or None to disable

• update (bool) – If True, immediately update the force visualization

update()

Update the force visualization.

Unless constructed with auto_update=True, this needs to be called whenever the force changes in order to see the effect in the visualization.

class Karana.KUtils.vizutils.SpringForceVisualizer(name: str, mdl: SpringModelProtocol, scene: Karana.Scene.ProxyScene, *, colors: tuple[Karana.Scene.Color, Karana.Scene.Color] = (Color.YELLOW, Color.BLUE), force_scale: float | collections.abc.Callable = 0.01, radius: float = 0.01, auto_update: bool = True)

Helper to visualize forces generated by contact.

The force is visualized as a pair of arrows emanating from the point where the force is applied. The arrow’s length scales based on the magnitude of the force.

Unless constructed with auto_update=True, the update method must be called periodically to update the arrows.

update(*args)

Update the force visualization.

Unless constructed with auto_update=True, this needs to be called whenever to the force changes in order to see the effect in the visualization.

class Karana.KUtils.vizutils.SpringModelProtocol

Bases: Protocol

A protocol for classes representing a spring model between a pair of nodes.

sourceNode() → Karana.Dynamics.Node

Return the starting node of the spring.

targetNode() → Karana.Dynamics.Node

Return the ending node of the spring.

Karana.KUtils.vizutils.computeSphereSweptHull(positions, *, sphere_radius: float = 0.03, points_per_sphere: int = 20)

Compute a sphere-swept convex hull.

Parameters:

• positions – An Nx3 array of vertex positions to form a hull over.

• sphere_radius (float) – Radius of the sphere to sweep over the hull. Defaults to 0.03.

• points_per_sphere (int) – Number of points on the sphere surface approximation. Defaults to 20.

Returns:

A StaticMeshGeometry for the sphere-swept convex hull

Return type:

StaticMeshGeometry

Karana.KUtils.vizutils.createBodyHullPartSpec(body: Karana.Dynamics.PhysicalBody, *, sphere_radius: float = 0.03, points_per_sphere: int = 20, material: Karana.Scene.PhysicalMaterial | Karana.Scene.PhongMaterial | None = None) → Karana.Scene.ScenePartSpec

Create a ScenePartSpec for a convex hull over a body’s nodes.

The resulting ScenePartSpec should be added to the body by calling PhysicalBody.addScenePartSpec.

Parameters:

• body (PhysicalBody) – The body of interest

• sphere_radius (float) – Radius of the sphere swept through the hull. Defaults to 0.03.

• points_per_sphere (int) – Number of points on the sphere surface approximation. Defaults to 20.

• material (PhysicalMaterial | PhongMaterial | None) – Material to apply. If None, uses a default material.

Returns:

A ScenePartSpec for the hull

Return type:

ScenePartSpec

class Karana.KUtils.vizutils.Axes3d(name: str, scene: Karana.Scene.ProxyScene, length: float = 1.0, radius: float = 0.1)

Create a 3d axes visualization.

property name: str

Get the name of the Axes3d.

Returns:

The name

Return type:

str

property node: Karana.Scene.ProxySceneNode

Get the base node of the axes.

Returns:

The node

Return type:

ks.ProxySceneNode

class Karana.KUtils.vizutils.ContactForceVisualizer(name: str, frame: Karana.Frame.Frame, scene: Karana.Scene.ProxyScene, fn: Karana.Models.PenaltyContact)

Bases: Karana.Core.Base

Visualize the contact forces created by a PenaltyContact KModel.

The frame provided is the frame the vectors will be drawn in.

static create(name: str, frame: Karana.Frame.Frame, scene: Karana.Scene.ProxyScene, fn: Karana.Models.PenaltyContact) → ContactForceVisualizer

Create a new instance of ContactForceVisualizer.

Parameters:

• name – Name of the visualizer.

• frame – The Frame where the vectors will be drawn in.

• scene – The ProxyScene to add the vectors to.

• penalty_contact – The PenaltyContact model to get the contact vectors from.

Returns:

A pointer to the newly created ContactForceVisualizer.

getColor() → Karana.Scene.Color

Get the color of the vectors.

Returns:

The color of the vectors.

getRadius() → float

Get the radius of the vectors.

Returns:

The radius of the vectors.

getScale() → float

Get the current scale.

Returns:

The current scale.

registerCallback() → None

Register the callback with the scene.

setColor(color: Karana.Scene.Color) → None

Set the color of the vectors.

Parameters:

color – The new color of the vectors.

setRadius(radius: SupportsFloat | SupportsIndex) → None

Set the radius of the vectors.

Parameters:

radius – The new radius of the vectors.

setScale(scale: SupportsFloat | SupportsIndex) → None

Set the current scale.

Parameters:

scale – The current scale.

unregisterCallback() → None

Unregister the callback with the scene.

class Karana.KUtils.vizutils.FrameToFrameRateType(*args, **kwds)

Bases: enum.Enum

Enums for the frame to frame rate vector types for visualization

ACCEL_ANGULAR: ClassVar[FrameToFrameRateType]

ACCEL_LINEAR: ClassVar[FrameToFrameRateType]

VEL_ANGULAR: ClassVar[FrameToFrameRateType]

VEL_LINEAR: ClassVar[FrameToFrameRateType]

class Karana.KUtils.vizutils.FrameToFrameVectorVisualizer(name: str, frame_to_frame: Karana.Frame.FrameToFrame, scene: Karana.Scene.ProxyScene)

Bases: Karana.Core.Base

Visualize a vector that spans the two frames in a FrameToFrame.

The origin of the vector is at the o-frame of the FrameToFrame, and the end of the vector is at the p-frame of the FrameToFrame.

static create(name: str, frame_to_frame: Karana.Frame.FrameToFrame, scene: Karana.Scene.ProxyScene) → FrameToFrameVectorVisualizer

Create a new instance of VectorVisualizer.

Parameters:

• name – Name of the visualizer.

• frame_to_frame – The FrameToFrame for the vector.

• scene – The ProxyScene to add the vector to.

Returns:

A pointer to the newly created FrameToFrameVectorVisualizer.

getEndOffset() → Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]

Get the ending offset of the vector.

This is the offset between the p-frame of the frame to frame and the end of the vector.

Returns:

The start offset of the vector.

setEndOffset(offset: Annotated[numpy.typing.ArrayLike, numpy.float64, [3, 1]]) → None

Set the end offset of the vector.

This is the offset between the p-frame of the frame to frame and the end of the vector.

Parameters:

offset – The new end offset of the vector.

class Karana.KUtils.vizutils.ScaledVectorVisualizer(name: str, frame: Karana.Frame.Frame, scene: Karana.Scene.ProxyScene, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]])

Bases: VectorVisualizer

A scaled version of VectorVisualizer.

This is like the VectorVisualizer class (see that class for more details) but the length of the vector can be scaled using get/setScale.

static create(name: str, frame: Karana.Frame.Frame, scene: Karana.Scene.ProxyScene, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]]) → ScaledVectorVisualizer

Create a new instance of VectorVisualizer.

Parameters:

• name – Name of the visualizer.

• frame – The Frame where the vector starts.

• scene – The ProxyScene to add the vector to.

• fn – The function used to update the vector.

Returns:

A pointer to the newly created ScaledVectorVisualizer.

getScale() → float

Get the current scale.

Returns:

The current scale.

setScale(scale: SupportsFloat | SupportsIndex) → None

Set the current scale.

Parameters:

scale – The current scale.

class Karana.KUtils.vizutils.VectorVisualizer(name: str, frame: Karana.Frame.Frame, scene: Karana.Scene.ProxyScene, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]])

Bases: Karana.Core.Base

Visualize a vector using a frame and a function.

The frame is origin of the vector, and the function provides the length/direction for the vector.

static create(name: str, frame: Karana.Frame.Frame, scene: Karana.Scene.ProxyScene, fn: collections.abc.Callable[[], Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]]) → VectorVisualizer

Create a new instance of VectorVisualizer.

Parameters:

• name – Name of the visualizer.

• frame – The Frame where the vector starts.

• scene – The ProxyScene to add the vector to.

• fn – The function used to update the vector.

Returns:

A pointer to the newly created VectorVisualizer.

getColor() → Karana.Scene.Color

Get the color of the vector.

Returns:

The color of the vector.

getRadius() → float

Get the radius of the vector.

Returns:

The radius of the vector.

getStartOffset() → Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]

Get the starting offset of the vector.

This is the offset between the frame origin and the start of the vector.

Returns:

The start offset of the vector.

registerCallback() → None

Register the callback with the scene.

setColor(color: Karana.Scene.Color) → None

Set the color of the vector.

Parameters:

color – The new color of the vector.

setRadius(radius: SupportsFloat | SupportsIndex) → None

Set the radius of the vector.

Parameters:

radius – The new radius of the vector.

setStartOffset(offset: Annotated[numpy.typing.ArrayLike, numpy.float64, [3, 1]]) → None

Set the start offset of the vector.

This is the offset between the frame origin and the start of the vector.

Parameters:

offset – The new start offset of the vector.

unregisterCallback() → None

Unregister the callback with the scene.

Karana.KUtils.vizutils.visualizeFrameToFrameRates(frame_to_frame: Karana.Frame.FrameToFrame, scene: Karana.Scene.ProxyScene, rate_type: FrameToFrameRateType) → ScaledVectorVisualizer

Visualize the frame_to_frame vel/accel values

Visualize the relative velocity/acceleration (as specified by the type argument) for the frame_to_frame as a vector originating from the pframe and whose size and direction is proportional to the selected relative rate. The orientation of the vector is in the oframe.

Parameters:

• frame_to_frame – Visualize the vector for the frame_to_frame’s rates.

• scene – The ProxyScene to use for visualizing.

• rate_type – The type of rate to visualize

Returns:

A ScaledVectorVisualizer for visualizing the frame-to-frame rates.

Karana.KUtils.vizutils.visualizeInterBodyForce(onode: Karana.Dynamics.HingeOnode, scene: Karana.Scene.ProxyScene, use_ta: bool) → ScaledVectorVisualizer

Visualize the interbody force on a node.

Parameters:

• onode – The Onode to visualize the force for.

• scene – The ProxyScene to use for visualizing.

• use_ta – If true, use TA getInterBodyForceTAFwdDyn to calculate the force. Otherwise, use getInterBodyForceTreeFwdDyn.

Returns:

A ScaledVectorVisualizer for visualizing the interbody force on the node.

Karana.KUtils.vizutils.visualizeInterBodyTorque(onode: Karana.Dynamics.HingeOnode, scene: Karana.Scene.ProxyScene, use_ta: bool) → ScaledVectorVisualizer

Visualize the interbody torque on a node.

Parameters:

• onode – The Onode to visualize the torque for.

• scene – The ProxyScene to use for visualizing.

• use_ta – If true, use TA getInterBodyForceTAFwdDyn to calculate the torque. Otherwise, use getInterBodyForceTreeFwdDyn.

Returns:

A ScaledVectorVisualizer for visualizing the interbody torque on the node.

Karana.KUtils.vizutils.visualizeNodeForce(node: Karana.Dynamics.Node, scene: Karana.Scene.ProxyScene) → ScaledVectorVisualizer

Visualize the force of a node.

Parameters:

• node – The node to visualize the force for.

• scene – The ProxyScene to use for visualizing.

Returns:

A ScaledVectorVisualizer for visualizing the node force.

Karana.KUtils.vizutils.visualizeNodeTorque(node: Karana.Dynamics.Node, scene: Karana.Scene.ProxyScene) → ScaledVectorVisualizer

Visualize the torque on a node.

Parameters:

• node – The node to visualize the torque for.

• scene – The ProxyScene to use for visualizing.

Returns:

A ScaledVectorVisualizer for visualizing the node force.