Karana.Collision

Karana.Collision#

Models and classes for collision detection and contact force calculation.

Submodules#

Karana.Collision.Collision_types

Classes#

`ContactForceBase`	Base class for all contact force models.
`ContactForceManager`	A ContactForceBase that delegates based on the Frame pair
`DampedContactForce`	ContactForceBase implementation using a Hunt-Crossley model
`DampedContactForceParams`	Structure that holds the DampedContactForce contact force parameters.
`DampedContactForceScratch`	Structure that holds the DampedContactForce scratch data
`FrameCollider`	Helper to bridge CollisionScene collisions to Frames
`FrameContact`	Data for a contact between a pair of Frames
`HuntCrossleyContactForce`	ContactForceBase implementation using a Hunt-Crossley model
`HuntCrossleyContactForceParams`	Structure that holds the HuntCrossleyContactForce contact force
`HuntCrossleyContactForceScratch`	Structure that holds the HuntCrossleyContactForce scratch data
`NonlinearContactForce`	Nonlinear penalty contact force with smoothly regularized damping and
`NonlinearContactForceParams`	Parameters used by the nonlinear contact-force model.
`NonlinearContactForceScratch`	Scratch data populated by the latest force computation.

Package Contents#

class Karana.Collision.ContactForceBase#

Bases: Karana.Core.Base

Base class for all contact force models.

See Collision dynamics for more discussion on contact and collision dynamics.

applyForce(contact: FrameContact, st: Karana.Dynamics.SubTree) → tuple[Karana.Dynamics.Node, Karana.Dynamics.Node]#

Apply the contact force for the associated contact.

This first calls computeForce to get the contact force. Then, it applies it to frames if those frames belong to a body.

Parameters:

contact – The contact to apply the force for.
st – The SubTree we are computing forces for.

Returns:

A pair of contact force nodes at which we applied the force.

toDS() → Karana.Collision.Collision_types.ContactForceBaseDS#

Create a ContactForceBaseDS from this ContactForceBase model.

Returns:

ContactForceBaseDS
A ContactForceBaseDS instance with values set to match this model.

class Karana.Collision.ContactForceManager(name: str)#

Bases: ContactForceBase

A ContactForceBase that delegates based on the Frame pair

See Collision dynamics for more discussion on contact and collision dynamics.

static create(name: str) → ContactForceManager#

Create an instance of ContactForceManager.

Parameters:: name – The name for the ContactForceManager instance.
Returns:: A ks_ptr to the newly created ContactForceManager.

clearDelegates() → None#: Clear out all registered ContactForceBase instances

getDelegate(contact: FrameContact) → ContactForceBase#

getDelegate() → ContactForceBase

getDelegate(frame1: Karana.Frame.Frame, frame2: Karana.Frame.Frame, strict: bool = False) → ContactForceBase

Get the most specific matching ContactForceBase

Parameters:: contact – The contact to get the delegate for.
Returns:: The ContactForceBase (may be nullptr)

setDelegate(force: ContactForceBase = None) → None#

setDelegate(frame1: Karana.Frame.Frame, frame2: Karana.Frame.Frame, force: ContactForceBase = None) → None

Set the ContactForceBase used by default

Parameters:: force – The ContactForceBase (may be nullptr)

class Karana.Collision.DampedContactForce(name: str)#

Bases: ContactForceBase

ContactForceBase implementation using a Hunt-Crossley model

Based on https://chatgpt.com/s/t_6955d6cac734819194154f53251a0038

See Collision dynamics for more discussion on contact and collision dynamics.

static create(name: str) → DampedContactForce#

Create an instance of the DampedContactForce contact force model.

Parameters:: name – The name for the DampedContactForce instance.
Returns:: A ks_ptr to the newly created DampedContactForce contact force model.

property params: DampedContactForceParams#: Parameters used for the contact model.

property scratch: DampedContactForceScratch#: Scratch values

class Karana.Collision.DampedContactForceParams#

Structure that holds the DampedContactForce contact force parameters.

property dmax: float#: DMAx - max penetration value where damping stops increasing

property e: float#: Damping exponent (default cubic dependency)

property kc: float#: Normal penetration restitution/damping coefficient

property kp: float#: Normal penetration stiffness coefficient

property linear_region_tol: float#

Tolerance at which friction is linearly interpolated between the real value and 0.

To avoid jittering for cases like rolling without friction, near zero, the friction force uses a linear interpolation between the full friction force and zero. This avoids rapid, large changes in the friction force as the velocity changes sign, and instead, smoothly, linearly interpolates between these large forces over a region of linear_region_tol * 2.

property mu: float#: Friction coefficient

property n: float#: Exponent

class Karana.Collision.DampedContactForceScratch#

Structure that holds the DampedContactForce scratch data

property C: float#: effecting damping coefficient, C = kd * (pen/dmax)^e (pen < dmax)

property f: Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]#: contact force

property linvel: Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]#: contact linear velocity

property penetration: float#: Normal penetration

class Karana.Collision.FrameCollider(proxy_scene: Karana.Scene.ProxyScene, collision_scene: Karana.Scene.CollisionScene)#

Helper to bridge CollisionScene collisions to Frames

See Collision dynamics for more discussion on contact and collision dynamics.

clearIgnoredFramePairs() → None#: Stop ignoring any frame-pair collisions

collide(col_func: collections.abc.Callable[[FrameContact], None], filter_func: collections.abc.Callable[[Karana.Scene.CollisionScenePart, Karana.Scene.CollisionScenePart], bool] = None) → None#

Process all collisions

Sweeps through all contacts between geometries attached to Frames, calling the collision handler for each unfiltered contact.

Parameters:

collision_handler –
- Callback to handle a contact
filter –
- Callback to skip potential collisions in the broadphase.

dump(prefix: str = '') → None#

Print dumpString on std::cout.

Parameters:: prefix – A string to use as prefix for each output line

dumpString(prefix: str = '') → str#

Return information about the object.

Parameters:: prefix – A string to use as prefix for each output line
Returns:: String with the information about the object.

getCollisionScene() → Karana.Scene.CollisionScene#

Return the CollisionScene used by this FrameCollider.

Returns:: The CollisionScene used by this FrameCollider.

getProxyScene() → Karana.Scene.ProxyScene#

Return the ProxyScene used by this FrameCollider.

Returns:: The ProxyScene used by this FrameCollider.

ignoreAllCurrentlyTouchingPairs() → None#: Call ignoreFramePair for each pair with a collision

ignoreFramePair(frame1: Karana.Frame.Frame, frame2: Karana.Frame.Frame) → None#

Ignore collisions between a pair of frames

Parameters:

frame1 – The first frame in the pair
frame2 – The second frame in the pair

lookupPartFrame(part: Karana.Scene.CollisionScenePart) → Karana.Frame.Frame#

lookupPartFrame(id: SupportsInt | SupportsIndex) → Karana.Frame.Frame

Get the Frame that a CollisionScenePart is attached to

Parameters:

part –

A CollisionScenePart managed by ProxyScene

Returns:

The ancestor Frame for the part.

toDS() → Karana.Collision.Collision_types.FrameColliderDS#

Create a FrameColliderDS from this FrameCollider model.

Returns:

FrameColliderDS
A FrameColliderDS instance with values set to match this model.

unignoreFramePair(frame1: Karana.Frame.Frame, frame2: Karana.Frame.Frame) → None#

Stop ignoring collisions between a pair of frames

Parameters:

frame1 – The first frame in the pair
frame2 – The second frame in the pair

class Karana.Collision.FrameContact#

Data for a contact between a pair of Frames

property frame_1: Karana.Frame.Frame#: The first Frame involved in the contact

property frame_2: Karana.Frame.Frame#: The second Frame involved in the contact

property location_1: Karana.Math.Ktyping.Length[Karana.Math.Ktyping.Vec3]#: Contact location on the first Frame relative to the first Frame and expressed in the first frame

property location_2: Karana.Math.Ktyping.Length[Karana.Math.Ktyping.Vec3]#: Contact location on the second Frame relative to the second Frame and expressed in the second frame

property normal_1: Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]#: Contact normal expressed first Frame

property normal_2: Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]#: Contact normal expressed second Frame

property penetration: Karana.Math.Ktyping.Length[float]#: Maximum penetration distance

class Karana.Collision.HuntCrossleyContactForce(name: str)#

Bases: ContactForceBase

ContactForceBase implementation using a Hunt-Crossley model

See Collision dynamics for more discussion on contact and collision dynamics.

static create(name: str) → HuntCrossleyContactForce#

Create an instance of the HuntCrossleyContactForce contact force model.

Parameters:: name – The name for the HuntCrossleyContactForce instance.
Returns:: A ks_ptr to the newly created HuntCrossleyContactForce contact force model.

toDS() → Karana.Collision.Collision_types.HuntCrossleyContactForceDS#

Create a HuntCrossleyContactForceDS from this HuntCrossleyContactForce model.

Returns:

HuntCrossleyContactForceDS
A HuntCrossleyContactForceDS instance with values set to match this model.

property params: HuntCrossleyContactForceParams#: Parameters used for the contact model.

property scratch: HuntCrossleyContactForceScratch#: Scratch values

class Karana.Collision.HuntCrossleyContactForceParams#

Structure that holds the HuntCrossleyContactForce contact force parameters.

property dissipation: float#: Hunt-Crossley dissipation ratio

property kp: float#: Normal penetration stiffness coefficient

property linear_region_tol: float#

Tolerance at which friction is linearly interpolated between the real value and 0.

property mu: float#: Friction coefficient

property n: float#: Exponent

class Karana.Collision.HuntCrossleyContactForceScratch#

Structure that holds the HuntCrossleyContactForce scratch data

property f: Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]#: contact force

property linvel: Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]#: contact linear velocity

property penetration: float#: Normal penetration

class Karana.Collision.NonlinearContactForce(name: str)#

Bases: ContactForceBase

Nonlinear penalty contact force with smoothly regularized damping and friction.

With penetration \(\delta\), signed closing speed \(v_n\), stiffness \(k_p\), exponent \(n\), damping \(k_c\), and full-damping depth \(d_{\max}\), the normal force magnitude is f[ F_n=maxleft(0,k_pdelta^n+k_c,S(delta/d_{max})v_nright). f] By default, \(S(a)=a^2(3-2a)\) with \(a\) clipped to \([0,1]\). Tangential friction follows a cubic, velocity- regularized Coulomb curve. Its magnitude rises smoothly from zero to \(\mu_s F_n\) at the stiction-transition speed \(v_s\), falls smoothly to \(\mu_d F_n\) at the friction-transition speed \(v_d\), and remains on that dynamic plateau thereafter.

The damping and friction transitions use a cubic polynomial approximation to a step function.

static create(name: str) → NonlinearContactForce#

Create a nonlinear contact-force model.

Parameters:: name – Object name.
Returns:: Newly allocated model.

toDS() → Karana.Collision.Collision_types.NonlinearContactForceDS#

Create a NonlinearContactForceDS from this NonlinearContactForce model.

Returns:

NonlinearContactForceDS
A NonlinearContactForceDS instance with values set to match this model.

property params: NonlinearContactForceParams#: Contact-law parameters.

property scratch: NonlinearContactForceScratch#: Latest computed contact values.

class Karana.Collision.NonlinearContactForceParams#

Parameters used by the nonlinear contact-force model.

property damping_ramp_depth: float#: Penetration at full damping in meters.

property friction_transition_speed: float#: Slip speed at the end of the friction transition in m/s.

property kc: float#: Maximum normal damping coefficient in N s/m.

property kp: float#: Penalty stiffness in N/m^n.

property mu_dynamic: float#: Dynamic friction coefficient.

property mu_static: float | None#: Static coefficient, or nullopt to use mu_dynamic.

property n: float#: Positive penetration exponent.

property stiction_transition_speed: float#: Slip speed of the static-friction peak in m/s.

class Karana.Collision.NonlinearContactForceScratch#

Scratch data populated by the latest force computation.

property f: Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]#: Total force on object 1 expressed in frame 1.

property linvel: Annotated[numpy.typing.NDArray[numpy.float64], [3, 1]]#: Relative contact-point velocity expressed in frame 1.

property penetration: float#: Positive penetration depth in meters.