C++¶

Build¶

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 a very similar process to download all external dependencies (using CPM).

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.

Tip

If your IPC_TOOLKIT_GIT_TAG is a tag (e.g. v1.3.1), then you can use the FetchContent_Declare argument GIT_SHALLOW TRUE to download only a single commit. Otherwise, you should use the default GIT_SHALLOW FALSE.

Dependencies¶

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: provably conservative CCD of [Wang and Ferguson et al. 2021]
SimpleBVH: a simple bounding volume hierarchy data structure
Scalable-CCD: scalable (GPU) CCD of [Belgrod et al. 2023]
spdlog: logging information

Optional¶

The following dependencies are optionally used based on CMake options:

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
Abseil: hashing utilities
- Enable by using the CMake option IPC_TOOLKIT_WITH_ABSEIL
- Enabled by default
filib: interval arithmetic for nonlinear trajectories/CCD
- Enable by using the CMake option IPC_TOOLKIT_WITH_FILIB
- Enabled by default
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
Etienne Vouga’s Collision Detection Library: inexact CCD
- Included for comparison with the original IPC library
- Enable by using the CMake option IPC_TOOLKIT_WITH_INEXACT_CCD

Warning

filib is licensed under LGPL-2.1 and as such it is required to be dynamically linked. Doing so automatically is a challenge, so by default we use static linkage. Enabling dynaic linkage requires copying the .so/.dylib/.dll file to the binary directory or system path. To enable this, set the CMake option FILIB_BUILD_SHARED_LIBS to ON and add this CMake code to copy the shared libaray object to the binary directory:

# Copy shared lib to the output directory
add_custom_command(
    TARGET ${MY_EXE_TARGET} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different $<TARGET_RUNTIME_DLLS:${MY_EXE_TARGET}> $<TARGET_FILE_DIR:${MY_EXE_TARGET}>
    COMMAND_EXPAND_LISTS
)

where ${MY_EXE_TARGET} is the name of your executable target. If you know a better way to handle this, please let us know!

If you would rather avoid LGPL code entirely, you can disable filib by setting IPC_TOOLKIT_WITH_FILIB to OFF. With this option disabled, CMake will not download or use any of filib’s code.

Usage¶

See the tutorial for a quick introduction to the toolkit, or the documentation for a full reference.

Unit Tests¶

We provide unit tests to ensure the correctness of our algorithmic pieces. To enable the unit tests use the CMake option IPC_TOOLKIT_BUILD_TESTS.

Dependencies¶

The following are downloaded when unit tests are enabled:

Catch2: testing framework
finite-diff: finite-difference comparisons
Nlohman’s JSON library: loading test data from JSON files

Last update: Nov 16, 2024