Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

merge sync.

Yuechen Liee83d086f332
diff --cc docs/implementation/ruled-tooling-a0-inline-step-probe-harness.md
index 3d970ec5,d1863467..9add0a37
--- a/docs/implementation/ruled-tooling-a0-inline-step-probe-harness.md
+++ b/docs/implementation/ruled-tooling-a0-inline-step-probe-harness.md
@@@ -1,147 -1,15 +1,7 @@@
- # RULED-TOOLING-A0: InlineStep probe harness for ruled/swept STEP experiments
-# RULED-TOOLING-A0 Inline STEP probe harness
- ## Why this exists
-RULED-ANALYZE-A0 updated analyze/reporting so exact swept surface kinds are recognized in analyzer summaries. `SURFACE_OF_LINEAR_EXTRUSION` imports now appear as `linear-extrusion`, and `SURFACE_OF_REVOLUTION` imports now appear as `surface-of-revolution`.
- RULED-A1 and RULED-A2 proved that Aetheris can preserve exact swept-surface semantics such as:
-Open ruled/swept surface bodies still do not have exact volume integration. `aetheris analyze volume` reports that state as unsupported instead of throwing a dictionary-key exception; this milestone did not add ruled-surface area or volume integration.
- - `SURFACE_OF_LINEAR_EXTRUSION`
- - `SURFACE_OF_REVOLUTION`
- - degree-1 `B_SPLINE_SURFACE_WITH_KNOTS` ruled classification
-## Spatial probe follow-up
- That is enough geometry capability to keep iterating, but it is not enough tooling. Hand-authoring a full AP242 packet every time a developer wants to test one uncertain ruled or swept surface representation is too slow and too error-prone.
-`aetheris analyze map` can now spatially inspect ruled and swept STEP artifacts as a ray/height-map probe. For example:
- RULED-TOOLING-A0 adds a lightweight harness around Firmament V2 `InlineStep` so the developer can focus on the small experimental STEP asset and let Aetheris handle canonical wrapping, real export, reimport, and evidence reporting.
-
- This milestone is tooling only. It does not add new ruled geometry capability, new Firmament ruled syntax, or new AIR ruled transitions.
-
- ## Workflow
-
- The harness follows this path:
-
- ```text
- small probe STEP
- -> aetheris canon --mode production
- -> generated Firmament V2 InlineStep wrapper
- -> aetheris build
- -> canonical AP242 output
- -> aetheris analyze reimport
- -> optional FreeCAD / SolidWorks inspection
- ```
-
- The important distinction is that the wrapper is generated on demand. Codex does not need to hand-author a full `.firmfixture` just to test one uncertain surface token.
-
- ## Entry point
-
- Use:
-
- ```powershell
- .\tools\Run-RuledStepProbe.ps1 `
- -Probe .\testdata\step242\generated\ruled-a2\ellipse-linear-extrusion-production.step `
- -Name ellipseLinearExtrusionProduction
- ```
-
- Optional examples:
-
- ```powershell
- .\tools\Run-RuledStepProbe.ps1 `
- -Probe .\testdata\step242\generated\ruled-a2\ellipse-linear-extrusion-production.step `
- -Name ellipseLinearExtrusionProduction `
- -Open
-
- .\tools\Run-RuledStepProbe.ps1 `
- -Probe .\testdata\step242\probes\surface-of-revolution-line.step `
- -Name surfaceOfRevolutionLine `
- -Out .\demo-output\my-ruled-probes `
- -FreeCAD `
- -Keep
- ```
-
- ## Output layout
-
- The default output directory is:
-
- ```text
- demo-output/ruled-probes/<probe-name>/
- ```
-
- Each run writes:
-
- ```text
- input/
- <original probe filename>
- <probe-name>.canonical-input.step
-
- wrapper/
- <probe-name>.firm
-
- output/
- <probe-name>.canonical.step
- probe-report.json
-```bash
-aetheris analyze map testdata/step242/generated/ruled-a2/ellipse-linear-extrusion-production.step --plane xy --direction -z --resolution 8x8 --json
```
- `input/<original probe filename>` preserves the original authored probe filename in the harness output. `input/<probe-name>.canonical-input.step` is the staged canonical STEP that `InlineStep` actually wraps, because current Firmament InlineStep intentionally remains canonical-input-only.
-
- If `-Keep` is supplied, the harness also preserves command artifacts such as canon/build/analyze JSON and optional FreeCAD output for debugging.
-
- ## Generated wrapper behavior
-
- The wrapper is intentionally tiny and uses the current Firmament V2 InlineStep syntax:
-
- ```firmament
- model ellipseLinearExtrusionProductionProbeHarness {
- units mm
-
- solid ellipseLinearExtrusionProduction: InlineStep {
- path: "../input/ellipseLinearExtrusionProduction.canonical-input.step"
- }
- }
- ```
-
- That means the experimental work stays inside the probe STEP asset. The wrapper is just a deterministic bridge into the real Aetheris pipeline.
-
- ## What to inspect
-
- The harness prints a receipt and writes `probe-report.json` with:
-
- - the original probe path;
- - the copied probe path;
- - the staged canonical InlineStep input path;
- - the generated wrapper path;
- - the canonical AP242 output path;
- - reimport success;
- - best-effort analyze status and raw analyzer output when analyze is not currently supported for the emitted body;
- - entity evidence from token scans;
- - optional FreeCAD status.
-
- The token scan is intentionally simple and easy to read. It reports presence/count for:
-
- - `SURFACE_OF_LINEAR_EXTRUSION`
- - `SURFACE_OF_REVOLUTION`
- - `B_SPLINE_SURFACE_WITH_KNOTS`
- - `ELLIPSE`
- - `LINE`
- - `CIRCLE`
- - `CONICAL_SURFACE`
- - `CYLINDRICAL_SURFACE`
-
- This is not a replacement for importer validation; it is a quick receipt for the representation the exporter actually emitted.
-
- For this milestone, the authoritative reimport check is a second `aetheris canon` smoke pass on the emitted output, because that routes through `Step242Importer` and `Step242Exporter` again. `aetheris analyze` is still run as additional evidence, but some open ruled/swept bodies can currently fail there even when canonical reimport succeeds.
-
- ## FreeCAD and SolidWorks workflow
-
- `-FreeCAD` is optional. When it is passed, the harness calls `tools/Validate-Step-FreeCAD.ps1` if present.
-
- - If `FreeCADCmd` is available on `PATH`, the harness validates the emitted canonical AP242 output and records the result.
- - If FreeCAD is unavailable, the harness reports a clear skip and still succeeds.
-
- SolidWorks remains a manual follow-up step outside CI. The intended path is to open `output/<probe-name>.canonical.step` from the harness output directory.
-
- ## Limitations
-
- - Current Firmament `InlineStep` still requires Aetheris-canonical AP242 input, so the harness stages a canonical input STEP before wrapping.
- - The harness is intentionally single-probe and single-body oriented.
- - The token scan is textual evidence only; it does not claim semantic correctness by itself.
- - Some emitted open ruled/swept bodies currently reimport successfully but still fail `aetheris analyze`; the harness reports that separately instead of hiding it.
- - FreeCAD is optional and must not be required for normal CI.
- - This milestone does not add new ruled/swept geometry capability.
-Linear-extrusion faces are reported through the tessellated fallback path unless an exact intersection path is added later; the JSON diagnostics make that fallback explicit.
diff --cc tools/Run-RuledStepProbe.ps1
index cea82ecc,8f6bb253..ef9bec77
--- a/tools/Run-RuledStepProbe.ps1
+++ b/tools/Run-RuledStepProbe.ps1
@@@ -1,341 -1,49 +1,19 @@@
param(
- [Parameter(Mandatory = $true)]
- [string]$Probe,
-
- [string]$Name,
-
- [string]$Out,
-
- [switch]$FreeCAD,
-
- [switch]$Open,
-
- [switch]$Keep
- [Parameter(Mandatory = $true)] [string] $Probe,
- [Parameter(Mandatory = $true)] [string] $Name
)
$ErrorActionPreference = 'Stop'
+ $repoRoot = Split-Path -Parent $PSScriptRoot
+ $probePath = Resolve-Path -Path $Probe
- function Get-RepoRoot {
- $dir = Resolve-Path (Join-Path $PSScriptRoot '..')
- while ($null -ne $dir) {
- if (Test-Path -LiteralPath (Join-Path $dir.Path 'Aetheris.slnx')) {
- return $dir.Path
- }
-Write-Host "probe: $Name"
-Write-Host "file: $probePath"
- $parent = Split-Path -Parent $dir.Path
- if ([string]::IsNullOrWhiteSpace($parent) -or $parent -eq $dir.Path) {
- break
- }
-
- $dir = Resolve-Path $parent
- }
-
- throw 'Unable to locate repository root from tools directory.'
-$analyze = & dotnet run --project (Join-Path $repoRoot 'Aetheris.CLI') -- analyze $probePath --json 2>&1
+ if ($LASTEXITCODE -ne 0) {
- Write-Host "analyze: failed"
- Write-Host $analyze
- exit $LASTEXITCODE
}
- function Get-SafeProbeName([string]$RawName) {
- if ([string]::IsNullOrWhiteSpace($RawName)) {
- return 'ruledProbe'
- }
-
- $safe = $RawName.Trim()
- foreach ($invalid in [System.IO.Path]::GetInvalidFileNameChars()) {
- $safe = $safe.Replace([string]$invalid, '-')
- }
-
- $safe = [System.Text.RegularExpressions.Regex]::Replace($safe, '\s+', '-')
- $safe = $safe.Trim('.').Trim('-')
- if ([string]::IsNullOrWhiteSpace($safe)) {
- return 'ruledProbe'
- }
-
- return $safe
-$volume = & dotnet run --project (Join-Path $repoRoot 'Aetheris.CLI') -- analyze volume $probePath --json 2>&1
-$volumeExit = $LASTEXITCODE
-if ($volumeExit -eq 0) {
- Write-Host "analyze: volume supported"
- Write-Host $volume
- exit 0
}
- function Get-SafeIdentifier([string]$RawName) {
- $identifier = [System.Text.RegularExpressions.Regex]::Replace($RawName, '[^A-Za-z0-9_]', '_')
- if ([string]::IsNullOrWhiteSpace($identifier)) {
- $identifier = 'probe'
- }
-
- if ($identifier[0] -match '[0-9]') {
- $identifier = "probe_$identifier"
- }
-
- return $identifier
-$message = ($volume | Out-String)
-if ($message -match 'given key') {
- Write-Host 'analyze: unexpected dictionary-key failure'
- Write-Host $message
- exit $volumeExit
}
- function Invoke-CliCommand {
- param(
- [Parameter(Mandatory = $true)]
- [string[]]$Arguments
- )
-
- if (-not $script:CliReady) {
- $buildOutput = & dotnet build 'Aetheris.CLI\Aetheris.CLI.csproj' -f net10.0 --nologo 2>&1 | ForEach-Object { $_.ToString() }
- if ($LASTEXITCODE -ne 0) {
- throw "Failed to build Aetheris.CLI before probe execution.$([Environment]::NewLine)$($buildOutput -join [Environment]::NewLine)"
- }
-
- $script:CliDllPath = Join-Path $script:RepoRoot 'Aetheris.CLI\bin\Debug\net10.0\aetheris.dll'
- if (-not (Test-Path -LiteralPath $script:CliDllPath)) {
- throw "Expected built CLI at '$script:CliDllPath' after dotnet build."
- }
-
- $script:CliReady = $true
- }
-
- $output = & dotnet $script:CliDllPath @Arguments 2>&1 | ForEach-Object { $_.ToString() }
- return [pscustomobject]@{
- ExitCode = $LASTEXITCODE
- StdOut = ($output -join [Environment]::NewLine)
- StdErr = ''
- Arguments = $Arguments
- }
-if ($message -match 'Exact volume is not supported' -and $message -match 'linear-extrusion') {
- Write-Host 'analyze: expected unsupported-volume nonzero for open linear-extrusion body'
- Write-Host $message
- exit 0
}
- function Get-EvidenceSummary([string]$StepText) {
- $tokens = @(
- 'SURFACE_OF_LINEAR_EXTRUSION',
- 'SURFACE_OF_REVOLUTION',
- 'B_SPLINE_SURFACE_WITH_KNOTS',
- 'ELLIPSE',
- 'LINE',
- 'CIRCLE',
- 'CONICAL_SURFACE',
- 'CYLINDRICAL_SURFACE'
- )
-
- $result = [ordered]@{}
- foreach ($token in $tokens) {
- $count = ([regex]::Matches($StepText, [regex]::Escape($token))).Count
- $result[$token] = [ordered]@{
- present = ($count -gt 0)
- count = $count
- }
- }
-
- return $result
-if ($message -match 'Exact volume is not supported' -or $message -match 'unsupported non-planar face') {
- Write-Host 'analyze: expected unsupported-volume nonzero'
- Write-Host $message
- exit 0
}
- function Write-CommandArtifact {
- param(
- [Parameter(Mandatory = $true)]
- [string]$BasePath,
-
- [Parameter(Mandatory = $true)]
- $Result
- )
-
- $artifact = [ordered]@{
- exitCode = $Result.ExitCode
- arguments = $Result.Arguments
- stdout = $Result.StdOut
- stderr = $Result.StdErr
- } | ConvertTo-Json -Depth 6
-
- Set-Content -LiteralPath $BasePath -Value $artifact -Encoding UTF8
- }
-
- $RepoRoot = Get-RepoRoot
- $resolvedProbe = (Resolve-Path -LiteralPath $Probe).Path
-
- if (-not (Test-Path -LiteralPath $resolvedProbe)) {
- throw "Probe STEP file not found: $Probe"
- }
-
- $requestedName = if ([string]::IsNullOrWhiteSpace($Name)) { [System.IO.Path]::GetFileNameWithoutExtension($resolvedProbe) } else { $Name }
- $probeName = Get-SafeProbeName $requestedName
- $wrapperIdentifier = Get-SafeIdentifier $requestedName
-
- $rootOut = if ([string]::IsNullOrWhiteSpace($Out)) {
- Join-Path $RepoRoot "demo-output\ruled-probes\$probeName"
- }
- else {
- $candidate = if ([System.IO.Path]::IsPathRooted($Out)) { $Out } else { Join-Path $RepoRoot $Out }
- [System.IO.Path]::GetFullPath($candidate)
- }
-
- $inputDir = Join-Path $rootOut 'input'
- $wrapperDir = Join-Path $rootOut 'wrapper'
- $outputDir = Join-Path $rootOut 'output'
-
- New-Item -ItemType Directory -Force -Path $inputDir, $wrapperDir, $outputDir | Out-Null
-
- $originalProbeName = [System.IO.Path]::GetFileName($resolvedProbe)
- $rawProbeCopyPath = Join-Path $inputDir $originalProbeName
- $canonicalInputPath = Join-Path $inputDir ($probeName + '.canonical-input.step')
- $wrapperPath = Join-Path $wrapperDir ($probeName + '.firm')
- $outputStepPath = Join-Path $outputDir ($probeName + '.canonical.step')
- $reimportSmokePath = Join-Path $outputDir ($probeName + '.reimport-smoke.step')
- $reportPath = Join-Path $outputDir 'probe-report.json'
-
- Copy-Item -LiteralPath $resolvedProbe -Destination $rawProbeCopyPath -Force
-
- $canonResult = Invoke-CliCommand -Arguments @('canon', $rawProbeCopyPath, '--out', $canonicalInputPath, '--mode', 'production', '--json')
- if ($Keep) {
- Write-CommandArtifact -BasePath (Join-Path $outputDir 'canon-result.json') -Result $canonResult
- }
-
- if ($canonResult.ExitCode -ne 0) {
- if (-not [string]::IsNullOrWhiteSpace($canonResult.StdErr)) {
- Write-Error $canonResult.StdErr.Trim()
- }
-
- if (-not [string]::IsNullOrWhiteSpace($canonResult.StdOut)) {
- Write-Host $canonResult.StdOut.Trim()
- }
-
- throw "Canonicalization failed for probe '$resolvedProbe'."
- }
-
- $wrapperRelativeInput = "../input/$([System.IO.Path]::GetFileName($canonicalInputPath))"
- $wrapperText = @"
- model ${wrapperIdentifier}ProbeHarness {
- units mm
-
- solid ${wrapperIdentifier}: InlineStep {
- path: "$wrapperRelativeInput"
- }
- }
- "@
-
- Set-Content -LiteralPath $wrapperPath -Value $wrapperText -Encoding UTF8
-
- $buildResult = Invoke-CliCommand -Arguments @('build', $wrapperPath, '--out', $outputStepPath, '--json')
- if ($Keep) {
- Write-CommandArtifact -BasePath (Join-Path $outputDir 'build-result.json') -Result $buildResult
- }
-
- if ($buildResult.ExitCode -ne 0) {
- if (-not [string]::IsNullOrWhiteSpace($buildResult.StdErr)) {
- Write-Error $buildResult.StdErr.Trim()
- }
-
- if (-not [string]::IsNullOrWhiteSpace($buildResult.StdOut)) {
- Write-Host $buildResult.StdOut.Trim()
- }
-
- throw "Build failed for wrapper '$wrapperPath'."
- }
-
- $reimportResult = Invoke-CliCommand -Arguments @('canon', $outputStepPath, '--out', $reimportSmokePath, '--json')
- if ($Keep) {
- Write-CommandArtifact -BasePath (Join-Path $outputDir 'reimport-result.json') -Result $reimportResult
- }
-
- $reimportSucceeded = ($reimportResult.ExitCode -eq 0)
- if (-not $Keep -and (Test-Path -LiteralPath $reimportSmokePath)) {
- Remove-Item -LiteralPath $reimportSmokePath -Force -ErrorAction SilentlyContinue
- }
-
- $analyzeResult = Invoke-CliCommand -Arguments @('analyze', $outputStepPath, '--json')
- if ($Keep) {
- Write-CommandArtifact -BasePath (Join-Path $outputDir 'analyze-result.json') -Result $analyzeResult
- }
-
- $analyzeSucceeded = ($analyzeResult.ExitCode -eq 0)
- $analyzeJson = $null
- if ($analyzeSucceeded -and -not [string]::IsNullOrWhiteSpace($analyzeResult.StdOut)) {
- $analyzeJson = $analyzeResult.StdOut | ConvertFrom-Json
- }
-
- $outputStepText = Get-Content -LiteralPath $outputStepPath -Raw
- $evidence = Get-EvidenceSummary $outputStepText
-
- $freeCadStatus = [ordered]@{
- attempted = [bool]$FreeCAD
- available = $false
- importSucceeded = $null
- shapeValid = $null
- skipped = $false
- exitCode = $null
- command = $null
- output = $null
- }
-
- if ($FreeCAD) {
- $validatorPath = Join-Path $RepoRoot 'tools\Validate-Step-FreeCAD.ps1'
- if (Test-Path -LiteralPath $validatorPath) {
- $freeCadCmd = Get-Command FreeCADCmd.exe, FreeCADCmd, freecadcmd -ErrorAction SilentlyContinue | Select-Object -First 1
- if ($null -ne $freeCadCmd) {
- $freeCadStatus.available = $true
- $freeCadStatus.command = "$validatorPath $outputStepPath"
-
- $freeCadOutput = & $validatorPath $outputStepPath 2>&1 | Out-String
- $freeCadExitCode = $LASTEXITCODE
- $freeCadStatus.exitCode = $freeCadExitCode
- $freeCadStatus.output = $freeCadOutput.Trim()
- $freeCadStatus.importSucceeded = ($freeCadExitCode -eq 0 -or $freeCadExitCode -eq 3)
- $freeCadStatus.shapeValid = ($freeCadOutput -match 'shape_valid=true')
-
- if ($Keep) {
- Set-Content -LiteralPath (Join-Path $outputDir 'freecad-output.txt') -Value $freeCadOutput -Encoding UTF8
- }
- }
- else {
- $freeCadStatus.skipped = $true
- $freeCadStatus.output = 'Skipped: FreeCADCmd was not found on PATH.'
- }
- }
- else {
- $freeCadStatus.skipped = $true
- $freeCadStatus.output = 'Skipped: tools/Validate-Step-FreeCAD.ps1 is not present in this repository.'
- }
- }
-
- $report = [ordered]@{
- toolingOnly = $true
- probe = $resolvedProbe
- probeName = $probeName
- rawProbeCopy = $rawProbeCopyPath
- inlineStepInput = $canonicalInputPath
- wrapper = $wrapperPath
- outputStep = $outputStepPath
- buildSucceeded = $true
- reimportSucceeded = $reimportSucceeded
- analyzeSucceeded = $analyzeSucceeded
- analyzeSummary = if ($null -ne $analyzeJson) { $analyzeJson.summary } else { $null }
- analyzeRaw = if ($analyzeSucceeded) { $null } else { $analyzeResult.StdOut }
- surfaceEvidence = $evidence
- freeCad = $freeCadStatus
- }
-
- $report | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $reportPath -Encoding UTF8
-
- Write-Host "Ruled STEP probe receipt"
- Write-Host " Input probe: $resolvedProbe"
- Write-Host " Input copy: $rawProbeCopyPath"
- Write-Host " InlineStep input: $canonicalInputPath"
- Write-Host " Generated wrapper: $wrapperPath"
- Write-Host " Canonical AP242 output: $outputStepPath"
- Write-Host " Reimport status: $(if ($reimportSucceeded) { 'succeeded' } else { 'failed' })"
- Write-Host " Analyze status: $(if ($analyzeSucceeded) { 'succeeded' } else { 'failed (best-effort only)' })"
- Write-Host " Report: $reportPath"
- Write-Host " Entity evidence:"
-
- foreach ($token in $evidence.Keys) {
- $entry = $evidence[$token]
- Write-Host " $token => present=$($entry.present) count=$($entry.count)"
- }
-
- if ($FreeCAD) {
- if ($freeCadStatus.available) {
- Write-Host " FreeCAD: exit=$($freeCadStatus.exitCode) shapeValid=$($freeCadStatus.shapeValid)"
- }
- else {
- Write-Host " FreeCAD: skipped ($($freeCadStatus.output))"
- }
- }
-
- if (-not $reimportSucceeded) {
- if (-not [string]::IsNullOrWhiteSpace($reimportResult.StdOut)) {
- Write-Host $reimportResult.StdOut.Trim()
- }
-
- throw "Reimport/analyze failed for '$outputStepPath'."
- }
-
- if ($Open) {
- Start-Process $rootOut | Out-Null
- }
-Write-Host 'analyze: unexpected failure'
-Write-Host $message
-exit $volumeExit