Parameters for contact mechanics simulation. More...

#include <contact_params.h>

Public Member Functions
	ContactParams ()=default
	ContactParams (real penaltyCoefficient, real penaltySmoothingHalfDistance, real penaltyThresholdDefault, real penaltyThresholdExtraPadding, bool frictionWithColliderNormal, real maxAlignmentNormals, real viscousFrictionCoefficient, real coulombFrictionCoefficient, real frictionFalloffVel, real normalViscousDampingCoefficient, real distanceErrorBound, real objScale, real collidingPenaltyLengthScale)
	Construct ContactParams with all parameters explicitly specified.
real	GetPenaltyThresholdDist (bool addPadding) const
	Get the total contact detection threshold.
bool	operator== (ContactParams const &) const =default

Public Attributes
real	collidingPenaltyLengthScale = 1_r
	[Experimental] Length scale [m] used to correct the penalty coefficient when the colliding body integrates contact traction over a lower-than-two-dimensional manifold, such as a rod or point mass.
real	coulombFrictionCoefficient = 0.5_r
	Coulomb friction coefficient (dimensionless).
real	distanceErrorBound = 0_r
	[Experimental] Padding [m] added to the collider's bounding volume for collision culling.
real	frictionFalloffVel = 0.01_r
	Velocity threshold for Coulomb friction smoothing [m/s].
bool	frictionWithColliderNormal = true
	Use collider's normal (normalized SDF gradient) for friction direction if true, or the colliding's surface normal at the sample point if false.
real	maxAlignmentNormals = 0_r
	Maximum normal alignment threshold.
real	normalViscousDampingCoefficient = 0_r
	Normal viscous damping coefficient [s/m].
real	objScale = 1_r
	[Experimental] Object scale relative to default size (dimensionless).
real	penaltyCoefficient = 1e9_r
	Stiffness of the contact penalty force [Pa/m].
real	penaltySmoothingHalfDistance = 0.005_r
	PolyReLU smoothing half-width [m].
real	penaltyThresholdDefault = 0.001_r
	Default contact detection threshold [m].
real	penaltyThresholdExtraPadding = 0_r
	Extra padding [m] added to the default contact detection threshold if the colliding actor has ColliderType::None or ColliderType::PointCloud.
real	viscousFrictionCoefficient = 0_r
	Viscous friction coefficient [s/m].

Detailed Description

Parameters for contact mechanics simulation.

Note

In contact between a colliding actor and a collider, the collider's contact parameters (not the colliding actor's) are used. The exceptions are:

For friction and dissipation coefficients (viscousFrictionCoefficient, coulombFrictionCoefficient, normalViscousDampingCoefficient), the geometric mean of the colliding and collider's coefficients is used. This disables friction/dissipation if either of them does.
For penalty coefficient (penaltyCoefficient) and friction velocity threshold (frictionFalloffVel), the geometric mean of the colliding and collider's values is used, except if the collider is static in which case the colliding's values are used.

Definition at line 38 of file contact_params.h.

Constructor & Destructor Documentation

◆ ContactParams() [1/2]

superdex::ContactParams::ContactParams ( )

default

◆ ContactParams() [2/2]

superdex::ContactParams::ContactParams	(	real	penaltyCoefficient,
		real	penaltySmoothingHalfDistance,
		real	penaltyThresholdDefault,
		real	penaltyThresholdExtraPadding,
		bool	frictionWithColliderNormal,
		real	maxAlignmentNormals,
		real	viscousFrictionCoefficient,
		real	coulombFrictionCoefficient,
		real	frictionFalloffVel,
		real	normalViscousDampingCoefficient,
		real	distanceErrorBound,
		real	objScale,
		real	collidingPenaltyLengthScale )

inline

Construct ContactParams with all parameters explicitly specified.

Parameters

[in]	penaltyCoefficient	See penaltyCoefficient.
[in]	penaltySmoothingHalfDistance	See penaltySmoothingHalfDistance.
[in]	penaltyThresholdDefault	See penaltyThresholdDefault.
[in]	penaltyThresholdExtraPadding	See penaltyThresholdExtraPadding.
[in]	frictionWithColliderNormal	See frictionWithColliderNormal.
[in]	maxAlignmentNormals	See maxAlignmentNormals.
[in]	viscousFrictionCoefficient	See viscousFrictionCoefficient.
[in]	coulombFrictionCoefficient	See coulombFrictionCoefficient.
[in]	frictionFalloffVel	See frictionFalloffVel.
[in]	normalViscousDampingCoefficient	See normalViscousDampingCoefficient.
[in]	distanceErrorBound	See distanceErrorBound.
[in]	objScale	See objScale.
[in]	collidingPenaltyLengthScale	See collidingPenaltyLengthScale.

Note: Must take every parameter in order.; Used when converting types to/from the C API.

Definition at line 24 of file contact_params_inl.h.

Member Function Documentation

◆ GetPenaltyThresholdDist()

real superdex::ContactParams::GetPenaltyThresholdDist ( bool addPadding ) const

inline

Get the total contact detection threshold.

Parameters

addPadding If true, includes penaltyThresholdExtraPadding.

Returns: Total contact detection threshold [m].

Definition at line 52 of file contact_params_inl.h.

◆ operator==()

bool superdex::ContactParams::operator== ( ContactParams const & ) const

default

Member Data Documentation

◆ collidingPenaltyLengthScale

real superdex::ContactParams::collidingPenaltyLengthScale = 1_r

[Experimental] Length scale [m] used to correct the penalty coefficient when the colliding body integrates contact traction over a lower-than-two-dimensional manifold, such as a rod or point mass.

E.g., the penalty is scaled by this value if the colliding body lumps contact tractions on a line, or this value squared if lumping contact forces on a point.

Warning: Contact with lower-dimensional bodies is an experimental feature. It may be changed or removed in the future. Use at your own risk.

Note: This value is not used in the most common case, where contact traction is integrated over a two-dimensional surface.; The colliding body's value is always used in a contact pair, because the colliding body determines the dimension of the contact traction integral.

Definition at line 259 of file contact_params.h.

◆ coulombFrictionCoefficient

real superdex::ContactParams::coulombFrictionCoefficient = 0.5_r

Coulomb friction coefficient (dimensionless).

Note: Must not be negative.; Both viscousFrictionCoefficient and coulombFrictionCoefficient can be >0.; The Coulomb friction coefficient used in a collision is the geometric mean of the colliding and collider's coefficients. This disables Coulomb friction if either of them does.

Definition at line 179 of file contact_params.h.

◆ distanceErrorBound

real superdex::ContactParams::distanceErrorBound = 0_r

[Experimental] Padding [m] added to the collider's bounding volume for collision culling.

Warning: This is an experimental feature. It may be changed or removed in the future. Use at your own risk.

Note: Useful, for example, with approximate SDFs (e.g., deep flow map) to compensate for potentially overestimating the true distance.

Definition at line 234 of file contact_params.h.

◆ frictionFalloffVel

real superdex::ContactParams::frictionFalloffVel = 0.01_r

Velocity threshold for Coulomb friction smoothing [m/s].

For C1Regularized, the Coulomb friction force smoothly transitions from 0 to full strength as tangential velocity increases from 0 to frictionFalloffVel (compact support). For CinfRegularized, the force asymptotically approaches full strength with no compact support boundary; frictionFalloffVel controls the regularization scale.

Note: Must not be negative. For CinfRegularized, a value of zero is clamped internally to avoid numerical issues.; Smaller velocity thresholds improve physical accuracy but may degrade stability.; The velocity threshold used in a collision is the geometric mean of the colliding and collider's thresholds. The exception is if the collider is static, in which case the colliding's threshold is used.

Definition at line 196 of file contact_params.h.

◆ frictionWithColliderNormal

bool superdex::ContactParams::frictionWithColliderNormal = true

Use collider's normal (normalized SDF gradient) for friction direction if true, or the colliding's surface normal at the sample point if false.

Note: For co-dimensional colliding actors with ambiguous normals, the collider's normal is always used regardless of frictionWithColliderNormal.

Definition at line 144 of file contact_params.h.

◆ maxAlignmentNormals

real superdex::ContactParams::maxAlignmentNormals = 0_r

Maximum normal alignment threshold.

Normal alignment is defined as the dot product between colliding and collider normals. Contact is disabled for sample points whose normal alignment exceeds this threshold. This prevents sample points from being trapped inside the collider when penetration is large.

Note: Valid range is [-1, 1]. -1 allows contact only for perfectly opposing normals, 1 allows all contacts.; For co-dimensional colliding actors with ambiguous normals, contact is not disabled regardless of maxAlignmentNormals (normal alignment cannot be computed).

Definition at line 158 of file contact_params.h.

◆ normalViscousDampingCoefficient

real superdex::ContactParams::normalViscousDampingCoefficient = 0_r

Normal viscous damping coefficient [s/m].

Damping force in the normal direction, proportional to the elastic normal contact force and the normal velocity. Analogous to viscousFrictionCoefficient but acting in the normal direction instead of tangentially.

Warning: The calibration diverges as CoR approaches zero, which may cause numerical problems when approaching fully-inelastic collisions.

Note: Must not be negative.; The normal viscous damping coefficient used in a collision is the geometric mean of the colliding and collider's coefficients. This disables normal damping if either of them does.; The resulting coefficient of restitution (CoR) is velocity-dependent. For a characteristic impact velocity, experimental::CalibrateNormalViscousDampingCoefficient computes the coefficient that approximates a target CoR, while experimental::EffectiveCoefficientOfRestitution recovers the CoR produced by a coefficient.; Because the damping force depends on the normal velocity at each contact point, it also introduces rolling resistance: a body rolling on a surface dissipates energy through the differing normal velocities across its contacting region.

Definition at line 220 of file contact_params.h.

◆ objScale

real superdex::ContactParams::objScale = 1_r

[Experimental] Object scale relative to default size (dimensionless).

Used by deep flow only.

Warning: Deep flow is an experimental feature. It may be changed or removed in the future. Use at your own risk.

Definition at line 243 of file contact_params.h.

◆ penaltyCoefficient

real superdex::ContactParams::penaltyCoefficient = 1e9_r

Stiffness of the contact penalty force [Pa/m].

Note: Must be strictly positive.; Higher penalties create stiffer contacts and reduce penetration.; Arbitrarily large penalties may degrade stability.; The default penalty is appropriate for actors with default density. For actors with much higher/lower density than the default density, the penalty coefficient may need to be increased/decreased accordingly.; The penalty coefficient used in a collision is the geometric mean of the colliding and collider's coefficients. The exception is if the collider is static, in which case the colliding's penalty is used.; The penalty coefficient is additionally scaled by length-scale corrections when the colliding or collider integrates contact over a non-2D manifold (e.g., rod, shell). See collidingPenaltyLengthScale.

Definition at line 94 of file contact_params.h.

◆ penaltySmoothingHalfDistance

real superdex::ContactParams::penaltySmoothingHalfDistance = 0.005_r

PolyReLU smoothing half-width [m].

The penalty force transitions from 0 to linear over the decreasing distance range (penaltyThreshold, penaltyThreshold - 2 * penaltySmoothingHalfDistance).

Note: Must not be negative.; Larger smoothing distances improve stability but may increase penetration.; Smoothing distance is expected to be small relative to the collider geometry.

Definition at line 106 of file contact_params.h.

◆ penaltyThresholdDefault

real superdex::ContactParams::penaltyThresholdDefault = 0.001_r

Default contact detection threshold [m].

The penalty force transitions from 0 to linear over the decreasing distance range (penaltyThreshold, penaltyThreshold - 2 * penaltySmoothingHalfDistance).

Note: Negative values are legal.; If the colliding actor has ColliderType::None or ColliderType::PointCloud, penaltyThreshold = penaltyThresholdDefault + penaltyThresholdExtraPadding. Otherwise, penaltyThreshold = penaltyThresholdDefault.

See also: penaltyThresholdExtraPadding, GetPenaltyThresholdDist

Definition at line 121 of file contact_params.h.

◆ penaltyThresholdExtraPadding

real superdex::ContactParams::penaltyThresholdExtraPadding = 0_r

Extra padding [m] added to the default contact detection threshold if the colliding actor has ColliderType::None or ColliderType::PointCloud.

Note: Must not be negative.; Extra padding is useful to avoid tunneling through thin actors when the other actor has ColliderType::None or ColliderType::PointCloud.

See also: penaltyThresholdDefault, GetPenaltyThresholdDist

Definition at line 133 of file contact_params.h.

◆ viscousFrictionCoefficient

real superdex::ContactParams::viscousFrictionCoefficient = 0_r

Viscous friction coefficient [s/m].

Note: Friction force is proportional to contact force and tangential velocity.; Must not be negative.; Both viscousFrictionCoefficient and coulombFrictionCoefficient can be >0.; The viscous friction coefficient used in a collision is the geometric mean of the colliding and collider's coefficients. This disables viscous friction if either of them does.

Definition at line 169 of file contact_params.h.

The documentation for this struct was generated from the following files:

Public Member Functions

Public Attributes