Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-F10.8 planar retained patch-set emitter

Yuechen Li4b2c08afa2cf
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
index e8a5f346..9fc302a0 100644
--- a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
@@ -232,6 +232,58 @@ public sealed class SurfacePatchDescriptorScaffoldTests
Assert.Contains(result.Diagnostics, d => d.Contains("multiple inner loops", StringComparison.OrdinalIgnoreCase));
}
+ [Fact]
+ public void PlanarPatchSet_BoxMinusCylinder_EmitsSupportedPlanarPatches()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
+ var result = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
+ Assert.True(result.Success);
+ Assert.True(result.EmittedCount > 0);
+ Assert.False(result.FullMaterialization);
+ Assert.Contains(result.Diagnostics, d => d.Contains("partial planar patch set", StringComparison.OrdinalIgnoreCase));
+ Assert.Contains(result.RemainingBlockers, d => d.Contains("cylindrical side surface emission", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void PlanarPatchSet_BoxMinusCylinder_IncludesInnerCirclePatchWhenEvidenceExists()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
+ var generation = FacePatchCandidateGenerator.Generate(root);
+ var hasCanonicalInnerEvidence = generation.Candidates.Any(c =>
+ c.RetentionRole == FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool
+ && c.SourceSurface.Family == SurfacePatchFamily.Planar
+ && c.RetainedRegionLoops.Any(l => l.LoopKind == RetainedRegionLoopKind.InnerTrim && l.CircularGeometry is not null && l.Status == RetainedRegionLoopStatus.ExactReady));
+ var result = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
+ if (hasCanonicalInnerEvidence)
+ {
+ Assert.Contains(result.Entries, e => e.Emitted && e.Emission?.Body?.Topology.Loops.Count() == 2);
+ }
+ else
+ {
+ Assert.DoesNotContain(result.Entries, e => e.Emitted && e.Emission?.Body?.Topology.Loops.Count() == 2);
+ }
+ }
+
+ [Fact]
+ public void PlanarPatchSet_SkipsCylindricalToolCandidate()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
+ var result = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
+ Assert.Contains(result.Entries, e =>
+ !e.Emitted
+ && e.Candidate.SourceSurface.Family == SurfacePatchFamily.Cylindrical
+ && e.Diagnostics.Any(d => d.Contains("retention role", StringComparison.OrdinalIgnoreCase)));
+ }
+
+ [Fact]
+ public void PlanarPatchSet_DoesNotClaimShellAssembly()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
+ var result = new PlanarSurfaceMaterializer().EmitSupportedPlanarPatches(root);
+ Assert.False(result.FullMaterialization);
+ Assert.Contains(result.Diagnostics, d => d.Contains("no shell assembly attempted", StringComparison.OrdinalIgnoreCase));
+ }
+
[Fact]
public void PlanarPayloadBuilder_RejectsNonPlanarSource()
{
diff --git a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
index 7cd2425f..a2e146de 100644
--- a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
+++ b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
@@ -1,4 +1,5 @@
using Aetheris.Kernel.Core.Geometry;
+using Aetheris.Kernel.Core.Cir;
using Aetheris.Kernel.Core.Geometry.Curves;
using Aetheris.Kernel.Core.Geometry.Surfaces;
using Aetheris.Kernel.Core.Brep;
@@ -160,6 +161,22 @@ internal sealed record SurfaceFamilyMaterializerEvaluation(
internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
{
+ internal sealed record PlanarPatchSetEntry(
+ FacePatchCandidate Candidate,
+ SurfaceMaterializationResult? Emission,
+ bool Emitted,
+ IReadOnlyList<string> Diagnostics);
+
+ internal sealed record PlanarPatchSetMaterializationResult(
+ bool Success,
+ IReadOnlyList<BrepBody> EmittedBodies,
+ int EmittedCount,
+ int SkippedCount,
+ bool FullMaterialization,
+ IReadOnlyList<PlanarPatchSetEntry> Entries,
+ IReadOnlyList<string> RemainingBlockers,
+ IReadOnlyList<string> Diagnostics);
+
internal enum PlanarLoopSupportStatus
{
Supported,
@@ -277,6 +294,109 @@ internal sealed class PlanarSurfaceMaterializer : ISurfaceFamilyMaterializer
return EmitRectangleWithInnerCircleBody(outer, circles[0]);
}
+ internal PlanarPatchSetMaterializationResult EmitSupportedPlanarPatches(CirNode root, NativeGeometryReplayLog? replayLog = null)
+ {
+ var generation = FacePatchCandidateGenerator.Generate(root, replayLog);
+ var entries = new List<PlanarPatchSetEntry>();
+ var emittedBodies = new List<BrepBody>();
+ var diagnostics = new List<string> { "scope-note: partial planar patch set only; no shell assembly attempted." };
+ var blockers = new List<string> { "remaining-blocker: cylindrical side surface emission not implemented (CylindricalSurfaceMaterializer topology emission pending)." };
+
+ foreach (var candidate in generation.Candidates)
+ {
+ if (candidate.RetentionRole != FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool)
+ {
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, ["skipped-candidate: retention role is not base-boundary retained outside tool."]));
+ continue;
+ }
+
+ if (candidate.SourceSurface.Family != SurfacePatchFamily.Planar)
+ {
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, ["skipped-non-planar-candidate: planar patch set emitter supports planar family only."]));
+ continue;
+ }
+
+ if (candidate.Readiness is FacePatchCandidateReadiness.RetentionDeferred or FacePatchCandidateReadiness.TrimDeferred or FacePatchCandidateReadiness.Unsupported)
+ {
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, [$"skipped-candidate-readiness: {candidate.Readiness}."]));
+ continue;
+ }
+
+ var readiness = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 1, 1, 1, 0, 0, 0, 0, [], false);
+ var retainedCircles = candidate.RetainedRegionLoops
+ .Where(l => l.LoopKind == RetainedRegionLoopKind.InnerTrim && l.CircularGeometry is not null && l.Status == RetainedRegionLoopStatus.ExactReady)
+ .Select(l => l.CircularGeometry!.Value)
+ .ToArray();
+ SurfaceMaterializationResult? emission = null;
+ if (retainedCircles.Length == 0)
+ {
+ if (candidate.SourceSurface.BoundedPlanarGeometry is not { Kind: BoundedPlanarPatchGeometryKind.Rectangle })
+ {
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, ["skipped-missing-rectangular-geometry: rectangular bounded planar geometry is required."]));
+ continue;
+ }
+
+ if (!PlanarPatchPayloadBuilder.TryBuildRectanglePayload(candidate.SourceSurface, out var rectanglePayload, out var payloadDiagnostic))
+ {
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, [$"skipped-missing-rectangular-geometry: {payloadDiagnostic}"]));
+ continue;
+ }
+
+ var normalizedSource = candidate.SourceSurface with { ParameterPayloadReference = rectanglePayload };
+ var normalizedPatch = candidate.ProposedPatch with { SourceSurface = normalizedSource };
+ emission = Emit(normalizedPatch, readiness);
+ if (!emission.Success)
+ {
+ entries.Add(new PlanarPatchSetEntry(candidate, emission, false, emission.Diagnostics));
+ continue;
+ }
+
+ emittedBodies.Add(emission.Body!);
+ entries.Add(new PlanarPatchSetEntry(candidate, emission, true, ["emitted-untrimmed-planar-patch: retained planar rectangle emitted without inner loops."]));
+ continue;
+ }
+
+ if (retainedCircles.Length > 1)
+ {
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, ["skipped-multiple-inner-loops: multiple retained circular loops are unsupported in CIR-F10.8."]));
+ continue;
+ }
+
+ var normalizedTrimmedSource = candidate.SourceSurface;
+ if (!PlanarPatchPayloadBuilder.TryBuildRectanglePayload(candidate.SourceSurface, out var trimmedPayload, out _))
+ {
+ entries.Add(new PlanarPatchSetEntry(candidate, null, false, ["skipped-missing-rectangular-geometry: bounded rectangular payload derivation failed for trimmed planar patch."]));
+ continue;
+ }
+
+ normalizedTrimmedSource = normalizedTrimmedSource with { ParameterPayloadReference = trimmedPayload };
+ emission = EmitRectangleWithInnerCircle(new RectWithInnerCircleEmissionRequest(normalizedTrimmedSource, retainedCircles[0], null, readiness));
+ if (!emission.Success)
+ {
+ entries.Add(new PlanarPatchSetEntry(candidate, emission, false, emission.Diagnostics));
+ continue;
+ }
+
+ emittedBodies.Add(emission.Body!);
+ entries.Add(new PlanarPatchSetEntry(candidate, emission, true, ["emitted-inner-circle-planar-patch: retained planar rectangle emitted with one canonical inner circular loop."]));
+ }
+
+ var emittedCount = entries.Count(e => e.Emitted);
+ var skippedCount = entries.Count - emittedCount;
+ diagnostics.Add($"planar-patch-set-summary: emitted={emittedCount} skipped={skippedCount} total={entries.Count}");
+ diagnostics.Add("full-materialization: false (planar subset only).");
+ diagnostics.AddRange(generation.Diagnostics);
+ return new PlanarPatchSetMaterializationResult(
+ Success: emittedCount > 0,
+ EmittedBodies: emittedBodies,
+ EmittedCount: emittedCount,
+ SkippedCount: skippedCount,
+ FullMaterialization: false,
+ Entries: entries,
+ RemainingBlockers: blockers,
+ Diagnostics: diagnostics.Distinct().ToArray());
+ }
+
private static SurfaceMaterializationResult EmitRectangleWithInnerCircleBody(BoundedPlanarPatchGeometry rect, RetainedCircularLoopGeometry inner)
{
var p = new[] { rect.Corner00, rect.Corner10, rect.Corner11, rect.Corner01 };
diff --git a/docs/cir-f108-planar-patch-set-emission.md b/docs/cir-f108-planar-patch-set-emission.md
new file mode 100644
index 00000000..f4ceaa5c
--- /dev/null
+++ b/docs/cir-f108-planar-patch-set-emission.md
@@ -0,0 +1,80 @@
+# CIR-F10.8 — Planar retained patch set emission (`Subtract(Box, Cylinder)`)
+
+## Purpose
+
+CIR-F10.8 adds a partial-surface emitter that materializes all **currently supported planar retained base patches** from real dry-run evidence for `Subtract(Box, Cylinder)`.
+
+This milestone is intentionally bounded:
+
+- emits planar base-side retained patches only,
+- keeps readiness-gated emission (`no readiness, no emission`),
+- preserves diagnostic-first behavior,
+- does **not** assemble a shell/solid.
+
+## API and result semantics
+
+`PlanarSurfaceMaterializer.EmitSupportedPlanarPatches(CirNode root, NativeGeometryReplayLog? replayLog = null)` returns a planar patch-set result with:
+
+- success flag,
+- emitted standalone planar patch bodies,
+- emitted and skipped counts,
+- per-candidate emitted/skipped diagnostics,
+- `FullMaterialization = false`,
+- remaining blockers (including cylindrical side emission).
+
+## Candidate filtering and emission categories
+
+The patch-set emitter consumes dry-run candidates from `FacePatchCandidateGenerator.Generate(...)` and evaluates each candidate with explicit categories:
+
+1. **Skipped non-planar or non-base candidates**
+ - not `RetentionRole = BaseBoundaryRetainedOutsideTool`, or
+ - not `SurfaceFamily = Planar`.
+
+2. **Skipped readiness-blocked candidates**
+ - candidate readiness is deferred/unsupported.
+
+3. **Emitted untrimmed rectangular planar patch**
+ - planar + base retained + rectangle geometry,
+ - no retained canonical inner circular loops.
+
+4. **Emitted rectangular planar patch with one inner circular loop**
+ - planar + base retained + rectangle geometry,
+ - exactly one canonical retained circular loop.
+
+5. **Skipped unsupported planar candidates**
+ - missing rectangle geometry,
+ - multiple inner loops,
+ - missing circular loop geometry for trimmed path,
+ - readiness blocked.
+
+## Expected `box - cylinder` outcome
+
+For canonical subtract dry-run evidence:
+
+- supported planar retained faces are emitted as standalone one-face bodies,
+- at least one rectangular-with-inner-circle planar patch can emit when canonical loop evidence exists,
+- cylindrical tool-side wall is not emitted and is reported as a remaining blocker,
+- full materialization/shell assembly remains out of scope.
+
+## Why this is not full materialization
+
+CIR-F10.8 deliberately avoids:
+
+- cylindrical side emission,
+- multi-family surface completion,
+- shell stitching,
+- solid closure/materialization claims.
+
+The result is a **partial planar family emission milestone**.
+
+## SEM-A0 alignment
+
+The implementation keeps semantic provenance/readiness guardrails in place:
+
+- candidate provenance remains dry-run sourced,
+- emission is bounded to supported readiness-qualified candidates,
+- unsupported/deferred paths are explicitly diagnostic.
+
+## Next milestone
+
+Implement cylindrical retained side-surface emission and safe shell assembly planning so planar and cylindrical retained families can be combined into a topology-complete materialization path.