Skip to content

Commit 9948269

Browse files
th-skamth-skam
committed
[doc] Created a documentation
1 parent fb2a460 commit 9948269

1 file changed

Lines changed: 181 additions & 0 deletions

File tree

‎doc/doc.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Summary: CollisionAlgorithm & ConstraintGeometry Repositories
2+
3+
These two SOFA plugins work together to provide a complete **needle insertion simulation system**. They form a two-stage pipeline: detection → constraint resolution.
4+
5+
---
6+
7+
## CollisionAlgorithm Repository
8+
9+
### Purpose
10+
A collision detection plugin specifically designed for **needle insertion simulations** in medical applications. It detects collisions between a needle and tissue, handling puncture, shaft collision, and insertion phases.
11+
12+
### Core Architecture
13+
14+
**Layered Design:**
15+
```
16+
Algorithm Layer (InsertionAlgorithm)
17+
↓
18+
Geometry Layer (Point/Edge/Triangle/TetrahedronGeometry)
19+
↓
20+
Element Layer (PointElement, EdgeElement, TriangleElement, TetrahedronElement)
21+
↓
22+
Proximity Layer (EdgeProximity, TriangleProximity, etc.)
23+
```
24+
25+
**Key Class Hierarchies:**
26+
27+
1. **Geometry Hierarchy** - Progressive complexity through inheritance:
28+
- `PointGeometry` → `EdgeGeometry` → `TriangleGeometry` → `TetrahedronGeometry`
29+
- Each adds element types from parent
30+
31+
2. **Element Classes** - Geometric primitives with caching:
32+
- Store precomputed data (normals, areas, barycentric denominators)
33+
- Use dirty flags for lazy recomputation
34+
35+
3. **Proximity Classes** - Interpolated contact points:
36+
- `EdgeProximity`, `TriangleProximity`, `TetrahedronProximity`
37+
- Store barycentric coordinates and provide position/velocity interpolation
38+
39+
4. **Broad-Phase System** - AABB spatial hashing:
40+
- Partitions space into 8×8×8 grid
41+
- Supports multithreading and SAT-based intersection tests
42+
43+
5. **Generic Operation Framework** - Type-dispatched operations:
44+
- `Project`: Find closest point on element
45+
- `FindClosestProximity`: Spatial search with filtering
46+
- Factory pattern for runtime type dispatch
47+
48+
### Main Algorithm: InsertionAlgorithm
49+
50+
Executes three phases:
51+
1. **Puncture Phase**: Detects first tissue contact
52+
2. **Shaft Collision Phase**: Tracks needle-tissue collisions along shaft
53+
3. **Insertion Phase**: Maintains coupling points during insertion
54+
55+
**Outputs:**
56+
- `d_collisionOutput` → proximity pairs for puncture/contact
57+
- `d_insertionOutput` → proximity pairs for insertion coupling
58+
59+
---
60+
61+
## ConstraintGeometry Repository
62+
63+
### Purpose
64+
A constraint resolution plugin that takes collision detection output and creates **Lagrangian constraints** for the physics solver. Handles bilateral, unilateral, and friction-based constraints.
65+
66+
### Core Architecture
67+
68+
**Constraint Pipeline:**
69+
```
70+
Detection Output (from CollisionAlgorithm)
71+
↓
72+
TBaseConstraint (processGeometricalData)
73+
↓
74+
InternalConstraint (proximity pairs + normals)
75+
↓
76+
ConstraintResolution (solver kernels)
77+
↓
78+
Force Application (storeLambda)
79+
```
80+
81+
**Key Class Hierarchies:**
82+
83+
1. **Constraint Types:**
84+
- `ConstraintBilateral` - Equality constraints (position coupling)
85+
- `ConstraintUnilateral` - Inequality constraints with optional Coulomb friction
86+
- `ConstraintInsertion` - Specialized insertion physics with friction
87+
88+
2. **Constraint Direction Strategies** - How to compute constraint normals:
89+
- `BindDirection`: Direct relative position
90+
- `ContactDirection`: Uses surface normal handler
91+
- `FirstDirection`/`SecondDirection`: Normal from one proximity
92+
- `FixedFrameDirection`: Fixed orthogonal frame
93+
94+
3. **Normal Handler Strategies** - Geometry-dependent normal computation:
95+
- `GouraudTriangleNormalHandler`: Face normals
96+
- `PhongTriangleNormalHandler`: Smooth interpolated normals
97+
- `EdgeNormalHandler`: Edge direction
98+
- `GravityPointNormalHandler`: Radial from center
99+
100+
4. **Constraint Resolution Classes** - Solver kernels:
101+
- `BilateralConstraintResolution1/2/3` - 1D/2D/3D bilateral
102+
- `UnilateralConstraintResolution` - 1D contact
103+
- `UnilateralFrictionResolution` - 3D contact + Coulomb friction
104+
- `InsertionConstraintResolution` - Specialized insertion solver
105+
106+
---
107+
108+
## How They Work Together
109+
110+
```
111+
┌─────────────────────────────────────────────────────────────────┐
112+
│ CollisionAlgorithm Plugin │
113+
│ │
114+
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
115+
│ │ Geometries │───▶│ Broad-Phase │───▶│ InsertionAlg │ │
116+
│ │ (Needle/ │ │ (AABB Grid) │ │ (Detection) │ │
117+
│ │ Tissue) │ └──────────────┘ └──────┬───────┘ │
118+
│ └──────────────┘ │ │
119+
│ ▼ │
120+
│ ┌───────────────────────────────┐ │
121+
│ │ DetectionOutput<Prox1, Prox2> │ │
122+
│ │ (Pairs of proximity points) │ │
123+
│ └───────────────┬───────────────┘ │
124+
└──────────────────────────────────────────────┼───────────────────┘
125+
│
126+
▼
127+
┌──────────────────────────────────────────────────────────────────┐
128+
│ ConstraintGeometry Plugin │
129+
│ │
130+
│ ┌──────────────────┐ ┌──────────────────┐ │
131+
│ │ TBaseConstraint │───▶│ ConstraintDir │ │
132+
│ │ (Bilateral/ │ │ + NormalHandler │ │
133+
│ │ Unilateral/ │ └────────┬─────────┘ │
134+
│ │ Insertion) │ │ │
135+
│ └────────┬─────────┘ ▼ │
136+
│ │ ┌──────────────────┐ │
137+
│ │ │ ConstraintNormal │ │
138+
│ │ │ (directions) │ │
139+
│ │ └────────┬─────────┘ │
140+
│ ▼ ▼ │
141+
│ ┌───────────────────────────────────────────┐ │
142+
│ │ InternalConstraint (pairs + normals) │ │
143+
│ └────────────────────┬──────────────────────┘ │
144+
│ ▼ │
145+
│ ┌───────────────────────────────────────────┐ │
146+
│ │ ConstraintResolution (solver kernels) │───▶ Forces │
147+
│ └───────────────────────────────────────────┘ │
148+
└───────────────────────────────────────────────────────────────────┘
149+
```
150+
151+
### Key Integration Points
152+
153+
1. **Shared Data Type**: `DetectionOutput<FIRST, SECOND>` contains pairs of `BaseProximity` subclasses that both plugins understand
154+
155+
2. **Proximity Abstraction**: Both plugins use the same proximity hierarchy (`EdgeProximity`, `TriangleProximity`, etc.) - defined in CollisionAlgorithm, consumed by ConstraintGeometry
156+
157+
3. **CollisionComponent Interface**: `BaseNormalHandler` in ConstraintGeometry inherits from `CollisionComponent` (from CollisionAlgorithm) to participate in the detection preparation phase
158+
159+
4. **Generic Operation System**: Both plugins use the same `GenericOperation` factory pattern for type-dispatched operations
160+
161+
---
162+
163+
## Design Patterns Used
164+
165+
| Pattern | Usage |
166+
|---------|-------|
167+
| **Template Method** | Base classes define algorithm skeleton, subclasses fill details |
168+
| **Strategy** | Multiple interchangeable direction/normal handlers |
169+
| **Factory** | Type-dispatched operations, constraint resolution creation |
170+
| **Iterator** | Element traversal with `ElementIterator` |
171+
| **Visitor** | SOFA scene graph traversal |
172+
| **Decorator** | `TConstraintProximity` wraps proximity with normal |
173+
174+
---
175+
176+
## Summary
177+
178+
- **CollisionAlgorithm** handles the "where" - detecting collision points between needle and tissue through geometric queries and spatial indexing
179+
- **ConstraintGeometry** handles the "how" - converting those detection points into physical constraints with proper force resolution
180+
181+
Together, they enable realistic needle insertion simulations with puncture resistance, friction, and tissue deformation.

0 commit comments

Comments
 (0)