Vortex Studio SDK Classes Documentation

Provides methods allowing the user to specify all physical properties of a Vx::VxMaterial or Vx::VxContactMaterial. More...
#include <Vx/VxMaterialBase.h>
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  
double  getAdhesiveForce () const 
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 Zaxis 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...  
void  setAdhesiveForce (double param) 
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 Zaxis 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.  
Additional Inherited Members  
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.  
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 Xaxis. 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 nonadhesive. 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.
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

kFrictionModelScaledBox 
Scaled box friction model (to simulate Coulomb friction). Friction is limited by 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 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.

kFrictionModelBoxProportionalHigh 
Box proportional friction model. Friction force is limited with 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.

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. 

inline 
Returns the maximum adhesive force in the normal contact direction.
Adhesive force allows objects to stick together, as if they were glued.

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
.
This value is only used if the corresponding model is set to kFrictionModelBox.

inline 
Returns the compliance parameter value.
Compliance is the inverse of stiffness.

inline 
Returns the damping parameter value.

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.
This value is only used if the corresponding model is set to kFrictionModelScaledBox.

inline 
Returns the friction model for this contact.
Returns the FrictionModel used for the specified friction axis
.

inline 
Sets the value of impact restitution, or bounciness.

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

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.

inline 

inline 
Returns the static friction force scaling factor.
Returns the stiction force scaling factor.
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 
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.
Nonzero 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.
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.
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.
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 \)
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 (directiondependence) 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.
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.void Vx::VxMaterialBase::setFrictionModel  (  FrictionAxis  axis, 
FrictionModel  inModel  
) 
Sets the friction model for this contact.
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.
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.
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.
void Vx::VxMaterialBase::setSlip  (  FrictionAxis  axis, 
double  inSlip  
) 
Sets the slip parameter value for Zaxis 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 nonspherical wheels. Small but nonzero slip introduces creep in the contact and this can allow a nonspherical 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
.
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.