Skip to main content

Crate rapier_cloth_core

Crate rapier_cloth_core 

Source
Expand description

§rapier-cloth-core

An engine-independent CPU cloth solver using extended position-based dynamics (XPBD). It provides triangle meshes, area-based masses, edge-length and dihedral bending constraints, fixed vertices, external forces and collision-source interfaces. The default solver’s only normal dependency is glam. The optional implicit feature adds faer and nalgebra for an experimental global shell solve (f64 only).

For Rapier collision queries, attachments and time synchronization, use rapier-cloth.

§Use

[dependencies]
rapier-cloth-core = "0.3"

A repository checkout also works as a path dependency (rapier-cloth-core = { path = "../rapier-cloth/crates/rapier-cloth-core" }).

Requires Rust 1.90 or newer. Select exactly one precision: f32 is the default; for f64, add default-features = false, features = ["f64"]. Do not use --all-features.

use rapier_cloth_core::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mesh = GridBuilder::new(32, 32).origin(Vec3::Y).build()?;
    let mut cloth = Cloth::new(mesh, ClothMaterial::default())?;
    for i in 0..32 {
        cloth.pin(i, cloth.positions()[i as usize])?;
    }
    let mut solver = Solver::new();
    solver.step(
        &mut cloth,
        1.0 / 240.0,
        -Vec3::Y * 9.81,
        &SolverSettings::default(),
    )?;
    assert_eq!(cloth.surface().positions.len(), 1024);
    Ok(())
}

This example has gravity and pins but no external collision source. The caller owns the substep loop and rendering. Mesh topology is fixed. Experimental discrete self-collision can be enabled with cloth.set_contact_settings(Some(ClothContactSettings::default()))?. This separates nonincident vertex-face and edge-edge features using a physical thickness (default 1 mm). It rejects initial intersections and uses bounded, refitted candidate searches. Setting continuous_self_collision: true also checks prediction and every accepted constraint-correction batch. This experimental mode can return a typed failure when a safe advance cannot be found; it has not qualified the complete folding task or its real-time performance. Experimental XPBD surface friction retains static/kinetic contact history. The Rapier adapter offers opt-in discrete whole-triangle rigid contacts through the core’s generalized surface interface. Its candidates share the configured work budget with self-collision. The core contains no rigid-shape queries; rigid_surface_collision selects this behavior only in an adapter that supports it. Tearing is not implemented. Material compliance describes discrete constraints and requires tuning with the chosen grid, time step and iteration count.

For a separate continuum shell model, enable f64,implicit and call cloth.set_implicit_solver(Some(ImplicitSettings::default()))?. This selects a global backward-Euler solve with a Neo-Hookean membrane, dihedral bending, positive-gap barrier and lagged smoothed Coulomb friction. Hard particle targets are supported; soft and weighted targets are rejected. It requires positive initial clearance, a positive activation margin and continuous contact checks. Its smoothed kinetic friction permits creep and does not enforce exact sticking. See the repository’s implicit solver guide for the optional ImplicitExecution::Parallel4 CPU budget (serial by default), checkpoint/recovery behavior, physical settings, the complete towel fixture and qualification limits.

See the repository’s documentation and examples.

Licensed under the MIT License.

Re-exports§

pub use math::Real;
pub use error::ClothError;
pub use material::ClothMaterial;
pub use mesh::ClothMesh;
pub use mesh::GridBuilder;
pub use garment::Garment;
pub use garment::GarmentLayers;
pub use garment::TShirtPattern;
pub use collision::ClothContactSettings;
pub use collision::CollisionBudgetKind;
pub use collision::CollisionLimits;
pub use collision::CollisionWork;
pub use implicit::ImplicitCapPolicy;
pub use implicit::ImplicitExecution;
pub use implicit::ImplicitOutcome;
pub use implicit::ImplicitSettings;
pub use implicit::ImplicitTermination;
pub use implicit::ShellMaterial;
pub use cloth::Cloth;
pub use cloth::ClothHandle;
pub use cloth::ClothSet;
pub use constraints::target::SurfaceTarget;
pub use contact::Contact;
pub use contact::ContactKey;
pub use contact::ContactMotion;
pub use contact::ContactSource;
pub use contact::ContactStage;
pub use contact::NoContacts;
pub use contact::SurfaceContact;
pub use contact::SurfaceContactKey;
pub use contact::SurfaceFeature;
pub use diagnostics::StepReport;
pub use solver::Solver;
pub use solver::SolverSettings;
pub use solver::Target;
pub use surface::SurfaceHit;
pub use surface::SurfacePoint;
pub use surface::SurfaceQueryLimits;
pub use surface::SurfaceRay;
pub use surface::SurfaceView;

Modules§

cloth
collision
Surface contact geometry, independent of any rigid-body engine.
constraints
contact
diagnostics
error
garment
Parametric garments built as flat-folded cloth meshes.
implicit
Experimental global implicit shell solver. Enable with the implicit feature. The f64 path supports hard particle grasps and finite-thickness surface contact. Neo-Hookean membrane, discrete shell bending, finite-thickness barrier and lagged regularized Coulomb friction share one position objective.
material
math
Precision aliases independent of Rapier and Parry.
mesh
solver
surface

Structs§

Vec3
A 3-dimensional vector.