DOCSEARCHbyAlgolia
Submit Docs

ZOZO's Contact Solver

repository·main·Indexed 24 days ago

https://github.com/st-tech/ppf-contact-solver

A high-performance, GPU-accelerated physics engine for contact resolution in simulations involving fabrics, solids, rods, and sand. It includes a Blender 5.0+ addon that communicates with a Rust-based server (ppf-cts-server) via TCP to perform simulations using various material models such as ARAP and Baraff-Witkin. The system supports remote solver connections via SSH, Docker, and local transports, and provides tools for pin operations, invisible colliders, and headless integration testing.

Tokens
118.1K
Snippets
191
Records
594
Agent score
89%

What's inside ppf-contact-solver

  1. Overview of Blender Add-on Integration Surfaces

    main

    The Blender add-on provides three primary integration entry points that all share the same validation layer and transport to ppf-cts-server:

    1. MCP Streamable HTTP server: A bundled server designed for external agents and automation.
    2. MCP-driven scene setup rules: Specific rules for setting up scenes via the Model Context Protocol.
    3. Python API: A native API exposed via bl_ext.user_default.ppf_contact_solver.ops.api for direct scripting within Blender.

  2. Overview of Constraints in the Blender Add-on

    main

    The Blender Add-on allows you to shape motion using three primary types of constraints:

    1. Pins: Pin specific vertices to control motion.
    2. Colliders: Introduce parametric collision boundaries that do not appear in the final scene.
    3. Snap & Merge: Stitch groups together or use snapping/merging mechanics.

    Detailed documentation for each constraint type is available in the dedicated sub-pages: pins, colliders, and snap_merge.

  3. Overview of ZOZO's Contact Solver Blender Addon

    main
    The ZOZO's Contact Solver Blender Addon is a physics-based contact simulation tool for Blender 5.0+. It operates by spawning a ppf-cts-server Rust binary (locally or remotely) and communicating via TCP. The addon transfers scene geometry and material parameters using CBOR envelopes and fetches animation results back into Blender to drive simulations.

  4. Overview of the Blender 5.0+ Add-on

    main
    The Blender 5.0+ add-on serves as a front-end for the ZOZO Contact Solver GPU-accelerated engine. It allows users to model scenes in Blender, assign material groups and pins, and then stream geometry and parameters to the solver engine (which can run locally or on a remote host). The add-on drives the simulation and fetches the resulting animation back into Blender.

  5. Overview of the Blender 5.0+ Add-on for Contact Solver

    main

    The Blender 5.0+ add-on serves as an interactive front-end for the ZOZO's Contact Solver GPU-accelerated contact simulation engine.

    Workflow Summary:

    1. Model in Blender: Assign material groups, pins, and colliders to your objects.
    2. Upload: The add-on uploads the scene to a ppf-cts-server instance.
    3. Simulate: The server runs the simulation.
    4. Fetch: The add-on fetches the resulting animation back into Blender, allowing you to scrub the simulation on the timeline.

  6. Overview of ZOZO's Contact Solver

    main
    ZOZO's Contact Solver is a robust, scalable contact solver for physics-based simulations. It supports various object types including shells (fabrics), solids, rods, rigid bodies, and sand. The solver is designed for high performance using GPU-accelerated FEM (Finite Element Method) and is capable of handling extreme scales (over 180M contacts).

  7. Overview of Contact Solver Repository Structure

    main

    ZOZO's Contact Solver is a GPU-accelerated contact simulation engine. The repository is organized into the following key components:

    • blender_addon/: A Blender 5.0+ front-end for modeling scenes, assigning material groups/pins, streaming geometry, and fetching animation. This package includes the LLM/ documentation tree.
    • crates/: A Rust workspace containing:
      • ppf-cts-core: Pure Rust data model, state machine, and numeric kernels.
      • ppf-cts-formats: Wire and file schemas.
      • ppf-cts-py: PyO3 bindings compiled to _ppf_cts_py cdylib.
      • ppf-cts-server: A standalone Rust binary (ppf-cts-server) that embeds the Python frontend and exposes the TCP/CBOR protocol used by the Blender add-on.
    • frontend/: A Python asset/scripting layer that imports _ppf_cts_py for in-process use (notebooks, tests, and ppf-cts-server).
    • docs/: The Sphinx-based HTML documentation site.

  8. Understand BVH construction behavior

    main
    The Bounding Volume Hierarchy (BVH) is not reconstructed at fixed intervals (e.g., every 10 frames). Instead, the BVH is continuously updated on the CPU in the background without blocking the simulation. At the start of each simulation step, the system checks if the background BVH construction is complete; if so, it updates the GPU buffer.

  9. Understand fabric preset physical parameters

    main

    The bundled fabric presets are defined by three physical behaviors:

    1. Drape: Measured by the Drape Coefficient (DC %). A low % indicates a soft, drapey fabric that collapses into deep folds. A high % indicates a stiff fabric that stays spread out.
    2. Bending: Measured by the cantilever tip droop angle (degrees). A higher angle indicates a more flexible fabric, while a lower angle indicates higher bending stiffness.
    3. Stretch: Described by young-mod (Young's modulus) and Poisson (Poisson's ratio) values, which define how the fabric stretches in its plane.

  10. Commercial use of ppf-contact-solver

    main

    The project is released under the Apache License 2.0.

    This allows you to:

    • Use, modify, and redistribute the code in commercial products.
    • Use it in proprietary software without paying royalties or being required to open-source your own code.

    Requirement: You must preserve the license notice and the attribution required by the Apache 2.0 license.

  11. Understand the Blender Python API proxy architecture

    main

    The fluent API acts as a thin layer of proxy objects over the add-on's operators and scene state. When writing scripts, follow these architectural constraints:

    • Attribute Access: solver.param provides access to whitelisted scene-level properties. Assigning an unknown name will raise an AttributeError.
    • Dynamic Parameters: Use solver.param.dyn(name) to obtain a dynamic-parameter builder.
    • Group Handles: solver.create_group(...) returns a handle where .param exposes the group's specific material/contact whitelist.
    • Pin Handles: group.create_pin(...) returns a handle where mutating methods return self to allow method chaining.
    • Builder Handles: Methods like solver.add_wall(...) and solver.add_sphere(...) return builder handles. The .time() cursor is tracked on the builder itself, and frames must be provided in strictly increasing order.

    Note: The underlying proxy types are internal. Do not use isinstance checks in your scripts; instead, rely on the documented attribute and method names.

  12. Understand the GitHub Actions CI pipeline

    main

    The project uses GitHub Actions to ensure the solver is penetration-free by performing explicit intersection checks at the end of each step. If an intersection is detected, the step raises an error.

    Available runner types:

    • Getting Started: Builds the solver and runs a single headless example on a fresh g6e.2xlarge AWS instance.
    • All Examples: Builds the solver and runs all examples in parallel, each on its own g6e.2xlarge AWS instance.
    • Blender CI: Exercises the Blender add-on on Linux and macOS runners. It uses Blender 5.1.1 and builds the Rust solver in CPU-emulated mode (no CUDA required). The add-on is installed as a Blender 5 extension.