Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add FL3 placement/reference friction mini-lab artifacts

Yuechen Li8e4f75bc27e7
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-blind-hole-face/anchor.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-blind-hole-face/anchor.toon
new file mode 100644
index 00000000..d0a87fe5
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-blind-hole-face/anchor.toon
@@ -0,0 +1,19 @@
+# friction-lab candidate syntax only
+# not production Firmament
+candidate:
+ id: placement-blind-hole-face
+ style: anchor
+ setup:
+ base_block:
+ op: box
+ size: [80, 60, 20]
+ placement:
+ hole_1:
+ type: blind_hole
+ on: base_block.top_face
+ normal: base_block.top_face.normal
+ offset:
+ from: base_block.top_face.center
+ xy: [12, -8]
+ diameter: 10
+ depth: 14
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-blind-hole-face/frame.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-blind-hole-face/frame.toon
new file mode 100644
index 00000000..69eeb4a6
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-blind-hole-face/frame.toon
@@ -0,0 +1,23 @@
+# friction-lab candidate syntax only
+# not production Firmament
+candidate:
+ id: placement-blind-hole-face
+ style: frame
+ setup:
+ base_block:
+ op: box
+ size: [80, 60, 20]
+ top_face_frame:
+ from_face: base_block.top_face
+ origin: center
+ x_axis: edge_u
+ y_axis: edge_v
+ z_axis: normal
+ placement:
+ hole_1:
+ type: blind_hole
+ frame: top_face_frame
+ position_xyz: [12, -8, 0]
+ direction: +z
+ diameter: 10
+ depth: 14
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-blind-hole-face/review.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-blind-hole-face/review.toon
new file mode 100644
index 00000000..dbc203af
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-blind-hole-face/review.toon
@@ -0,0 +1,32 @@
+case: placement-blind-hole-face
+comparison:
+ anchor:
+ possible: true
+ awkwardness: low
+ verbosity: medium
+ pretzel_risk: low
+ pain_points:
+ - must choose stable face center convention
+ - offset axes can be ambiguous without face orientation note
+ smallest_feature_shape: "blind_hole on face + center-relative offset + depth"
+ frame:
+ possible: true
+ awkwardness: medium
+ verbosity: high
+ pretzel_risk: medium
+ pain_points:
+ - frame boilerplate dominates a single hole
+ - explicit axis naming adds coordinate-soup pressure
+ smallest_feature_shape: "frame from face, then one positioned feature"
+ semantic:
+ possible: true
+ awkwardness: low
+ verbosity: low
+ pretzel_risk: low
+ pain_points:
+ - narrow vocabulary may break for non-orthogonal face conventions
+ smallest_feature_shape: "blind_hole(face, offset_xy, depth)"
+verdict:
+ preferred_candidate: semantic
+ why: "single-feature case stays shortest and clearest with minimal coordinate handling"
+ what_should_be_tried_first_in_production: "start with tiny blind-hole placement sugar over existing selectors"
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-blind-hole-face/semantic.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-blind-hole-face/semantic.toon
new file mode 100644
index 00000000..e3f9439a
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-blind-hole-face/semantic.toon
@@ -0,0 +1,15 @@
+# friction-lab candidate syntax only
+# not production Firmament
+candidate:
+ id: placement-blind-hole-face
+ style: semantic
+ setup:
+ base_block:
+ op: box
+ size: [80, 60, 20]
+ placement:
+ blind_hole:
+ face: base_block.top_face
+ from_face_center_xy: [12, -8]
+ diameter: 10
+ depth: 14
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-bracket-rib/anchor.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-bracket-rib/anchor.toon
new file mode 100644
index 00000000..8f9138f2
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-bracket-rib/anchor.toon
@@ -0,0 +1,24 @@
+# friction-lab candidate syntax only
+# not production Firmament
+candidate:
+ id: placement-bracket-rib
+ style: anchor
+ setup:
+ bracket:
+ op: box
+ size: [90, 50, 10]
+ wall:
+ op: box
+ size: [10, 50, 60]
+ on: bracket.back_face
+ placement:
+ rib_1:
+ type: rib
+ on: bracket.top_face
+ normal: bracket.top_face.normal
+ between:
+ - wall.inner_face
+ - bracket.top_face
+ offset_from_edge: 14
+ thickness: 6
+ height: 35
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-bracket-rib/frame.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-bracket-rib/frame.toon
new file mode 100644
index 00000000..54d07036
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-bracket-rib/frame.toon
@@ -0,0 +1,29 @@
+# friction-lab candidate syntax only
+# not production Firmament
+candidate:
+ id: placement-bracket-rib
+ style: frame
+ setup:
+ bracket:
+ op: box
+ size: [90, 50, 10]
+ wall:
+ op: box
+ size: [10, 50, 60]
+ on: bracket.back_face
+ rib_frame:
+ from_face: bracket.top_face
+ origin: front_left_corner
+ x_axis: along_length
+ y_axis: along_width
+ z_axis: normal
+ placement:
+ rib_1:
+ type: rib
+ frame: rib_frame
+ base_line_xy:
+ start: [14, 10]
+ end: [14, 40]
+ extrude_height: 35
+ thickness: 6
+ lean_to_face: wall.inner_face
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-bracket-rib/review.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-bracket-rib/review.toon
new file mode 100644
index 00000000..cbd99d99
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-bracket-rib/review.toon
@@ -0,0 +1,32 @@
+case: placement-bracket-rib
+comparison:
+ anchor:
+ possible: true
+ awkwardness: medium
+ verbosity: medium
+ pretzel_risk: medium
+ pain_points:
+ - "between" endpoints become fuzzy on non-rectangular faces
+ - offset source edge needs explicit disambiguation
+ smallest_feature_shape: "rib on face with edge offset toward support face"
+ frame:
+ possible: true
+ awkwardness: medium
+ verbosity: high
+ pretzel_risk: medium
+ pain_points:
+ - local line construction adds ceremony for simple rib intent
+ - corner-based origin can flip when topology naming shifts
+ smallest_feature_shape: "face frame + base line + extrusion"
+ semantic:
+ possible: true
+ awkwardness: low
+ verbosity: low
+ pretzel_risk: low
+ pain_points:
+ - span presets may be too rigid beyond common bracket shapes
+ smallest_feature_shape: "support_rib(base_face, toward_face, edge_offset, thickness, height)"
+verdict:
+ preferred_candidate: semantic
+ why: "common bracket rib reads as intent-first with minimal reference scaffolding"
+ what_should_be_tried_first_in_production: "small rib placement helper constrained to orthogonal bracket scenarios"
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-bracket-rib/semantic.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-bracket-rib/semantic.toon
new file mode 100644
index 00000000..c6270798
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-bracket-rib/semantic.toon
@@ -0,0 +1,21 @@
+# friction-lab candidate syntax only
+# not production Firmament
+candidate:
+ id: placement-bracket-rib
+ style: semantic
+ setup:
+ bracket:
+ op: box
+ size: [90, 50, 10]
+ wall:
+ op: box
+ size: [10, 50, 60]
+ on: bracket.back_face
+ placement:
+ support_rib:
+ base_face: bracket.top_face
+ toward_face: wall.inner_face
+ offset_from_edge: 14
+ span_mode: full_between_side_edges
+ thickness: 6
+ height: 35
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-flange-bolt-circle/anchor.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-flange-bolt-circle/anchor.toon
new file mode 100644
index 00000000..9f719c47
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-flange-bolt-circle/anchor.toon
@@ -0,0 +1,21 @@
+# friction-lab candidate syntax only
+# not production Firmament
+candidate:
+ id: placement-flange-bolt-circle
+ style: anchor
+ setup:
+ flange:
+ op: cylinder
+ radius: 70
+ height: 14
+ placement:
+ bolt_holes:
+ type: blind_hole_pattern
+ on: flange.top_face
+ concentric_with: flange.axis
+ radius_from_axis: 52
+ count: 6
+ angle_step_deg: 60
+ start_angle_deg: 0
+ diameter: 9
+ depth: 12
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-flange-bolt-circle/frame.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-flange-bolt-circle/frame.toon
new file mode 100644
index 00000000..8b57041c
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-flange-bolt-circle/frame.toon
@@ -0,0 +1,28 @@
+# friction-lab candidate syntax only
+# not production Firmament
+candidate:
+ id: placement-flange-bolt-circle
+ style: frame
+ setup:
+ flange:
+ op: cylinder
+ radius: 70
+ height: 14
+ flange_top_frame:
+ from_face: flange.top_face
+ origin: center
+ x_axis: radial_zero
+ y_axis: tangent_zero
+ z_axis: normal
+ placement:
+ bolt_holes:
+ type: circular_pattern
+ frame: flange_top_frame
+ seed_feature:
+ type: blind_hole
+ position_xyz: [52, 0, 0]
+ direction: +z
+ diameter: 9
+ depth: 12
+ count: 6
+ angle_step_deg: 60
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-flange-bolt-circle/review.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-flange-bolt-circle/review.toon
new file mode 100644
index 00000000..637fd095
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-flange-bolt-circle/review.toon
@@ -0,0 +1,33 @@
+case: placement-flange-bolt-circle
+comparison:
+ anchor:
+ possible: true
+ awkwardness: low
+ verbosity: medium
+ pretzel_risk: low
+ pain_points:
+ - pattern semantics still need explicit angle defaults
+ - axis orientation for start angle must be consistent
+ smallest_feature_shape: "holes on face concentric_with axis at radial offset"
+ frame:
+ possible: true
+ awkwardness: medium
+ verbosity: high
+ pretzel_risk: medium
+ pain_points:
+ - seed+pattern split is more ceremony than intent
+ - local frame setup duplicates known flange axis intent
+ smallest_feature_shape: "frame + one seed hole + rotate copies"
+ semantic:
+ possible: true
+ awkwardness: low
+ verbosity: low
+ pretzel_risk: low
+ pain_points:
+ - only works while bolt-circle assumptions remain simple
+ - custom pitch or skips likely escape tiny sugar
+ smallest_feature_shape: "bolt_circle_holes(face, axis, radius, count)"
+verdict:
+ preferred_candidate: semantic
+ why: "directly names an everyday bolt-circle task without extra scaffolding"
+ what_should_be_tried_first_in_production: "introduce tiny bolt-circle helper backed by existing pattern mechanics"
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-flange-bolt-circle/semantic.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-flange-bolt-circle/semantic.toon
new file mode 100644
index 00000000..3a73a9b3
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-flange-bolt-circle/semantic.toon
@@ -0,0 +1,19 @@
+# friction-lab candidate syntax only
+# not production Firmament
+candidate:
+ id: placement-flange-bolt-circle
+ style: semantic
+ setup:
+ flange:
+ op: cylinder
+ radius: 70
+ height: 14
+ placement:
+ bolt_circle_holes:
+ face: flange.top_face
+ around_axis: flange.axis
+ bolt_circle_radius: 52
+ hole_count: 6
+ start_angle_deg: 0
+ hole_diameter: 9
+ hole_depth: 12
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-shaft-keyway/anchor.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-shaft-keyway/anchor.toon
new file mode 100644
index 00000000..91c0c865
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-shaft-keyway/anchor.toon
@@ -0,0 +1,22 @@
+# friction-lab candidate syntax only
+# not production Firmament
+candidate:
+ id: placement-shaft-keyway
+ style: anchor
+ setup:
+ shaft:
+ op: cylinder
+ radius: 18
+ height: 140
+ placement:
+ keyway:
+ type: slot_cut
+ on: shaft.side_face
+ axis: shaft.axis
+ normal: shaft.side_face.normal_at_angle(0)
+ offset:
+ along_axis: 20
+ radial: 0
+ width: 6
+ depth: 3
+ length: 42
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-shaft-keyway/frame.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-shaft-keyway/frame.toon
new file mode 100644
index 00000000..7604fc66
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-shaft-keyway/frame.toon
@@ -0,0 +1,27 @@
+# friction-lab candidate syntax only
+# not production Firmament
+candidate:
+ id: placement-shaft-keyway
+ style: frame
+ setup:
+ shaft:
+ op: cylinder
+ radius: 18
+ height: 140
+ keyway_frame:
+ from_cylinder: shaft.side_face
+ origin:
+ angle_deg: 0
+ z: 20
+ x_axis: shaft.axis
+ y_axis: outward_radial
+ z_axis: tangential
+ placement:
+ keyway:
+ type: slot_cut
+ frame: keyway_frame
+ center_xyz: [21, 0, 0]
+ length_dir: +x
+ width: 6
+ depth: 3
+ length: 42
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-shaft-keyway/review.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-shaft-keyway/review.toon
new file mode 100644
index 00000000..ea323b8b
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-shaft-keyway/review.toon
@@ -0,0 +1,32 @@
+case: placement-shaft-keyway
+comparison:
+ anchor:
+ possible: partial
+ awkwardness: medium
+ verbosity: medium
+ pretzel_risk: medium
+ pain_points:
+ - side-face normal on cylinder needs extra clocking concept
+ - mixing axial and radial offsets is easy to misread
+ smallest_feature_shape: "slot on cylindrical side using axis + clocking + z offset"
+ frame:
+ possible: partial
+ awkwardness: high
+ verbosity: high
+ pretzel_risk: high
+ pain_points:
+ - cylindrical frame definition is cognitively heavy for routine keyway
+ - multiple axes/center values invite coordinate mistakes
+ smallest_feature_shape: "cylinder-derived frame at angle + z"
+ semantic:
+ possible: true
+ awkwardness: low
+ verbosity: low
+ pretzel_risk: low
+ pain_points:
+ - very task-specific; general slot variants may not fit
+ smallest_feature_shape: "shaft_keyway(shaft, clocking, start_z, length, width, depth)"
+verdict:
+ preferred_candidate: semantic
+ why: "captures common shaft keyway intent without forcing cylindrical frame math"
+ what_should_be_tried_first_in_production: "prototype tiny keyway sugar only for straight shaft cases"
diff --git a/Aetheris.Firmament.FrictionLab/PlacementLab/placement-shaft-keyway/semantic.toon b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-shaft-keyway/semantic.toon
new file mode 100644
index 00000000..64da27ca
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/PlacementLab/placement-shaft-keyway/semantic.toon
@@ -0,0 +1,18 @@
+# friction-lab candidate syntax only
+# not production Firmament
+candidate:
+ id: placement-shaft-keyway
+ style: semantic
+ setup:
+ shaft:
+ op: cylinder
+ radius: 18
+ height: 140
+ placement:
+ shaft_keyway:
+ on_shaft: shaft
+ clocking_deg: 0
+ start_z: 20
+ length: 42
+ width: 6
+ depth: 3
diff --git a/Aetheris.Firmament.FrictionLab/README.md b/Aetheris.Firmament.FrictionLab/README.md
index 7b8343a4..d47e534d 100644
--- a/Aetheris.Firmament.FrictionLab/README.md
+++ b/Aetheris.Firmament.FrictionLab/README.md
@@ -19,6 +19,20 @@ The suite is designed for measurement, not pass-rate inflation:
- partials expose awkward or fragile expressions,
- failures document genuinely missing shape capabilities.
+## FL3 milestone — placement/reference ergonomics mini-lab
+
+FL3 adds `PlacementLab/` as a candidate-syntax experiment to compare three placement authoring models before any implementation work:
+
+- **anchor-based** placement (`on`, `axis`, `normal`, `offset`, `concentric_with` style intent),
+- **frame-based** placement (explicit local frame/origin/axes),
+- **tiny semantic sugar** for narrow, common mechanical placement tasks.
+
+These FL3 files are **not production Firmament syntax** and are intentionally isolated from production parser/compiler fixtures.
+
+FL3 keeps the anti-pretzel rule active: if a candidate style becomes awkward, verbose, or unnatural, record that friction directly instead of inventing helper scaffolding.
+
+Goal: establish the smallest, clearest placement model to trial first, using friction evidence rather than overengineering.
+
## Anti-pretzel rule (mandatory)
If a case cannot be expressed cleanly:
diff --git a/Aetheris.Firmament.FrictionLab/Reports/placement-summary.json b/Aetheris.Firmament.FrictionLab/Reports/placement-summary.json
new file mode 100644
index 00000000..da34cd48
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/Reports/placement-summary.json
@@ -0,0 +1,48 @@
+{
+ "milestone": "FL3",
+ "experiment": "placement/reference ergonomics mini-lab",
+ "total_cases": 4,
+ "candidates_compared": [
+ "anchor",
+ "frame",
+ "semantic"
+ ],
+ "per_case_preferred_candidate": {
+ "placement-blind-hole-face": "semantic",
+ "placement-flange-bolt-circle": "semantic",
+ "placement-shaft-keyway": "semantic",
+ "placement-bracket-rib": "semantic"
+ },
+ "preferred_candidate_histogram": {
+ "anchor": 0,
+ "frame": 0,
+ "semantic": 4
+ },
+ "repeated_pain_points": [
+ {
+ "pain_point": "frame boilerplate and axis setup add ceremony for ordinary features",
+ "seen_in": [
+ "placement-blind-hole-face",
+ "placement-flange-bolt-circle",
+ "placement-shaft-keyway",
+ "placement-bracket-rib"
+ ]
+ },
+ {
+ "pain_point": "orientation/clocking conventions are easy to misread without explicit defaults",
+ "seen_in": [
+ "placement-blind-hole-face",
+ "placement-flange-bolt-circle",
+ "placement-shaft-keyway"
+ ]
+ },
+ {
+ "pain_point": "semantic sugar is concise but risks narrow coverage outside common patterns",
+ "seen_in": [
+ "placement-flange-bolt-circle",
+ "placement-shaft-keyway",
+ "placement-bracket-rib"
+ ]
+ }
+ ]
+}