Offset Geometric Contact #192

zfergus · 2025-10-02T20:24:34Z

Description

Implementation of "Offset Geometric Contact" [Chen et al. 2025].

Details

This PR implements the Offset Geometric Contact (OGC) algorithm [Chen et al. 2025], a penetration-free contact model that replaces continuous collision detection (CCD) with a trust-region-based approach.

1. Core Library (`src/ipc/ogc/`)

New Namespace: Introduced ipc::ogc to encapsulate OGC-specific functionality.
Trust Region Implementation:
- Added TrustRegion class (trust_region.hpp, trust_region.cpp) to manage per-vertex conservative bounds.
- Implemented warm_start_time_step to initialize the trust region and handle initial predictions.
- Implemented filter_step to scale optimization steps ensuring vertices stay within safe bounds.
- Implemented update and update_if_needed to dynamically resize trust regions based on motion.
Feasible Region Logic:
- Added feasible_region.hpp and feasible_region.cpp containing geometric predicates (e.g., check_vertex_feasible_region, is_edge_edge_feasible) to verify if primitives are within valid non-penetrating regions.

2. Python Bindings (`python/src/ogc/`)

Exposed the OGC functionality to Python via the ipctk.ogc module.
Added bindings for TrustRegion and related classes, allowing seamless integration with Python-based optimization loops.

3. Documentation (`docs/`)

New Tutorial: Added a comprehensive tutorial (docs/source/tutorials/ogc.rst) explaining:
- The high-level OGC algorithm.
- How to configure NormalCollisions for OGC.
- Step-by-step integration of the TrustRegion class into a simulation loop (C++ and Python).
Configuration: Updated docs/source/conf.py to support new documentation features.

4. Build System

Updated CMake configuration to include the new ogc source directory and dependencies.
Mark tsl::robin_map and absl::hash as private dependencies in CMake. Update the dependency documentation accordingly.
Convert SpatialHash to PImpl idiom to hide tsl::robin_map and absl::hash from the public API.

Key Implementation Details

Step Scaling: Unlike the original paper's projection method, TrustRegion::filter_step scales the descent direction $\beta$ to keep vertices on the trust region boundary. This preserves the descent direction, ensuring compatibility with line-search-based solvers.

Type of change

Enhancement (non-breaking change which improves existing functionality)
New feature (non-breaking change which adds functionality)
This change requires a documentation update

…n Candidates class

- Introduced CollisionSetType enum to manage different collision strategies: IPC, IMPROVED_MAX_APPROX, and OGC. - Updated NormalCollisions and NormalCollisionsBuilder to utilize the new collision set type. - Replaced deprecated methods related to improved max approximator with the new collision set type methods. - Enhanced collision building logic to accommodate the new OGC strategy. - Updated tests to validate behavior across different collision set types.

…t_broad_phase.cpp

… parameters

codecov · 2025-10-02T21:12:25Z

Codecov Report

❌ Patch coverage is 96.30996% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.38%. Comparing base (6e2fd31) to head (2a553dc).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/ipc/ogc/trust_region.cpp	90.66%	7 Missing ⚠️
...pc/collisions/normal/normal_collisions_builder.cpp	87.23%	6 Missing ⚠️
src/ipc/collision_mesh.hpp	71.42%	4 Missing ⚠️
src/ipc/barrier/barrier.hpp	0.00%	2 Missing ⚠️
src/ipc/candidates/candidates.cpp	99.03%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #192      +/-   ##
==========================================
- Coverage   97.42%   97.38%   -0.05%     
==========================================
  Files         153      157       +4     
  Lines       23917    24240     +323     
  Branches      804      844      +40     
==========================================
+ Hits        23301    23605     +304     
- Misses        616      635      +19

Flag	Coverage Δ
unittests	`97.38% <96.30%> (-0.05%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot

Pull Request Overview

Copilot reviewed 39 out of 42 changed files in this pull request and generated 6 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

tests/src/tests/potential/test_barrier_potential.cpp

src/ipc/utils/logger.hpp

src/ipc/collisions/normal/normal_collisions_builder.cpp

src/ipc/candidates/candidates.cpp

src/ipc/broad_phase/spatial_hash.cpp

python/examples/solver.py

…ions in collision_mesh.cpp; remove unused assertions in normal_collisions_builder.cpp and clean up test_barrier_potential.cpp

…vertex position

…rtions in OGC tests

…and implement unit tests for TrustRegion functionality

…isions_builder.hpp

- Included TinyAD in the list of dependencies with a brief description. - Specified the license type (MIT) and provided a link to the GitHub repository.

Copilot

Pull request overview

Copilot reviewed 74 out of 77 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/ipc/ogc/trust_region.cpp

docs/source/tutorials/ogc.rst

src/ipc/collision_mesh.cpp

notebooks/ogc.py

python/examples/find_ipctk.py

zfergus added 16 commits June 26, 2025 23:58

Add two-stage barrier

480645a

Add conversion functions for edge-vertex and face-vertex candidates i…

be47660

…n Candidates class

Add compute_per_vertex_safe_distances to Candidates

c5ee3a2

Replace unordered_set with vector in CollisionMesh

d230b32

Merge branch 'main' into ogc

4b3d966

Fix python tests

c2fed90

Parallelize using atomic min

6e2c245

Parallelize compute_noncandidate_conservative_stepsize

4575c0c

Failed attempt to compute_per_vertex_collision_free_stepsize

a412e5c

Merge branch 'main' into ogc

8f1e449

Merge branch 'main' into ogc

0e689f1

Make tsl::robin_map and absl:hash private dependencies

b33c32a

Merge branch 'main' into ogc

2527c42

Fix log_and_throw_error to use fmt::runtime for formatting

3057dd0

Update CMake configuration for Xcode and upgrade spdlog package version

fd3cf3f

zfergus added this to the v1.5.0 milestone Oct 2, 2025

zfergus added the enhancement New feature or request label Oct 2, 2025

zfergus requested a review from Copilot October 2, 2025 20:24

zfergus and others added 2 commits October 2, 2025 16:51

Revert spdlog package version to 1.11.0 and include <optional> in tes…

4165326

…t_broad_phase.cpp

Refactor check_vertex_feasible_region to use VectorMax3d for position…

d1ab0c2

… parameters

Copilot AI reviewed Oct 2, 2025

View reviewed changes

zfergus requested a review from Copilot October 3, 2025 00:39

Copilot AI reviewed Oct 3, 2025

View reviewed changes

zfergus added 5 commits October 3, 2025 10:04

Merge branch 'main' into ogc

d672f85

Refactor collision set type in solver.py and improve adjacency assert…

c1b46e5

…ions in collision_mesh.cpp; remove unused assertions in normal_collisions_builder.cpp and clean up test_barrier_potential.cpp

Update scalable CCD package URI to a specific commit hash

9d041b7

Fix assert in CollisionMesh::init_adjacencies

e979199

Fix feasibility check in check_vertex_feasible_region to use correct …

e122d86

…vertex position

Add test for per-vertex safe distances in candidates

ba9fb68

zfergus marked this pull request as ready for review October 4, 2025 18:56

zfergus added 22 commits October 4, 2025 15:15

Update GIT_TAG for ipc_toolkit_test_data and modify mesh loading asse…

24f475e

…rtions in OGC tests

Add Python bindings for new features

096fd81

Refactor OGC module and add trust region helper class

422a171

Add trust region update mechanism and modify filter_step signature

455bb91

Add assertions for input validation in AABB and TrustRegion classes, …

3fb3e46

…and implement unit tests for TrustRegion functionality

Merge branch 'main' into ogc

291b5e8

Update internal header comments and include directives in smooth_coll…

2ace21a

…isions_builder.hpp

Document TinyAD as a dependency for automatic differentiation

e625a7c

- Included TinyAD in the list of dependencies with a brief description. - Specified the license type (MIT) and provided a link to the GitHub repository.

Bind TrustRegion class

68df7b4

Merge branch 'main' into ogc

cc241b0

Update ogc.rst

874dad5

Merge branch 'main' into ogc

c400d7e

Merge branch 'main' into ogc

29158b3

Merge branch 'main' into ogc

9756393

Remove unused edge gradient from dihedral_angle_gradient

39a1d4e

Update dependencies.rst typo

17084ce

Merge branch 'main' into ogc

db256cc

Merge branch 'main' into ogc

7333114

Merge branch 'main' into ogc

12ba0e4

Merge branch 'main' into ogc

70fdc8b

Update python bindings

89e8c45

Update documentation and add YouTube integration for OGC tutorial

d625dec

zfergus requested a review from Copilot January 15, 2026 20:03

Copilot started reviewing on behalf of zfergus January 15, 2026 20:03 View session

Copilot AI reviewed Jan 15, 2026

View reviewed changes

Resolve comments

2a553dc

zfergus merged commit 90b7caf into main Jan 15, 2026
26 of 27 checks passed

zfergus deleted the ogc branch January 15, 2026 22:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Offset Geometric Contact #192

Offset Geometric Contact #192

Uh oh!

zfergus commented Oct 2, 2025 •

edited

Loading

Uh oh!

codecov bot commented Oct 2, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Offset Geometric Contact #192

Offset Geometric Contact #192

Uh oh!

Conversation

zfergus commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Details

1. Core Library (src/ipc/ogc/)

2. Python Bindings (python/src/ogc/)

3. Documentation (docs/)

4. Build System

Key Implementation Details

Type of change

Uh oh!

codecov bot commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zfergus commented Oct 2, 2025 •

edited

Loading

1. Core Library (`src/ipc/ogc/`)

2. Python Bindings (`python/src/ogc/`)

3. Documentation (`docs/`)

codecov bot commented Oct 2, 2025 •

edited

Loading