Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

C3: close analyze honesty contract gaps

Yuechen Li05ef91ef80a3
diff --git a/Aetheris.CLI.Tests/CliBaselineTests.cs b/Aetheris.CLI.Tests/CliBaselineTests.cs
index 5fdd816f..53aec3f7 100644
--- a/Aetheris.CLI.Tests/CliBaselineTests.cs
+++ b/Aetheris.CLI.Tests/CliBaselineTests.cs
@@ -32,7 +32,7 @@ public sealed class CliBaselineTests
}
[Fact]
- public void Analyze_Command_Reports_Summary_Facts()
+ public void Analyze_Command_Reports_Summary_Facts_And_Discoverability()
{
var stdout = new StringWriter();
var stderr = new StringWriter();
@@ -44,8 +44,7 @@ public sealed class CliBaselineTests
Assert.Equal(0, exitCode);
using var doc = JsonDocument.Parse(stdout.ToString());
- var root = doc.RootElement;
- var summary = root.GetProperty("summary");
+ var summary = doc.RootElement.GetProperty("summary");
Assert.Equal(1, summary.GetProperty("bodyCount").GetInt32());
Assert.Equal(1, summary.GetProperty("shellCount").GetInt32());
Assert.Equal(6, summary.GetProperty("faceCount").GetInt32());
@@ -53,25 +52,37 @@ public sealed class CliBaselineTests
Assert.Equal(8, summary.GetProperty("vertexCount").GetInt32());
Assert.Equal("enclosed-manifold", summary.GetProperty("structuralAssessment").GetString());
Assert.Equal(0, summary.GetProperty("surfaceFamilies").GetProperty("bspline").GetInt32());
+
+ Assert.Equal("mm", summary.GetProperty("lengthUnit").GetString());
+ Assert.Contains("assumed", summary.GetProperty("lengthUnitBasis").GetString(), StringComparison.OrdinalIgnoreCase);
+
+ var faceIds = summary.GetProperty("faceIds");
+ Assert.Equal(1, faceIds.GetProperty("min").GetInt32());
+ Assert.Equal(6, faceIds.GetProperty("max").GetInt32());
+ Assert.Equal(6, faceIds.GetProperty("count").GetInt32());
+ Assert.True(faceIds.GetProperty("contiguous").GetBoolean());
+
+ var edgeIds = summary.GetProperty("edgeIds");
+ Assert.Equal(1, edgeIds.GetProperty("min").GetInt32());
+ Assert.Equal(12, edgeIds.GetProperty("max").GetInt32());
+ Assert.Equal(12, edgeIds.GetProperty("count").GetInt32());
+ Assert.True(edgeIds.GetProperty("contiguous").GetBoolean());
+
+ var vertexIds = summary.GetProperty("vertexIds");
+ Assert.Equal(1, vertexIds.GetProperty("min").GetInt32());
+ Assert.Equal(8, vertexIds.GetProperty("max").GetInt32());
+ Assert.Equal(8, vertexIds.GetProperty("count").GetInt32());
+ Assert.True(vertexIds.GetProperty("contiguous").GetBoolean());
}
[Fact]
public void Analyze_Command_Provides_Numeric_Face_Detail_Anchors()
{
var stepPath = ExportPrimitiveToTempStep(BrepPrimitives.CreateCylinder(5d, 12d).Value, "cli-cylinder-face-truth");
- var stdout = new StringWriter();
- var stderr = new StringWriter();
-
- var exitCode = Aetheris.CLI.CliRunner.Run(
- ["analyze", stepPath, "--face", "2", "--json"],
- stdout,
- stderr);
-
- Assert.Equal(0, exitCode);
- using var doc = JsonDocument.Parse(stdout.ToString());
- var face = doc.RootElement.GetProperty("face");
+ var face = AnalyzeFace(stepPath, 2);
Assert.Equal(2, face.GetProperty("faceId").GetInt32());
Assert.Equal("Plane", face.GetProperty("surfaceType").GetString());
+ Assert.Equal("bound", face.GetProperty("surfaceStatus").GetString());
AssertPoint(face.GetProperty("anchorPoint"), 0d, 0d, 6d);
AssertVector(face.GetProperty("planarNormal"), 0d, 0d, 1d);
Assert.Single(face.GetProperty("adjacentEdgeIds").EnumerateArray());
@@ -81,34 +92,43 @@ public sealed class CliBaselineTests
public void Analyze_Command_Reports_Truthful_Edge_Length_Fields()
{
var stepPath = ExportPrimitiveToTempStep(BrepPrimitives.CreateCylinder(5d, 8d).Value, "cli-cylinder-edge-truth");
- var stdout = new StringWriter();
- var stderr = new StringWriter();
- var exitCode = Aetheris.CLI.CliRunner.Run(
- ["analyze", stepPath, "--edge", "1", "--json"],
- stdout,
- stderr);
+ var lineEdge = AnalyzeEdge(stepPath, 1);
+ Assert.Equal(1, lineEdge.GetProperty("edgeId").GetInt32());
+ Assert.Equal("Line3", lineEdge.GetProperty("curveType").GetString());
+ Assert.Equal(8d, lineEdge.GetProperty("arcLength").GetDouble(), 8);
+ Assert.Equal(8d, lineEdge.GetProperty("parameterRange").GetDouble(), 8);
+ Assert.Equal("computed", lineEdge.GetProperty("arcLengthStatus").GetString());
- Assert.Equal(0, exitCode);
- using var doc = JsonDocument.Parse(stdout.ToString());
- var edge = doc.RootElement.GetProperty("edge");
- Assert.Equal(1, edge.GetProperty("edgeId").GetInt32());
- Assert.Equal("Line3", edge.GetProperty("curveType").GetString());
- Assert.Equal(8d, edge.GetProperty("arcLength").GetDouble(), 8);
- Assert.Equal(8d, edge.GetProperty("parameterRange").GetDouble(), 8);
-
- stdout.GetStringBuilder().Clear();
- stderr.GetStringBuilder().Clear();
- exitCode = Aetheris.CLI.CliRunner.Run(
- ["analyze", stepPath, "--edge", "2", "--json"],
- stdout,
- stderr);
- Assert.Equal(0, exitCode);
- using var circleDoc = JsonDocument.Parse(stdout.ToString());
- var circleEdge = circleDoc.RootElement.GetProperty("edge");
+ var circleEdge = AnalyzeEdge(stepPath, 2);
Assert.Equal("Circle3", circleEdge.GetProperty("curveType").GetString());
Assert.Equal(2d * double.Pi, circleEdge.GetProperty("parameterRange").GetDouble(), 8);
Assert.Equal(10d * double.Pi, circleEdge.GetProperty("arcLength").GetDouble(), 8);
+ Assert.Equal("computed", circleEdge.GetProperty("arcLengthStatus").GetString());
+ }
+
+ [Fact]
+ public void Analyze_Command_Explains_Null_ArcLength_For_Unsupported_Curve_Kinds()
+ {
+ var stepPath = Path.Combine(RepoRoot, "testdata/step242/nist/STC/nist_stc_06_asme1_ap242-e3.stp");
+ var summary = AnalyzeSummary(stepPath);
+ var maxEdgeId = summary.GetProperty("edgeIds").GetProperty("max").GetInt32();
+
+ for (var edgeId = 1; edgeId <= maxEdgeId; edgeId++)
+ {
+ var edge = AnalyzeEdge(stepPath, edgeId);
+ var curveType = edge.GetProperty("curveType").GetString();
+ if (curveType is "Line3" or "Circle3")
+ {
+ continue;
+ }
+
+ Assert.True(edge.GetProperty("arcLength").ValueKind == JsonValueKind.Null);
+ Assert.Equal("unsupported-for-curve-kind", edge.GetProperty("arcLengthStatus").GetString());
+ return;
+ }
+
+ throw new Xunit.Sdk.XunitException("Expected at least one non-line/non-circle edge in NIST fixture.");
}
[Fact]
@@ -131,7 +151,7 @@ public sealed class CliBaselineTests
}
[Fact]
- public void Analyze_Command_Provides_Cylinder_Sphere_And_Torus_Anchors()
+ public void Analyze_Command_Provides_Cylinder_Sphere_And_Torus_Anchors_With_Sphere_Axis_Omitted()
{
var cylinderStepPath = ExportPrimitiveToTempStep(BrepPrimitives.CreateCylinder(4d, 12d).Value, "cli-cylinder-face-anchor");
var sphereStepPath = ExportPrimitiveToTempStep(BrepPrimitives.CreateSphere(3d).Value, "cli-sphere-face-anchor");
@@ -146,7 +166,7 @@ public sealed class CliBaselineTests
var sphereFace = AnalyzeFace(sphereStepPath, 1);
Assert.Equal("Sphere", sphereFace.GetProperty("surfaceType").GetString());
AssertPoint(sphereFace.GetProperty("anchorPoint"), 0d, 0d, 0d);
- AssertVector(sphereFace.GetProperty("axis"), 0d, 0d, 1d);
+ Assert.False(sphereFace.TryGetProperty("axis", out _));
Assert.Equal(3d, sphereFace.GetProperty("radius").GetDouble(), 8);
var torusFace = AnalyzeFace(torusStepPath, 1);
@@ -157,6 +177,18 @@ public sealed class CliBaselineTests
Assert.Equal(2d, torusFace.GetProperty("minorRadius").GetDouble(), 8);
}
+ [Fact]
+ public void Analyze_Command_Uses_Binding_Missing_Surface_Status_Instead_Of_Unknown_Surface_Type()
+ {
+ var boxBody = BrepPrimitives.CreateBox(10d, 6d, 4d).Value;
+ var brokenBody = RemoveFaceBinding(boxBody, new[] { 1 });
+
+ var result = StepAnalyzer.AnalyzeImportedBody(brokenBody, "in-memory", faceId: 1);
+ Assert.NotNull(result.Face);
+ Assert.Null(result.Face!.SurfaceType);
+ Assert.Equal("binding-missing", result.Face.SurfaceStatus);
+ }
+
[Fact]
public void Analyze_Command_Returns_Structured_Json_Failure()
{
@@ -190,6 +222,45 @@ public sealed class CliBaselineTests
Assert.Contains("coedge incidence", summary.GetProperty("structuralAssessmentBasis").GetString(), StringComparison.OrdinalIgnoreCase);
}
+ private static BrepBody RemoveFaceBinding(BrepBody source, IReadOnlyCollection<int> faceIdsToSkip)
+ {
+ var bindings = new BrepBindingModel();
+ foreach (var edgeBinding in source.Bindings.EdgeBindings)
+ {
+ bindings.AddEdgeBinding(edgeBinding);
+ }
+
+ foreach (var faceBinding in source.Bindings.FaceBindings)
+ {
+ if (!faceIdsToSkip.Contains(faceBinding.FaceId.Value))
+ {
+ bindings.AddFaceBinding(faceBinding);
+ }
+ }
+
+ var vertexPoints = source.Topology.Vertices
+ .Where(vertex => source.TryGetVertexPoint(vertex.Id, out _))
+ .ToDictionary(
+ vertex => vertex.Id,
+ vertex =>
+ {
+ source.TryGetVertexPoint(vertex.Id, out var point);
+ return point;
+ });
+
+ return new BrepBody(source.Topology, source.Geometry, bindings, vertexPoints);
+ }
+
+ private static JsonElement AnalyzeSummary(string stepPath)
+ {
+ var stdout = new StringWriter();
+ var stderr = new StringWriter();
+ var exitCode = Aetheris.CLI.CliRunner.Run(["analyze", stepPath, "--json"], stdout, stderr);
+ Assert.Equal(0, exitCode);
+ using var doc = JsonDocument.Parse(stdout.ToString());
+ return doc.RootElement.GetProperty("summary").Clone();
+ }
+
private static JsonElement AnalyzeFace(string stepPath, int faceId)
{
var stdout = new StringWriter();
@@ -200,6 +271,16 @@ public sealed class CliBaselineTests
return doc.RootElement.GetProperty("face").Clone();
}
+ private static JsonElement AnalyzeEdge(string stepPath, int edgeId)
+ {
+ var stdout = new StringWriter();
+ var stderr = new StringWriter();
+ var exitCode = Aetheris.CLI.CliRunner.Run(["analyze", stepPath, "--edge", edgeId.ToString(), "--json"], stdout, stderr);
+ Assert.Equal(0, exitCode);
+ using var doc = JsonDocument.Parse(stdout.ToString());
+ return doc.RootElement.GetProperty("edge").Clone();
+ }
+
private static string ExportPrimitiveToTempStep(BrepBody body, string stem)
{
var export = Step242Exporter.ExportBody(body);
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.cs
index b2b56bbb..8599a3f2 100644
--- a/Aetheris.CLI/CliRunner.cs
+++ b/Aetheris.CLI/CliRunner.cs
@@ -191,6 +191,10 @@ public static class CliRunner
stdout.WriteLine($"Vertices: {summary.VertexCount}");
stdout.WriteLine($"BoundingBox: {FormatBox(summary.BoundingBox)}");
stdout.WriteLine($"Structure: {summary.StructuralAssessment} ({summary.StructuralAssessmentBasis})");
+ stdout.WriteLine($"LengthUnit: {summary.LengthUnit} ({summary.LengthUnitBasis})");
+ stdout.WriteLine($"FaceIds: min={summary.FaceIds.Min}, max={summary.FaceIds.Max}, count={summary.FaceIds.Count}, contiguous={summary.FaceIds.Contiguous}");
+ stdout.WriteLine($"EdgeIds: min={summary.EdgeIds.Min}, max={summary.EdgeIds.Max}, count={summary.EdgeIds.Count}, contiguous={summary.EdgeIds.Contiguous}");
+ stdout.WriteLine($"VertexIds: min={summary.VertexIds.Min}, max={summary.VertexIds.Max}, count={summary.VertexIds.Count}, contiguous={summary.VertexIds.Contiguous}");
stdout.WriteLine("Surface Families:");
foreach (var family in summary.SurfaceFamilies)
{
@@ -199,12 +203,12 @@ public static class CliRunner
if (analysis.Face is not null)
{
- stdout.WriteLine($"Face {analysis.Face.FaceId}: type={analysis.Face.SurfaceType}, bbox={FormatBox(analysis.Face.BoundingBox)}, point={FormatPoint(analysis.Face.RepresentativePoint)}, anchor={FormatPoint(analysis.Face.AnchorPoint)}, apex={FormatPoint(analysis.Face.Apex)}, normal={FormatVector(analysis.Face.PlanarNormal)}, axis={FormatVector(analysis.Face.Axis)}, radius={FormatDouble(analysis.Face.Radius)}, placementRadius={FormatDouble(analysis.Face.PlacementRadius)}, majorRadius={FormatDouble(analysis.Face.MajorRadius)}, minorRadius={FormatDouble(analysis.Face.MinorRadius)}, semiAngleRadians={FormatDouble(analysis.Face.SemiAngleRadians)}, edges=[{string.Join(",", analysis.Face.AdjacentEdgeIds)}]");
+ stdout.WriteLine($"Face {analysis.Face.FaceId}: type={analysis.Face.SurfaceType ?? "n/a"}, status={analysis.Face.SurfaceStatus}, bbox={FormatBox(analysis.Face.BoundingBox)}, point={FormatPoint(analysis.Face.RepresentativePoint)}, anchor={FormatPoint(analysis.Face.AnchorPoint)}, apex={FormatPoint(analysis.Face.Apex)}, normal={FormatVector(analysis.Face.PlanarNormal)}, axis={FormatVector(analysis.Face.Axis)}, radius={FormatDouble(analysis.Face.Radius)}, placementRadius={FormatDouble(analysis.Face.PlacementRadius)}, majorRadius={FormatDouble(analysis.Face.MajorRadius)}, minorRadius={FormatDouble(analysis.Face.MinorRadius)}, semiAngleRadians={FormatDouble(analysis.Face.SemiAngleRadians)}, edges=[{string.Join(",", analysis.Face.AdjacentEdgeIds)}]");
}
if (analysis.Edge is not null)
{
- stdout.WriteLine($"Edge {analysis.Edge.EdgeId}: curve={analysis.Edge.CurveType}, start={analysis.Edge.StartVertexId}:{FormatPoint(analysis.Edge.StartVertex)}, end={analysis.Edge.EndVertexId}:{FormatPoint(analysis.Edge.EndVertex)}, faces=[{string.Join(",", analysis.Edge.AdjacentFaceIds)}], parameterRange={FormatDouble(analysis.Edge.ParameterRange)}, arcLength={FormatDouble(analysis.Edge.ArcLength)}");
+ stdout.WriteLine($"Edge {analysis.Edge.EdgeId}: curve={analysis.Edge.CurveType}, start={analysis.Edge.StartVertexId}:{FormatPoint(analysis.Edge.StartVertex)}, end={analysis.Edge.EndVertexId}:{FormatPoint(analysis.Edge.EndVertex)}, faces=[{string.Join(",", analysis.Edge.AdjacentFaceIds)}], parameterRange={FormatDouble(analysis.Edge.ParameterRange)}, arcLength={FormatDouble(analysis.Edge.ArcLength)}, arcLengthStatus={analysis.Edge.ArcLengthStatus}");
}
if (analysis.Vertex is not null)
diff --git a/Aetheris.CLI/StepAnalysisModels.cs b/Aetheris.CLI/StepAnalysisModels.cs
index 947011ab..8a2160a1 100644
--- a/Aetheris.CLI/StepAnalysisModels.cs
+++ b/Aetheris.CLI/StepAnalysisModels.cs
@@ -1,7 +1,14 @@
+using System.Text.Json.Serialization;
using Aetheris.Kernel.Core.Math;
namespace Aetheris.CLI;
+public sealed record IdRangeSummary(
+ int Min,
+ int Max,
+ int Count,
+ bool Contiguous);
+
public sealed record AnalyzeSummary(
int BodyCount,
int ShellCount,
@@ -11,17 +18,23 @@ public sealed record AnalyzeSummary(
BoundingBox3D? BoundingBox,
string StructuralAssessment,
IReadOnlyDictionary<string, int> SurfaceFamilies,
- string StructuralAssessmentBasis);
+ string StructuralAssessmentBasis,
+ string LengthUnit,
+ string LengthUnitBasis,
+ IdRangeSummary FaceIds,
+ IdRangeSummary EdgeIds,
+ IdRangeSummary VertexIds);
public sealed record FaceDetail(
int FaceId,
- string SurfaceType,
+ string? SurfaceType,
+ string SurfaceStatus,
BoundingBox3D? BoundingBox,
Point3D? RepresentativePoint,
Point3D? AnchorPoint,
Point3D? Apex,
Vector3D? PlanarNormal,
- Vector3D? Axis,
+ [property: JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] Vector3D? Axis,
double? Radius,
double? PlacementRadius,
double? MajorRadius,
@@ -38,7 +51,8 @@ public sealed record EdgeDetail(
Point3D? EndVertex,
IReadOnlyList<int> AdjacentFaceIds,
double? ParameterRange,
- double? ArcLength);
+ double? ArcLength,
+ string ArcLengthStatus);
public sealed record VertexDetail(
int VertexId,
diff --git a/Aetheris.CLI/StepAnalyzer.cs b/Aetheris.CLI/StepAnalyzer.cs
index 7d12be9b..6fa31789 100644
--- a/Aetheris.CLI/StepAnalyzer.cs
+++ b/Aetheris.CLI/StepAnalyzer.cs
@@ -17,7 +17,11 @@ public static class StepAnalyzer
throw new InvalidOperationException(string.Join(Environment.NewLine, import.Diagnostics.Select(d => d.Message)));
}
- var body = import.Value;
+ return AnalyzeImportedBody(import.Value, fullPath, faceId, edgeId, vertexId);
+ }
+
+ public static AnalyzeResult AnalyzeImportedBody(BrepBody body, string stepPath, int? faceId = null, int? edgeId = null, int? vertexId = null)
+ {
var notes = new List<string>();
var summary = BuildSummary(body, notes);
@@ -25,7 +29,7 @@ public static class StepAnalyzer
var edge = edgeId.HasValue ? BuildEdgeDetail(body, new EdgeId(edgeId.Value), notes) : null;
var vertex = vertexId.HasValue ? BuildVertexDetail(body, new VertexId(vertexId.Value), notes) : null;
- return new AnalyzeResult(fullPath, summary, face, edge, vertex, notes);
+ return new AnalyzeResult(stepPath, summary, face, edge, vertex, notes);
}
private static AnalyzeSummary BuildSummary(BrepBody body, ICollection<string> notes)
@@ -83,7 +87,12 @@ public static class StepAnalyzer
bbox,
structural,
surfaceFamilies,
- basis);
+ basis,
+ "mm",
+ "assumed; STEP import length units not yet preserved",
+ BuildIdRange(topology.Faces.Select(f => f.Id.Value)),
+ BuildIdRange(topology.Edges.Select(e => e.Id.Value)),
+ BuildIdRange(topology.Vertices.Select(v => v.Id.Value)));
}
private static FaceDetail BuildFaceDetail(BrepBody body, FaceId faceId, ICollection<string> notes)
@@ -116,7 +125,7 @@ public static class StepAnalyzer
if (!body.TryGetFaceSurface(faceId, out var surface) || surface is null)
{
- return new FaceDetail(faceId.Value, "unknown", bbox, rep, null, null, null, null, null, null, null, null, null, edgeIds);
+ return new FaceDetail(faceId.Value, null, "binding-missing", bbox, rep, null, null, null, null, null, null, null, null, null, edgeIds);
}
Point3D? anchor = null;
@@ -154,8 +163,8 @@ public static class StepAnalyzer
if (surface.Sphere is { } sphere)
{
anchor = sphere.Center;
- axis = sphere.Axis.ToVector();
radius = sphere.Radius;
+ notes.Add($"Face {faceId.Value} is spherical; axis omitted because spheres have no intrinsic axis.");
}
if (surface.Torus is { } torus)
@@ -166,7 +175,7 @@ public static class StepAnalyzer
minorRadius = torus.MinorRadius;
}
- return new FaceDetail(faceId.Value, surface.Kind.ToString(), bbox, rep, anchor, apex, normal, axis, radius, placementRadius, majorRadius, minorRadius, semiAngle, edgeIds);
+ return new FaceDetail(faceId.Value, surface.Kind.ToString(), "bound", bbox, rep, anchor, apex, normal, axis, radius, placementRadius, majorRadius, minorRadius, semiAngle, edgeIds);
}
private static EdgeDetail BuildEdgeDetail(BrepBody body, EdgeId edgeId, ICollection<string> notes)
@@ -179,6 +188,8 @@ public static class StepAnalyzer
var curveType = "unknown";
double? parameterRange = null;
double? arcLength = null;
+ var arcLengthStatus = "unavailable";
+
if (body.Bindings.TryGetEdgeBinding(edgeId, out var binding))
{
curveType = binding.TrimInterval is null ? "untrimmed" : "trimmed";
@@ -196,17 +207,31 @@ public static class StepAnalyzer
{
case CurveGeometryKind.Line3:
arcLength = double.Abs(trim.End - trim.Start);
+ arcLengthStatus = "computed";
break;
case CurveGeometryKind.Circle3 when curve.Circle3 is { } circle:
arcLength = circle.Radius * double.Abs(trim.End - trim.Start);
+ arcLengthStatus = "computed";
+ break;
+ default:
+ arcLengthStatus = "unsupported-for-curve-kind";
break;
}
}
+ else
+ {
+ arcLengthStatus = "unavailable-no-trim-interval";
+ }
+ }
+ else
+ {
+ arcLengthStatus = "unavailable-curve-missing";
}
}
else
{
notes.Add($"Edge {edgeId.Value} has no curve binding, so curve-type and length are limited.");
+ arcLengthStatus = "unavailable-binding-missing";
}
Point3D? startPoint = body.TryGetVertexPoint(edge.StartVertexId, out var start) ? start : null;
@@ -216,7 +241,7 @@ public static class StepAnalyzer
? faces.Select(id => id.Value).OrderBy(v => v).ToArray()
: [];
- return new EdgeDetail(edgeId.Value, curveType, edge.StartVertexId.Value, startPoint, edge.EndVertexId.Value, endPoint, adjacentFaces, parameterRange, arcLength);
+ return new EdgeDetail(edgeId.Value, curveType, edge.StartVertexId.Value, startPoint, edge.EndVertexId.Value, endPoint, adjacentFaces, parameterRange, arcLength, arcLengthStatus);
}
private static VertexDetail BuildVertexDetail(BrepBody body, VertexId vertexId, ICollection<string> notes)
@@ -241,6 +266,27 @@ public static class StepAnalyzer
return new VertexDetail(vertexId.Value, position, incidentEdges);
}
+ private static IdRangeSummary BuildIdRange(IEnumerable<int> ids)
+ {
+ var sorted = ids.OrderBy(id => id).ToArray();
+ if (sorted.Length == 0)
+ {
+ return new IdRangeSummary(0, 0, 0, true);
+ }
+
+ var contiguous = true;
+ for (var index = 1; index < sorted.Length; index++)
+ {
+ if (sorted[index] != sorted[index - 1] + 1)
+ {
+ contiguous = false;
+ break;
+ }
+ }
+
+ return new IdRangeSummary(sorted[0], sorted[^1], sorted.Length, contiguous);
+ }
+
private static BoundingBox3D? TryComputeBodyBoundingBox(BrepBody body)
{
var points = body.Topology.Vertices
diff --git a/docs/cli-baseline.md b/docs/cli-baseline.md
index e5ad239e..bad58ff4 100644
--- a/docs/cli-baseline.md
+++ b/docs/cli-baseline.md
@@ -1,4 +1,4 @@
-# Aetheris.CLI baseline (C1)
+# Aetheris.CLI baseline (C3)
## Supported commands
@@ -7,11 +7,11 @@ aetheris build <file.firmament> [--out <path>] [--json]
aetheris analyze <file.step> [--face <id>] [--edge <id>] [--vertex <id>] [--json]
```
-### Contract notes
+## Contract notes
-- `build` runs the existing `FirmamentBuildAndExport.Run` pipeline; it does not implement a parallel compiler/export path.
+- `build` runs `FirmamentBuildAndExport.Run`; no parallel compile/export path is introduced.
- `build` default output path remains deterministic: `<repo>/testdata/firmament/exports/<source-filename>.step`.
-- `analyze` imports STEP using `Step242Importer.ImportBody` and reports facts from imported topology/geometry bindings.
+- `analyze` imports STEP with `Step242Importer.ImportBody` and reports imported topology/geometry facts.
- At most one detail selector is allowed on `analyze`: `--face`, `--edge`, or `--vertex`.
- `analyze --json` is the canonical machine-readable mode.
@@ -28,15 +28,21 @@ aetheris analyze <file.step> [--face <id>] [--edge <id>] [--vertex <id>] [--json
"vertexCount": 8,
"boundingBox": { "min": { "x": 0, "y": 0, "z": 0 }, "max": { "x": 10, "y": 5, "z": 2 } },
"structuralAssessment": "enclosed-manifold",
+ "structuralAssessmentBasis": "derived from imported topology edge-to-face coedge incidence counts",
+ "lengthUnit": "mm",
+ "lengthUnitBasis": "assumed; STEP import length units not yet preserved",
"surfaceFamilies": {
"plane": 6,
"cylinder": 0,
"cone": 0,
"sphere": 0,
"torus": 0,
+ "bspline": 0,
"other": 0
},
- "structuralAssessmentBasis": "derived from imported topology edge-to-face adjacency counts"
+ "faceIds": { "min": 1, "max": 6, "count": 6, "contiguous": true },
+ "edgeIds": { "min": 1, "max": 12, "count": 12, "contiguous": true },
+ "vertexIds": { "min": 1, "max": 8, "count": 8, "contiguous": true }
},
"face": null,
"edge": null,
@@ -45,8 +51,67 @@ aetheris analyze <file.step> [--face <id>] [--edge <id>] [--vertex <id>] [--json
}
```
-## Truthfulness and deferrals
+### Structural assessment enum semantics
-- Structural classification is based on edge-to-face adjacency counts from imported topology.
-- If bounding boxes or points cannot be determined from available vertex coordinates, output is `null` (JSON) / `unknown` (text), and a note is emitted.
-- No renderer/viewer, no schema redesign, and no generalized command framework are included in C1.
+- `enclosed-manifold`: every imported edge is used by exactly two face coedges.
+- `leaky-or-open`: at least one imported edge is used by only one face coedge.
+- `non-manifold`: no leaky edges, but one or more edges have coedge incidence different from 2.
+
+### Unit semantics (honesty contract)
+
+- `lengthUnit` is currently emitted as `mm`.
+- `lengthUnitBasis` communicates trust level of that value.
+- Current C3 truth: `lengthUnit` is an Aetheris analyzer assumption/normalization output, not preserved STEP source-unit provenance.
+
+## Face detail contract (`--face <id>`)
+
+Common fields:
+
+- `faceId`, `surfaceType`, `surfaceStatus`, `boundingBox`, `representativePoint`, `adjacentEdgeIds`
+
+Surface binding semantics:
+
+- Bound face: `surfaceStatus: "bound"`, `surfaceType` is a concrete kind (`Plane`, `Cylinder`, `Cone`, `Sphere`, `Torus`, `BSplineSurfaceWithKnots`, ...).
+- Missing surface binding: `surfaceStatus: "binding-missing"`, `surfaceType: null`.
+
+Kind-specific fields:
+
+- Plane: `anchorPoint`, `planarNormal`
+- Cylinder: `anchorPoint`, `axis`, `radius`
+- Cone: `anchorPoint`, `apex`, `axis`, `semiAngleRadians`, `placementRadius`
+- Sphere: `anchorPoint`, `radius` (no `axis` field is emitted; spheres have no intrinsic axis)
+- Torus: `anchorPoint`, `axis`, `majorRadius`, `minorRadius`
+
+## Edge detail contract (`--edge <id>`)
+
+Fields:
+
+- `edgeId`, `curveType`, `startVertexId`, `startVertex`, `endVertexId`, `endVertex`, `adjacentFaceIds`, `parameterRange`, `arcLength`, `arcLengthStatus`
+
+`arcLengthStatus` enum semantics:
+
+- `computed`: current curve-kind support computed a numeric `arcLength`.
+- `unsupported-for-curve-kind`: `arcLength` is null because current analyzer does not implement that curve kind.
+- `unavailable-no-trim-interval`: edge is present but has no trim interval.
+- `unavailable-curve-missing`: curve binding exists but curve geometry is unresolved.
+- `unavailable-binding-missing`: edge has no curve binding.
+- `unavailable`: generic fallback when no narrower status applies.
+
+## Analyze failure JSON shape
+
+When `--json` is requested and analyze fails:
+
+```json
+{
+ "success": false,
+ "stepPath": "<resolved-path>",
+ "error": "<message>"
+}
+```
+
+## Truthfulness and scope boundaries
+
+- Structural classification is derived from imported edge-to-face coedge incidence counts.
+- Missing coordinate-dependent fields are emitted as null and accompanied by notes.
+- C3 does not add arbitrary source-unit preservation/export redesign.
+- C3 does not add renderer/viewer scope, language redesign, or broad CLI framework redesign.