We recommend exploring the official CMake documentation to beginner CMake users, if they wish to build this project from source.
The Physics Based Animation Toolkit (PBAT) is a (mostly templated) cross-platform C++20 library of algorithms and data structures commonly used in computer graphics research on physically-based simulation in dimensions 1,2,3. For most use cases, we recommend using our library via its Python interface, enabling seamless integration into Python's ecosystem of powerful scientific computing packages.
Online documentation coming soon.
1,2,31,2,3Currently, the
masterbranch may contain breaking changes at any point in time. We recommend users to use specific git tags, i.e. viagit checkout v<major>.<minor>.<patch>, where the version<major>.<minor>.<patch>matches the installedpbatoolkit's version downloaded from PyPI (i.e. frompip install pbatoolkit).
We recommend downloading the Tracy profiler server to analyze execution of PBAT algorithms, available as precompiled executable. PBAT currently supports Tracy 0.10.
Take a look at the unit tests, found in the library's source (.cpp or .cu) files.
To download and install from PyPI, run in command line
pip install pbatoolkit
or, alternatively
pip install pbatoolkit-gpu
if your environment is properly setup to use our GPU algorithms.
Verify pbatoolkit's contents in a Python shell
import pbatoolkit as pbat
help(pbat.fem)
help(pbat.geometry)
help(pbat.profiling)
help(pbat.math)
help(pbat.gpu)
A bunch of Python scripts demonstrating usage of pbatoolkit can be found in the examples folder, along with their associated requirements.txt for easily downloading necessary dependencies via pip install -r path/to/requirements.txt. Their command line interface follows the pattern
python[.exe] path/to/examples/[example].py -i path/to/input/mesh
The full interface is always revealed by -h or --help, i.e.
python[.exe] path/to/examples/[example].py -h
The examples assume the user provides the meshes to
pbatoolkit. Triangle (surface) meshes can easily be obtained via Thingi10K, TurboSquid or authored yourself in Blender. Tools like TetWild, fTetWild and TetGen can then convert them into tetrahedral (volume) meshes. We provide helper scripts to facilitate mesh processing and their associatedrequirements.txt.
Example results are showcased in our Gallery.
Head over to our hands-on tutorials section to learn more about physics based animation in both theory and practice!
See vcpkg.json for a versioned list of our external dependencies, available via vcpkg.
Use of vcpkg is not mandatory, as long as external dependencies have compatible versions and are discoverable by CMake's
find_packagemechanism.
pbatoolkit-gpu (downloaded from PyPI) requires dynamically linking to an instance of the
Recall that the CUDA Runtime is ABI compatible up to major version.
On 64-bit Windows, these are cudart64_12.dll and nvcuda.dll. Ensure that they are discoverable via Windows' DLL search order. We recommend adding <drive>:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.<minor>\bin (i.e. the binary folder of your CUDA Toolkit installation) to the PATH environment variable. The driver should already be on the search path by default after installation.
On Linux, they are libcudart.so.12 and libcuda.so.1. Ensure that they are discoverable via Linux's dynamic linker/loader. If they are not already in a default search path, we recommend simply updating the library search path, i.e. export LD_LIBRARY_PATH="path/to/driver/folder;path/to/runtime/folder;$LD_LIBRARY_PATH".
MacOS does not support CUDA GPUs.
Our pbatoolkit-gpu prebuilt binaries include PTX, such that program load times will be delayed by JIT compilation on first use. Verify that your NVIDIA GPU supports compute capability at least 7.0. For example, only RTX 2060 up to 4090 chips are supported in the GeForce series. Runtime GPU performance may be constrained by the targeted compute capability.
Consider locally building and installing pbatoolkit against your native GPU for the following reasons.
| Option | Values | Default | Description |
|---|---|---|---|
PBAT_BUILD_PYTHON_BINDINGS | ON,OFF | OFF | Enable PhysicsBasedAnimationToolkit_PhysicsBasedAnimationToolkit Python bindings. Generates the CMake target PhysicsBasedAnimationToolkit_Python, an extension module for Python, built by this project. |
PBAT_BUILD_TESTS | ON,OFF | OFF | Enable PhysicsBasedAnimationToolkit_PhysicsBasedAnimationToolkit unit tests. Generates the CMake target executable PhysicsBasedAnimationToolkit_Tests, built by this project. |
PBAT_ENABLE_PROFILER | ON,OFF | OFF | Enable Tracy instrumentation profiling in built PhysicsBasedAnimationToolkit_PhysicsBasedAnimationToolkit. |
PBAT_PROFILE_ON_DEMAND | ON,OFF | OFF | Activate Tracy's on-demand profiling when PBAT_ENABLE_PROFILER is ON. |
PBAT_USE_INTEL_MKL | ON,OFF | OFF | Link to user-provided Intel MKL installation via CMake's find_package. |
PBAT_USE_SUITESPARSE | ON,OFF | OFF | Link to user-provided SuiteSparse installation via CMake's find_package. |
PBAT_BUILD_SHARED_LIBS | ON,OFF | OFF | Build project's library targets as shared/dynamic. |
Either run CMake's configure step manually
cmake -S <path/to/PhysicsBasedAnimationToolkit> -B <path/to/build> -D<option>=<value> ...
or, alternatively (and preferably)
cmake --preset=<my-favorite-user-preset>
Our project provides configuration presets that capture typical use configurations. For the best experience, install vcpkg and set VCPKG_ROOT=path/to/vcpkg as an environment variable. Then, you can select one of our available presets, for example cmake --preset=default. Refer to the CMake presets documentation for more information.
Build and install transparently across platforms using the cmake build CLI and cmake install CLI, respectively.
Our CMake project exposes the following build targets
| Target | Description |
|---|---|
PhysicsBasedAnimationToolkit_PhysicsBasedAnimationToolkit | The PBA Toolkit library. |
PhysicsBasedAnimationToolkit_Tests | The test executable, using doctest. |
PhysicsBasedAnimationToolkit_Python | PBAT's Python extension module, using pybind11. |
For example, to build tests, run
cmake --build <path/to/build/folder> --target PhysicsBasedAnimationToolkit_Tests --config Release
To install PhysicsBasedAnimationToolkit locally, run
cd path/to/PhysicsBasedAnimationToolkit
cmake -S . -B build -D<option>=<value> ...
cmake --install build --config Release
For a local installation, which builds from source, our Python bindings build relies on Scikit-build-core, which relies on CMake's install mechanism. As such, you can configure the installation as you typically would when using the CMake CLI directly, by now passing the corresponding CMake arguments in pip's config-settings parameter (refer to the Scikit-build-core documentation for the relevant parameters). See our pyinstall workflow for working examples of building from source on Linux, MacOS and Windows. Then, assuming that external dependencies are found via CMake's find_package, you can build and install our Python package pbatoolkit locally and get the most up to date features.
Consider using a Python virtual environment for this step.
As an example, assuming use of vcpkg for external dependency management with VCPKG_ROOT=path/to/vcpkg set as an environment variable, run
pip install . --config-settings=cmake.args="--preset=pip-cuda" -v
on the command line to build pbatoolkit from source with GPU algorithms included. Additional environment variables (i.e. CUDA_PATH) and/or CMake variables (i.e. CMAKE_CUDA_COMPILER) may be required to be set in order for CMake to correctly discover and compile against your targeted local CUDA installation. Refer to the CMake documentation for more details.
Below, we show a few examples of what can be done in just a few lines of code using pbatoolkit and Python. Code can be found here.
Our GPU implementation of the eXtended Position Based Dynamics (XPBD) algorithm simulates a ~324k element FEM elastic mesh interactively with contact.
Combining pbatoolkit's FEM+elasticity features and the IPC Toolkit results in guaranteed inter-penetration free contact dynamics between deformable bodies.
The hyper elastic beam's representative deformation modes, i.e. its low frequency eigen vectors, are animated as time continuous signals.
Real-time collision detection between 2 large scale meshes (~324k tetrahedra) is accelerated by highly parallel implementations of the sweep and prune algorithm, or linear bounding volume hierarchies.
A smooth (harmonic) function is constructed on Entei, required to evaluate to 1 on its paws, and 0 at the top of its tail, using piece-wise linear (left) and quadratic (right) shape functions. Its isolines are displayed as black curves.
Approximate geodesic distances are computed from the top center vertex of Metagross by diffusing heat from it (left), and recovering a function whose gradient matches the normalized heat's negative gradient. Its isolines are displayed as black curves.
Fine details of Godzilla's skin are smoothed out by diffusing x,y,z coordinates in time.
Computation details are gathered when using pbatoolkit and consulted in the Tracy profiling server GUI.
A .clang-format description file is provided in the repository root which should be used to enforce a uniform coding style throughout the code base using the clang-format tool. Recent versions of Visual Studio Code and Visual Studio should come bundled with a clang-format installation. On Unix-like systems, clang-format can be installed using your favorite package manager.
FAQs
Physics Based Animation Toolkit
We found that pbatoolkit demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.