Simulation Config Example

Simulation Config Example#

Simulation config is a set of parameters that illustrate the composition of scene and describe how cloth behaves. It is composed of 3 parts:

  • pipeline: which pipeline to use. There are 3 pipelines by default: smpl, gltf and universal.

  • animation: animation settings, e.g., whether record animations, export format, etc.

  • solver: solver settings. There are 2 modes of solver: swift mode and quality mode.

Format#

A simulation config should follow the structure as shown below:

{
	"PIPELINE_NAME":
	{
		//...
	},
	"ANIMATION":
	{
		//...
	},
	"MODE_NAME":
	{
		//...
	}
}

Pipeline#

SMPL#

PARAM FIELD TYPE DEFAULT VALUE DESCRIPTION
CLOTH_STYLES Required vector - Name of clothes in assets to be simulated.
NPZ_PATH Required string - Path to body motion in npz format.
BODY_MODEL Required string - The body model used for simulation, e.g., SMPL, SMPLH, SMPLX.
NUM_LERPED_FRAMES Optional int 0 Number of frames that transform character from rest-pose to motion.
ENABLE_COLLISION_FILTER Optional bool false The collision of hands and head will be ignored when set to True.

GLTF#

PARAM FIELD TYPE DEFAULT VALUE DESCRIPTION
CLOTH_STYLES Required vector - Name of clothes in assets to be simulated.
CHARACTER_NAME Required string - Name of the character in assets.
GLTF_PATH Required string - Path to gltf file that contains keyframe animations.
NUM_LERPED_FRAMES Optional int 0 Number of frames that transform character from rest-pose to motion.

Universal#

PARAM FIELD TYPE DEFAULT VALUE DESCRIPTION
CLOTHES Required vector<CLOTH> - Clothes to be added to the scene.
OBSTACLES Required vector<OBSTACLE> - Obstacles to be added to the scene.
NUM_FRAMES Optional int 100 Number of frames to simulate.

in which the CLOTH and OBSTACLE are defined as follows:

  • CLOTH:

PARAM FIELD TYPE DEFAULT VALUE DESCRIPTION
OBJ_PATH Required string - Path to the cloth file in obj format.
POSITION Optional vec3 (0, 0, 0) Position of the cloth in world space.
ROTATION Optional vec3 (0, 0, 0) Euler rotation of the cloth in world space.
SCALE Optional vec3 (1, 1, 1) Scale of the cloth in world space.
ATTACHED_INDICES Optional vector<int> [] Indices of vertices to be fixed during the simulation.

  • OBSTACLE:

PARAM FIELD TYPE DEFAULT VALUE DESCRIPTION
OBJ_PATH Required string - Path to the obstacle file in obj format.
POSITION Optional vec3 (0, 0, 0) Position of the obstacle in world space.
ROTATION Optional vec3 (0, 0, 0) Euler rotation of the obstacle in world space.
SCALE Optional vec3 (1, 1, 1) Scale of the obstacle in world space.

Animation#

PARAM FIELD TYPE DEFAULT VALUE DESCRIPTION
NUM_PRE_SIMULATION_FRAMES Optional int 120 Number of warmup frames to pass-by before simulation.
RECORD_OBSTACLE Optional bool true Whether record obstacle animation.
RECORD_CLOTH Optional bool true Whether record cloth animation.
EXPORT_FORMAT Optional int 0 Animation file export format. 0: alembic; 1: obj sequence.
EXPORT_DIRECTORY Required string - Path to save synthesized animation.

Solver Mode#

Swift#

SCOPE PARAM FIELD TYPE DEFAULT VALUE DESCRIPTION
SOLVER NUM_SUBSTEPS Optional int 4 Number of steps that execute within a frame.
NUM_ITERATIONS Optional int 10 Number of solver iterations to perform per-substep.
MAX_SPEED Optional float 1e6f Maximum velocity of particles.
GRAVITY Optional vec3 (0.0f, -9.8f, 0.0f) Constant acceleration applied to all particles.
FABRIC STRETCH_COMPLIANCE Optional float 0.0f See Miles Macklin's blog. Gravity is strong enough to cause stretching, we recommend using zero compliance on cloth mesh edges with XPBD.
BEND_COMPLIANCE Optional float 10.0f Larger bend compliance results in larger bend resistance.
RELAXATION_FACTOR Optional float 0.25f Control the convergence rate of the Jacobi solver. If the value is too small, the solver will not converge, while value that is too large may lead to instability.
LONG_RANGE_STRETCHINESS Optional float 1.05f Control the maximum radius that particles can be reached.
GEODESIC_LRA Optional bool true Measurement of LRA. true: Geodesic distance; false: Euclidean distance.
SOLVE_BENDING Optional bool false Whether solve bending constraint.
COLLISION NUM_COLLISION_PASSES Optional int 10 Number of interleaved collisions. Higher iteration count results in better convergency with computational overhead.
SDF_COLLISION_MARGIN Optional float 0.01f Distance particles maintain against shapes.
BVH_TORLENCE float Optional 0.001f Slightly extend the BVH along the vertex normal.
COLLISION / PARTICLE FRICTION Optional float 0.1 Strength of friction.
MAX_NEIGHBOR_SIZE Optional int 64 Maximum number of neighbor particles to cache.
INTER_LEAVED_HASH Optional int 3 Hash once every n substeps. This can improves performance greatly.
ENABLE_SELF_COLLISION Optional bool true Whether enable self-collision between cloth vertices.
PARTICLE_DIAMETER Optional float 1.5f Multiply original stretch length by this scalar to obtain particle diameter.
HASH_CELL_SIZE Optional float 1.5f Multiply particle diameter by this scalar to obtain hash cell size.

Quality#

SCOPE PARAM FIELD TYPE DEFAULT VALUE DESCRIPTION
SOLVER NUM_SUBSTEPS Optional int 1 Number of steps that execute within a frame. Note that high step count may lead to instability.
NUM_ITERATIONS Optional int 200 Number of solver iterations to perform per-substep.
MAX_SPEED Optional float 1e6f Maximum velocity of particles.
GRAVITY Optional vec3 (0.0f, -9.8f, 0.0f) Constant acceleration applied to all particles.
DAMPING Optional float 0.98f Viscous drag force, applies a force proportional, and opposite to the particle velocity.
FABRIC XX_STIFFNESS Optional float 1.0f Stiffness in xx direction.
XY_STIFFNESS Optional float 1.0f Stiffness in xy direction.
YY_STIFFNESS Optional float 1.0f Stiffness in yy direction.
XY_POISSION_RATIO Optional float 0.3f Possion ratio in xy direction.
YX_POISSION_RATIO Optional float 0.3f Possion ratio in yx direction.
SOLVE_BENDING Optional bool false Whether solve bending constraint.
BENDING_STIFFNESS Optional float 1.0f Stiffness of bending constraint.
LONG_RANGE_STRETCHINESS Optional float 1.05f Control the maximum radius that particles can be reached.
GEODESIC_LRA Optional bool true Measurement of LRA. true: Geodesic distance; false: Euclidean distance.
REPULSION ENABLE_IMMINENT_REPULSION Optional bool true Whether enable imminent repulsions.
IMMINENT_THICKNESS Optional float 1e-3f Thickness of imminent repulsion.
ENABLE_PBD_REPULSION Optional bool true Whether enable PBD repulsions.
PBD_THICKNESS Optional float 1e-3f Thickness of PBD repulsion.
RELAXATION_RATE Optional float 0.25f Control the convergence rate of the repulsion solver.
IMPACT_ZONE OBSTACLE_MASS Optional float 1e3f Mass of obstacle.
THICKNESS Optional float 1e-4f Cloth collision thickness.
Contents