Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Publish structured STEP PMI semantics and controls

Yuechen Libbd2dcbf0ea4
diff --git a/Aetheris.Kernel.Core/Brep/BrepBindings.cs b/Aetheris.Kernel.Core/Brep/BrepBindings.cs
index e873822d..303c029c 100644
--- a/Aetheris.Kernel.Core/Brep/BrepBindings.cs
+++ b/Aetheris.Kernel.Core/Brep/BrepBindings.cs
@@ -12,7 +12,8 @@ public readonly record struct EdgeGeometryBinding(
public readonly record struct FaceGeometryBinding(
FaceId FaceId,
SurfaceGeometryId SurfaceGeometryId,
- bool SameSense = true);
+ bool SameSense = true,
+ int? SourceStepEntityId = null);
/// <summary>
/// Explicit topology-to-geometry binding container.
diff --git a/Aetheris.Kernel.Core/Step242/Step242Importer.cs b/Aetheris.Kernel.Core/Step242/Step242Importer.cs
index 2337f297..86449194 100644
--- a/Aetheris.Kernel.Core/Step242/Step242Importer.cs
+++ b/Aetheris.Kernel.Core/Step242/Step242Importer.cs
@@ -475,7 +475,14 @@ public static class Step242Importer
var (surfaceGeometryId, surfaceGeometry) = bindSurfaceResult.Value;
nextSurfaceGeometryId++;
geometry.AddSurface(surfaceGeometryId, surfaceGeometry);
- bindings.AddFaceBinding(new FaceGeometryBinding(faceId, surfaceGeometryId, faceSameSenseResult.Value));
+ // Preserve interchange identity as provenance. Semantic associations such as
+ // GEOMETRIC_ITEM_SPECIFIC_USAGE refer to the ADVANCED_FACE entity number;
+ // consumers must not guess this relationship from allocation order.
+ bindings.AddFaceBinding(new FaceGeometryBinding(
+ faceId,
+ surfaceGeometryId,
+ faceSameSenseResult.Value,
+ SourceStepEntityId: faceEntity.Id));
}
foreach (var coedge in coedges)
diff --git a/Aetheris.Server.Tests/KernelApiIntegrationTests.cs b/Aetheris.Server.Tests/KernelApiIntegrationTests.cs
index 4cdfbb78..bdc1f8f2 100644
--- a/Aetheris.Server.Tests/KernelApiIntegrationTests.cs
+++ b/Aetheris.Server.Tests/KernelApiIntegrationTests.cs
@@ -993,6 +993,48 @@ public sealed class KernelApiIntegrationTests : IClassFixture<WebApplicationFact
Assert.True(Guid.TryParse(loaded.Data.BodyId, out _));
}
+ [Fact]
+ public async Task StepImport_Ctc03PublishesStructuredSemanticPmiWithRealFaceAssociations()
+ {
+ var document = await CreateDocumentAsync("/api/v1/documents");
+ var path = Path.Combine(
+ RepositoryRoot(),
+ "docs", "modules", "sheetmetal", "artifacts", "ctc03-manufacturing-release",
+ "ctc03-manufacturing-ap242.step");
+ var response = await _client.PostAsJsonAsync(
+ $"/api/v1/documents/{document.Data!.DocumentId}/import/step",
+ new StepImportRequestDto(await File.ReadAllTextAsync(path), "CTC-03 manufacturing"));
+ response.EnsureSuccessStatusCode();
+ var imported = await response.Content.ReadFromJsonAsync<ApiResponseDto<StepImportResponseDto>>();
+
+ Assert.True(imported!.Success);
+ var presentation = Assert.IsType<CadmataVisualizationArtifactDto>(imported.Data!.SemanticPresentation);
+ Assert.Equal(3, presentation.Metrics["datumCount"]);
+ Assert.Equal(13, presentation.Metrics["dimensionCount"]);
+ Assert.Equal(5, presentation.Metrics["geometricToleranceCount"]);
+ Assert.Equal(8, presentation.Metrics["annotationCount"]);
+ Assert.Equal(11, presentation.Metrics["repeatedFeaturePmiCount"]);
+
+ var position = Assert.Single(presentation.Entities, entity => entity.Kind == "Position" && entity.Label == "FrontMountPosition");
+ Assert.Equal("A | B | C", position.Metadata!["datumRefs"]);
+ Assert.Equal(2, position.Topology!.FaceIds!.Count);
+ Assert.Equal(3, position.SelectionIds!.Count);
+ Assert.All(position.Topology.FaceIds, faceId =>
+ Assert.Contains(presentation.Entities, entity => entity.Kind == "BRepFace" && entity.Topology!.FaceIds!.Contains(faceId)));
+ Assert.Equal(
+ ["3738", "3750"],
+ position.Topology.FaceIds
+ .Select(faceId => presentation.Entities.Single(entity => entity.Kind == "BRepFace" && entity.Topology!.FaceIds!.Contains(faceId)).Metadata!["stepEntityId"])
+ .OrderBy(value => value, StringComparer.Ordinal));
+
+ var localNote = Assert.Single(presentation.Entities, entity => entity.Kind == "Annotation" && entity.Label == "ProtectDatumA");
+ Assert.Single(localNote.Topology!.FaceIds!);
+ Assert.Contains("support surface", localNote.Metadata!["text"], StringComparison.Ordinal);
+ Assert.All(
+ presentation.Entities.Where(entity => entity.Kind is "Datum" or "Dimension" or "Diameter" or "Position" or "Annotation"),
+ entity => Assert.StartsWith("STEP #", entity.SourceSpan, StringComparison.Ordinal));
+ }
+
[Fact]
public async Task CadmataHexBoltV2Fixture_PublishesTemplateParametersAndGeneratedFaceOwnership()
{
diff --git a/Aetheris.Server/Api/CadmataStepSemanticBridge.cs b/Aetheris.Server/Api/CadmataStepSemanticBridge.cs
new file mode 100644
index 00000000..9624cbf4
--- /dev/null
+++ b/Aetheris.Server/Api/CadmataStepSemanticBridge.cs
@@ -0,0 +1,232 @@
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.Core.Topology;
+using Aetheris.Server.Contracts;
+
+namespace Aetheris.Server.Api;
+
+/// <summary>
+/// Adapts imported AP242 product-definition semantics into Cadmata's existing
+/// inspectable application model. This layer publishes semantic identity and
+/// associations only; camera-facing placement remains presentation state.
+/// </summary>
+internal static class CadmataStepSemanticBridge
+{
+ public static CadmataVisualizationArtifactDto? Build(string stepText, string sourceName, BrepBody body)
+ {
+ var inspection = Step242SemanticPmiInspector.Inspect(stepText);
+ if (!inspection.Success || inspection.Items.Count == 0) return null;
+
+ var sourceFaceToBrepFace = body.Bindings.FaceBindings
+ .Where(binding => binding.SourceStepEntityId.HasValue)
+ .ToDictionary(binding => binding.SourceStepEntityId!.Value, binding => binding.FaceId.Value);
+ var bodyAnchor = BodyAnchor(body);
+ var entities = new List<CadmataVisualizationEntityDto>();
+ var targetIds = inspection.Items
+ .Select(item => item.Target)
+ .Where(target => !string.IsNullOrWhiteSpace(target))
+ .Distinct(StringComparer.Ordinal)
+ .OrderBy(target => target, StringComparer.Ordinal)
+ .ToDictionary(target => target, TargetId, StringComparer.Ordinal);
+ var datumTargetIds = inspection.Items
+ .Where(item => item.Kind == "Datum")
+ .ToDictionary(item => item.Name, item => targetIds.GetValueOrDefault(item.Target), StringComparer.Ordinal);
+
+ entities.Add(Entity(
+ "step:product",
+ "Body",
+ sourceName,
+ "SemanticProductDefinition",
+ Point(bodyAnchor),
+ childIds: targetIds.Values.ToArray(),
+ metadata: new Dictionary<string, string>
+ {
+ ["authority"] = "STEP AP242 semantic product definition",
+ ["presentationAuthority"] = "Cadmata derived presentation"
+ }));
+
+ foreach (var (target, stableId) in targetIds)
+ {
+ var items = inspection.Items.Where(item => item.Target == target).ToArray();
+ var faceIds = ResolveFaceIds(items.SelectMany(item => item.GeometricFaceEntityIds), sourceFaceToBrepFace);
+ entities.Add(Entity(
+ stableId,
+ "EngineeringTarget",
+ DisplayTarget(target),
+ "SemanticTarget",
+ Point(Anchor(body, faceIds, bodyAnchor)),
+ parentIds: ["step:product"],
+ topology: Topology(faceIds),
+ metadata: new Dictionary<string, string>
+ {
+ ["semanticPath"] = target,
+ ["associationAuthority"] = faceIds.Count > 0 ? "GEOMETRIC_ITEM_SPECIFIC_USAGE" : "product target"
+ }));
+ }
+
+ foreach (var item in inspection.Items)
+ {
+ var targetId = targetIds.GetValueOrDefault(item.Target) ?? "step:product";
+ var faceIds = ResolveFaceIds(item.GeometricFaceEntityIds, sourceFaceToBrepFace);
+ var references = item.Kind == "Position"
+ ? item.DatumReferences.Select(reference => datumTargetIds.GetValueOrDefault(reference))
+ .Where(reference => reference is not null).Cast<string>().ToArray()
+ : [];
+ var metadata = new Dictionary<string, string>
+ {
+ ["target"] = item.Target,
+ ["targetSemanticId"] = targetId,
+ ["semanticKind"] = item.Kind,
+ ["provenance"] = $"STEP AP242 entity #{item.EntityId}",
+ ["sourceEntityId"] = item.EntityId.ToString(System.Globalization.CultureInfo.InvariantCulture),
+ ["presentation"] = "derived; imported annotation transforms are non-authoritative"
+ };
+ Add(metadata, "nominal", item.Value);
+ Add(metadata, "tolerancePlus", item.TolerancePlus);
+ Add(metadata, "toleranceMinus", item.ToleranceMinus);
+ Add(metadata, "quantity", item.Quantity);
+ if (item.Value.HasValue) metadata["unit"] = "mm";
+ if (item.DatumReferences.Count > 0) metadata["datumRefs"] = string.Join(" | ", item.DatumReferences);
+ if (!string.IsNullOrWhiteSpace(item.Text)) metadata["text"] = item.Text;
+
+ entities.Add(Entity(
+ $"step-pmi:{item.EntityId}",
+ item.Kind,
+ DisplayLabel(item),
+ Role(item.Kind),
+ Point(Anchor(body, faceIds, bodyAnchor)),
+ sourceSpan: $"STEP #{item.EntityId}",
+ parentIds: [targetId],
+ topology: Topology(faceIds),
+ selectionIds: references,
+ metadata: metadata));
+ }
+
+ var targetOwnersByFace = entities
+ .Where(entity => entity.Kind == "EngineeringTarget" && entity.Topology?.FaceIds is { Count: > 0 })
+ .SelectMany(entity => entity.Topology!.FaceIds!.Select(faceId => (faceId, entity.StableId)))
+ .GroupBy(item => item.faceId)
+ .ToDictionary(group => group.Key, group => (IReadOnlyList<string>)group.Select(item => item.StableId).Distinct().ToArray());
+ foreach (var binding in body.Bindings.FaceBindings.OrderBy(binding => binding.FaceId.Value))
+ {
+ var faceId = binding.FaceId.Value;
+ entities.Add(Entity(
+ $"brep:face:{faceId}",
+ "BRepFace",
+ $"Face {faceId}",
+ "MaterialFace",
+ null,
+ parentIds: targetOwnersByFace.GetValueOrDefault(faceId),
+ topology: new CadmataTopologyDto([faceId]),
+ metadata: binding.SourceStepEntityId is { } sourceId
+ ? new Dictionary<string, string> { ["stepEntityId"] = sourceId.ToString(System.Globalization.CultureInfo.InvariantCulture) }
+ : null));
+ }
+
+ var diagnostics = inspection.Diagnostics
+ .Select(message => new CadmataVisualizationDiagnosticDto("STEP.PMI.Inspection", message, "warning"))
+ .ToArray();
+ return new CadmataVisualizationArtifactDto(
+ "cadmata-concept-viz-x1",
+ sourceName,
+ sourceName,
+ entities,
+ [],
+ diagnostics,
+ new Dictionary<string, double>
+ {
+ ["entityCount"] = entities.Count,
+ ["datumCount"] = inspection.DatumCount,
+ ["dimensionCount"] = inspection.DimensionCount,
+ ["geometricToleranceCount"] = inspection.GeometricToleranceCount,
+ ["annotationCount"] = inspection.AnnotationCount,
+ ["repeatedFeaturePmiCount"] = inspection.Items.Count(item => item.Quantity is > 1)
+ });
+ }
+
+ private static CadmataVisualizationEntityDto Entity(
+ string stableId,
+ string kind,
+ string label,
+ string role,
+ CadmataGeometryDto? geometry,
+ string? sourceSpan = null,
+ IReadOnlyList<string>? parentIds = null,
+ IReadOnlyList<string>? childIds = null,
+ CadmataTopologyDto? topology = null,
+ IReadOnlyList<string>? selectionIds = null,
+ IReadOnlyDictionary<string, string>? metadata = null) =>
+ new(stableId, kind, label, "selections", role, geometry, sourceSpan, parentIds, childIds, null, null, topology, selectionIds, null, null, metadata);
+
+ private static string TargetId(string target) => $"step-target:{target}";
+ private static string DisplayTarget(string target) => target.Split('.').LastOrDefault() ?? target;
+ private static string Role(string kind) => kind switch
+ {
+ "Datum" => "Datum",
+ "Dimension" or "Diameter" => "Dimension",
+ "Position" => "GeometricTolerance",
+ "Annotation" => "EngineeringAnnotation",
+ _ => "SemanticPMI"
+ };
+ private static string DisplayLabel(Step242SemanticPmiInspectionItem item) => item.Kind switch
+ {
+ "Datum" => $"Datum {item.Name}",
+ "Diameter" => DisplayTarget(item.Target),
+ "Annotation" => item.Name,
+ _ => item.Name
+ };
+
+ private static IReadOnlyList<int> ResolveFaceIds(IEnumerable<int> sourceIds, IReadOnlyDictionary<int, int> map) =>
+ sourceIds.Where(map.ContainsKey).Select(sourceId => map[sourceId]).Distinct().OrderBy(id => id).ToArray();
+
+ private static CadmataTopologyDto? Topology(IReadOnlyList<int> faceIds) => faceIds.Count == 0 ? null : new(faceIds);
+ // CadmataGeometryDto's transport shape represents point-like evidence as a
+ // one-sample polyline (the client already treats its final sample as an anchor).
+ private static CadmataGeometryDto Point(Point3D point) => new("polyline", Points: [new(point.X, point.Y, point.Z)]);
+
+ private static Point3D BodyAnchor(BrepBody body)
+ {
+ var points = body.Topology.Vertices
+ .Select(vertex => body.TryGetVertexPoint(vertex.Id, out var point) ? (Point3D?)point : null)
+ .Where(point => point.HasValue).Select(point => point!.Value).ToArray();
+ if (points.Length == 0) return new Point3D(0, 0, 0);
+ return new Point3D(
+ (points.Min(point => point.X) + points.Max(point => point.X)) / 2,
+ (points.Min(point => point.Y) + points.Max(point => point.Y)) / 2,
+ (points.Min(point => point.Z) + points.Max(point => point.Z)) / 2);
+ }
+
+ private static Point3D Anchor(BrepBody body, IReadOnlyList<int> faceIds, Point3D fallback)
+ {
+ var vertices = new HashSet<VertexId>();
+ foreach (var faceId in faceIds)
+ {
+ if (!body.Topology.TryGetFace(new FaceId(faceId), out var face) || face is null) continue;
+ foreach (var loopId in face.LoopIds)
+ {
+ var loop = body.Topology.GetLoop(loopId);
+ foreach (var coedgeId in loop.CoedgeIds)
+ {
+ var edge = body.Topology.GetEdge(body.Topology.GetCoedge(coedgeId).EdgeId);
+ vertices.Add(edge.StartVertexId);
+ vertices.Add(edge.EndVertexId);
+ }
+ }
+ }
+ var points = vertices.Select(vertex => body.TryGetVertexPoint(vertex, out var point) ? (Point3D?)point : null)
+ .Where(point => point.HasValue).Select(point => point!.Value).ToArray();
+ if (points.Length == 0) return fallback;
+ return new Point3D(points.Average(point => point.X), points.Average(point => point.Y), points.Average(point => point.Z));
+ }
+
+ private static void Add(IDictionary<string, string> metadata, string key, double? value)
+ {
+ if (value.HasValue) metadata[key] = value.Value.ToString("0.###", System.Globalization.CultureInfo.InvariantCulture);
+ }
+
+ private static void Add(IDictionary<string, string> metadata, string key, int? value)
+ {
+ if (value.HasValue) metadata[key] = value.Value.ToString(System.Globalization.CultureInfo.InvariantCulture);
+ }
+}
diff --git a/Aetheris.Server/Api/KernelEndpoints.cs b/Aetheris.Server/Api/KernelEndpoints.cs
index 46a24627..f87cd049 100644
--- a/Aetheris.Server/Api/KernelEndpoints.cs
+++ b/Aetheris.Server/Api/KernelEndpoints.cs
@@ -268,7 +268,17 @@ public static class KernelEndpoints
var occurrenceName = string.IsNullOrWhiteSpace(request.Name) ? "Imported" : request.Name;
var imported = document.AddDefinitionAndOccurrence(importResult.Value, occurrenceName);
- return ApiMappings.Ok(new StepImportResponseDto(documentId, imported.DefinitionId, imported.OccurrenceId, occurrenceName, []));
+ var semanticPresentation = CadmataStepSemanticBridge.Build(
+ request.StepText,
+ occurrenceName,
+ importResult.Value);
+ return ApiMappings.Ok(new StepImportResponseDto(
+ documentId,
+ imported.DefinitionId,
+ imported.OccurrenceId,
+ occurrenceName,
+ [],
+ semanticPresentation));
}));
documents.MapPost("/{documentId:guid}/bodies/{bodyId:guid}/transform", (Guid documentId, Guid bodyId, TranslateBodyRequestDto request, KernelDocumentStore store) =>
diff --git a/Aetheris.Server/Contracts/ApiContracts.cs b/Aetheris.Server/Contracts/ApiContracts.cs
index def1b151..b9d36371 100644
--- a/Aetheris.Server/Contracts/ApiContracts.cs
+++ b/Aetheris.Server/Contracts/ApiContracts.cs
@@ -44,7 +44,13 @@ public sealed record StepExportResponseDto(Guid DocumentId, Guid DefinitionId, s
public sealed record StepImportRequestDto(string? StepText, string? Name);
-public sealed record StepImportResponseDto(Guid DocumentId, Guid DefinitionId, Guid OccurrenceId, string? Name, IReadOnlyList<DiagnosticDto> Diagnostics);
+public sealed record StepImportResponseDto(
+ Guid DocumentId,
+ Guid DefinitionId,
+ Guid OccurrenceId,
+ string? Name,
+ IReadOnlyList<DiagnosticDto> Diagnostics,
+ CadmataVisualizationArtifactDto? SemanticPresentation = null);
public sealed record ExtrudeRequestDto(
IReadOnlyList<ProfilePoint2Dto> Profile,
diff --git a/aetheris.client/src/App.css b/aetheris.client/src/App.css
index f8958196..faff9f66 100644
--- a/aetheris.client/src/App.css
+++ b/aetheris.client/src/App.css
@@ -546,11 +546,43 @@ strong {
line-height: 1.1;
white-space: nowrap;
cursor: pointer;
+ text-align: left;
+ user-select: none;
}
.pmi-callout small {
font-size: 10px;
opacity: 0.85;
}
+.pmi-callout--datums {
+ grid-template-columns: auto auto;
+ align-items: center;
+}
+.pmi-callout__datum {
+ display: grid;
+ place-items: center;
+ min-width: 24px;
+ height: 24px;
+ border: 1px solid currentColor;
+ font-size: 14px;
+}
+.pmi-callout--geometricTolerances strong {
+ letter-spacing: 0.04em;
+}
+.pmi-callout--engineeringAnnotations {
+ width: 230px;
+ white-space: normal;
+}
+.pmi-callout--engineeringAnnotations small {
+ line-height: 1.3;
+}
+.pmi-callout--global {
+ border-style: dashed;
+ opacity: 0.88;
+}
+.pmi-callout.is-selected {
+ box-shadow: 0 0 0 2px currentColor, 0 4px 14px rgb(0 0 0 / 45%);
+ opacity: 1;
+}
.property-table th {
width: 46%;
diff --git a/aetheris.client/src/App.tsx b/aetheris.client/src/App.tsx
index 4e8da0b5..db2e9cfb 100644
--- a/aetheris.client/src/App.tsx
+++ b/aetheris.client/src/App.tsx
@@ -56,6 +56,7 @@ import {
loadViewportThemePreference,
saveViewportThemePreference,
} from "./viewer/viewportThemePreference";
+import { DEFAULT_PMI_VISIBILITY, type PmiCategory, type PmiVisibility } from "./viewer/PmiAnnotationLayer";
type RequestStatus = "idle" | "loading" | "success" | "error";
type BooleanOperationUi = "Union" | "Subtract" | "Intersect";
@@ -224,6 +225,7 @@ function App() {
useState<CadmataLayerVisibility>(DEFAULT_CADMATA_LAYERS);
const [selectedCadmataId, setSelectedCadmataId] = useState<string | null>(null);
const [isPmiVisible, setIsPmiVisible] = useState(true);
+ const [pmiVisibility, setPmiVisibility] = useState<PmiVisibility>(DEFAULT_PMI_VISIBILITY);
const startupStepClaimed = useRef(false);
const viewportTheme = useMemo(() => viewportThemeById(viewportThemeId), [viewportThemeId]);
useEffect(() => saveViewportThemePreference(viewportThemeId), [viewportThemeId]);
@@ -252,6 +254,7 @@ function App() {
setCadmataArtifact(null);
setSelectedCadmataId(null);
setIsPmiVisible(true);
+ setPmiVisibility(DEFAULT_PMI_VISIBILITY);
setImportStatusMessage("Preparing workspace…");
}, [dispatchDocumentEvent]);
@@ -541,6 +544,11 @@ function App() {
}
const imported = await importStep(documentId, stepText, fileName);
+ const semanticPresentation = imported.semanticPresentation
+ ? parseCadmataVisualizationArtifact(imported.semanticPresentation)
+ : null;
+ setCadmataArtifact(semanticPresentation);
+ setSelectedCadmataId(null);
setStepExportText("");
const displayRefresh = await refreshSummaryAndActiveTessellation(
imported.occurrenceId,
@@ -1028,6 +1036,25 @@ function App() {
>
PMI
</button>
+ {([
+ ["datums", "DATUM"],
+ ["dimensions", "DIM"],
+ ["geometricTolerances", "GD&T"],
+ ["engineeringAnnotations", "NOTES"],
+ ] as const).map(([category, label]) => (
+ <button
+ key={category}
+ type="button"
+ className={pmiVisibility[category] && isPmiVisible ? "viewport-segmented__button is-active" : "viewport-segmented__button"}
+ onClick={() => {
+ setIsPmiVisible(true);
+ setPmiVisibility((current) => ({ ...current, [category as PmiCategory]: !current[category] }));
+ }}
+ aria-pressed={pmiVisibility[category] && isPmiVisible}
+ >
+ {label}
+ </button>
+ ))}
<button
type="button"
className={
@@ -1076,6 +1103,7 @@ function App() {
selectedCadmataIds={cadmataSelection?.entityIds}
onCadmataSelect={setSelectedCadmataId}
showPmi={isPmiVisible}
+ pmiVisibility={pmiVisibility}
assemblyPacket={assemblyPacket}
selectedAssemblyOccurrenceId={selectedAssemblyOccurrenceId}
onAssemblyOccurrenceSelect={setSelectedAssemblyOccurrenceId}
diff --git a/aetheris.client/src/__tests__/pmiPresentation.test.ts b/aetheris.client/src/__tests__/pmiPresentation.test.ts
new file mode 100644
index 00000000..a594c892
--- /dev/null
+++ b/aetheris.client/src/__tests__/pmiPresentation.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import {
+ DEFAULT_PMI_VISIBILITY,
+ layoutPmiCallouts,
+ semanticPmiItems,
+} from "../viewer/PmiAnnotationLayer";
+import type { CadmataVisualizationArtifact } from "../viewer/conceptVisualization";
+
+const artifact: CadmataVisualizationArtifact = {
+ schemaVersion: "cadmata-concept-viz-x1",
+ fixtureId: "pmi",
+ sourcePath: "part.step",
+ selections: [],
+ entities: [
+ { stableId: "datum-a", kind: "Datum", label: "Datum A", layer: "selections", geometry: { type: "polyline", points: [{ x: 0, y: 0, z: 0 }] } },
+ { stableId: "position", kind: "Position", label: "Mount position", layer: "selections", geometry: { type: "polyline", points: [{ x: 0, y: 0, z: 0 }] }, metadata: { datumRefs: "A | B | C" } },
+ { stableId: "note", kind: "Annotation", label: "Deburr", layer: "selections", geometry: { type: "polyline", points: [{ x: 0, y: 0, z: 0 }] } },
+ ],
+};
+
+describe("semantic PMI presentation", () => {
+ it("filters independent categories without changing semantic entities", () => {
+ const allVisible = { datums: true, dimensions: true, geometricTolerances: true, engineeringAnnotations: true };
+ expect(semanticPmiItems(artifact, allVisible).map((item) => item.entity.stableId)).toEqual(["datum-a", "position", "note"]);
+ expect(semanticPmiItems(artifact, { ...allVisible, engineeringAnnotations: false }).map((item) => item.entity.stableId)).toEqual(["datum-a", "position"]);
+ expect(artifact.entities).toHaveLength(3);
+ });
+
+ it("places coincident anchors deterministically without collisions", () => {
+ const items = semanticPmiItems(artifact, { ...DEFAULT_PMI_VISIBILITY, engineeringAnnotations: true }).map((item) => ({ ...item, screenAnchor: { x: 400, y: 300, z: 0 } }));
+ const first = layoutPmiCallouts(items, 800, 600, new Map());
+ const second = layoutPmiCallouts(items, 800, 600, new Map());
+ expect(second).toEqual(first);
+ expect(new Set(first.filter((item) => !item.hidden).map((item) => `${item.x.toFixed(2)},${item.y.toFixed(2)}`)).size).toBe(first.filter((item) => !item.hidden).length);
+ });
+
+ it("honors presentation-only manual offsets", () => {
+ const [item] = semanticPmiItems(artifact, DEFAULT_PMI_VISIBILITY);
+ const [placed] = layoutPmiCallouts([{ ...item, screenAnchor: { x: 400, y: 300, z: 0 } }], 800, 600, new Map([["datum-a", { x: 90, y: -40 }]]));
+ expect(placed).toMatchObject({ x: 490, y: 260, hidden: false });
+ expect(item.anchor).toEqual([0, 0, 0]);
+ });
+});
diff --git a/aetheris.client/src/api/aetherisApi.ts b/aetheris.client/src/api/aetherisApi.ts
index 1583b59e..92da9da1 100644
--- a/aetheris.client/src/api/aetherisApi.ts
+++ b/aetheris.client/src/api/aetherisApi.ts
@@ -63,6 +63,7 @@ export interface StepImportResponseDto {
occurrenceId: string;
name: string | null;
diagnostics: DiagnosticDto[];
+ semanticPresentation?: unknown | null;
}
export type BooleanOperation = "union" | "subtract" | "intersect";
diff --git a/aetheris.client/src/components/SemanticInspector.tsx b/aetheris.client/src/components/SemanticInspector.tsx
index 845c0300..bb4e92c2 100644
--- a/aetheris.client/src/components/SemanticInspector.tsx
+++ b/aetheris.client/src/components/SemanticInspector.tsx
@@ -5,6 +5,7 @@ import type { ReactNode } from "react";
import { PropertyTable, type PropertyRecord } from "./PropertyTable";
import {
indexSemanticInspection,
+ SEMANTIC_PMI_KINDS,
semanticTree,
type SemanticTreeNode,
} from "../viewer/semanticInspection";
@@ -123,8 +124,8 @@ function BrepDetails({
{pmi.length ? pmi.map((item) => item.label).join(", ") : "None"}
</p>
<p className="semantic-provenance">
- Advanced traceability: Aetheris topology IDs are shown above. STEP entity IDs are not yet
- published by this fixture channel.
+ Advanced traceability: Aetheris topology IDs are shown above; imported STEP entity
+ provenance is shown when the importer preserves it.
</p>
</>
);
@@ -199,13 +200,13 @@ export function SemanticInspector({
onSelect: (id: string) => void;
}) {
if (!artifact)
- return <p>Load a real Firmament fixture to inspect compiler-published semantic structure.</p>;
+ return <p>Load a STEP/Firmament model with published semantics to inspect its engineering structure.</p>;
const entity = artifact.entities.find((candidate) => candidate.stableId === selectedId) ?? null;
const details: ReactNode = entity
? (matchKind(
entity.kind.startsWith("BRep")
? { kind: "BRep" as const, entity }
- : entity.kind === "HoleDiameter" || entity.kind === "Datum"
+ : SEMANTIC_PMI_KINDS.has(entity.kind)
? { kind: "Pmi" as const, entity }
: { kind: "Generic" as const, entity },
{
diff --git a/aetheris.client/src/viewer/AetherisViewport.tsx b/aetheris.client/src/viewer/AetherisViewport.tsx
index 46f4a1fe..fce7c083 100644
--- a/aetheris.client/src/viewer/AetherisViewport.tsx
+++ b/aetheris.client/src/viewer/AetherisViewport.tsx
@@ -30,7 +30,7 @@ import { buildAdaptiveGridPlan, type GridBounds } from "./logarithmicGrid";
import { CadmataOverlay, type CadmataLayerVisibility } from "./CadmataOverlay";
import type { CadmataVisualizationArtifact } from "./conceptVisualization";
import { ATELIER_VIEWPORT_THEME, type ViewportTheme } from "./viewportTheme";
-import { PmiAnnotationLayer } from "./PmiAnnotationLayer";
+import { DEFAULT_PMI_VISIBILITY, PmiAnnotationLayer, type PmiVisibility } from "./PmiAnnotationLayer";
import { ThemeBackground } from "./ThemeBackground";
function intersectGround(origin: Vector3, direction: Vector3, y: number): Vector3 | null {
@@ -282,6 +282,7 @@ export interface AetherisViewportProps {
selectedCadmataIds?: Set<string>;
onCadmataSelect?: (stableId: string) => void;
showPmi?: boolean;
+ pmiVisibility?: PmiVisibility;
assemblyPacket?: AssemblyDisplayPacketDto | null;
selectedAssemblyOccurrenceId?: string | null;
onAssemblyOccurrenceSelect?: (stableId: string) => void;
@@ -575,6 +576,7 @@ export function AetherisViewport({
selectedCadmataIds = new Set(),
onCadmataSelect = () => undefined,
showPmi = true,
+ pmiVisibility = DEFAULT_PMI_VISIBILITY,
assemblyPacket = null,
selectedAssemblyOccurrenceId = null,
onAssemblyOccurrenceSelect = () => undefined,
@@ -698,6 +700,7 @@ export function AetherisViewport({
<PmiAnnotationLayer
artifact={cadmataArtifact}
visible={showPmi}
+ visibility={pmiVisibility}
selectedIds={selectedCadmataIds}
onSelect={onCadmataSelect}
theme={theme}
diff --git a/aetheris.client/src/viewer/CadmataOverlay.tsx b/aetheris.client/src/viewer/CadmataOverlay.tsx
index 2a6f90cd..6722daf9 100644
--- a/aetheris.client/src/viewer/CadmataOverlay.tsx
+++ b/aetheris.client/src/viewer/CadmataOverlay.tsx
@@ -8,6 +8,7 @@ import type {
CadmataVisualizationArtifact,
} from "./conceptVisualization";
import type { ViewportTheme } from "./viewportTheme";
+import { SEMANTIC_PMI_KINDS } from "./semanticInspection";
export type CadmataLayerVisibility = Record<CadmataLayer, boolean>;
export const DEFAULT_CADMATA_LAYERS: CadmataLayerVisibility = {
@@ -142,7 +143,7 @@ export function CadmataOverlay({
return (
<group name="CadmataCompilerOverlays">
{artifact.entities
- .filter((entity) => layers[entity.layer])
+ .filter((entity) => layers[entity.layer] && !SEMANTIC_PMI_KINDS.has(entity.kind) && entity.kind !== "EngineeringTarget")
.map((entity) => (
<OverlayEntity
key={entity.stableId}
diff --git a/aetheris.client/src/viewer/PmiAnnotationLayer.tsx b/aetheris.client/src/viewer/PmiAnnotationLayer.tsx
index ce9e7ff7..b2ccb8ec 100644
--- a/aetheris.client/src/viewer/PmiAnnotationLayer.tsx
+++ b/aetheris.client/src/viewer/PmiAnnotationLayer.tsx
@@ -1,79 +1,204 @@
+/* eslint-disable react-refresh/only-export-components -- the presentation contract and its pure deterministic layout helpers are tested together with the rendering adapter. */
import { Html, Line } from "@react-three/drei";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Vector3 } from "three";
import type { CadmataEntity, CadmataVisualizationArtifact } from "./conceptVisualization";
-import { formatPmiLabel } from "./semanticInspection";
+import { formatPmiLabel, SEMANTIC_PMI_KINDS } from "./semanticInspection";
import type { ViewportTheme } from "./viewportTheme";
-function anchor(entity: CadmataEntity): [number, number, number] | null {
+export type PmiCategory = "datums" | "dimensions" | "geometricTolerances" | "engineeringAnnotations";
+export type PmiVisibility = Record<PmiCategory, boolean>;
+export const DEFAULT_PMI_VISIBILITY: PmiVisibility = {
+ datums: true,
+ dimensions: false,
+ geometricTolerances: true,
+ engineeringAnnotations: false,
+};
+
+type Point = [number, number, number];
+type ScreenPoint = { x: number; y: number; z: number };
+type LayoutItem = { entity: CadmataEntity; anchor: Point; width: number; height: number };
+type Placement = { entity: CadmataEntity; anchor: Point; label: Point; hidden: boolean };
+
+function anchor(entity: CadmataEntity): Point | null {
const geometry = entity.geometry;
if (geometry?.type === "circle") return [geometry.center.x, geometry.center.y, geometry.center.z];
if (geometry?.type === "point") return [geometry.point.x, geometry.point.y, geometry.point.z];
if (geometry?.type === "polyline" && geometry.points.length) {
- const p = geometry.points[geometry.points.length - 1];
- return [p.x, p.y, p.z];
+ const point = geometry.points[geometry.points.length - 1];
+ return [point.x, point.y, point.z];
}
return null;
}
+export function pmiCategory(entity: CadmataEntity): PmiCategory | null {
+ if (entity.kind === "Datum") return "datums";
+ if (entity.kind === "Dimension" || entity.kind === "Diameter" || entity.kind === "HoleDiameter") return "dimensions";
+ if (entity.kind === "Position") return "geometricTolerances";
+ if (entity.kind === "Annotation") return "engineeringAnnotations";
+ return null;
+}
+
+function priority(entity: CadmataEntity) {
+ const category = pmiCategory(entity);
+ return category === "datums" ? 0 : category === "geometricTolerances" ? 1 : category === "dimensions" ? 2 : 3;
+}
+
+function estimatedSize(entity: CadmataEntity) {
+ const category = pmiCategory(entity);
+ if (category === "datums") return { width: 86, height: 38 };
+ if (category === "geometricTolerances") return { width: 190, height: 54 };
+ if (category === "engineeringAnnotations") return { width: 230, height: 82 };
+ return { width: 166, height: 48 };
+}
+
+export function semanticPmiItems(artifact: CadmataVisualizationArtifact, visibility: PmiVisibility): LayoutItem[] {
+ return artifact.entities
+ .filter((entity) => SEMANTIC_PMI_KINDS.has(entity.kind))
+ .filter((entity) => {
+ const category = pmiCategory(entity);
+ return category !== null && visibility[category];
+ })
+ .map((entity) => {
+ const resolvedAnchor = anchor(entity);
+ return resolvedAnchor ? { entity, anchor: resolvedAnchor, ...estimatedSize(entity) } : null;
+ })
+ .filter((item): item is LayoutItem => item !== null)
+ .sort((left, right) => priority(left.entity) - priority(right.entity) || left.entity.stableId.localeCompare(right.entity.stableId));
+}
+
+function overlaps(a: { x: number; y: number; width: number; height: number }, b: { x: number; y: number; width: number; height: number }) {
+ return Math.abs(a.x - b.x) < (a.width + b.width) / 2 + 8 && Math.abs(a.y - b.y) < (a.height + b.height) / 2 + 6;
+}
+
+/** Deterministic bounded greedy screen-space placement. */
+export function layoutPmiCallouts(
+ items: readonly (LayoutItem & { screenAnchor: ScreenPoint })[],
+ width: number,
+ height: number,
+ manualOffsets: ReadonlyMap<string, { x: number; y: number }>,
+) {
+ const placed: { x: number; y: number; width: number; height: number }[] = [];
+ return items.map((item, index) => {
+ const manual = manualOffsets.get(item.entity.stableId);
+ const radialCandidates = Array.from({ length: 32 }, (_, attempt) => {
+ const ring = Math.floor(attempt / 8);
+ const angle = ((attempt + index * 3) % 8) * (Math.PI / 4);
+ const radius = 68 + ring * 58;
+ return { x: item.screenAnchor.x + Math.cos(angle) * radius, y: item.screenAnchor.y + Math.sin(angle) * radius };
+ });
+ const gridCandidates = Array.from({ length: 10 }, (_, slot) => ({
+ x: slot % 2 === 0 ? item.width / 2 + 18 : width - item.width / 2 - 18,
+ y: 106 + Math.floor(slot / 2) * Math.max(item.height + 14, 92),
+ }));
+ const candidates = manual
+ ? [{ x: item.screenAnchor.x + manual.x, y: item.screenAnchor.y + manual.y }]
+ : [...radialCandidates, ...gridCandidates];
+ let candidate = candidates.find((point) => {
+ const box = { ...point, width: item.width, height: item.height };
+ return point.x - item.width / 2 >= 8 && point.x + item.width / 2 <= width - 8 && point.y - item.height / 2 >= 56 && point.y + item.height / 2 <= height - 8 && !placed.some((other) => overlaps(box, other));
+ });
+ const hidden = !candidate && priority(item.entity) >= 3 && items.length > 10;
+ candidate ??= candidates[candidates.length - 1];
+ candidate = {
+ x: Math.max(item.width / 2 + 8, Math.min(width - item.width / 2 - 8, candidate.x)),
+ y: Math.max(item.height / 2 + 56, Math.min(height - item.height / 2 - 8, candidate.y)),
+ };
+ if (!hidden) placed.push({ ...candidate, width: item.width, height: item.height });
+ return { ...candidate, hidden };
+ });
+}
+
+function CalloutContent({ entity }: { entity: CadmataEntity }) {
+ if (entity.kind === "Datum") return <><strong className="pmi-callout__datum">{entity.label.replace(/^Datum\s+/i, "")}</strong><span>DATUM</span></>;
+ if (entity.kind === "Position") return <><strong>POSITION · ⌀{String(entity.metadata?.nominal ?? "?")} {String(entity.metadata?.unit ?? "mm")}</strong><small>{String(entity.metadata?.datumRefs ?? "No datum frame")} · {String(entity.metadata?.target ?? "")}</small></>;
+ if (entity.kind === "Annotation") return <><strong>{entity.label}</strong><small>{String(entity.metadata?.text ?? "")}</small></>;
+ return <><strong>{formatPmiLabel(entity)} {String(entity.metadata?.unit ?? "")}</strong><small>{String(entity.metadata?.target ?? "")}</small></>;
+}
+
export function PmiAnnotationLayer({
artifact,
visible,
+ visibility,
selectedIds,
onSelect,
theme,
}: {
artifact: CadmataVisualizationArtifact | null;
visible: boolean;
+ visibility: PmiVisibility;
selectedIds: Set<string>;
onSelect: (id: string) => void;
theme: ViewportTheme;
}) {
+ const { camera, size } = useThree();
+ const items = useMemo(() => artifact ? semanticPmiItems(artifact, visibility) : [], [artifact, visibility]);
+ const [placements, setPlacements] = useState<Placement[]>([]);
+ const [manualOffsets, setManualOffsets] = useState<Map<string, { x: number; y: number }>>(new Map());
+ const drag = useRef<{ id: string; originX: number; originY: number; initial: { x: number; y: number } } | null>(null);
+ const lastSignature = useRef("");
+
+ useEffect(() => {
+ const move = (event: PointerEvent) => {
+ if (!drag.current) return;
+ const current = drag.current;
+ setManualOffsets((previous) => new Map(previous).set(current.id, {
+ x: current.initial.x + event.clientX - current.originX,
+ y: current.initial.y + event.clientY - current.originY,
+ }));
+ };
+ const up = () => { drag.current = null; };
+ window.addEventListener("pointermove", move);
+ window.addEventListener("pointerup", up);
+ return () => { window.removeEventListener("pointermove", move); window.removeEventListener("pointerup", up); };
+ }, []);
+
+ useFrame(() => {
+ if (!visible || items.length === 0) return;
+ camera.updateMatrixWorld(false);
+ const signature = `${size.width}:${size.height}:${camera.matrixWorld.elements.map((value) => value.toFixed(4)).join(",")}:${camera.projectionMatrix.elements.map((value) => value.toFixed(4)).join(",")}:${items.map((item) => item.entity.stableId).join("|")}:${JSON.stringify([...manualOffsets])}`;
+ if (signature === lastSignature.current) return;
+ lastSignature.current = signature;
+ const projected = items.map((item) => {
+ const screen = new Vector3(...item.anchor).project(camera);
+ return { ...item, screenAnchor: { x: (screen.x + 1) * size.width / 2, y: (1 - screen.y) * size.height / 2, z: screen.z } };
+ });
+ const layout = layoutPmiCallouts(projected, size.width, size.height, manualOffsets);
+ setPlacements(projected.map((item, index) => {
+ const screen = layout[index];
+ const world = new Vector3(screen.x / size.width * 2 - 1, 1 - screen.y / size.height * 2, item.screenAnchor.z).unproject(camera);
+ return { entity: item.entity, anchor: item.anchor, label: [world.x, world.y, world.z], hidden: screen.hidden };
+ }));
+ });
+
if (!visible || !artifact) return null;
- return (
- <group name="semantic-pmi-annotations">
- {artifact.entities
- .filter((entity) => entity.kind === "HoleDiameter" || entity.kind === "Datum")
- .map((entity) => {
- const target = anchor(entity);
- if (!target) return null;
- const isDatum = entity.kind === "Datum";
- const selected = selectedIds.has(entity.stableId);
- const offset: [number, number, number] = [
- target[0] + (isDatum ? -12 : 12),
- target[1] + 2.4,
- target[2] + 0.2,
- ];
- const color = selected
- ? theme.annotation.selected
- : isDatum
- ? theme.annotation.datum
- : theme.annotation.dimension;
- return (
- <group key={entity.stableId}>
- <Line
- points={[target, offset]}
- color={theme.annotation.leader}
- lineWidth={selected ? 2.5 : 1.3}
- />
- <Html position={offset} center style={{ pointerEvents: "auto" }}>
- <button
- className="pmi-callout"
- type="button"
- onClick={(event) => {
- event.stopPropagation();
- onSelect(entity.stableId);
- }}
- style={{ color, background: theme.annotation.background, borderColor: color }}
- aria-label={`Inspect ${entity.label}`}
- >
- <span>{isDatum ? `DATUM ${entity.label}` : formatPmiLabel(entity)}</span>
- {!isDatum && entity.metadata?.datumRefs ? (
- <small>{String(entity.metadata.datumRefs)}</small>
- ) : null}
- </button>
- </Html>
- </group>
- );
- })}
- </group>
- );
+ return <group name="semantic-pmi-annotations">
+ {placements.filter((placement) => !placement.hidden).map(({ entity, anchor: target, label }) => {
+ const category = pmiCategory(entity)!;
+ const selected = selectedIds.has(entity.stableId);
+ const color = selected ? theme.annotation.selected : category === "datums" ? theme.annotation.datum : category === "dimensions" ? theme.annotation.dimension : theme.annotation.text;
+ const wholePart = !(entity.topology?.faceIds?.length);
+ return <group key={entity.stableId}>
+ <Line points={[target, label]} color={theme.annotation.leader} lineWidth={selected ? 2.5 : 1.2} depthTest={false} />
+ <Html position={label} center style={{ pointerEvents: "auto" }} zIndexRange={selected ? [90, 80] : [60, 10]}>
+ <button
+ className={`pmi-callout pmi-callout--${category}${wholePart ? " pmi-callout--global" : ""}${selected ? " is-selected" : ""}`}
+ type="button"
+ onPointerDown={(event) => {
+ event.stopPropagation();
+ const initial = manualOffsets.get(entity.stableId) ?? { x: 0, y: 0 };
+ drag.current = { id: entity.stableId, originX: event.clientX, originY: event.clientY, initial };
+ }}
+ onClick={(event) => { event.stopPropagation(); onSelect(entity.stableId); }}
+ style={{ color, background: theme.annotation.background, borderColor: color }}
+ aria-label={`Inspect ${entity.label}`}
+ title="Select; drag to adjust presentation only"
+ >
+ <CalloutContent entity={entity} />
+ </button>
+ </Html>
+ </group>;
+ })}
+ </group>;
}
diff --git a/aetheris.client/src/viewer/conceptVisualization.ts b/aetheris.client/src/viewer/conceptVisualization.ts
index 749d180b..0f1e828c 100644
--- a/aetheris.client/src/viewer/conceptVisualization.ts
+++ b/aetheris.client/src/viewer/conceptVisualization.ts
@@ -173,6 +173,7 @@ export function resolveCadmataSelection(
...(entity.childIds ?? []),
...(entity.constructionDescendantIds ?? []),
...(entity.materializedDescendantIds ?? []),
+ ...(entity.selectionIds ?? []),
...(ownedChildren.get(id) ?? []),
);
}
diff --git a/aetheris.client/src/viewer/semanticInspection.ts b/aetheris.client/src/viewer/semanticInspection.ts
index b02fe6c5..23706523 100644
--- a/aetheris.client/src/viewer/semanticInspection.ts
+++ b/aetheris.client/src/viewer/semanticInspection.ts
@@ -12,10 +12,23 @@ const KIND_ORDER = [
"SlotFeature",
"ConstructionPlane",
"Datum",
+ "Dimension",
+ "Diameter",
+ "Position",
+ "Annotation",
"HoleDiameter",
"PMI",
];
+export const SEMANTIC_PMI_KINDS = new Set([
+ "Datum",
+ "Dimension",
+ "Diameter",
+ "Position",
+ "Annotation",
+ "HoleDiameter",
+]);
+
/** Document-scoped index: all correspondence is published by Aetheris; no ownership is inferred here. */
export function indexSemanticInspection(artifact: CadmataVisualizationArtifact) {
const byId = new Map(artifact.entities.map((entity) => [entity.stableId, entity]));
@@ -49,7 +62,7 @@ export function indexSemanticInspection(artifact: CadmataVisualizationArtifact)
edgeOwners.set(edgeId, owners);
}
const target = entity.metadata?.targetSemanticId;
- if ((entity.kind === "Datum" || entity.kind === "HoleDiameter") && typeof target === "string")
+ if (SEMANTIC_PMI_KINDS.has(entity.kind) && typeof target === "string")
(pmiByTarget.get(target) ?? pmiByTarget.set(target, []).get(target)!).push(entity);
}
const brepFaceById = new Map(
@@ -106,5 +119,11 @@ export function formatPmiLabel(entity: CadmataEntity) {
const plus = entity.metadata?.tolerancePlus;
const minus = entity.metadata?.toleranceMinus;
const tolerance = plus || minus ? ` +${plus ?? "0"}/-${minus ?? "0"}` : "";
- return entity.kind === "HoleDiameter" ? `⌀${value}${tolerance}` : entity.label;
+ const quantity = Number(entity.metadata?.quantity ?? 0);
+ const prefix = quantity > 1 ? `${quantity}× ` : "";
+ return entity.kind === "HoleDiameter" || entity.kind === "Diameter"
+ ? `${prefix}⌀${value}${tolerance}`
+ : entity.kind === "Dimension"
+ ? `${prefix}${entity.label}: ${value}${tolerance}`
+ : entity.label;
}
diff --git a/aetheris.client/vite.config.ts b/aetheris.client/vite.config.ts
index 60a0dac2..aca63307 100644
--- a/aetheris.client/vite.config.ts
+++ b/aetheris.client/vite.config.ts
@@ -78,7 +78,10 @@ export default defineConfig(({ command }) => ({
},
port: 5173,
strictPort: true,
- https: ensureCertificates(),
+ // The packaged app remains HTTPS by default. Browser-driven localhost
+ // validation may opt into HTTP when the automation surface cannot trust
+ // the developer certificate.
+ https: env.AETHERIS_VITE_HTTP === "1" ? undefined : ensureCertificates(),
}
: undefined,
}));
diff --git a/docs/cadmata/artifacts/pmi-x1/README.md b/docs/cadmata/artifacts/pmi-x1/README.md
new file mode 100644
index 00000000..77a81d58
--- /dev/null
+++ b/docs/cadmata/artifacts/pmi-x1/README.md
@@ -0,0 +1,112 @@
+# CADMATA-PMI-X1 — semantic 3D PMI and annotation presentation
+
+## Result
+
+X1 establishes the real AP242-to-Cadmata semantic presentation path for the CTC-03 production subset. Semantic PMI and notes are imported with stable STEP-derived identity, structured engineering fields, target identities, and actual BRep face associations. Three.js receives a presentation adapter, not a duplicate engineering model.
+
+The default view intentionally shows datums and GD&T controls. Dimensions and notes remain one-click category layers so the initial document is legible instead of displaying all 29 requirements at once.
+
+## Architecture
+
+```text
+Firmament-authored semantic PMI
+ -> STEP AP242 product-definition entities
+ -> Step242SemanticPmiInspector
+ -> CadmataStepSemanticBridge
+ stable semantic entity identity
+ structured payload and provenance
+ STEP ADVANCED_FACE -> Aetheris FaceId association
+ -> semantic target / PMI / BRep entities in the Cadmata application model
+ -> face-derived target anchor
+ -> deterministic camera-facing callout + leader presentation
+ -> existing selection, picking, highlighting, and inspector paths
+```
+
+`FaceGeometryBinding.SourceStepEntityId` preserves imported `ADVANCED_FACE` provenance. The bridge resolves `GEOMETRIC_ITEM_SPECIFIC_USAGE` references through that explicit mapping; it never assumes that STEP entity order equals Aetheris topology order.
+
+Callout screen position, collision displacement, camera-facing orientation, visibility, and user drag offset exist only in the client presentation adapter. Moving or orbiting a callout does not change its target, value, tolerance, datum frame, provenance, or face association.
+
+Anchors are derived from associated face boundary vertices. Product-level requirements use the body-bounds center and are visually distinguished with dashed panels. Imported graphical placement/orientation is neither read nor treated as authority.
+
+## Supported entity matrix
+
+| Semantic entity | 3D presentation | Feature association | Selectable | Target highlight | Filterable |
+| --- | --- | --- | --- | --- | --- |
+| Datum | Camera-facing datum badge + leader | Datum target and associated faces | Yes | Datum feature face | Datums |
+| Linear/thickness dimension | Structured name/value/tolerance panel | Target and associated faces where AP242 supplies them | Yes | Associated faces | Dimensions |
+| Diameter | Quantity-aware diameter panel | Pattern/feature and cylindrical faces | Yes | All associated pattern faces | Dimensions |
+| Position control | Position/value panel with ordered datum frame | Controlled target plus referenced datum targets | Yes | Controlled faces and A\|B\|C features | GD&T |
+| Engineering annotation | Local/global note panel + leader | Target and faces for local notes | Yes | Associated local faces | Notes |
+| Repeated-feature requirement | One quantity-bearing semantic callout | Preserves one requirement over all associated faces | Yes | Whole associated pattern | Parent category |
+
+## CTC-03 inventory
+
+Inventory comes from the ordinary STEP import endpoint and is asserted by `KernelApiIntegrationTests.StepImport_Ctc03PublishesStructuredSemanticPmiWithRealFaceAssociations`.
+
+| Class | Loaded | Presented |
+| --- | ---: | ---: |
+| Datums | 3 | 3 |
+| Toleranced dimensions/diameters | 13 | 13 |
+| Position / GD&T controls | 5 | 5 |
+| Engineering annotations | 8 | 8 |
+| Quantity-bearing repeated-feature PMI objects | 11 | 11 |
+
+The imported document publishes 44 engineering objects/targets (29 PMI/annotation entities plus 15 target entities) and 129 BRep face entities in one inspectable Cadmata artifact. The complete application artifact contains 173 stable entities.
+
+## Dogfood evidence
+
+### Clean default presentation
+
+Datums and inspection controls are visible by default; dimensions and notes remain independently available.
+
+![Clean default CTC-03 PMI presentation](default-presentation.png)
+
+### Datum interaction
+
+Selecting datum A highlights the associated MainDeck support face and exposes stable identity, STEP provenance, target, and Aetheris face ID.
+
+![Datum A selected with referenced geometry highlighted](datum-a-selected.png)
+
+### GD&T interaction
+
+Selecting `FrontMountPosition` exposes position `0.8 mm`, quantity `2`, controlled target `FrontMountHoles`, and ordered datum frame `A | B | C`. Its controlled faces and referenced datum features are selected through published relationships.
+
+![Front mounting position control selected](front-mount-position-selected.png)
+
+### Engineering annotations
+
+The Notes filter shows all eight semantic notes. Local notes retain feature leaders; whole-part notes use a distinct dashed presentation.
+
+![All CTC-03 engineering notes in the filtered presentation](engineering-notes-filtered.png)
+
+### Orbit, zoom, and dimension filtering
+
+After orbit and zoom, dimension panels remain camera-facing, leaders remain attached to semantic anchors, and the deterministic greedy layout recomputes in screen space.
+
+![Dimension-only presentation after orbit and zoom](dimensions-orbit-zoom.png)
+
+Additional browser dogfood verified:
+
+- clicking `ProtectDatumA` highlighted Face 1 and exposed its full text and STEP `#4088` provenance;
+- clicking model Face 1 surfaced owners MainDeck, Datum A, DeckWidth, DeckLength, and ProtectDatumA plus STEP face `#182` provenance;
+- dragging DeckWidth changed its screen rectangle while its inspected target remained `MainDeck` byte-for-byte unchanged;
+- all eight notes and all thirteen dimensions were present in their filtered views;
+- the default and post-orbit layouts retained camera-readable text and deterministic ordering.
+
+## Remaining limitations
+
+- X1 supports the production subset: datum, dimension/diameter, position, quantity, and semantic note. Composite frames, modifiers, profile, flatness, projected zones, and other AP242 PMI constructs remain unsupported.
+- Face-derived anchors use associated-boundary centroids. Future feature/pattern centroid and measurement-endpoint resolvers can improve leader intent without changing semantic entities.
+- The bounded greedy layout is viewport-local, not a global drafting optimizer. Dense all-category views may de-emphasize low-priority notes; the intended X1 workflow uses category filters.
+- Drag offsets are volatile per viewer session. They are explicitly presentation state but are not yet persisted in a reusable presentation-hints document.
+- Callout panels use modern readable HTML rather than complete ISO/ASME glyph typography. Structured semantic data remains available independently of those glyphs.
+- Geometry-to-PMI discovery currently appears in the semantic inspector; a dedicated contextual action menu and LLM command surface are future presentation conveniences over the same application entities.
+- Anchors and callouts are not yet lowered into Drawing IR. The bridge is independent of Three.js so drawing projection can consume the same semantic objects later.
+
+## Validation
+
+- `dotnet run --project Aetheris.CLI -- analyze .../ctc03-manufacturing-ap242.step --json`: 129 faces, enclosed manifold, semantic counts 3/13/5/8, zero semantic diagnostics.
+- Server integration tests exercise the real import endpoint, face provenance, target associations, datum references, and inventory.
+- Client tests exercise semantic category filtering, deterministic collision placement, and presentation-only manual offsets.
+- Browser dogfood used the actual CTC-03 manufacturing STEP through the startup/import path, not a fixture-specific mapping.
+- Full solution validation: zero build warnings/errors; 2,943 .NET tests passed serially (the FrictionLab assembly has no discoverable tests); 81 client tests, lint, and production build passed.
diff --git a/docs/cadmata/artifacts/pmi-x1/datum-a-selected.png b/docs/cadmata/artifacts/pmi-x1/datum-a-selected.png
new file mode 100644
index 00000000..c3a91684
Binary files /dev/null and b/docs/cadmata/artifacts/pmi-x1/datum-a-selected.png differ
diff --git a/docs/cadmata/artifacts/pmi-x1/default-presentation.png b/docs/cadmata/artifacts/pmi-x1/default-presentation.png
new file mode 100644
index 00000000..d80b1316
Binary files /dev/null and b/docs/cadmata/artifacts/pmi-x1/default-presentation.png differ
diff --git a/docs/cadmata/artifacts/pmi-x1/dimensions-orbit-zoom.png b/docs/cadmata/artifacts/pmi-x1/dimensions-orbit-zoom.png
new file mode 100644
index 00000000..057f3e9b
Binary files /dev/null and b/docs/cadmata/artifacts/pmi-x1/dimensions-orbit-zoom.png differ
diff --git a/docs/cadmata/artifacts/pmi-x1/engineering-notes-filtered.png b/docs/cadmata/artifacts/pmi-x1/engineering-notes-filtered.png
new file mode 100644
index 00000000..3b93fe0c
Binary files /dev/null and b/docs/cadmata/artifacts/pmi-x1/engineering-notes-filtered.png differ
diff --git a/docs/cadmata/artifacts/pmi-x1/front-mount-position-selected.png b/docs/cadmata/artifacts/pmi-x1/front-mount-position-selected.png
new file mode 100644
index 00000000..f71d806f
Binary files /dev/null and b/docs/cadmata/artifacts/pmi-x1/front-mount-position-selected.png differ
diff --git a/docs/cadmata/concept-visualization-x1.md b/docs/cadmata/concept-visualization-x1.md
index 8d6f6725..647b5028 100644
--- a/docs/cadmata/concept-visualization-x1.md
+++ b/docs/cadmata/concept-visualization-x1.md
@@ -106,3 +106,7 @@ the shaft envelope, shaft-to-DrillPoint circle, analytic cone envelope, and
Tip marker come from `LocalFrameHoleBRepPlan`/`ConeSurface` metadata. Selecting
the DrillPoint entity follows only its cone-face and Tip descendants; Cadmata
does not infer a cone from display tessellation.
+
+# Follow-on semantic PMI presentation
+
+The [CADMATA-PMI-X1 report](artifacts/pmi-x1/README.md) extends this application model to imported AP242 datums, dimensions, GD&T, repeated-feature requirements, and engineering annotations without making rendered callouts authoritative.