Skip to content

Commit 4d58fbf

Browse files
th-skamth-skam
committed
[doc] Add UML diagrams
1 parent 6dcbe27 commit 4d58fbf

7 files changed

Lines changed: 1254 additions & 0 deletions

File tree

‎doc/diagrams/algorithm.puml‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
@startuml collision-algorithm-algorithm
2+
3+
skinparam backgroundColor #FAFAFA
4+
skinparam defaultFontName Sans
5+
skinparam defaultFontSize 11
6+
7+
skinparam class {
8+
BackgroundColor #EEF2FB
9+
BorderColor #5577AA
10+
HeaderBackgroundColor #7AA3CC
11+
FontColor #222222
12+
HeaderFontColor #FFFFFF
13+
HeaderFontStyle bold
14+
ArrowColor #2E3436
15+
AttributeFontSize 10
16+
}
17+
18+
skinparam class<<abstract>> {
19+
HeaderBackgroundColor #4E9A06
20+
}
21+
22+
skinparam class<<data>> {
23+
HeaderBackgroundColor #75507B
24+
}
25+
26+
skinparam class<<SOFA>> {
27+
HeaderBackgroundColor #888888
28+
}
29+
30+
skinparam note {
31+
BackgroundColor #FFFBD5
32+
BorderColor #C8A000
33+
}
34+
35+
' ─────────────────────────────────────────────
36+
' SOFA root (external)
37+
' ─────────────────────────────────────────────
38+
class BaseObject <<SOFA>> {
39+
}
40+
41+
' ─────────────────────────────────────────────
42+
' Pipeline stubs (defined in pipeline.puml)
43+
' ─────────────────────────────────────────────
44+
abstract class CollisionAlgorithm <<abstract>> {
45+
+ {abstract} doDetection()
46+
}
47+
48+
BaseObject <|-- CollisionAlgorithm
49+
50+
' ─────────────────────────────────────────────
51+
' Detection output (repeated for self-containedness)
52+
' ─────────────────────────────────────────────
53+
class "DetectionOutput<FIRST, SECOND>" as DetectionOutput <<data>> {
54+
+ add(first, second)
55+
+ add(other : DetectionOutput)
56+
+ size() : unsigned
57+
+ begin() : const_iterator
58+
+ end() : const_iterator
59+
+ operator[](i) : PairDetection
60+
+ back() : PairDetection
61+
+ clear()
62+
# m_output : vector<PairDetection>
63+
}
64+
65+
note right of DetectionOutput
66+
PairDetection = pair<FIRST::SPtr, SECOND::SPtr>
67+
FIRST, SECOND default to BaseProximity.
68+
end note
69+
70+
' ─────────────────────────────────────────────
71+
' BaseAlgorithm + filter (stub with filter detail)
72+
' ─────────────────────────────────────────────
73+
abstract class BaseAlgorithm <<abstract>> {
74+
+ acceptFilter(p1, p2) : bool
75+
+ addFilter(BaseFilter::SPtr)
76+
+ getFilterFunc() : FilterFUNC
77+
+ {static} getDefaultFilterFunc() : FilterFUNC
78+
# m_filters : vector<BaseFilter::SPtr>
79+
}
80+
81+
abstract class "BaseAlgorithm::BaseFilter" as BaseFilter <<abstract>> {
82+
+ l_algo : SingleLink<BaseAlgorithm>
83+
+ init()
84+
+ {abstract} accept(p1, p2) : bool
85+
}
86+
87+
CollisionAlgorithm <|-- BaseAlgorithm
88+
BaseAlgorithm "1" o-- "*" BaseFilter : filters >
89+
90+
' ─────────────────────────────────────────────
91+
' InsertionAlgorithm
92+
' ─────────────────────────────────────────────
93+
class InsertionAlgorithm {
94+
.. geometry links ..
95+
+ l_tipGeom : SingleLink<BaseGeometry>
96+
+ l_surfGeom : SingleLink<BaseGeometry>
97+
+ l_shaftGeom : SingleLink<BaseGeometry>
98+
+ l_volGeom : SingleLink<BaseGeometry>
99+
.. detection outputs ..
100+
+ d_collisionOutput : Data<DetectionOutput>
101+
+ d_insertionOutput : Data<DetectionOutput>
102+
.. flags ..
103+
+ d_enablePuncture : Data<bool>
104+
+ d_enableInsertion : Data<bool>
105+
+ d_enableShaftCollision : Data<bool>
106+
+ d_projective : Data<bool>
107+
.. thresholds ..
108+
+ d_punctureForceThreshold : Data<SReal>
109+
+ d_tipDistThreshold : Data<SReal>
110+
.. state ..
111+
+ m_couplingPts : vector<BaseProximity::SPtr>
112+
.. methods ..
113+
+ doDetection()
114+
+ {virtual} puncturePhase() : DetectionOutput
115+
+ {virtual} shaftCollisionPhase() : DetectionOutput
116+
+ {virtual} insertionPhase()
117+
+ {virtual} reprojectCouplingPoints() : DetectionOutput
118+
}
119+
120+
note right of InsertionAlgorithm
121+
puncturePhase, shaftCollisionPhase, and
122+
insertionPhase are virtual — subclasses can
123+
override individual phases without reimplementing
124+
the full detection dispatch in doDetection().
125+
end note
126+
127+
BaseAlgorithm <|-- InsertionAlgorithm
128+
InsertionAlgorithm ..> DetectionOutput : produces >
129+
130+
' ─────────────────────────────────────────────
131+
' Find2DClosestProximityAlgorithm
132+
' ─────────────────────────────────────────────
133+
class Find2DClosestProximityAlgorithm {
134+
+ l_from : SingleLink<BaseGeometry>
135+
+ l_dest : SingleLink<BaseGeometry>
136+
+ d_projectionMatrix : Data<Mat3x4d>
137+
+ d_output : Data<DetectionOutput>
138+
+ doDetection()
139+
+ project(p : Vec3) : Vec2
140+
+ findClosestProximity2D(prox, it) : BaseProximity::SPtr
141+
}
142+
143+
note right of Find2DClosestProximityAlgorithm
144+
Projects 3D positions into 2D via a camera
145+
projection matrix, then finds the closest
146+
element by 2D screen-space distance.
147+
end note
148+
149+
BaseAlgorithm <|-- Find2DClosestProximityAlgorithm
150+
Find2DClosestProximityAlgorithm ..> DetectionOutput : produces >
151+
152+
@enduml

‎doc/diagrams/broadphase.puml‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
@startuml collision-algorithm-broadphase
2+
3+
skinparam backgroundColor #FAFAFA
4+
skinparam defaultFontName Sans
5+
skinparam defaultFontSize 11
6+
7+
skinparam class {
8+
BackgroundColor #EEF2FB
9+
BorderColor #5577AA
10+
HeaderBackgroundColor #7AA3CC
11+
FontColor #222222
12+
HeaderFontColor #FFFFFF
13+
HeaderFontStyle bold
14+
ArrowColor #2E3436
15+
AttributeFontSize 10
16+
}
17+
18+
skinparam class<<abstract>> {
19+
HeaderBackgroundColor #4E9A06
20+
}
21+
22+
skinparam class<<SOFA>> {
23+
HeaderBackgroundColor #888888
24+
}
25+
26+
skinparam note {
27+
BackgroundColor #FFFBD5
28+
BorderColor #C8A000
29+
}
30+
31+
' ─────────────────────────────────────────────
32+
' SOFA root (external)
33+
' ─────────────────────────────────────────────
34+
class BaseObject <<SOFA>> {
35+
}
36+
37+
' ─────────────────────────────────────────────
38+
' Stubs from other diagrams
39+
' ─────────────────────────────────────────────
40+
class BaseGeometry
41+
class BaseElement
42+
43+
' ─────────────────────────────────────────────
44+
' BroadPhase interface (nested in BaseGeometry)
45+
' ─────────────────────────────────────────────
46+
abstract class "BaseGeometry::BroadPhase" as BroadPhase <<abstract>> {
47+
+ l_geometry : SingleLink<BaseGeometry>
48+
+ init()
49+
+ {abstract} getNbox() : Vec3i
50+
+ {abstract} getBoxCoord(P : Vec3) : Vec3i
51+
+ {abstract} getElementSet(i, j, k) : set<BaseElement>
52+
+ getTypeInfo() : type_info&
53+
+ {abstract} initBroadPhase()
54+
+ {abstract} updateBroadPhase()
55+
}
56+
57+
note right of BroadPhase
58+
Nested class inside BaseGeometry.
59+
Registered as a slave object —
60+
BaseGeometry::setBroadPhase()
61+
calls initBroadPhase() on attachment.
62+
end note
63+
64+
BaseObject <|-- BroadPhase
65+
BroadPhase ..> BaseGeometry : l_geometry >
66+
BroadPhase ..> BaseElement : getElementSet() returns set of >
67+
68+
' ─────────────────────────────────────────────
69+
' AABB base
70+
' ─────────────────────────────────────────────
71+
abstract class BaseAABBBroadPhase <<abstract>> {
72+
+ d_nbox : Data<Vec3i> ' default (8,8,8)
73+
+ d_static : Data<bool> ' skip update if true
74+
+ d_method : Data<int> ' 0=project, 1=SAT, 2=bbox
75+
+ d_thread : Data<int> ' thread count for method 2
76+
+ getBBox() : BoundingBox
77+
+ getMin() : Vec3
78+
+ getMax() : Vec3
79+
+ getCellSize() : Vec3
80+
+ getBoxCoord(P) : Vec3i
81+
+ getNbox() : Vec3i
82+
+ initBroadPhase()
83+
+ updateBroadPhase()
84+
+ doUpdate()
85+
+ updateElemInBoxes()
86+
+ projectElemOnBoxes() ' method 0
87+
+ boxTriangleSAT() ' method 1
88+
+ bboxIntersection() ' method 2 — multithreaded
89+
+ {abstract} newContainer()
90+
+ {abstract} addElement(i, j, k, elmt)
91+
+ {abstract} updateData()
92+
# m_Bmin : Vec3
93+
# m_Bmax : Vec3
94+
# m_cellSize : Vec3
95+
# m_nbox : Vec3i
96+
# m_data : vector<vector<ELMT_THREAD>>
97+
}
98+
99+
note right of BaseAABBBroadPhase
100+
Three strategies to map elements to cells,
101+
selected at runtime via d_method:
102+
0 — project element centre, check residual
103+
1 — SAT-based triangle-box overlap test
104+
2 — pure bounding-box intersection (threaded)
105+
end note
106+
107+
BroadPhase <|-- BaseAABBBroadPhase
108+
109+
' ─────────────────────────────────────────────
110+
' Concrete implementations
111+
' ─────────────────────────────────────────────
112+
class AABBBroadPhase {
113+
+ updateData()
114+
+ getElementSet(i, j, k) : set<BaseElement>
115+
+ newContainer()
116+
+ addElement(i, j, k, elmt)
117+
+ getKey(i, j, k) : Index
118+
+ getIKey(key) : unsigned
119+
+ getJKey(key) : unsigned
120+
+ getKKey(key) : unsigned
121+
# m_indexedElement : map<unsigned, set<BaseElement>>
122+
# m_offset : Vec<2, size_t>
123+
}
124+
125+
class FullAABBBroadPhase {
126+
+ updateData() ' no-op — no offset needed
127+
+ getElementSet(i, j, k) : set<BaseElement>
128+
+ newContainer()
129+
+ addElement(i, j, k, elmt)
130+
# m_indexedElement : vector<vector<vector<set<BaseElement>>>>
131+
# m_offset : Vec<2, size_t>
132+
}
133+
134+
note bottom of AABBBroadPhase
135+
Sparse storage: hash map keyed by
136+
a linearised (i,j,k) index.
137+
Good for scenes where most cells are empty.
138+
end note
139+
140+
note bottom of FullAABBBroadPhase
141+
Dense storage: pre-allocated 3D vector.
142+
O(1) lookup at the cost of memory for
143+
all nbox[0]×nbox[1]×nbox[2] cells.
144+
end note
145+
146+
BaseAABBBroadPhase <|-- AABBBroadPhase
147+
BaseAABBBroadPhase <|-- FullAABBBroadPhase
148+
149+
@enduml

0 commit comments

Comments
 (0)