Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add RULED-A0 AP242 ruled surface audit

Yuechen Li2f5e8a7aceb0
diff --git a/docs/audits/ruled-a0-ap242-ruled-swept-surface-audit.md b/docs/audits/ruled-a0-ap242-ruled-swept-surface-audit.md
new file mode 100644
index 00000000..0da956ec
--- /dev/null
+++ b/docs/audits/ruled-a0-ap242-ruled-swept-surface-audit.md
@@ -0,0 +1,210 @@
+# RULED-A0 AP242 exact ruled/swept surface audit
+
+## 1. Summary verdict
+
+Aetheris currently has a solid elementary-surface AP242 lane for `PLANE`, `CYLINDRICAL_SURFACE`, `CONICAL_SURFACE`, `SPHERICAL_SURFACE`, and `TOROIDAL_SURFACE`, plus a generic `B_SPLINE_SURFACE_WITH_KNOTS` preservation lane. It does **not** currently parse or export `SURFACE_OF_LINEAR_EXTRUSION`, `SURFACE_OF_REVOLUTION`, or `RULED_SURFACE` in the STEP surface binding path.
+
+Degree-1 B-spline surfaces are accepted by the geometry model because `BSplineSurfaceWithKnots` permits degrees greater than or equal to one, and the STEP importer/exporter preserves the stored degrees and knot data. However, the current recovery lane does not label degree-1 surfaces as exact ruled surfaces. It only attempts a bounded rational B-spline-to-cylinder recovery for a degree `(1,3)` or `(3,1)` two-ring cubic profile, then otherwise preserves the B-spline surface as a B-spline.
+
+Therefore, the minimal next implementation path is not `RULED_SURFACE` first. It is:
+
+1. add exact internal surface kinds for linear extrusion and revolution;
+2. parse/export `SURFACE_OF_LINEAR_EXTRUSION` and `SURFACE_OF_REVOLUTION` without degrading them to generic B-splines;
+3. add a degree-1 B-spline ruled classifier that records exact ruled semantics while preserving original B-spline data;
+4. only then decide whether a schema-backed `RULED_SURFACE` lane is useful.
+
+## 2. Current importer support matrix
+
+| Representation | Import | Evidence and notes |
+| --- | --- | --- |
+| `PLANE` | yes | `Step242Importer.BindAdvancedFaceSurface` dispatches `PLANE` to `ReadPlaneSurface` and stores `SurfaceGeometry.FromPlane`. |
+| `CYLINDRICAL_SURFACE` | yes | The importer dispatches `CYLINDRICAL_SURFACE` to `ReadCylindricalSurface` and stores `SurfaceGeometry.FromCylinder`. |
+| `CONICAL_SURFACE` | yes | The importer dispatches `CONICAL_SURFACE` to `ReadConicalSurface` and stores `SurfaceGeometry.FromCone`. |
+| `SPHERICAL_SURFACE` | yes | The importer dispatches `SPHERICAL_SURFACE` to `ReadSphericalSurface` and stores `SurfaceGeometry.FromSphere`. |
+| `TOROIDAL_SURFACE` | yes | The importer dispatches `TOROIDAL_SURFACE` to `ReadToroidalSurface` and stores `SurfaceGeometry.FromTorus`. |
+| `SURFACE_OF_LINEAR_EXTRUSION` | no | No STEP importer dispatch, decoder, surface kind, or constructor-specific code was found for this entity. It will reach the unsupported-surface failure path. |
+| `SURFACE_OF_REVOLUTION` | no | No STEP importer dispatch, decoder, surface kind, or constructor-specific code was found for this entity. It will reach the unsupported-surface failure path. |
+| `B_SPLINE_SURFACE_WITH_KNOTS` degree 1 | partial | The decoder reads degree values generically, and `BSplineSurfaceWithKnots` allows degree 1. Import preserves it as a B-spline unless cylinder recovery succeeds. It is not classified as ruled. |
+| `B_SPLINE_SURFACE_WITH_KNOTS` degree 1,1 | partial | Same as degree-1 generally: it can be imported and preserved as B-spline data, but no bilinear ruled-patch semantic classification exists. |
+| `RULED_SURFACE` if schema-present | no | No current STEP implementation code references `RULED_SURFACE`; only older docs mention that exporter work was intentionally out of scope. |
+
+## 3. Current exporter support matrix
+
+| Representation | Export | Evidence and notes |
+| --- | --- | --- |
+| `PLANE` | yes | `Step242Exporter.BuildSurface` maps `SurfaceGeometryKind.Plane` to `BuildPlane`. |
+| `CYLINDRICAL_SURFACE` | yes | `BuildSurface` maps `SurfaceGeometryKind.Cylinder` to `BuildCylinder`, which writes `CYLINDRICAL_SURFACE`. |
+| `CONICAL_SURFACE` | yes | `BuildSurface` maps `SurfaceGeometryKind.Cone` to `BuildCone`, which writes `CONICAL_SURFACE`. |
+| `SPHERICAL_SURFACE` | yes | `BuildSurface` maps `SurfaceGeometryKind.Sphere` to `BuildSphere`, which writes `SPHERICAL_SURFACE`. |
+| `TOROIDAL_SURFACE` | yes | `BuildSurface` maps `SurfaceGeometryKind.Torus` to `BuildTorus`, which writes `TOROIDAL_SURFACE`. |
+| `SURFACE_OF_LINEAR_EXTRUSION` | no | No `SurfaceGeometryKind` or exporter builder exists for linear-extrusion surfaces. |
+| `SURFACE_OF_REVOLUTION` | no | No `SurfaceGeometryKind` or exporter builder exists for revolution surfaces. |
+| `B_SPLINE_SURFACE_WITH_KNOTS` degree 1 | partial | If an internal `BSplineSurfaceWithKnots` has degree 1, `BuildBSplineSurfaceWithKnots` writes those degree fields unchanged. Aetheris does not yet choose degree-1 B-spline export as an exact ruled semantic lane. |
+| `B_SPLINE_SURFACE_WITH_KNOTS` degree 1,1 | partial | Same as degree-1 generally: preserved if already represented as B-spline, but not deliberately emitted as bilinear ruled patch by a ruled-surface exporter. |
+| `RULED_SURFACE` if schema-present | no | No exporter builder or surface kind exists. |
+
+## 4. Combined support matrix
+
+| Representation | Import | Export | Reimport | External CAD | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `PLANE` | yes | yes | yes | unknown | Internal AP242 import/export/reimport is supported by elementary surface lanes; external CAD validation is not yet documented as evidence for this audit. |
+| `CYLINDRICAL_SURFACE` | yes | yes | yes | unknown | Export fixtures contain `CYLINDRICAL_SURFACE`; importer has a direct analytic lane. |
+| `CONICAL_SURFACE` | yes | yes | yes | unknown | Export fixtures contain `CONICAL_SURFACE`; importer has a direct analytic lane. |
+| `SPHERICAL_SURFACE` | yes | yes | yes | unknown | Direct import/export code exists; audit did not add external evidence. |
+| `TOROIDAL_SURFACE` | yes | yes | yes | unknown | Direct import/export code exists; audit did not add external evidence. |
+| `SURFACE_OF_LINEAR_EXTRUSION` | no | no | no | unknown | Not represented in current internal surface model or STEP binding. |
+| `SURFACE_OF_REVOLUTION` | no | no | no | unknown | Not represented in current internal surface model or STEP binding. |
+| `B_SPLINE_SURFACE_WITH_KNOTS` degree 1 | partial | partial | partial | unknown | Accepted and serialized as B-spline data, but not marked as exact ruled. |
+| `B_SPLINE_SURFACE_WITH_KNOTS` degree 1,1 | partial | partial | partial | unknown | Accepted and serialized as B-spline data, but not marked as bilinear ruled. |
+| `RULED_SURFACE` if schema-present | no | no | no | unknown | No schema/parser/exporter evidence found in implementation. |
+
+## 5. Recovery-lane behavior
+
+`Step242BsplineSurfaceRecoveryLane` currently has two candidates: `analytic_cylinder` and `reject`. The analytic cylinder candidate is only admissible when the source entity is rational-like and the control net matches a bounded two-ring cubic profile. The supported profiles are degree `(1,3)` with two U rows and four V columns, or degree `(3,1)` with four U rows and two V columns.
+
+Important consequences:
+
+- Degree-1 in one direction is used only as part of the cylinder probe shape; it is not a general ruled-surface classifier.
+- Degree `(1,1)` bilinear patches are not recognized as a special exact ruled representation.
+- Non-rational degree-1 B-spline ruled patches fall through to ordinary B-spline preservation.
+- The lane is appropriately bounded for analytic recovery, but it should not be the final home for ruled-surface semantics unless expanded with explicit candidate names, rejection reasons, and preservation policy.
+
+## 6. Profile-stack/prismatic export behavior
+
+The audited prismatic/extrude code builds planar side faces for polygonal extrusions and analytic cylindrical/conical faces for recognized round/conical features. It does not emit `SURFACE_OF_LINEAR_EXTRUSION` for prismatic side faces. In many polygonal-prismatic cases this is still exact because a line extruded along a vector is a plane, and `PLANE` is the preferred simpler AP242 representation. For non-planar directrix extrusions, Aetheris has no current exact swept-surface lane and would need a new internal surface kind rather than forcing the representation through generic B-splines or tessellation.
+
+## 7. Recommended export preference ladder
+
+Use the following export ladder for ruled/swept surfaces:
+
+1. `PLANE` for planar faces, including line extrusions that simplify to planes.
+2. `CYLINDRICAL_SURFACE` for true circular cylinders.
+3. `CONICAL_SURFACE` for true cones/frusta.
+4. `SPHERICAL_SURFACE` / `TOROIDAL_SURFACE` where the internal analytic surface exactly matches.
+5. `SURFACE_OF_LINEAR_EXTRUSION` for exact translational sweeps of a supported STEP directrix curve where the surface does not simplify to an elementary surface.
+6. `SURFACE_OF_REVOLUTION` for exact rotational sweeps of a supported STEP directrix curve where the surface does not simplify to cylinder/cone/sphere/torus.
+7. `B_SPLINE_SURFACE_WITH_KNOTS` with degree 1 in the ruling direction for exact ruled tensor-product patches when no elementary or swept entity is a better semantic fit.
+8. Higher-degree `B_SPLINE_SURFACE_WITH_KNOTS` fallback for genuine smooth/NURBS surfaces and existing analytic recovery fixtures.
+
+Rationale: current code already has stable elementary-surface lanes, and those should remain preferred. `SURFACE_OF_LINEAR_EXTRUSION` and `SURFACE_OF_REVOLUTION` should be added before treating degree-1 B-splines as the primary ruled path, because AP242 swept surfaces carry stronger directrix/sweep semantics. Degree-1 B-splines should still be treated as exact when they are the best available representation.
+
+## 8. Recommended import/recovery ladder
+
+Use the following import/recovery ladder:
+
+1. Preserve elementary surfaces directly: `PLANE`, `CYLINDRICAL_SURFACE`, `CONICAL_SURFACE`, `SPHERICAL_SURFACE`, `TOROIDAL_SURFACE`.
+2. Preserve `SURFACE_OF_LINEAR_EXTRUSION` as an exact swept surface when the directrix curve and vector can be decoded.
+3. Preserve `SURFACE_OF_REVOLUTION` as an exact swept surface when the directrix curve and axis can be decoded.
+4. Detect `B_SPLINE_SURFACE_WITH_KNOTS` with degree 1 in one direction as an exact ruled candidate.
+5. Detect degree `(1,1)` as an exact bilinear ruled patch.
+6. Attempt optional simplification, in order: plane, cylinder, cone, surface of linear extrusion, surface of revolution.
+7. If simplification is not exact/admissible, preserve the exact degree-1 B-spline ruled patch and record that it is exact ruled, not approximate recovery garbage.
+8. Use the existing higher-degree B-spline analytic recovery lane only for bounded degree-2/3 or rational approximation/recovery cases with explicit candidate names, scoring, and rejection reasons.
+
+## 9. External validation plan
+
+Internal Aetheris roundtrip is necessary but insufficient. External validation should use optional tools and manual CAD inspection without making CI depend on commercial software.
+
+### FreeCAD optional validation
+
+This milestone adds `tools/Validate-Step-FreeCAD.ps1`, an optional script that:
+
+- checks whether `FreeCADCmd.exe`, `FreeCADCmd`, or `freecadcmd` is on `PATH`;
+- prints a clear skipped message and exits `0` when FreeCAD is unavailable;
+- opens the supplied STEP file with FreeCAD `Import.open` when available;
+- prints object count and shape validity when available;
+- exits nonzero if FreeCAD import fails or imported shapes report invalid.
+
+Example commands:
+
+```powershell
+pwsh ./tools/Validate-Step-FreeCAD.ps1 ./testdata/firmament/exports/cylinder_basic.step
+pwsh ./tools/Validate-Step-FreeCAD.ps1 ./testdata/step242/probes/surface-of-linear-extrusion-line.step
+```
+
+The second command is a future probe command until that fixture exists.
+
+### SolidWorks manual validation
+
+For each generated AP242 file:
+
+1. Open SolidWorks.
+2. Use **File -> Open** and select the STEP AP242 output.
+3. Confirm import succeeds.
+4. Confirm a surface body or solid body exists.
+5. Confirm there are no visibly broken faces or failed import diagnostics.
+6. For PMI demo files, note that AP242 PMI may or may not display graphically depending on SolidWorks settings.
+7. For ruled/swept fixtures, inspect face/surface properties if the installed SolidWorks version exposes them.
+
+Limitation: SolidWorks may not expose the original STEP surface entity type directly in normal UI. If it only reports a healed body/surface, use that as external import evidence, not as proof that the exact AP242 entity survived semantically.
+
+## 10. Minimal next implementation milestone
+
+Recommended next milestone: **RULED-A1 — exact swept surface import/export skeleton and ruled B-spline classification**.
+
+Scope:
+
+1. Add internal `SurfaceGeometryKind.LinearExtrusion` and `SurfaceGeometryKind.SurfaceOfRevolution` records with directrix curve references/values and sweep vector or axis.
+2. Add STEP decoder support for `SURFACE_OF_LINEAR_EXTRUSION` and `SURFACE_OF_REVOLUTION` for a minimal curve subset: `LINE`, `CIRCLE`, and existing B-spline curves if already decodable.
+3. Add exporter builders for those two entities.
+4. Add small static/import fixtures for:
+ - `surface-of-linear-extrusion-line.step`;
+ - `surface-of-revolution-line.step`;
+ - `bspline-degree-1-1-bilinear.step`.
+5. Add importer tests proving current unsupported entities become supported and reexport as exact swept entities where possible.
+6. Add a degree-1 B-spline classifier that records exact ruled/bilinear semantics and does not call it approximation by default.
+7. Keep FreeCAD validation optional and non-CI-blocking unless a future environment explicitly installs FreeCAD.
+
+Exit criterion: Aetheris can import/export/reimport at least one linear-extrusion surface, one revolution surface, and one degree `(1,1)` bilinear B-spline patch with explicit exactness semantics.
+
+## 11. Deferred features
+
+- General loft syntax or modeling features.
+- Firmament ruled syntax.
+- AIR ruled transition primitive.
+- Full BRep ruled face materialization beyond the minimal fixture path.
+- General NURBS conversion.
+- Broad STEP schema expansion unrelated to the three target lanes.
+- Required FreeCAD/SolidWorks execution in normal CI.
+- `RULED_SURFACE` implementation unless future schema/code investigation proves it is relevant to target AP242 data.
+
+## 12. Direct answers to audit questions
+
+1. `SURFACE_OF_LINEAR_EXTRUSION` parse: **no**.
+2. `SURFACE_OF_LINEAR_EXTRUSION` export: **no**.
+3. `SURFACE_OF_REVOLUTION` parse: **no**.
+4. `SURFACE_OF_REVOLUTION` export: **no**.
+5. Degree-1 `B_SPLINE_SURFACE_WITH_KNOTS` parse/export without approximation: **partial**. It is accepted and preserved as a B-spline, but not classified as exact ruled.
+6. `Step242BsplineSurfaceRecoveryLane` degree-1 distinction: **no for general ruled**, **partial for cylinder recovery** because it probes degree `(1,3)`/`(3,1)` rational-like profiles only.
+7. Profile-stack extrude/prismatic faces: **elementary when currently supported**. Polygonal extrude sides emit planes; round/conical recognized features emit cylinders/cones. No swept-surface entities are emitted.
+8. `RULED_SURFACE` support/schema evidence: **no implementation evidence found**.
+9. Exact entities surviving Aetheris import/export/reimport today: **elementary surfaces yes; B-spline surfaces partially as B-splines; linear extrusion/revolution/ruled no**.
+10. Exact entities surviving external CAD import: **unknown pending FreeCAD/SolidWorks validation**.
+
+## 13. Code-search evidence
+
+Required searches were run for:
+
+```text
+SURFACE_OF_LINEAR_EXTRUSION
+SURFACE_OF_REVOLUTION
+B_SPLINE_SURFACE_WITH_KNOTS
+B_SPLINE_SURFACE
+BsplineSurfaceRecovery
+CONICAL_SURFACE
+CYLINDRICAL_SURFACE
+RULED_SURFACE
+swept_surface
+```
+
+Key files/classes:
+
+- `Aetheris.Kernel.Core/Step242/Step242Importer.cs` — elementary surface import dispatch, B-spline surface resolution, unsupported surface fallback.
+- `Aetheris.Kernel.Core/Step242/Step242SubsetDecoder.cs` — `B_SPLINE_SURFACE_WITH_KNOTS`, cylinder, cone, sphere, torus decoders.
+- `Aetheris.Kernel.Core/Step242/Step242Exporter.cs` — elementary and B-spline surface exporters.
+- `Aetheris.Kernel.Core/Step242/Step242BsplineSurfaceRecoveryLane.cs` — bounded rational B-spline cylinder recovery lane.
+- `Aetheris.Kernel.Core/Geometry/SurfaceGeometry.cs` — current internal surface-kind vocabulary.
+- `Aetheris.Kernel.Core/Geometry/Surfaces/BSplineSurfaceWithKnots.cs` — B-spline surface invariants, including degree `>= 1`.
+- `Aetheris.Kernel.Core/Brep/Features/BrepExtrude.cs` — extrude side faces created as planes.
+- `Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanBoxCylinderHoleBuilder.cs` — recognized analytic hole/frustum faces created as cylinder/cone surfaces.
+- `docs/air-v5-frustum-ruled-transition-production.md` — confirms older `RULED_SURFACE` exporter work was explicitly not in that milestone's scope.
diff --git a/tools/Validate-Step-FreeCAD.ps1 b/tools/Validate-Step-FreeCAD.ps1
new file mode 100644
index 00000000..1ddb52a7
--- /dev/null
+++ b/tools/Validate-Step-FreeCAD.ps1
@@ -0,0 +1,62 @@
+param(
+ [Parameter(Mandatory = $true, Position = 0)]
+ [string]$StepFile
+)
+
+$ErrorActionPreference = 'Stop'
+
+if (-not (Test-Path -LiteralPath $StepFile)) {
+ Write-Error "STEP file not found: $StepFile"
+ exit 2
+}
+
+$freeCadCmd = Get-Command FreeCADCmd.exe, FreeCADCmd, freecadcmd -ErrorAction SilentlyContinue | Select-Object -First 1
+if (-not $freeCadCmd) {
+ Write-Host "Skipped: FreeCADCmd was not found on PATH. Install FreeCAD or add FreeCADCmd to PATH to run external STEP import validation."
+ exit 0
+}
+
+$tempScript = [System.IO.Path]::GetTempFileName() + '.py'
+@'
+import sys
+import FreeCAD
+import Import
+
+step_file = sys.argv[1]
+doc = FreeCAD.newDocument('StepImportValidation')
+try:
+ Import.open(step_file)
+ doc = FreeCAD.ActiveDocument or doc
+ objects = list(doc.Objects)
+ valid = True
+ invalid = []
+ for obj in objects:
+ shape = getattr(obj, 'Shape', None)
+ if shape is not None and hasattr(shape, 'isValid'):
+ ok = bool(shape.isValid())
+ valid = valid and ok
+ if not ok:
+ invalid.append(getattr(obj, 'Name', '<unnamed>'))
+ print('FreeCAD STEP import succeeded')
+ print('object_count={}'.format(len(objects)))
+ print('shape_valid={}'.format(str(valid).lower()))
+ if invalid:
+ print('invalid_objects={}'.format(','.join(invalid)))
+ sys.exit(0 if valid else 3)
+except Exception as exc:
+ print('FreeCAD STEP import failed: {}'.format(exc), file=sys.stderr)
+ sys.exit(1)
+finally:
+ try:
+ FreeCAD.closeDocument(doc.Name)
+ except Exception:
+ pass
+'@ | Set-Content -LiteralPath $tempScript -Encoding UTF8
+
+try {
+ & $freeCadCmd.Source $tempScript (Resolve-Path -LiteralPath $StepFile).Path
+ exit $LASTEXITCODE
+}
+finally {
+ Remove-Item -LiteralPath $tempScript -Force -ErrorAction SilentlyContinue
+}