Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add circular bounded planar evidence for cylinder caps

Yuechen Lief9b7d962fcc
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
index 677def3f..1c32a083 100644
--- a/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/SurfacePatchDescriptorScaffoldTests.cs
@@ -151,12 +151,72 @@ public sealed class SurfacePatchDescriptorScaffoldTests
Assert.All(planar, d =>
{
var g = d.BoundedPlanarGeometry!.Value;
+ Assert.Equal(BoundedPlanarPatchGeometryKind.Rectangle, g.Kind);
Assert.True((g.Corner10 - g.Corner00).Length > 0d);
Assert.True((g.Corner01 - g.Corner00).Length > 0d);
Assert.True(g.Normal.Length > 0d);
});
}
+ [Fact]
+ public void SourceSurfaceExtractor_CylinderCaps_HaveCircularBoundedGeometry()
+ {
+ var extraction = SourceSurfaceExtractor.Extract(new CirCylinderNode(5, 20));
+ Assert.Single(extraction.Descriptors.Where(d => d.Family == SurfacePatchFamily.Cylindrical));
+ var caps = extraction.Descriptors.Where(d => d.Family == SurfacePatchFamily.Planar && d.ParameterPayloadReference is "cap-top" or "cap-bottom").ToArray();
+ Assert.Equal(2, caps.Length);
+
+ var top = Assert.Single(caps.Where(c => c.ParameterPayloadReference == "cap-top"));
+ var bottom = Assert.Single(caps.Where(c => c.ParameterPayloadReference == "cap-bottom"));
+ Assert.Equal(BoundedPlanarPatchGeometryKind.Circle, top.BoundedPlanarGeometry!.Value.Kind);
+ Assert.Equal(BoundedPlanarPatchGeometryKind.Circle, bottom.BoundedPlanarGeometry!.Value.Kind);
+ Assert.Equal(new Point3D(0, 0, 10), top.BoundedPlanarGeometry!.Value.Center);
+ Assert.Equal(new Point3D(0, 0, -10), bottom.BoundedPlanarGeometry!.Value.Center);
+ Assert.True(top.BoundedPlanarGeometry!.Value.Normal.Z > 0);
+ Assert.True(bottom.BoundedPlanarGeometry!.Value.Normal.Z < 0);
+ Assert.Equal(5d, top.BoundedPlanarGeometry!.Value.Radius, 8);
+ Assert.Equal(5d, bottom.BoundedPlanarGeometry!.Value.Radius, 8);
+ }
+
+ [Fact]
+ public void SourceSurfaceExtractor_CylinderCaps_RespectTranslationTransform()
+ {
+ var node = new CirTransformNode(new CirCylinderNode(5, 20), Transform3D.CreateTranslation(new Vector3D(2, -3, 7)));
+ var extraction = SourceSurfaceExtractor.Extract(node);
+ var top = Assert.Single(extraction.Descriptors.Where(c => c.ParameterPayloadReference == "cap-top"));
+ var bottom = Assert.Single(extraction.Descriptors.Where(c => c.ParameterPayloadReference == "cap-bottom"));
+ Assert.Equal(new Point3D(2, -3, 17), top.BoundedPlanarGeometry!.Value.Center);
+ Assert.Equal(new Point3D(2, -3, -3), bottom.BoundedPlanarGeometry!.Value.Center);
+ Assert.Equal(5d, top.BoundedPlanarGeometry!.Value.Radius, 8);
+ Assert.Equal(5d, bottom.BoundedPlanarGeometry!.Value.Radius, 8);
+ }
+
+ [Fact]
+ public void PlanarPayloadBuilder_RejectsCircularCapGeometry()
+ {
+ var extraction = SourceSurfaceExtractor.Extract(new CirCylinderNode(3, 8));
+ var top = Assert.Single(extraction.Descriptors.Where(c => c.ParameterPayloadReference == "cap-top"));
+ var success = PlanarPatchPayloadBuilder.TryBuildRectanglePayload(top, out _, out var diagnostic);
+ Assert.False(success);
+ Assert.Contains("circular planar cap emission is deferred", diagnostic, StringComparison.OrdinalIgnoreCase);
+ }
+
+ [Fact]
+ public void PlanarSurfaceMaterializer_DoesNotEmitCircularCapYet()
+ {
+ var extraction = SourceSurfaceExtractor.Extract(new CirCylinderNode(3, 8));
+ var top = Assert.Single(extraction.Descriptors.Where(c => c.ParameterPayloadReference == "cap-top"));
+ var ready = PlanarPatchPayloadBuilder.TryBuildRectanglePayload(top, out var payload, out _);
+ Assert.False(ready);
+ Assert.Null(payload);
+
+ var patch = new FacePatchDescriptor(top, [], [], FacePatchOrientationRole.Forward, "outer", []);
+ var readiness = new MaterializationReadinessReport(true, EmissionReadiness.EvidenceReadyForEmission, [], [], 1, 1, 1, 0, 0, 0, 0, [], false);
+ var result = new PlanarSurfaceMaterializer().Emit(patch, readiness);
+ Assert.False(result.Success);
+ Assert.Null(result.Body);
+ }
+
[Fact]
public void PlanarPayloadBuilder_BoxTopFace_DerivesRect3d()
{
diff --git a/Aetheris.Kernel.Firmament/Execution/SourceSurfaceExtraction.cs b/Aetheris.Kernel.Firmament/Execution/SourceSurfaceExtraction.cs
index cceca09b..1bb93a4a 100644
--- a/Aetheris.Kernel.Firmament/Execution/SourceSurfaceExtraction.cs
+++ b/Aetheris.Kernel.Firmament/Execution/SourceSurfaceExtraction.cs
@@ -86,8 +86,8 @@ internal static class SourceSurfaceExtractor
case CirBoxNode box:
AddBoxDescriptors(box, accumulated, descriptors, replayLog, nameof(CirBoxNode));
return;
- case CirCylinderNode:
- AddCylinderDescriptors(accumulated, descriptors, replayLog, nameof(CirCylinderNode));
+ case CirCylinderNode cylinder:
+ AddCylinderDescriptors(cylinder, accumulated, descriptors, replayLog, diagnostics, nameof(CirCylinderNode));
return;
case CirSphereNode:
descriptors.Add(CreateDescriptor(SurfacePatchFamily.Spherical, "sphere", null, accumulated, node, replayLog, FacePatchOrientationRole.Forward));
@@ -127,11 +127,23 @@ internal static class SourceSurfaceExtractor
descriptors.Add(CreateDescriptor(SurfacePatchFamily.Planar, "back", CreateBoundedPatch(transform, new(-hx, -hy, hz), new(hx, -hy, hz), new(hx, -hy, -hz), new(-hx, -hy, -hz)), transform, CirNodeKind.Box, replayLog, FacePatchOrientationRole.Forward, owningKind));
}
- private static void AddCylinderDescriptors(Transform3D transform, List<SourceSurfaceDescriptor> descriptors, NativeGeometryReplayLog? replayLog, string owningKind)
+ private static void AddCylinderDescriptors(CirCylinderNode cylinder, Transform3D transform, List<SourceSurfaceDescriptor> descriptors, NativeGeometryReplayLog? replayLog, List<SourceSurfaceExtractionDiagnostic> diagnostics, string owningKind)
{
descriptors.Add(CreateDescriptor(SurfacePatchFamily.Cylindrical, "side", null, transform, CirNodeKind.Cylinder, replayLog, FacePatchOrientationRole.Forward, owningKind));
- descriptors.Add(CreateDescriptor(SurfacePatchFamily.Planar, "cap-top", null, transform, CirNodeKind.Cylinder, replayLog, FacePatchOrientationRole.Forward, owningKind));
- descriptors.Add(CreateDescriptor(SurfacePatchFamily.Planar, "cap-bottom", null, transform, CirNodeKind.Cylinder, replayLog, FacePatchOrientationRole.Reversed, owningKind));
+ var topCap = TryCreateCircularCapGeometry(cylinder, transform, isTopCap: true, out var topDiagnostic);
+ var bottomCap = TryCreateCircularCapGeometry(cylinder, transform, isTopCap: false, out var bottomDiagnostic);
+ if (topDiagnostic is not null)
+ {
+ diagnostics.Add(topDiagnostic);
+ }
+
+ if (bottomDiagnostic is not null)
+ {
+ diagnostics.Add(bottomDiagnostic);
+ }
+
+ descriptors.Add(CreateDescriptor(SurfacePatchFamily.Planar, "cap-top", topCap, transform, CirNodeKind.Cylinder, replayLog, FacePatchOrientationRole.Forward, owningKind));
+ descriptors.Add(CreateDescriptor(SurfacePatchFamily.Planar, "cap-bottom", bottomCap, transform, CirNodeKind.Cylinder, replayLog, FacePatchOrientationRole.Reversed, owningKind));
}
@@ -141,7 +153,34 @@ internal static class SourceSurfaceExtractor
var w10 = transform.Apply(c10);
var w11 = transform.Apply(c11);
var w01 = transform.Apply(c01);
- return new(w00, w10, w11, w01, (w10 - w00).Cross(w01 - w00));
+ return BoundedPlanarPatchGeometry.CreateRectangle(w00, w10, w11, w01, (w10 - w00).Cross(w01 - w00));
+ }
+
+ private static BoundedPlanarPatchGeometry? TryCreateCircularCapGeometry(CirCylinderNode cylinder, Transform3D transform, bool isTopCap, out SourceSurfaceExtractionDiagnostic? diagnostic)
+ {
+ diagnostic = null;
+ var z = (isTopCap ? 1d : -1d) * cylinder.Height * 0.5d;
+ var localCenter = new Point3D(0d, 0d, z);
+ var localNormal = new Vector3D(0d, 0d, isTopCap ? 1d : -1d);
+ var localRadialX = new Vector3D(cylinder.Radius, 0d, 0d);
+ var localRadialY = new Vector3D(0d, cylinder.Radius, 0d);
+
+ var worldCenter = transform.Apply(localCenter);
+ var worldNormal = transform.Apply(localNormal);
+ var worldRadialX = transform.Apply(localRadialX);
+ var worldRadialY = transform.Apply(localRadialY);
+ var radiusX = worldRadialX.Length;
+ var radiusY = worldRadialY.Length;
+ var tolerance = 1e-9;
+ if (double.Abs(radiusX - radiusY) > tolerance)
+ {
+ diagnostic = new SourceSurfaceExtractionDiagnostic(
+ "cylinder-cap-circular-geometry-deferred",
+ "Cylinder cap transformed with non-uniform radial scaling/shear; circular bounded planar geometry omitted under current model.");
+ return null;
+ }
+
+ return BoundedPlanarPatchGeometry.CreateCircle(worldCenter, worldNormal, radiusX);
}
private static SourceSurfaceDescriptor CreateDescriptor(SurfacePatchFamily family, string provenanceRole, BoundedPlanarPatchGeometry? boundedPlanarGeometry, Transform3D transform, CirNodeKind nodeKind, NativeGeometryReplayLog? replayLog, FacePatchOrientationRole orientation, string owningKind)
diff --git a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
index fdb902b2..dd7923ad 100644
--- a/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
+++ b/Aetheris.Kernel.Firmament/Execution/SurfacePatchDescriptorScaffold.cs
@@ -60,12 +60,28 @@ internal sealed record SourceSurfaceDescriptor(
int? ReplayOpIndex,
FacePatchOrientationRole OrientationRole);
+internal enum BoundedPlanarPatchGeometryKind
+{
+ Rectangle,
+ Circle
+}
+
internal readonly record struct BoundedPlanarPatchGeometry(
+ BoundedPlanarPatchGeometryKind Kind,
Point3D Corner00,
Point3D Corner10,
Point3D Corner11,
Point3D Corner01,
- Vector3D Normal);
+ Point3D Center,
+ Vector3D Normal,
+ double Radius)
+{
+ internal static BoundedPlanarPatchGeometry CreateRectangle(Point3D corner00, Point3D corner10, Point3D corner11, Point3D corner01, Vector3D normal)
+ => new(BoundedPlanarPatchGeometryKind.Rectangle, corner00, corner10, corner11, corner01, Point3D.Origin, normal, 0d);
+
+ internal static BoundedPlanarPatchGeometry CreateCircle(Point3D center, Vector3D normal, double radius)
+ => new(BoundedPlanarPatchGeometryKind.Circle, Point3D.Origin, Point3D.Origin, Point3D.Origin, Point3D.Origin, center, normal, radius);
+}
internal sealed record TrimCurveDescriptor(
TrimCurveFamily Family,
@@ -267,6 +283,12 @@ internal static class PlanarPatchPayloadBuilder
if (source.BoundedPlanarGeometry is { } bounded)
{
+ if (bounded.Kind == BoundedPlanarPatchGeometryKind.Circle)
+ {
+ diagnostic = "payload-derivation-rejected: PlanarPatchPayloadBuilder currently supports rectangular planar payloads only; circular planar cap emission is deferred.";
+ return false;
+ }
+
payload = $"rect3d:{FormatPoint(bounded.Corner00)};{FormatPoint(bounded.Corner10)};{FormatPoint(bounded.Corner11)};{FormatPoint(bounded.Corner01)}";
diagnostic = "payload-derivation-succeeded: derived rect3d payload from bounded planar source geometry.";
return true;
diff --git a/docs/cir-f102-cylinder-cap-planar-geometry.md b/docs/cir-f102-cylinder-cap-planar-geometry.md
new file mode 100644
index 00000000..362eb55e
--- /dev/null
+++ b/docs/cir-f102-cylinder-cap-planar-geometry.md
@@ -0,0 +1,72 @@
+# CIR-F10.2: bounded planar geometry for cylinder cap source surfaces
+
+## Purpose
+
+CIR-F10.1 added bounded planar **rectangular** geometry for `CirBoxNode` planar descriptors so real extracted box faces can deterministically derive `rect3d:` payloads.
+
+CIR-F10.2 extends bounded planar **source evidence** for `CirCylinderNode` planar cap descriptors to include deterministic **circular** bounded geometry.
+
+This milestone is evidence-enrichment only. It does not emit circular cap topology.
+
+## Geometry model update
+
+`BoundedPlanarPatchGeometry` is now explicit about shape kind:
+
+- `Rectangle`
+ - corners (`Corner00`, `Corner10`, `Corner11`, `Corner01`)
+ - normal
+- `Circle`
+ - center (`Center`)
+ - normal
+ - radius (`Radius`)
+
+Factory helpers (`CreateRectangle`, `CreateCircle`) keep construction deterministic and explicit.
+
+## Cylinder cap extraction behavior
+
+For `CirCylinderNode`, extraction now produces:
+
+- 1 cylindrical side descriptor (unchanged),
+- 2 planar cap descriptors (`cap-top`, `cap-bottom`) with circular bounded geometry when representable.
+
+Per cap:
+
+- center is computed in world-space,
+- normal is transformed to world-space,
+- radius is transformed from radial basis vectors,
+- role and orientation remain stable (`cap-top` forward, `cap-bottom` reversed).
+
+## Transform policy in CIR-F10.2
+
+Supported:
+
+- identity,
+- translation,
+- transforms that keep radial x/y magnitudes equal after transform (still circular under current model).
+
+Deferred with diagnostic:
+
+- transforms that produce non-uniform radial magnitudes (`radiusX != radiusY`) indicating non-circular cap bounds under current circle-only bounded model.
+
+Diagnostic code:
+
+- `cylinder-cap-circular-geometry-deferred`
+
+## Payload builder behavior
+
+`PlanarPatchPayloadBuilder.TryBuildRectanglePayload` remains rectangle-only and now explicitly rejects circular bounded planar geometry with a clear deferred diagnostic.
+
+No circular cap is forced into `rect3d:`.
+
+## Non-goals preserved
+
+- no circular cap BRep loop/face emission,
+- no cylinder side emission changes,
+- no shell assembly changes,
+- no STEP export or Boolean behavior changes,
+- no public CLI surface change,
+- no generated topology naming (SEM-A0 guardrails preserved).
+
+## Next milestone
+
+Add a circle-cap planar emission path in `PlanarSurfaceMaterializer` (or a closely scoped successor) that consumes circular bounded planar geometry directly rather than coercing to `rect3d:`.