Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-F8.5 retained-region loop scaffolding

Yuechen Li06c81eb1eae7
diff --git a/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs b/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs
index 43cde92b..4daeb7f7 100644
--- a/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs
@@ -6,7 +6,7 @@ namespace Aetheris.Kernel.Firmament.Tests;
public sealed class FacePatchCandidateDryRunTests
{
[Fact]
- public void Retention_BoxMinusCylinder_ClassifiesBaseAndToolRoles()
+ public void LoopScaffold_BoxMinusCylinder_ProducesTrimLoopDescriptors()
{
var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
@@ -16,11 +16,15 @@ public sealed class FacePatchCandidateDryRunTests
Assert.Contains(result.Candidates, c => c.CandidateRole == "base-surface-candidate" && c.RetentionRole == FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool);
Assert.Contains(result.Candidates, c => c.SourceSurface.Family == SurfacePatchFamily.Cylindrical && c.RetentionRole == FacePatchRetentionRole.ToolBoundaryRetainedInsideBase);
Assert.Contains(result.Candidates, c => c.RetentionStatus == FacePatchRetentionStatus.KnownTrimmedSurface);
+ Assert.Contains(result.Candidates, c => c.CandidateRole == "base-surface-candidate" && c.RetainedRegionLoops.Any(l => l.SourceSurfaceFamily == SurfacePatchFamily.Planar));
+ Assert.Contains(result.Candidates, c => c.SourceSurface.Family == SurfacePatchFamily.Cylindrical && c.RetainedRegionLoops.Any(l => l.OppositeSurfaceFamily == SurfacePatchFamily.Planar));
+ Assert.Contains(result.Candidates.SelectMany(c => c.RetainedRegionLoops), l => l.TrimCurveFamily is TrimCurveFamily.Line or TrimCurveFamily.Circle or TrimCurveFamily.Ellipse);
+ Assert.Contains(result.Candidates.SelectMany(c => c.RetainedRegionLoops), l => l.Status is RetainedRegionLoopStatus.ExactReady or RetainedRegionLoopStatus.SpecialCaseReady);
Assert.False(result.TopologyAssemblyImplemented);
}
[Fact]
- public void Retention_BoxMinusSphere_ReportsSphericalToolRetainedInsideBase()
+ public void LoopScaffold_BoxMinusSphere_ProducesCircularTrimLoopDescriptors()
{
var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(3));
@@ -36,11 +40,12 @@ public sealed class FacePatchCandidateDryRunTests
|| (t.FamilyA == SurfacePatchFamily.Spherical && t.FamilyB == SurfacePatchFamily.Planar))
&& t.Classification == TrimCapabilityClassification.ExactSupported
&& t.CurveFamilies.Contains(TrimCurveFamily.Circle));
+ Assert.Contains(result.Candidates, c => c.SourceSurface.Family == SurfacePatchFamily.Spherical && c.RetainedRegionLoops.Any(l => l.TrimCurveFamily == TrimCurveFamily.Circle && l.Status == RetainedRegionLoopStatus.ExactReady));
Assert.DoesNotContain(result.Candidates, c => c.Diagnostics.Any(d => d.Contains("generic unsupported", StringComparison.OrdinalIgnoreCase)));
}
[Fact]
- public void Retention_BoxMinusTorus_ReportsKnownRoleButTrimDeferred()
+ public void LoopScaffold_BoxMinusTorus_ProducesDeferredLoopDiagnostics()
{
var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirTorusNode(4, 1));
@@ -53,10 +58,13 @@ public sealed class FacePatchCandidateDryRunTests
&& c.Readiness == FacePatchCandidateReadiness.TrimDeferred
&& c.RetentionStatus == FacePatchRetentionStatus.Deferred);
Assert.Contains(result.Candidates.SelectMany(c => c.Diagnostics), d => d.Contains("quartic/algebraic", StringComparison.OrdinalIgnoreCase));
+ Assert.Contains(result.Candidates, c =>
+ c.SourceSurface.Family == SurfacePatchFamily.Toroidal
+ && c.RetainedRegionLoops.Any(l => l.Status == RetainedRegionLoopStatus.Deferred));
}
[Fact]
- public void Retention_NonSubtract_IsDeferredOrNotApplicable()
+ public void LoopScaffold_NonSubtract_DoesNotInventLoops()
{
var root = new CirUnionNode(new CirBoxNode(10, 10, 10), new CirSphereNode(2));
@@ -65,6 +73,7 @@ public sealed class FacePatchCandidateDryRunTests
Assert.False(result.IsSuccess);
Assert.All(result.Candidates, c => Assert.Equal(FacePatchRetentionRole.NotApplicable, c.RetentionRole));
Assert.All(result.Candidates, c => Assert.Equal(FacePatchRetentionStatus.Deferred, c.RetentionStatus));
+ Assert.All(result.Candidates, c => Assert.Empty(c.RetainedRegionLoops));
}
[Fact]
diff --git a/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs b/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs
index caa1b4f6..645a2566 100644
--- a/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs
+++ b/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs
@@ -28,6 +28,36 @@ internal enum FacePatchRetentionStatus
Unsupported
}
+internal enum RetainedRegionLoopKind
+{
+ OuterBoundary,
+ InnerTrim,
+ MouthTrim,
+ CapTrim,
+ SeamTrim,
+ Deferred,
+ Unsupported
+}
+
+internal enum RetainedRegionLoopStatus
+{
+ ExactReady,
+ SpecialCaseReady,
+ Deferred,
+ Unsupported
+}
+
+internal sealed record RetainedRegionLoopDescriptor(
+ RetainedRegionLoopKind LoopKind,
+ TrimCurveFamily TrimCurveFamily,
+ TrimCapabilityClassification TrimCapability,
+ SurfacePatchFamily SourceSurfaceFamily,
+ SurfacePatchFamily OppositeSurfaceFamily,
+ FacePatchOrientationRole OrientationHint,
+ FacePatchRetentionRole RetentionRole,
+ RetainedRegionLoopStatus Status,
+ string Diagnostic);
+
internal sealed record FacePatchCandidate(
SourceSurfaceDescriptor SourceSurface,
FacePatchDescriptor ProposedPatch,
@@ -38,6 +68,9 @@ internal sealed record FacePatchCandidate(
FacePatchRetentionStatus RetentionStatus,
string RetentionReason,
IReadOnlyList<SurfacePatchFamily> OppositeFamilies,
+ IReadOnlyList<RetainedRegionLoopDescriptor> RetainedRegionLoops,
+ RetainedRegionLoopStatus LoopReadiness,
+ string LoopDiagnostic,
IReadOnlyList<string> Diagnostics);
internal sealed record FacePatchCandidateGenerationResult(
@@ -81,6 +114,9 @@ internal static class FacePatchCandidateGenerator
FacePatchRetentionStatus.Deferred,
"retention-not-applicable: CIR-F8.4 retention classification applies to subtract roots only.",
[],
+ [],
+ RetainedRegionLoopStatus.Deferred,
+ "loop-retention-not-applicable: retained-region loop scaffolding applies to subtract roots with classified retention only.",
["retention-not-applicable: non-subtract root leaves candidate retention unclassified."]));
}
@@ -104,6 +140,9 @@ internal static class FacePatchCandidateGenerator
var readiness = EvaluateReadiness(trim);
var (retentionRole, retentionStatus, retentionReason) = EvaluateRetention(isBase, trim, relevantOther.Count);
+ var loopDescriptors = BuildRetainedRegionLoops(source, relevantOther, retentionRole, retentionStatus, isBase);
+ var loopReadiness = EvaluateLoopReadiness(loopDescriptors);
+ var loopDiagnostic = BuildLoopDiagnostic(loopDescriptors, retentionStatus);
var candidateDiagnostics = new List<string>();
if (trim is null)
{
@@ -135,15 +174,18 @@ internal static class FacePatchCandidateGenerator
candidateDiagnostics.Add($"retention-role: {retentionRole}");
candidateDiagnostics.Add($"retention-status: {retentionStatus}");
candidateDiagnostics.Add(retentionReason);
+ candidateDiagnostics.Add($"loop-readiness: {loopReadiness}");
+ candidateDiagnostics.Add(loopDiagnostic);
+ candidateDiagnostics.AddRange(loopDescriptors.Select(l => l.Diagnostic));
var orientation = isBase ? source.OrientationRole : FacePatchOrientationRole.Reversed;
var patchRole = isBase ? "base-boundary-retained-outside-tool" : "tool-boundary-retained-inside-base";
var patch = new FacePatchDescriptor(source, [], [], orientation, patchRole, []);
- candidates.Add(new FacePatchCandidate(source, patch, role, readiness, trim, retentionRole, retentionStatus, retentionReason, oppositeFamilies, candidateDiagnostics));
+ candidates.Add(new FacePatchCandidate(source, patch, role, readiness, trim, retentionRole, retentionStatus, retentionReason, oppositeFamilies, loopDescriptors, loopReadiness, loopDiagnostic, candidateDiagnostics));
}
diagnostics.Add("topology-assembly-not-implemented: dry-run emits candidate descriptors only and does not emit BRep topology.");
- diagnostics.Add("retention-region-deferred: subtract retention roles are classified, but retained trim loops and topology assembly are deferred in CIR-F8.4.");
+ diagnostics.Add("topology-assembly-not-implemented: retained-region loop scaffolding emits descriptor diagnostics only; no BRep loops/coedges/edges/vertices are created.");
var success = extraction.IsSuccess && candidates.Count > 0;
return new(success, candidates, extraction.Descriptors, trimSummaries, extraction.Diagnostics, deferred.Distinct().ToArray(), diagnostics, TopologyAssemblyImplemented: false);
@@ -230,4 +272,103 @@ internal static class FacePatchCandidateGenerator
private static (SurfacePatchFamily, SurfacePatchFamily) Normalize(SurfacePatchFamily a, SurfacePatchFamily b)
=> a <= b ? (a, b) : (b, a);
+
+ private static IReadOnlyList<RetainedRegionLoopDescriptor> BuildRetainedRegionLoops(
+ SourceSurfaceDescriptor source,
+ IReadOnlyList<SourceSurfaceDescriptor> opposite,
+ FacePatchRetentionRole retentionRole,
+ FacePatchRetentionStatus retentionStatus,
+ bool isBase)
+ {
+ if (retentionRole is FacePatchRetentionRole.NotApplicable or FacePatchRetentionRole.RetentionDeferred)
+ {
+ return [];
+ }
+
+ if (retentionStatus != FacePatchRetentionStatus.KnownTrimmedSurface && retentionStatus != FacePatchRetentionStatus.Deferred)
+ {
+ return [];
+ }
+
+ var loops = new List<RetainedRegionLoopDescriptor>();
+ foreach (var other in opposite)
+ {
+ var trim = TrimCapabilityMatrix.Evaluate(source.Family, other.Family);
+ var loopKind = DetermineLoopKind(source.Family, isBase, trim.Classification);
+ var status = trim.Classification switch
+ {
+ TrimCapabilityClassification.ExactSupported => RetainedRegionLoopStatus.ExactReady,
+ TrimCapabilityClassification.SpecialCaseOnly => RetainedRegionLoopStatus.SpecialCaseReady,
+ TrimCapabilityClassification.Deferred => RetainedRegionLoopStatus.Deferred,
+ _ => RetainedRegionLoopStatus.Unsupported
+ };
+
+ var families = trim.CurveFamilies.Count == 0 ? [TrimCurveFamily.Unsupported] : trim.CurveFamilies;
+ foreach (var curveFamily in families)
+ {
+ loops.Add(new RetainedRegionLoopDescriptor(
+ loopKind,
+ curveFamily,
+ trim.Classification,
+ source.Family,
+ other.Family,
+ isBase ? source.OrientationRole : FacePatchOrientationRole.Reversed,
+ retentionRole,
+ status,
+ BuildPerLoopDiagnostic(source.Family, other.Family, curveFamily, status, trim.Reason)));
+ }
+ }
+
+ return loops;
+ }
+
+ private static RetainedRegionLoopKind DetermineLoopKind(SurfacePatchFamily sourceFamily, bool isBase, TrimCapabilityClassification classification)
+ {
+ if (classification == TrimCapabilityClassification.Deferred) return RetainedRegionLoopKind.Deferred;
+ if (classification == TrimCapabilityClassification.Unsupported) return RetainedRegionLoopKind.Unsupported;
+ if (isBase) return RetainedRegionLoopKind.InnerTrim;
+ return sourceFamily == SurfacePatchFamily.Cylindrical || sourceFamily == SurfacePatchFamily.Spherical
+ ? RetainedRegionLoopKind.MouthTrim
+ : RetainedRegionLoopKind.InnerTrim;
+ }
+
+ private static RetainedRegionLoopStatus EvaluateLoopReadiness(IReadOnlyList<RetainedRegionLoopDescriptor> loops)
+ {
+ if (loops.Count == 0) return RetainedRegionLoopStatus.Deferred;
+ if (loops.Any(l => l.Status == RetainedRegionLoopStatus.ExactReady)) return RetainedRegionLoopStatus.ExactReady;
+ if (loops.Any(l => l.Status == RetainedRegionLoopStatus.SpecialCaseReady)) return RetainedRegionLoopStatus.SpecialCaseReady;
+ if (loops.Any(l => l.Status == RetainedRegionLoopStatus.Deferred)) return RetainedRegionLoopStatus.Deferred;
+ return RetainedRegionLoopStatus.Unsupported;
+ }
+
+ private static string BuildLoopDiagnostic(IReadOnlyList<RetainedRegionLoopDescriptor> loops, FacePatchRetentionStatus retentionStatus)
+ {
+ if (loops.Count == 0)
+ {
+ return retentionStatus == FacePatchRetentionStatus.Deferred
+ ? "loop-scaffold-deferred: retention is deferred, so retained-region loop descriptors are not emitted."
+ : "loop-scaffold-empty: no retained-region loops were generated for this candidate.";
+ }
+
+ if (loops.All(l => l.Status == RetainedRegionLoopStatus.Deferred))
+ {
+ return "loop-scaffold-deferred: trim matrix marks all retained-region loops deferred.";
+ }
+
+ if (loops.Any(l => l.Status == RetainedRegionLoopStatus.SpecialCaseReady) && !loops.Any(l => l.Status == RetainedRegionLoopStatus.ExactReady))
+ {
+ return "loop-scaffold-special-case-ready: retained-region loop types are known with special-case restrictions; exact parameter solving remains deferred.";
+ }
+
+ return "loop-scaffold-ready: retained-region loop types are known; exact curve parameters and topology assembly remain deferred.";
+ }
+
+ private static string BuildPerLoopDiagnostic(SurfacePatchFamily source, SurfacePatchFamily opposite, TrimCurveFamily family, RetainedRegionLoopStatus status, string reason)
+ => status switch
+ {
+ RetainedRegionLoopStatus.ExactReady => $"loop-exact-ready: {source}/{opposite} uses {family} trim family; parameters deferred ({reason})",
+ RetainedRegionLoopStatus.SpecialCaseReady => $"loop-special-case-ready: {source}/{opposite} uses {family} trim family with restrictions ({reason})",
+ RetainedRegionLoopStatus.Deferred => $"loop-deferred: {source}/{opposite} trim loop remains deferred ({reason})",
+ _ => $"loop-unsupported: {source}/{opposite} trim loop unsupported ({reason})"
+ };
}
diff --git a/docs/cir-f85-retained-region-loop-scaffolding.md b/docs/cir-f85-retained-region-loop-scaffolding.md
new file mode 100644
index 00000000..fc701613
--- /dev/null
+++ b/docs/cir-f85-retained-region-loop-scaffolding.md
@@ -0,0 +1,82 @@
+# CIR-F8.5: retained-region loop scaffolding for trim-ready face patch candidates
+
+## Purpose
+
+CIR-F8.5 adds a dry-run-only descriptor layer between CIR-F8.4 retention classification and future topology assembly.
+
+For subtract candidates whose retention role is known, the generator now emits **retained-region loop descriptors** that state what loop families would be required to bound retained patches.
+
+No BRep topology is created.
+
+## Descriptor model
+
+Each `FacePatchCandidate` now carries:
+
+- `RetainedRegionLoops` (`RetainedRegionLoopDescriptor[]`)
+- `LoopReadiness` (`ExactReady`, `SpecialCaseReady`, `Deferred`, `Unsupported`)
+- `LoopDiagnostic` (candidate-level summary)
+
+`RetainedRegionLoopDescriptor` contains:
+
+- `LoopKind`
+- `TrimCurveFamily`
+- `TrimCapability`
+- `SourceSurfaceFamily`
+- `OppositeSurfaceFamily`
+- `OrientationHint`
+- `RetentionRole`
+- `Status`
+- `Diagnostic`
+
+## Loop kinds and statuses
+
+Loop kinds are bounded to scaffold vocabulary:
+
+- `OuterBoundary`
+- `InnerTrim`
+- `MouthTrim`
+- `CapTrim`
+- `SeamTrim`
+- `Deferred`
+- `Unsupported`
+
+Status reflects trim capability policy:
+
+- `ExactReady` for `ExactSupported`
+- `SpecialCaseReady` for `SpecialCaseOnly`
+- `Deferred` for matrix-deferred entries
+- `Unsupported` for unsupported entries
+
+## Behavior by scenario
+
+### subtract(box, cylinder)
+
+- Base planar retained candidates emit `InnerTrim` loop descriptors against planar/cylindrical pairings.
+- Cylindrical tool retained candidates emit `MouthTrim` loop descriptors against base planar families.
+- Status surfaces as `SpecialCaseReady` (planar/cylindrical matrix policy) and can include exact-ready descriptors for planar/planar pairings.
+
+### subtract(box, sphere)
+
+- Base planar retained candidates emit circular loop descriptors from planar/spherical exact trim capability.
+- Spherical tool retained candidates emit circular `MouthTrim` loop descriptors with `ExactReady` status.
+
+### subtract(box, torus)
+
+- Toroidal candidates emit deferred loop descriptors with matrix reason.
+- Diagnostics preserve explicit quartic/algebraic deferred reason from planar/toroidal policy.
+
+## Non-subtract behavior
+
+For non-subtract roots, retention remains `NotApplicable`; loop descriptors are intentionally empty and diagnostics explain the bounded scope.
+
+## Still deferred (intentional)
+
+- Any BRep loop/coedge/edge/vertex emission
+- Exact trim curve parameter solving
+- Topology assembly and adjacency graphing
+- Pair-specific subtract materializers
+- Generated topology naming (SEM-A0 preserved)
+
+## Recommended next step (CIR-F8.6)
+
+Introduce bounded retained-loop grouping and canonical ordering per retained candidate (outer vs inner grouping and orientation contracts) while still avoiding BRep emission; use this to define a stable handoff contract for future topology assembly.