Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Implement semantic simple shaft hole materialization

Yuechen Libbcfbf3471eb
diff --git a/Aetheris.Kernel.Firmament.Tests/AirHoleSimpleShaftMaterializerTests.cs b/Aetheris.Kernel.Firmament.Tests/AirHoleSimpleShaftMaterializerTests.cs
new file mode 100644
index 00000000..d2ef4d0c
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/AirHoleSimpleShaftMaterializerTests.cs
@@ -0,0 +1,86 @@
+using Aetheris.Kernel.Core.Air;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class AirHoleSimpleShaftMaterializerTests
+{
+ [Fact]
+ public void ThroughAllSimpleShaftHole_MaterializesAndPreservesSemanticParentage()
+ {
+ var feature = ValidFeature(new AirHoleEndCondition.ThroughAll());
+ var result = AirHoleSimpleShaftMaterializer.Execute(feature, Host());
+
+ Assert.True(result.Succeeded, string.Join("\n", result.Diagnostics));
+ Assert.NotNull(result.Body);
+ Assert.NotNull(result.Plan);
+ Assert.Same(feature, result.Plan.SemanticFeature);
+ Assert.Equal("hole-001", result.Plan.SemanticFeatureId);
+ Assert.Equal(nameof(AirHoleFeature), result.Plan.SemanticSourceKind);
+ Assert.Equal(AirHoleEndConditionKind.ThroughAll, result.Plan.EndConditionKind);
+ Assert.Equal(1.5, result.Plan.CenterU);
+ Assert.Equal(-1, result.Plan.CenterV);
+ Assert.Equal(1.5, result.Plan.ProfileStackSpec.CenterX);
+ Assert.Equal(-1, result.Plan.ProfileStackSpec.CenterY);
+ Assert.Equal(-5, result.Plan.CutZMin);
+ Assert.Equal(5, result.Plan.CutZMax);
+ Assert.Contains(result.Diagnostics, d => d.Contains("semantic-parent featureId=hole-001", StringComparison.Ordinal));
+ Assert.DoesNotContain(result.Diagnostics, d => d.Contains("CylinderCut", StringComparison.OrdinalIgnoreCase));
+
+ var step = Step242Exporter.ExportBody(result.Body!);
+ Assert.True(step.IsSuccess);
+ Assert.Contains("CYLINDRICAL_SURFACE", step.Value, StringComparison.Ordinal);
+ Assert.Contains("MANIFOLD_SOLID_BREP", step.Value, StringComparison.Ordinal);
+ }
+
+ [Fact]
+ public void DepthSimpleShaftHole_MaterializesBoundedBlindSpanAndPreservesSemanticParentage()
+ {
+ var feature = ValidFeature(new AirHoleEndCondition.Depth(3));
+ var result = AirHoleSimpleShaftMaterializer.Execute(feature, Host());
+
+ Assert.True(result.Succeeded, string.Join("\n", result.Diagnostics));
+ Assert.NotNull(result.Plan);
+ Assert.Same(feature, result.Plan.SemanticFeature);
+ Assert.Equal(AirHoleEndConditionKind.Depth, result.Plan.EndConditionKind);
+ Assert.Equal(2, result.Plan.CutZMin);
+ Assert.Equal(5, result.Plan.CutZMax);
+ Assert.Contains(result.Plan.ProfileStackSpec.Layers, l => !l.InnerCircleRadius.HasValue && l.Role.Contains("solid-before-blind-depth", StringComparison.Ordinal));
+ Assert.Contains(result.Plan.ProfileStackSpec.Layers, l => l.InnerCircleRadius == 2 && l.Role.Contains("hole-001", StringComparison.Ordinal));
+ Assert.Contains(result.Diagnostics, d => d.Contains("ProfileStackExtrudeSpec is lowering furniture", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void UnsupportedPlacement_RejectsDeterministicallyWithoutAnonymousCylinderFallback()
+ {
+ var feature = AirHoleFeature.CreateSimpleShaft(
+ "mount-hole",
+ "hole-unsupported",
+ "body-main",
+ new AirFaceLocalHolePlacement("curved-wall", 0, 0, "face(curved-wall):unsupported", "face(curved-wall)"),
+ new AirHoleAxis(Direction3D.Create(new Vector3D(1, 0, 0)), false),
+ new AirHoleShaft(4),
+ new AirHoleEndCondition.ThroughAll());
+
+ var result = AirHoleSimpleShaftMaterializer.Execute(feature, Host());
+
+ Assert.Equal(AirHoleSimpleShaftMaterializationStatus.UnsupportedPlacement, result.Status);
+ Assert.Null(result.Body);
+ Assert.Null(result.Plan);
+ Assert.Contains(result.Diagnostics, d => d.Contains("only planar top/+Z and bottom/-Z", StringComparison.Ordinal));
+ Assert.DoesNotContain(result.Diagnostics, d => d.Contains("CylinderCut", StringComparison.OrdinalIgnoreCase));
+ }
+
+ private static AirHoleSimpleShaftHost Host() => new(20, 20, -5, 5);
+
+ private static AirHoleFeature ValidFeature(AirHoleEndCondition endCondition) => AirHoleFeature.CreateSimpleShaft(
+ "mount-hole",
+ "hole-001",
+ "body-main",
+ new AirFaceLocalHolePlacement("top", 1.5, -1, "face(top):u=+X,v=+Y", "face(top)"),
+ new AirHoleAxis(Direction3D.Create(new Vector3D(0, 0, 1)), true),
+ new AirHoleShaft(4),
+ endCondition);
+}
diff --git a/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs b/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs
new file mode 100644
index 00000000..94bc6228
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Materializer/AirHoleSimpleShaftMaterializer.cs
@@ -0,0 +1,143 @@
+using Aetheris.Kernel.Core.Air;
+using Aetheris.Kernel.Core.Brep;
+
+namespace Aetheris.Kernel.Firmament.Materializer;
+
+internal enum AirHoleSimpleShaftMaterializationStatus
+{
+ Succeeded,
+ InvalidSemanticHole,
+ UnsupportedPlacement,
+ ExecutionFailed
+}
+
+internal sealed record AirHoleSimpleShaftHost(
+ double Width,
+ double Depth,
+ double ZMin,
+ double ZMax,
+ string TopFaceName = "top",
+ string BottomFaceName = "bottom")
+{
+ public double Thickness => ZMax - ZMin;
+}
+
+internal sealed record AirHoleSimpleShaftMaterializationPlan(
+ AirHoleFeature SemanticFeature,
+ AirHoleSimpleShaftHost Host,
+ string SemanticFeatureId,
+ string SemanticSourceKind,
+ string EntryFaceName,
+ double CenterU,
+ double CenterV,
+ double AxisZ,
+ double Radius,
+ double CutZMin,
+ double CutZMax,
+ AirHoleEndConditionKind EndConditionKind,
+ ProfileStackExtrudeSpec ProfileStackSpec,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record AirHoleSimpleShaftMaterializationResult(
+ AirHoleSimpleShaftMaterializationStatus Status,
+ AirHoleSimpleShaftMaterializationPlan? Plan,
+ BrepBody? Body,
+ IReadOnlyList<string> Diagnostics)
+{
+ public bool Succeeded => Status == AirHoleSimpleShaftMaterializationStatus.Succeeded;
+}
+
+internal static class AirHoleSimpleShaftMaterializer
+{
+ private const double Tolerance = 1e-9;
+
+ public static AirHoleSimpleShaftMaterializationResult Execute(AirHoleFeature feature, AirHoleSimpleShaftHost host)
+ {
+ var planResult = TryCreatePlan(feature, host);
+ if (planResult.Status != AirHoleSimpleShaftMaterializationStatus.Succeeded || planResult.Plan is null)
+ {
+ return planResult;
+ }
+
+ var diagnostics = planResult.Diagnostics.ToList();
+ diagnostics.Add("air-hole-x2 execution route: semantic AirHoleFeature -> simple shaft materialization plan -> ProfileStackExtrudeExecutor.");
+ diagnostics.Add($"air-hole-x2 semantic-parent featureId={planResult.Plan.SemanticFeatureId} source={planResult.Plan.SemanticSourceKind}.");
+
+ var execution = ProfileStackExtrudeExecutor.Execute(planResult.Plan.ProfileStackSpec);
+ diagnostics.AddRange(execution.Diagnostics);
+ if (execution.Status != ProfileStackExtrudeExecutionStatus.Succeeded || execution.Body is null)
+ {
+ diagnostics.Add($"air-hole-x2 profile-stack execution failed: {execution.Status}.");
+ return new(AirHoleSimpleShaftMaterializationStatus.ExecutionFailed, planResult.Plan, null, diagnostics);
+ }
+
+ diagnostics.Add("air-hole-x2 materialization succeeded with semantic parent preserved; ProfileStackExtrudeSpec is lowering furniture, not source truth.");
+ return new(AirHoleSimpleShaftMaterializationStatus.Succeeded, planResult.Plan, execution.Body, diagnostics);
+ }
+
+ public static AirHoleSimpleShaftMaterializationResult TryCreatePlan(AirHoleFeature feature, AirHoleSimpleShaftHost host)
+ {
+ var diagnostics = new List<string> { "air-hole-x2 simple shaft planner started." };
+ if (!feature.IsValid)
+ {
+ diagnostics.AddRange(feature.Diagnostics.Select(d => $"semantic diagnostic {d.Code}: {d.Message}"));
+ diagnostics.Add("air-hole-x2 rejected: semantic hole invalid before materialization.");
+ return new(AirHoleSimpleShaftMaterializationStatus.InvalidSemanticHole, null, null, diagnostics);
+ }
+
+ if (!IsFinite(host.Width) || !IsFinite(host.Depth) || !IsFinite(host.ZMin) || !IsFinite(host.ZMax) || host.Width <= 0d || host.Depth <= 0d || host.Thickness <= Tolerance)
+ {
+ diagnostics.Add("air-hole-x2 rejected: host must be a finite rectangular profile stack with positive width/depth/thickness.");
+ return new(AirHoleSimpleShaftMaterializationStatus.UnsupportedPlacement, null, null, diagnostics);
+ }
+
+ if (Math.Abs(feature.Placement.U) + feature.Shaft.Radius > host.Width / 2d + Tolerance ||
+ Math.Abs(feature.Placement.V) + feature.Shaft.Radius > host.Depth / 2d + Tolerance)
+ {
+ diagnostics.Add("air-hole-x2 rejected: face-local center/radius does not fit within the supported rectangular entry face.");
+ return new(AirHoleSimpleShaftMaterializationStatus.UnsupportedPlacement, null, null, diagnostics);
+ }
+
+ var axisZ = feature.Axis.Direction.Z;
+ var top = string.Equals(feature.Placement.EntryFaceName, host.TopFaceName, StringComparison.OrdinalIgnoreCase) && axisZ > 1d - Tolerance;
+ var bottom = string.Equals(feature.Placement.EntryFaceName, host.BottomFaceName, StringComparison.OrdinalIgnoreCase) && axisZ < -1d + Tolerance;
+ if (!top && !bottom)
+ {
+ diagnostics.Add("air-hole-x2 rejected: only planar top/+Z and bottom/-Z face-local placements are supported by this rectangular profile-stack lowering lane.");
+ return new(AirHoleSimpleShaftMaterializationStatus.UnsupportedPlacement, null, null, diagnostics);
+ }
+
+ var (cutZMin, cutZMax) = ResolveCutSpan(feature, host, top);
+ if (cutZMax - cutZMin <= Tolerance)
+ {
+ diagnostics.Add("air-hole-x2 rejected: resolved cut span is empty.");
+ return new(AirHoleSimpleShaftMaterializationStatus.UnsupportedPlacement, null, null, diagnostics);
+ }
+
+ var layers = BuildLayers(feature, host, cutZMin, cutZMax).ToArray();
+ var spec = new ProfileStackExtrudeSpec(host.Width, host.Depth, host.ZMin, host.ZMax, layers,
+ [$"air-hole-x2 provenance featureId={feature.FeatureId}", $"air-hole-x2 provenance source={nameof(AirHoleFeature)}"],
+ feature.Placement.U,
+ feature.Placement.V);
+ var plan = new AirHoleSimpleShaftMaterializationPlan(feature, host, feature.FeatureId, nameof(AirHoleFeature), feature.Placement.EntryFaceName,
+ feature.Placement.U, feature.Placement.V, axisZ, feature.Shaft.Radius, cutZMin, cutZMax, feature.EndCondition.Kind, spec, diagnostics.ToArray());
+ diagnostics.Add("air-hole-x2 plan created; semantic AirHoleFeature remains parent intent.");
+ return new(AirHoleSimpleShaftMaterializationStatus.Succeeded, plan, null, diagnostics);
+ }
+
+ private static (double CutZMin, double CutZMax) ResolveCutSpan(AirHoleFeature feature, AirHoleSimpleShaftHost host, bool top)
+ {
+ if (feature.EndCondition is AirHoleEndCondition.ThroughAll) return (host.ZMin, host.ZMax);
+ var depth = ((AirHoleEndCondition.Depth)feature.EndCondition).Value;
+ return top ? (Math.Max(host.ZMin, host.ZMax - depth), host.ZMax) : (host.ZMin, Math.Min(host.ZMax, host.ZMin + depth));
+ }
+
+ private static IEnumerable<ProfileStackLayer> BuildLayers(AirHoleFeature feature, AirHoleSimpleShaftHost host, double cutZMin, double cutZMax)
+ {
+ if (cutZMin > host.ZMin + Tolerance) yield return new(host.ZMin, cutZMin, null, "air-hole-x2-solid-before-blind-depth", []);
+ yield return new(cutZMin, cutZMax, feature.Shaft.Radius, $"air-hole-x2-simple-shaft:{feature.FeatureId}", []);
+ if (cutZMax < host.ZMax - Tolerance) yield return new(cutZMax, host.ZMax, null, "air-hole-x2-solid-after-blind-depth", []);
+ }
+
+ private static bool IsFinite(double value) => !double.IsNaN(value) && !double.IsInfinity(value);
+}
diff --git a/Aetheris.Kernel.Firmament/Materializer/ProfileStackExtrudeExecutor.cs b/Aetheris.Kernel.Firmament/Materializer/ProfileStackExtrudeExecutor.cs
index 21499c36..95e0d053 100644
--- a/Aetheris.Kernel.Firmament/Materializer/ProfileStackExtrudeExecutor.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/ProfileStackExtrudeExecutor.cs
@@ -28,7 +28,9 @@ public sealed record ProfileStackExtrudeSpec(
double ZMin,
double ZMax,
IReadOnlyList<ProfileStackLayer> Layers,
- IReadOnlyList<string> Diagnostics);
+ IReadOnlyList<string> Diagnostics,
+ double CenterX = 0d,
+ double CenterY = 0d);
public sealed record ProfileStackExtrudeExecutionResult(
ProfileStackExtrudeExecutionStatus Status,
@@ -69,9 +71,9 @@ public static class ProfileStackExtrudeExecutor
: (Math.Abs(l.ZMax - spec.ZMax) < 1e-9
? SupportedBooleanHoleSpanKind.BlindFromTop
: SupportedBooleanHoleSpanKind.Contained);
- var cyl = new RecognizedCylinder(new Point3D(0, 0, 0), zAxis, l.InnerCircleRadius!.Value, l.ZMin, l.ZMax);
+ var cyl = new RecognizedCylinder(new Point3D(spec.CenterX, spec.CenterY, 0), zAxis, l.InnerCircleRadius!.Value, l.ZMin, l.ZMax);
holes.Add(new SupportedBooleanHole(l.Role, new AnalyticSurface(AnalyticSurfaceKind.Cylinder, Cylinder: cyl), 0, 0,
- new Point3D(0, 0, l.ZMin), new Point3D(0, 0, l.ZMax), zAxis, xAxis,
+ new Point3D(spec.CenterX, spec.CenterY, l.ZMin), new Point3D(spec.CenterX, spec.CenterY, l.ZMax), zAxis, xAxis,
l.InnerCircleRadius.Value, l.InnerCircleRadius.Value, span, l.ZMin, l.ZMax));
}
diff --git a/docs/implementation/hole-x1-semantic-hole-feature.md b/docs/implementation/hole-x1-semantic-hole-feature.md
index 8d155f53..2763b81f 100644
--- a/docs/implementation/hole-x1-semantic-hole-feature.md
+++ b/docs/implementation/hole-x1-semantic-hole-feature.md
@@ -33,3 +33,7 @@ The semantic rule is that a hole remains a feature until a lower execution layer
## Why intent must survive before lowering
Manufacturing features carry identity, placement, end-condition, and provenance that a bare cylinder or BRep subtraction cannot reliably express. Preserving that intent lets later milestones add stack components, standards, PMI, diagnostics, and controlled lowerers without changing the authoring contract or forcing recovery machinery to guess what the user meant.
+
+## HOLE-X2 continuation
+
+HOLE-X2 adds an executable simple-shaft materialization lane for the scaffold introduced here. See `docs/implementation/hole-x2-simple-shaft-hole-materialization.md` for the bounded profile-stack/BRep route, provenance story, and remaining deferred hole-family scope.
diff --git a/docs/implementation/hole-x2-simple-shaft-hole-materialization.md b/docs/implementation/hole-x2-simple-shaft-hole-materialization.md
new file mode 100644
index 00000000..50f7eac4
--- /dev/null
+++ b/docs/implementation/hole-x2-simple-shaft-hole-materialization.md
@@ -0,0 +1,63 @@
+# HOLE-X2 simple shaft hole materialization
+
+HOLE-X2 makes the first production semantic-hole vertical slice executable: a semantic `AirHoleFeature` simple shaft hole can now lower through a bounded Firmament materialization lane into BRep output while preserving the semantic hole as parent intent.
+
+## What materializes now
+
+The implemented executable family is intentionally narrow:
+
+- semantic `AirHoleFeature` only;
+- simple shaft hole only;
+- planar face-local entry placement on the supported rectangular profile-stack host lane;
+- top/+Z and bottom/-Z entry directions for the current rectangular host path;
+- shaft diameter/radius from the semantic feature;
+- `throughAll` and fixed `depth` end conditions;
+- BRep output via the existing `ProfileStackExtrudeExecutor`/safe box-cylinder composition route.
+
+The current production lane uses the same rectangular profile-stack execution infrastructure used by the bounded hole-family materializer work. Face-local `U`/`V` coordinates are validated against the rectangular entry face, preserved in the HOLE-X2 plan, and passed into the profile-stack executor as the shaft center for this simple rectangular host lane.
+
+## Materialization path
+
+The executable route is:
+
+```text
+AirHoleFeature
+ -> AirHoleSimpleShaftMaterializationPlan
+ SemanticFeature / SemanticFeatureId / SemanticSourceKind
+ EntryFaceName + face-local U/V
+ AxisZ
+ Radius
+ CutZMin/CutZMax
+ EndConditionKind
+ -> ProfileStackExtrudeSpec
+ -> ProfileStackExtrudeExecutor
+ -> BrepBody
+```
+
+`ProfileStackExtrudeSpec` is lower-level implementation furniture only. It is not exposed as the AIR semantic source model, and the plan keeps the source `AirHoleFeature` object plus stable feature id so tests and diagnostics can trace the materialized body back to the semantic parent.
+
+## End-condition behavior
+
+- `throughAll` creates one circular cut interval spanning the full host thickness.
+- `depth` creates a bounded circular cut interval from the entry face inward plus a solid interval for the uncut remainder.
+- Depths larger than the host thickness clamp to the full host span in this lane, which deterministically yields through-like geometry while preserving `EndConditionKind.Depth` in the semantic plan. Invalid non-positive depths remain rejected by HOLE-X1 validation before materialization.
+
+## Unsupported/deferred features
+
+HOLE-X2 deliberately does not add counterbore, countersink, mouth chamfer, drill-tip geometry, thread/tap geometry, standards/fit libraries, hole groups, patterns, arbitrary datum placement, `upToFace`, `upToNext`, non-planar entry faces, multi-body propagation, broad parser syntax, or general raw 3D Boolean authoring.
+
+Unsupported placement produces deterministic diagnostics and no anonymous `CylinderCut` fallback.
+
+## Relationship to `07-holes-are-semantic-features.md`
+
+The semantic rule remains unchanged: holes are semantic features, not anonymous cylinders. HOLE-X2 adds an executable lowering boundary for the smallest safe family while keeping profile stacks, cylindrical faces, safe booleans, trim loops, and BRep details below that boundary.
+
+## Validation commands
+
+The HOLE-X2 changes were validated with:
+
+```bash
+dotnet test Aetheris.Kernel.Firmament.Tests/Aetheris.Kernel.Firmament.Tests.csproj -f net10.0 --filter AirHoleSimpleShaft --logger "console;verbosity=minimal"
+```
+
+Full milestone validation should also run the solution restore/build and focused `Air`/`Hole`/`FirmamentV2` filters documented in the milestone prompt.