IPC Toolkit is a set of reusable functions to integrate Incremental Potential Contact (IPC) into a simulation.
- IPC barrier function and its derivatives and adaptive barrier stiffness algorithm
- Broad-phase and narrow-phase continuous collision detection (CCD)
- Distance computation and derivatives between edges in 2D and triangles in 3D
- Distance barrier potential and its derivatives
- Smooth and lagged dissipative friction potential and its derivatives
This is not a full simulation library. As such it does not include any physics or solvers. For a full simulation implementation, we recommend PolyFEM (a finite element library) or Rigid IPC (rigid-body dynamics) both of which utilize the IPC Toolkit.
The easiest way to add the toolkit to an existing CMake project is to download it through CMake. CMake provides functionality for doing this called FetchContent (requires CMake ≥ 3.14). We use this same process to download all external dependencies.
For example,
include(FetchContent)
FetchContent_Declare(
ipc_toolkit
GIT_REPOSITORY https://github.com/ipc-sim/ipc-toolkit.git
GIT_TAG ${IPC_TOOLKIT_GIT_TAG}
)
FetchContent_MakeAvailable(ipc_toolkit)
where IPC_TOOLKIT_GIT_TAG
is set to the version of the toolkit you want to use. This will download and add the toolkit to CMake. The toolkit can then be linked against using
# Link against the IPC Toolkit
target_link_libraries(${PROJECT_NAME} PUBLIC ipc::toolkit)
where PROJECT_NAME
is the name of your library/binary.
All required dependencies are downloaded through CMake depending on the build options.
The following libraries are used in this project:
- Eigen: linear algebra
- libigl: basic geometry functions and predicates
- oneTBB: parallelism
- Tight-Inclusion: correct (conservative) CCD
- SimpleBVH: a simple bounding volume hierarchy data structure
- spdlog: logging information
- robin-map: faster hash set/map than
std::unordered_set
/std::unordered_map
- Enable by using the CMake option
IPC_TOOLKIT_WITH_ROBIN_MAP
- Enabled by default
- Enable by using the CMake option
- Abseil: hashing utilities
- Enable by using the CMake option
IPC_TOOLKIT_WITH_ABSEIL
- Enabled by default
- Enable by using the CMake option
- filib: interval arithmetic for nonlinear trajectories/CCD
- Enable by using the CMake option
IPC_TOOLKIT_WITH_FILIB
- Enabled by default
- Enable by using the CMake option
- rational-cpp: rational arithmetic used for exact intersection checks
- Enable by using the CMake option
IPC_TOOLKIT_WITH_RATIONAL_INTERSECTION
- Requires GMP to be installed at a system level
- Enable by using the CMake option
- Etienne Vouga's Collision Detection Library: inexact CCD
- Included for comparison with the original IPC library
- Enable by disabling the CMake option
IPC_TOOLKIT_WITH_CORRECT_CCD
- Replaces the default Tight-Inclusion CCD
See the tutorial for a quick introduction to the toolkit, or the documentation for a full reference.
We provide unit tests to ensure the correctness of our algorithmic pieces.
To enable the unit tests use the CMake option IPC_TOOLKIT_BUILD_UNIT_TESTS
.
The following are downloaded when unit tests are enabled (IPC_TOOLKIT_BUILD_TESTS
)
- Catch2: testing framework
- finite-diff: finite-difference comparisons
- Nlohman's JSON library: loading test data from JSON files
We provide Python bindings for functions in the toolkit using pybind11.
For more information see the Python documentation.
This project is open to contributors! Contributions can come in the form of feature requests, bug fixes, documentation, tutorials, and the like. We highly recommend filing an Issue first before submitting a Pull Request.
Simply fork this repository and make a Pull Request! We would appreciate:
- Implementation of new features
- Bug Reports
- Documentation
- Testing
If you use the IPC Toolkit in your project, please consider citing our work:
@software{ipc_toolkit,
author = {Zachary Ferguson and others},
title = {{IPC Toolkit}},
url = {https://github.com/ipc-sim/ipc-toolkit},
year = {2020},
}
Additionally, you can cite the original IPC paper:
@article{Li2020IPC,
author = {Minchen Li and Zachary Ferguson and Teseo Schneider and Timothy Langlois and
Denis Zorin and Daniele Panozzo and Chenfanfu Jiang and Danny M. Kaufman},
title = {Incremental Potential Contact: Intersection- and Inversion-free Large Deformation Dynamics},
journal = {{ACM} Trans. Graph. (SIGGRAPH)},
year = {2020},
volume = {39},
number = {4},
articleno = {49}
}
MIT License © 2020, the IPC-Sim organization (See LICENSE
for details).