C++

Build Docs https://codecov.io/github/ipc-sim/ipc-toolkit/graph/badge.svg?token=9BR6GPKRY8 License

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:


Last update: Dec 03, 2024