Contact Materials¶

Overview ¶

In simulation, the behavior of objects in contact with each other is determined by parameters such as friction and restitution coefficients. These parameters are properties determined by the combination of the materials of the objects in contact.

Choreonoid provides the “contact material” mechanism to handle this. In this mechanism, you first assign a “material”, which represents the material type, to each object (link). Then, for each combination of two materials, you define the parameters that determine the contact behavior as a “contact material”. The simulator items load these definitions, and the parameters corresponding to the combination of materials are applied when objects come into contact with each other.

This mechanism is supported by all simulator items, and basic parameters such as friction and restitution coefficients can be configured with the common description regardless of the physics engine used.

Defining Materials ¶

Materials and contact materials are defined in a material file in the YAML format. The standard definition file “default/materials.yaml” is provided in the share directory of Choreonoid.

A material file consists of two parts: materials, which defines the materials, and contact_materials, which defines the contact materials. The following is an example description.

materials:
  -
    name: Ground
    roughness: 1.0
    viscosity: 1.0
  -
    name: Ball
    roughness: 0.5
    viscosity: 0.36

contact_materials:
  -
    materials: [ Ground, Ball ]
    friction: 0.5
    restitution: 0.8

In materials, list the name of each material ( name ) and the physical properties of the material itself. In contact_materials, specify a pair of two material names with the materials key, and describe the parameters to be applied when a contact occurs with that combination.

Material Parameters¶

The main parameters available for each material in materials are as follows. The “Supported by” column shows the simulator items that interpret the parameter.

Parameter	Default value	Meaning	Supported by
`name`	(required)	The name of the material. It is used for assigning the material to links and for specifying the pairs of the contact materials.	All
`roughness`	0.5	A value representing the roughness of the surface. It is used to compute the friction coefficient for pairs for which no contact material is defined (see below).	All
`viscosity`	1.0	A value representing the viscosity of the surface. It is used to compute the restitution coefficient for pairs for which no contact material is defined (see below).	All
`stiffness`	0.0	The stiffness of the contact. When a value greater than 0 is set, contacts of the material are treated as soft (compliant) contacts with the specified stiffness.	PhysX / Bullet
`damping`	0.0	The damping of the compliant contacts described above. It is used when `stiffness` is set.	PhysX / Bullet
`density` , `youngs_modulus` , `surface_viscosity` , etc.	—	Additional parameters interpreted by the AGX simulator. See Additional Parameters for Physical Materials for details.	AGX

Contact Material Parameters¶

The main parameters available for each contact material in contact_materials are as follows.

Parameter	Default value	Meaning	Supported by
`materials`	(required)	The pair of the target material names, specified as a list of two material names. You can also target contacts between objects of the same material by specifying the same name twice.	All
`friction`	0.5	The friction coefficient. This value is set to both the static and dynamic friction coefficients.	All
`static_friction`	0.5	The static friction coefficient. Use this when you want to specify it separately from the dynamic friction coefficient.	All (see note)
`dynamic_friction`	0.5	The dynamic friction coefficient. The distinction between static and dynamic friction is supported by the AIST simulator, where they are switched according to the slipping state of each contact point.	AIST
`restitution`	0.0	The restitution coefficient. 0 means no restitution, and values closer to 1 result in more bouncing.	All
`cullingDistance`	simulator setting	The distance threshold of the contact point culling applied to this pair. It overrides the value of the “Contact culling distance” property of the AIST simulator for each pair.	AIST
`cullingDepth`	simulator setting	The depth threshold of the contact point culling applied to this pair. It overrides the value of the “Contact culling depth” property of the AIST simulator for each pair.	AIST
`max_num_contact_points`	simulator setting	The maximum number of contact points per link pair applied to this pair. It overrides the value of the “Max contact points” property of the AIST simulator for each pair.	AIST
`friction_model` , etc.	—	Additional parameters interpreted by the AGX simulator, such as the selection of the friction model and the solver. See Additional Parameters for Physical Materials for details.	AGX

(Note) When only static_friction is specified, the value of the static friction coefficient is used as the friction coefficient in the simulators other than AIST.

Each simulator simply ignores the parameters it does not support. This allows a material file containing parameters for a specific engine to be shared among multiple engines.

Handling of Combinations without a Contact Material ¶

It is not necessary to define contact materials for all combinations of materials. For combinations for which no contact material is defined, the friction and restitution coefficients are automatically computed from the roughness and viscosity values set for each material with the following formulas.

Let r1 be the roughness value of one material and r2 be the roughness value of the other material. Then the friction coefficient is

friction coefficient = √(r1 × r2)

Also, let v1 be the viscosity value of one material and v2 be the viscosity value of the other material. Then the restitution coefficient is

restitution coefficient = √((1 − v1) × (1 − v2))

That is, the rougher the materials are, the larger the friction becomes, and the less viscous the materials are, the more they bounce. This computation method is common to all simulator items.

Therefore, if you set roughness and viscosity appropriately for each material, you can obtain plausible contact behaviors without enumerating all the combinations. On top of that, you can define contact materials when you want to explicitly adjust the behavior of specific combinations.

Assigning Materials to Models ¶

Materials are assigned to links with the material key in body-format model files. For example, in the model of a ball (share/model/misc/ball.body), the Ball material is assigned to the link as follows.

links:
  -
    name: Ball
    ...
    material: Ball

Links for which no material is specified are treated as if the default material (Default) were assigned.

Application to Simulation ¶

The world item is in charge of loading material files. The world item loads the material file specified by the “Default material table” property and keeps it as the material table. The default value of this property is “${SHARE}/default/materials.yaml”, which is the standard definition file.

The simulator items obtain the material table from the world item at the start of the simulation and determine the contact parameters based on the combination of the materials assigned to the links. This mechanism works automatically if materials are assigned to the models, without any special configuration.

Customizing Material Definitions ¶

The standard definition file “default/materials.yaml” is the default definition used by the samples bundled with Choreonoid, and users are not expected to edit this file directly. If you want to add or modify material definitions, create your own material file and load it into the project.

Specifically, prepare a material file described in the format explained above, and load it from the main menu with “File” - “Load” - “Material Table” while the world item is selected. A material table item is then created, and you place it as a child item of the world item. The item tree becomes, for example, as follows.

[ ] - World
[/]   + Robot
[/]   + Floor
[ ]   + MaterialTable
[ ]   + AISTSimulator

With this configuration, the contents of the material table item are merged into the default material table. When you describe a material with the same name or a contact material with the same combination as the default definition, your definition takes precedence. Therefore, it is sufficient to describe only what you want to define or change in the additional material file.

Samples ¶

The following sample projects are provided for checking the effects of contact materials. Each sample contains the simulator items of the physics engines, and you can also compare the behaviors by switching the engines.

Ball¶

sample/general/Ball.cnoid is a simple sample in which a ball is dropped on the floor. The Ball material is assigned to the ball model, and the standard material definition sets the restitution coefficient of the contact material between Ground and Ball to 0.8, so you can observe the ball bouncing on the floor. The way the ball bounces changes when you change the restitution coefficient, so this sample can also be used as a practice for adjusting contact materials.

SR1WalkSlippy¶

sample/SimpleController/SR1WalkSlippy.cnoid is a version of the walking sample of the biped robot SR1 with a slippery floor. In this project, an additional material file SlippyMaterialSet.yaml is loaded as a material table item (SlippyMaterialSet) under the world item, and it overrides the friction coefficient of the contact material between the floor (Ground) and the soles (Sole) to 0.01. When you run the simulation, you can observe the soles slipping and the walking being disturbed. This sample is also a practical example of how to customize material definitions.