[PR02 Mesh Intersection] Sofa cgal vertex push using CGAL methodes

[FadiWahbeh]

Based #2

PR 02B - CGAL Local Repulsion with Rest-Position Stabilization

Goal

This PR introduces a CGAL-based local repulsion system inside MeshRepulsionEngine.

The objective is to move the slave mesh outside the master mesh using a local correction. The correction is computed locally from the relation between slave vertices and the master surface.

---

Main Idea

The component uses CGAL to detect slave vertices located inside the master mesh.

For each problematic slave vertex, CGAL computes a local geometric correction using the closest point on the master surface.

The correction is then applied progressively to the slave mesh.

The general workflow is:

CGAL detects slave vertices inside the master
→ CGAL finds the closest point on the master surface
→ a local outward correction direction is computed
→ candidate slave positions are generated
→ the correction is validated
→ position is updated
→ restPosition can also be updated to keep SOFA consistent

The correction remains local and non-rigid.

---

Why restPosition Is Updated

In SOFA, physical components such as FEM or springs may use restPosition as the reference configuration.

If only position is updated, the solver can still try to bring the mesh back toward its old reference shape.

If this old reference shape is still interpenetrating the master mesh, SOFA may pull the slave mesh back inside the master.

To avoid this conflict, this PR allows the component to update both:

position
restPosition

This helps keep the CGAL correction and the SOFA simulation state consistent.

---

Modified Files

src/CGALPlugin/MeshRepulsionEngine.h
src/CGALPlugin/MeshRepulsionEngine.cpp

---

Moddify Test Scene

scenes/MeshRepulsion.scn

---

Important Scene Parameters

Example configuration:

<MeshRepulsionEngine
    name="meshRepulsion"
    masterState="@master/MechanicalObject"
    masterTopology="@master/topology"
    slaveState="@slave/MechanicalObject"
    slaveTopology="@slave/topology"
    enableCgalDetection="true"
    enablePositionUpdate="true"
    updateRestPosition="true"
    rejectIfInsideIncreases="true"
    maxMovedVerticesPerStep="0"
    alpha="0.35"
    maxStep="0.10"
    safetyDistance="0.25"
    rebuildMasterEveryStep="false"
    logEveryNSteps="1"
/>

---

Parameters

enableCgalDetection

enableCgalDetection="true"

Enables CGAL inside / boundary / outside detection.

---

enablePositionUpdate

enablePositionUpdate="true"

Enables the local correction of slave vertex positions.

When disabled, the component can still be used for detection and diagnostics only.

---

updateRestPosition

updateRestPosition="true"

When enabled, the component updates both the current position and the rest position of the slave mesh.

This prevents the SOFA solver from pulling the slave mesh back toward an invalid initial configuration.

---

rejectIfInsideIncreases

rejectIfInsideIncreases="true"

Rejects a correction step if the number of inside vertices increases after applying the candidate correction.

Example:

insideBefore = 120
insideAfter  = 142
accepted     = false

In this case, the correction step is cancelled.

---

maxMovedVerticesPerStep

maxMovedVerticesPerStep="0"

A value of 0 means that there is no artificial limit on the number of corrected vertices per step.

This avoids leaving some inside vertices untreated while other vertices are already corrected.

---

alpha

alpha="0.35"

Controls the fraction of the correction applied at each step.

lower alpha  → smoother but slower correction
higher alpha → faster but more aggressive correction

---

maxStep

maxStep="0.10"

Limits the maximum displacement applied to one slave vertex during one correction step.

This avoids large jumps.

---

safetyDistance

safetyDistance="0.25"

Defines the target gap outside the master surface.

The goal is not only to put the slave vertex exactly on the master surface, but slightly outside it.

---

CGAL Methods Used

This PR uses CGAL for the geometric part of the correction.

Main CGAL structures:

CGAL::Surface_mesh
CGAL::Side_of_triangle_mesh
CGAL::AABB_tree
CGAL::AABB_traits
CGAL::AABB_face_graph_triangle_primitive

Main geometric operations:

inside / boundary / outside classification
closest point query on the master surface
local outward correction direction

---

Algorithm

The code follows this logic:

1. Read current master positions from SOFA.
2. Read current slave positions from SOFA.
3. Build or reuse the CGAL master Surface_mesh.
4. Build or reuse the CGAL AABB tree.
5. Use CGAL Side_of_triangle_mesh to classify slave vertices.
6. For each slave vertex detected inside the master:
   - find the closest point on the master surface;
   - compute a local outward direction;
   - compute a bounded displacement;
   - store the candidate corrected position.
7. Count the number of inside vertices after the candidate correction.
8. If the correction is valid:
   - update slave position;
   - optionally update slave restPosition.
9. If the correction makes the inside count worse:
   - reject the step.
10. Print diagnostics.

---

Validation Checklist

• The plugin builds successfully.
• The PR 02 scene loads correctly.
• The master and slave meshes are loaded correctly.
• CGAL structures are built without errors.
• The terminal prints PR 02 diagnostics.
• insideBefore decreases over simulation steps.
• insideAfter does not increase when rejectIfInsideIncreases=true.
• accepted remains 1 for valid correction steps.

---

Not Included Yet

This PR does not include:

• full edge / face intersection correction;
• sphere-vs-triangle correction;
• tetrahedral slave support;
• volumetric FEM correction;
• automatic OBJ export;
• automatic parameter tuning;

---

2026-07-07.08-02-18.mp4