Vortex Studio SDK Classes Documentation
Vx::VxMaterialBase Class Referenceabstract

Provides methods allowing the user to specify all physical properties of a Vx::VxMaterial or Vx::VxContactMaterial. More...

#include <Vx/VxMaterialBase.h>

Inheritance diagram for Vx::VxMaterialBase:

## Public Types

enum  FrictionAxis {
kFrictionAxisLinearPrimary = 0, kFrictionAxisLinearSecondary, kFrictionAxisAngularNormal, kFrictionAxisAngularPrimary,
kFrictionAxisAngularSecondary, kFrictionAxisCount, kFrictionAxisLinear
}
Friction axis settings. More...

enum  FrictionModel {
kFrictionModelBox, kFrictionModelScaledBox, kFrictionModelBoxProportionalLow, kFrictionModelBoxProportionalHigh,
kFrictionModelScaledBoxFast, kFrictionModelNeutral, kFrictionModelNone
}
Friction models available on each friction axis. More...

## Public Member Functions

Returns the maximum adhesive force in the normal contact direction. More...

double getBoxFrictionForce (FrictionAxis axis) const
Returns the maximum allowed friction force or torque for the specified friction axis. More...

double getCompliance () const
Returns the compliance parameter value. More...

double getDamping () const
Returns the damping parameter value. More...

double getFrictionCoefficient (FrictionAxis axis) const
Returns the friction coefficient for the friction axis. More...

FrictionModel getFrictionModel (FrictionAxis axis) const
Returns the friction model for this contact. More...

double getRestitution () const
Sets the value of impact restitution, or bounciness. More...

double getRestitutionThreshold () const
Sets the value of the normal incident contact velocity over which contacting objects are considered to be impacting each other. More...

double getSlide (FrictionAxis axis) const
Returns the force relative velocity between constrained parts along or around the specified axis. More...

double getSlip (FrictionAxis axis) const
Returns the slip parameter value for Z-axis friction. More...

double getStaticFrictionScale (FrictionAxis axis) const
Returns the static friction force scaling factor. More...

void * getUserData () const
Returns the contact material variable for storing user data.

bool isCompliant () const
Returns if this contact is compliant or not. More...

virtual void reset ()
Initializes the contact parameters structure to default values. More...

Sets the maximum adhesive force in the normal contact direction for this contact type. More...

void setBoxFrictionForce (FrictionAxis axis, double maxForce)
Sets the maximum allowed friction force or torque for the specified friction axis. More...

void setCompliance (double param)
Sets the normal contact compliance parameter value. More...

void setDamping (double param)
Sets the damping parameter value. More...

void setFrictionCoefficient (FrictionAxis axis, double coeff)
Sets the friction coefficient for the friction axis. More...

void setFrictionModel (FrictionAxis axis, FrictionModel inModel)
Sets the friction model for this contact. More...

void setRestitution (double param)
Sets the impact restitution coefficient (bounciness) for this contact type. More...

void setRestitutionThreshold (double param)
Sets the value of the normal incident contact velocity over which contacting objects are considered to be impacting each other. More...

void setSlide (FrictionAxis axis, double inSlide)
Sets the force relative velocity between constrained parts along or around the specified axis. More...

void setSlip (FrictionAxis axis, double inSlip)
Sets the slip parameter value for Z-axis friction. More...

void setStaticFrictionScale (FrictionAxis axis, double scale)
Sets the static friction (stiction) force scaling factor. More...

void setUserData (void *data)
Sets the contact material variable for storing user data.

Public Member Functions inherited from Vx::VxBase
virtual const char * getClassName () const =0
Returns the class name.

unsigned int getCreationIndex () const
Access the creation index of the instance.

const char * getName () const
Retrieves the name. More...

void setCombinedName (const char *base, const char *name, size_t i=0)
Utility to set the name to a concatenate string = base_name_i.

virtual void setName (const char *name)
Sets the name.

## Protected Member Functions

virtual void updateValue ()=0
Called whenever a parameter value is changed in the VxMaterialBase.

## Friends

VXCORE_SYMBOL bool operator!= (const VxMaterialBase &iLeft, const VxMaterialBase &iRight)
Inequality operator.

VXCORE_SYMBOL bool operator== (const VxMaterialBase &iLeft, const VxMaterialBase &iRight)
Equality operator.

Static Public Member Functions inherited from Vx::VxBase
static Subscriber * getConstructorSubscriber ()
Returns default static VxBase Subscriber that is be called each time an instance of VxBase is create.

static void setConstructorSubscriber (Subscriber *inSub)
Sets a default static VxBase Subscriber that will be called each time an instance of VxBase is create.

## Detailed Description

Provides methods allowing the user to specify all physical properties of a Vx::VxMaterial or Vx::VxContactMaterial.

This includes parameters which govern the computation of the normal contact forces which prevent penetration between solid objects, parameters governing the computation of the tangential contact force which lies in the separating plane, as well as parameters controlling the computation of impulses at impact points.

The configuration geometry of a contact constraint includes a plane defined by a contact point and a normal vector. The relative velocity between contacting bodies projected onto the contact normal is the incident velocity. The contact plane itself is spanned by an orthogonal basis formed by the primary and secondary contact directions. By default, the primary contact direction is aligned along the X-axis. The secondary contact direction is always computed internally so as to complete the orthogonal basis.

The contact force contains two main components: the normal force which prevents penetration; and the tangential force.

By default, the normal force computed by Vortex corresponds to very hard, almost perfectly rigid contacts, and is non-adhesive. This can be adjusted using the setCompliance(), setDamping(), and setAdhesiveForce() methods:

Also relevant to the normal force are the restitution and restitution threshold values, which you can set with the setRestitution() and setRestitutionThreshold() methods.

The tangential force can be zero to simulate frictionless contacts, maintained along the primary direction only to simulate a perfectly sliding skate, or planar, which is the most common case.

The value of the tangential force is controlled by a number of parameters. Several options controlling the friction model are provided for the user to tune according to specific needs.

VxMaterial
VxContactMaterial
VxMaterialTable

## Member Enumeration Documentation

Friction axis settings.

These settings allow you to define how friction will affect the contact point, which can potentially constrain up to six degrees of freedom between the colliding objects.

Enumerator
kFrictionAxisLinearPrimary

Friction force in contact plane along the primary axis.

kFrictionAxisLinearSecondary

Friction force in contact plane along secondary axis.

kFrictionAxisAngularNormal

Friction torque around the normal axis (this simulates spinning friction)

kFrictionAxisAngularPrimary

Friction torque around the primary axis (this simulates rolling resistance)

kFrictionAxisAngularSecondary

Friction torque around the secondary axis (this simulates rolling resistance)

kFrictionAxisCount

Number of axes with friction.

kFrictionAxisLinear

Friction in the whole plane.

This sets the whole friction plane (kFrictionAxisLinearPrimary and kFrictionAxisLinearSecondary) in a single function call.

Friction models available on each friction axis.

The kFrictionModelNone value is used only for contact merging and has minimum priority; kFrictionModelNone has the highest.

Enumerator
kFrictionModelBox

Box friction model.

Friction is limited with a specified force.

This model generates the friction forces or torque within predefined boundary limits. In the friction plane, this has the effect of replacing the friction cone of Coulomb friction with a box.

The drawback of this model is that the same force is used for all objects. A reasonable value for the force would be partMass * gravity. This means that using this material for two parts with very different masses will result in very different behaviour.

Note
The kFrictionModelBox, kFrictionModelBoxProportionalLow, and kFrictionModelBoxProportionalHigh models are very quick in execution but have limited accuracy because the pressure on the contact is not considered (at the time when friction boundaries have to be specified, the pressure is not yet known).
setBoxFrictionForce
kFrictionModelScaledBox

Scaled box friction model (to simulate Coulomb friction).

Friction is limited by friction coefficient * normal force.

This model is similar to the kFrictionModelBox friction model, but provides a better approximation of Coulomb friction.

With this model, the dynamic solver is invoked for more than one solving step. After each step, Vortex uses the computed contact normal force to evaluate the friction boundary:

friction boundary = friction coefficient * normal force magnitude
kFrictionModelBoxProportionalLow

Box proportional friction model.

Friction force is limited with specified acceleration * min(colliding part's mass).

This model generates the friction forces or torque within predefined boundary limits. The difference is that the force will be scaled by the lightest part's mass between the two colliding parts. If one of the parts is not a dynamic part, the dynamic part's mass will be used. In other words, the force argument passed in calls to the setBoxFrictionForce() method is interpreted as a bound on acceleration.

setBoxFrictionForce
kFrictionModelBoxProportionalHigh

Box proportional friction model.

Friction force is limited with specified acceleration * max(colliding part's mass).

This model is similar to kFrictionModelBoxProportionalLow. The major difference is that the heaviest part's mass is being used; therefore, use this model carefully. This model would be appropriate in a case, for example, where a gripper tries to grasp an object that is heavier than the gripper's finger part mass. In such a case, the kFrictionModelBoxProportionalHigh model adapts the friction according to the grasped part. The box friction force has to be set for this model.

setBoxFrictionForce
kFrictionModelScaledBoxFast

Scaled box friction model.

If this is a new contact, it behaves like kFrictionModelScaledBox; otherwise it uses the friction cap from the previous frame.

This model is similar to kFrictionModelScaledBox, but if a contact can be identified from a previous frame, the previous normal force is used to compute the friction boundary for the upcoming step, and the model will revert to kFrictionModelBox. If the contact is new or unmatched, Vortex reverts to the standard kFrictionModelScaledBox model.

This model is in fact an evolutive model, since for permanent contact the accuracy of the friction boundary improves at each step while using the same computation time as the box model.

kFrictionModelNeutral

Undefined.

Ignored when merging two contact properties.

kFrictionModelNone

No friction.

## Member Function Documentation

inline

Returns the maximum adhesive force in the normal contact direction.

Adhesive force allows objects to stick together, as if they were glued.

materials overview page in Vortex SDK
 double Vx::VxMaterialBase::getBoxFrictionForce ( FrictionAxis axis ) const
inline

Returns the maximum allowed friction force or torque for the specified friction axis.

Returns the max friction force used for the specified friction axis.

setBoxFrictionForce()
materials overview page in Vortex SDK

This value is only used if the corresponding model is set to kFrictionModelBox.

setBoxFrictionForce()
 double Vx::VxMaterialBase::getCompliance ( ) const
inline

Returns the compliance parameter value.

Compliance is the inverse of stiffness.

setCompliance()
materials overview page in Vortex SDK
 double Vx::VxMaterialBase::getDamping ( ) const
inline

Returns the damping parameter value.

setDamping()
materials overview page in Vortex SDK
 double Vx::VxMaterialBase::getFrictionCoefficient ( FrictionAxis axis ) const
inline

Returns the friction coefficient for the friction axis.

Returns the friction coefficient used for the specified friction axis.

This is used in conjunction with the kFrictionModelScaledBox model.

setFrictionCoefficient()
materials overview page in Vortex SDK

This value is only used if the corresponding model is set to kFrictionModelScaledBox.

setFrictionCoefficient()
 VxMaterialBase::FrictionModel Vx::VxMaterialBase::getFrictionModel ( FrictionAxis axis ) const
inline

Returns the friction model for this contact.

Returns the FrictionModel used for the specified friction axis.

setFrictionModel()
materials overview page in Vortex SDK
setFrictionModel()
 double Vx::VxMaterialBase::getRestitution ( ) const
inline

Sets the value of impact restitution, or bounciness.

setRestitution()
materials overview page in Vortex SDK
 double Vx::VxMaterialBase::getRestitutionThreshold ( ) const
inline

Sets the value of the normal incident contact velocity over which contacting objects are considered to be impacting each other.

materials overview page in Vortex SDK
 double Vx::VxMaterialBase::getSlide ( FrictionAxis axis ) const
inline

Returns the force relative velocity between constrained parts along or around the specified axis.

Returns the slide used for the specified friction axis.

The default value is 0.

setSlide()
materials overview page in Vortex SDK
setSlide()
 double Vx::VxMaterialBase::getSlip ( FrictionAxis axis ) const
inline

Returns the slip parameter value for Z-axis friction.

Returns the slip used for the specified friction axis.

Positive values of

setSlip()
materials overview page in Vortex SDK
setSlip()
 double Vx::VxMaterialBase::getStaticFrictionScale ( FrictionAxis axis ) const
inline

Returns the static friction force scaling factor.

Returns the stiction force scaling factor.

setStaticFrictionScale()
materials overview page in Vortex SDK
setStaticFrictionScale()
 bool Vx::VxMaterialBase::isCompliant ( ) const

Returns if this contact is compliant or not.

To be compliant, a contact has a compliance that is not zero or a damping that is not zero.

 virtual void Vx::VxMaterialBase::reset ( )
virtual

Initializes the contact parameters structure to default values.

These are the values that usually remain constant over a contact's lifetime. The default values for all axes are listed in the page.

 void Vx::VxMaterialBase::setAdhesiveForce ( double param )

Sets the maximum adhesive force in the normal contact direction for this contact type.

Non-zero maximum adhesive force allows objects to stick together and resist separation as if they were glued. The maximum adhesive force of the contact property is the minimum force required to separate the two objects in contact.

materials overview page in Vortex SDK
 void Vx::VxMaterialBase::setBoxFrictionForce ( FrictionAxis axis, double maxForce )

Sets the maximum allowed friction force or torque for the specified friction axis.

The default value is set to 0.

The values set here apply only when using the kFrictionModelBox model is in use.

materials overview page in Vortex SDK
 void Vx::VxMaterialBase::setCompliance ( double param )

Sets the normal contact compliance parameter value.

Compliance is the inverse of stiffness.

This replaces the default hard contact type with one which yields elastically under external pressure, producing slight interpenetration. The damping rate of the oscillations is set using the setDamping() function.

materials overview page in Vortex SDK
 void Vx::VxMaterialBase::setDamping ( double param )

Sets the damping parameter value.

This corresponds to the normal velocity viscous drag coefficient of a contact type.

This variable controls a normal viscous drag force proportional to the normal contact speed. Sufficient damping is necessary to prevent increasing the energy of the system during collisions.

Nearly optimal value of damping is given by the following, where time_step is the time step of your simulation, and compliance is the value of this normal contact compliance:

$$damping = 5 * time_step/compliance$$

setCompliance()
materials overview page in Vortex SDK
 void Vx::VxMaterialBase::setFrictionCoefficient ( FrictionAxis axis, double coeff )

Sets the friction coefficient for the friction axis.

This is used in conjunction with the kFrictionModelScaledBox model. The default value is 0.

Friction forces are computed independently along each direction in the contact plane and torque can be computed along the three axes of the contact frame to simulate spinning friction and rollong resistance.

For friction in the friction plane, this leads to a small anisotropy (direction-dependence) such that there is an error of at most a factor of sqrt(2) between the actual magnitude of the tangential force vector and the theoretical maximum value which is the product of the friction coefficient and the normal contact force.

The scaled box model essentially replaces the standard Coulomb cone by a pyramid aligned with the principal and secondary contact directions. Anisotropy can be reduced by setting the primary direction in a intersect subscriber to be aligned with the tangential contact force of the last time step.

For spinning friction and rolling resistance, the friction coefficient is such that it will limit the corresponding friction torque to $$T = coeff*Fn$$ where Fn represents the contact force along the normal and coeff has the dimension of length.

For rolling resistance, the resulting force is $$Frr = Trr/R = coeff*Fn/R$$ where R represents the radial distance between the part's COM and the contact position. The rolling resistance friction coeff as set in Vortex has the dimension of length and $$coeff = Crr * r$$ with Crr the unitless coefficient of rolling resistance and r the surface radius of curvature.

Note
In this case r and R are the same for a sphere or a rolling cylinder but would be different otherwise. For a wheel case, if Crr is known, $$Crr * wheel_radius$$ should be provided.
materials overview page in Vortex SDK
 void Vx::VxMaterialBase::setFrictionModel ( FrictionAxis axis, FrictionModel inModel )

Sets the friction model for this contact.

materials_friction_model
 void Vx::VxMaterialBase::setRestitution ( double param )

Sets the impact restitution coefficient (bounciness) for this contact type.

When a collision occurs between two solid bodies, they experience an almost instantaneous change in momentum. The fraction of net incident momentum lost during this change is the coefficient of restitution and it measures the degree of elasticity of the pair of contacting bodies. When restitution is 0, all the momentum on the contact plane is dissipated. When it is 1, the net momentum is conserved, and so is the kinetic energy.

Because the Vortex stepper resolves impacts and collision at the same time as ordinary forces, and because it catches contacts after the fact, it is possible that high velocity impacts violate energy conservation by a small amount. This is never a problem if restitution is small enough and the normal contact compliance and damping parameters have been left to their default or set to a sensible value. However, when restitution is set to 1, the total energy of the system may increase slightly at each impact. Strict energy conservation at each step would require much more computational effort and it is therefore recommended to set the value restitution conservatively.

Vortex will only add restitution when the incident normal velocity is above a given threshold.

setDamping()
setRestitutionThreshold()
materials overview page in Vortex SDK
 void Vx::VxMaterialBase::setRestitutionThreshold ( double param )

Sets the value of the normal incident contact velocity over which contacting objects are considered to be impacting each other.

If they are impacting each other, an impulse is applied to produce the given restitution.

setRestitution()
materials overview page in Vortex SDK
 void Vx::VxMaterialBase::setSlide ( FrictionAxis axis, double inSlide )

Sets the force relative velocity between constrained parts along or around the specified axis.

The default value is 0.

materials overview page in Vortex SDK
 void Vx::VxMaterialBase::setSlip ( FrictionAxis axis, double inSlip )

Sets the slip parameter value for Z-axis friction.

Positive values of slip introduce a viscous drag force in the contact plane. The value of the drag coefficient is the inverse of the slip set here.

In other words, the slip coefficient is the proportionality constant relating the contact velocity along one of the contact directions and the corresponding tangential contact force. More precisely, $$v = -sF$$, where v is the tangential contact velocity along one of the planar contact directions, s is the value of the slip coefficient, and F is the magnitude of the corresponding tangential force.

When the slip value is too high, true static friction is no longer possible. The minimum value of the contact slip is the same as the global value of the constraint linear or angular kinetic loss as set in VxSolverParameters.

Contact slip is useful for simulating tires on non-spherical wheels. Small but non-zero slip introduces creep in the contact and this can allow a non-spherical wheel to turn with less force. However, when simulating the wheel of a car, for instance, it is preferable to set different slip parameter for the primary and secondary directions.

Finally, the slip can also be interpreted as the inverse of the gain of a PD controller aiming at eliminating the relative velocity corresponding to axis.

materials overview page in Vortex SDK
 void Vx::VxMaterialBase::setStaticFrictionScale ( FrictionAxis axis, double scale )

Sets the static friction (stiction) force scaling factor.

The default value is 1.

If the friction model is set to kFrictionModelBox, the stiction force will be limited to the value of $$scale * BoxFrictionForce$$

If the friction model is set to kFrictionModelScaledBox, the stiction force will be limited to the value of $$scale * FrictionCoefficient * normalContactForce$$

Stiction mode in the friction plane is enabled if the colliding objects are not sliding at all collision points. Stiction modes for rolling resistance and spin friction are only enabled if there is no sliding in the friction planes and contact matching is enabled.