Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Clarify tessellate endpoint contract

Yuechen Liabc73c56a86c
diff --git a/Aetheris.Server.Tests/KernelApiIntegrationTests.cs b/Aetheris.Server.Tests/KernelApiIntegrationTests.cs
index 122fe414..94b96037 100644
--- a/Aetheris.Server.Tests/KernelApiIntegrationTests.cs
+++ b/Aetheris.Server.Tests/KernelApiIntegrationTests.cs
@@ -316,7 +316,11 @@ public sealed class KernelApiIntegrationTests : IClassFixture<WebApplicationFact
var tessellationResponse = await _client.PostAsJsonAsync(
$"/api/v1/documents/{document.Data.DocumentId}/bodies/{imported.Data.OccurrenceId}/tessellate",
new TessellateRequestDto(null));
- tessellationResponse.EnsureSuccessStatusCode();
+ if (!tessellationResponse.IsSuccessStatusCode)
+ {
+ var errorBody = await tessellationResponse.Content.ReadAsStringAsync();
+ throw new Xunit.Sdk.XunitException($"tessellate failed {(int)tessellationResponse.StatusCode}: {errorBody}");
+ }
var tessellation = await tessellationResponse.Content.ReadFromJsonAsync<ApiResponseDto<TessellationResponseDto>>();
Assert.NotNull(tessellation);
Assert.True(tessellation!.Success);
@@ -613,13 +617,52 @@ public sealed class KernelApiIntegrationTests : IClassFixture<WebApplicationFact
var tessellationResponse = await _client.PostAsJsonAsync(
$"/api/v1/documents/{document.Data.DocumentId}/bodies/{imported.Data.OccurrenceId}/tessellate",
new TessellateRequestDto(null));
- tessellationResponse.EnsureSuccessStatusCode();
+ await AssertTessellationEndpointContractAsync(tessellationResponse);
+ }
- var tessellation = await tessellationResponse.Content.ReadFromJsonAsync<ApiResponseDto<TessellationResponseDto>>();
- Assert.NotNull(tessellation);
- Assert.True(tessellation!.Success);
- Assert.NotEmpty(tessellation.Data!.FacePatches);
- Assert.NotEmpty(tessellation.Data.EdgePolylines);
+ [Fact]
+ public async Task StepIo_ExportImportRoundTrip_TessellationEndpointContract_IsExplicit()
+ {
+ var (documentId, importedOccurrenceId) = await CreateImportedRoundTripBoxOccurrenceAsync();
+
+ var tessellationResponse = await _client.PostAsJsonAsync(
+ $"/api/v1/documents/{documentId}/bodies/{importedOccurrenceId}/tessellate",
+ new TessellateRequestDto(null));
+ await AssertTessellationEndpointContractAsync(tessellationResponse);
+ }
+
+ [Fact]
+ public async Task StepIo_ExportImportRoundTrip_DisplayPrepareStillReturnsDisplayIR()
+ {
+ var (documentId, importedOccurrenceId) = await CreateImportedRoundTripBoxOccurrenceAsync();
+
+ var prepared = await PrepareDisplayAsync(documentId, importedOccurrenceId);
+
+ Assert.NotNull(prepared.Data);
+ Assert.Equal("BRep", prepared.Data!.SourceAuthority);
+ Assert.Equal("DisplayIR", prepared.Data.DisplayAuthority);
+ Assert.NotNull(prepared.Data.Faces);
+ Assert.NotEmpty(prepared.Data.Faces!);
+ Assert.Contains(prepared.Data.Faces, face => face.PatchKind is "AnalyticPatch" or "MeshPatch" or "WirePatch" or "DiagnosticPatch");
+ }
+
+ [Fact]
+ public async Task TessellateEndpoint_DoesNotMasqueradeAsDisplayAuthority()
+ {
+ var (documentId, importedOccurrenceId) = await CreateImportedRoundTripBoxOccurrenceAsync();
+
+ var tessellationResponse = await _client.PostAsJsonAsync(
+ $"/api/v1/documents/{documentId}/bodies/{importedOccurrenceId}/tessellate",
+ new TessellateRequestDto(null));
+ var tessellationJson = await tessellationResponse.Content.ReadAsStringAsync();
+ using var tessellationDocument = JsonDocument.Parse(tessellationJson);
+ Assert.False(tessellationDocument.RootElement.TryGetProperty("displayAuthority", out _));
+ Assert.False(tessellationDocument.RootElement.TryGetProperty("data", out var tessellationData)
+ && tessellationData.ValueKind == JsonValueKind.Object
+ && tessellationData.TryGetProperty("displayAuthority", out _));
+
+ var prepared = await PrepareDisplayAsync(documentId, importedOccurrenceId);
+ Assert.Equal("DisplayIR", prepared.Data!.DisplayAuthority);
}
@@ -771,6 +814,55 @@ public sealed class KernelApiIntegrationTests : IClassFixture<WebApplicationFact
return body!;
}
+ private static async Task AssertTessellationEndpointContractAsync(HttpResponseMessage tessellationResponse)
+ {
+ if (!tessellationResponse.IsSuccessStatusCode)
+ {
+ Assert.Equal(HttpStatusCode.UnprocessableEntity, tessellationResponse.StatusCode);
+ var error = await tessellationResponse.Content.ReadFromJsonAsync<ApiResponseDto<object>>();
+ Assert.NotNull(error);
+ Assert.False(error!.Success);
+ Assert.NotEmpty(error.Diagnostics);
+ Assert.Contains(error.Diagnostics, diagnostic =>
+ diagnostic.Code is "ValidationFailed"
+ && diagnostic.Source is "Viewer.Tessellation.Timeout"
+ && diagnostic.Message.Contains("bounded execution budget", StringComparison.OrdinalIgnoreCase));
+ return;
+ }
+
+ var tessellation = await tessellationResponse.Content.ReadFromJsonAsync<ApiResponseDto<TessellationResponseDto>>();
+ Assert.NotNull(tessellation);
+ Assert.True(tessellation!.Success);
+ Assert.NotNull(tessellation.Data);
+ Assert.NotEmpty(tessellation.Data!.FacePatches);
+ Assert.NotEmpty(tessellation.Data.EdgePolylines);
+ Assert.Empty(tessellation.Diagnostics);
+ }
+
+ private async Task<(Guid DocumentId, Guid ImportedOccurrenceId)> CreateImportedRoundTripBoxOccurrenceAsync()
+ {
+ var document = await CreateDocumentAsync("/api/v1/documents");
+ var box = await CreateBoxAsync("/api/v1/documents", document.Data!.DocumentId, 2, 2, 2);
+
+ var exportResponse = await _client.GetAsync($"/api/v1/documents/{document.Data.DocumentId}/definitions/{box.Data!.DefinitionId}/export/step");
+ exportResponse.EnsureSuccessStatusCode();
+ var exported = await exportResponse.Content.ReadFromJsonAsync<ApiResponseDto<StepExportResponseDto>>();
+ Assert.NotNull(exported);
+ Assert.True(exported!.Success);
+ Assert.NotNull(exported.Data);
+
+ var importResponse = await _client.PostAsJsonAsync(
+ $"/api/v1/documents/{document.Data.DocumentId}/import/step",
+ new StepImportRequestDto(exported.Data!.StepText, "Imported Box"));
+ importResponse.EnsureSuccessStatusCode();
+ var imported = await importResponse.Content.ReadFromJsonAsync<ApiResponseDto<StepImportResponseDto>>();
+ Assert.NotNull(imported);
+ Assert.True(imported!.Success);
+ Assert.NotNull(imported.Data);
+
+ return (document.Data.DocumentId, imported.Data!.OccurrenceId);
+ }
+
private async Task<ApiResponseDto<DisplayPreparationResponseDto>> PrepareDisplayAsync(Guid documentId, Guid bodyId)
{
var response = await _client.PostAsJsonAsync(
diff --git a/aetheris.client/src/App.tsx b/aetheris.client/src/App.tsx
index 0741ae1d..0dff67e2 100644
--- a/aetheris.client/src/App.tsx
+++ b/aetheris.client/src/App.tsx
@@ -20,7 +20,7 @@ import {
} from './api/aetherisApi';
import { StepImportDropzone } from './components/StepImportDropzone';
import { Button } from './components/ui/button';
-import { ViewerViewport } from './viewer/ViewerViewport';
+import { AetherisViewport } from './viewer/AetherisViewport';
import { buildDisplaySceneData } from './viewer/displaySceneBuilder';
import { STEP_UPLOAD_LIMIT_BYTES, STEP_UPLOAD_LIMIT_MB, formatMegabytes } from './config/stepUpload';
@@ -388,10 +388,11 @@ function App() {
setPickHits([]);
setCopyHashMessage('');
});
- if (didImport && displayError) {
+ const importDisplayError = displayError as ApiError | null;
+ if (didImport && importDisplayError) {
setStatus('error');
- setStatusMessage(`View materialization failed after import: ${displayError.message}`);
- setDiagnostics(displayError.diagnostics);
+ setStatusMessage(`View materialization failed after import: ${importDisplayError.message}`);
+ setDiagnostics(importDisplayError.diagnostics);
setImportStatus('success');
setImportStatusMessage('Import complete. View materialization failed.');
} else {
@@ -599,7 +600,8 @@ function App() {
COORD
</button>
</div>
- <ViewerViewport
+ <AetherisViewport
+ displayScene={displayScene.displayScene}
sceneData={sceneData}
highlightedFaceId={highlightedFaceId}
highlightedEdgeId={highlightedEdgeId}
diff --git a/aetheris.client/src/__tests__/AetherisViewport.test.tsx b/aetheris.client/src/__tests__/AetherisViewport.test.tsx
new file mode 100644
index 00000000..2fe5c7cf
--- /dev/null
+++ b/aetheris.client/src/__tests__/AetherisViewport.test.tsx
@@ -0,0 +1,55 @@
+import { render } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { AetherisViewport } from '../viewer/AetherisViewport';
+import type { DisplayScene } from '../viewer/displayRenderables';
+
+vi.mock('@react-three/fiber', () => ({
+ Canvas: ({ children }: { children: React.ReactNode }) => <div data-testid="canvas">{children}</div>,
+ useFrame: () => undefined,
+ useThree: () => ({ camera: { position: { x: 0, z: 0 }, zoom: 1 }, gl: { domElement: { addEventListener: vi.fn(), removeEventListener: vi.fn() } } }),
+}));
+
+vi.mock('@react-three/drei', () => ({
+ Line: ({ points }: { points: unknown }) => <div data-testid="line" data-points={JSON.stringify(points)} />,
+ OrbitControls: () => <div data-testid="orbit" />,
+ Text: ({ children }: { children: React.ReactNode }) => <span>{children}</span>,
+}));
+
+vi.mock('three', async () => {
+ const actual = await vi.importActual<typeof import('three')>('three');
+ return {
+ ...actual,
+ BufferGeometry: class { setAttribute() { return this; } setIndex() { return this; } computeBoundingSphere() { return this; } },
+ MeshStandardMaterial: class {},
+ };
+});
+
+const baseScene: DisplayScene = { renderables: [], sourceAuthority: 'BRep', displayAuthority: 'DisplayIR', displayLanes: [], displayStatus: 'Complete' };
+
+describe('AetherisViewport', () => {
+ it('RendersMeshPatch', () => {
+ const scene: DisplayScene = {
+ ...baseScene,
+ renderables: [{ kind: 'MeshPatch', faceId: 1, surfaceKind: 'Plane', status: 'Mesh', patchKind: 'MeshPatch', materializationLane: 'BoundedMesh', diagnostics: [], mesh: { faceId: 1, positions: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]), normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]), indices: new Uint32Array([0, 1, 2]) } }],
+ };
+ expect(() => render(<AetherisViewport displayScene={scene} sceneData={null} showGrid={false} showAxisGuide={false} />)).not.toThrow();
+ });
+
+ it('RendersWirePatchWithoutMeshArrays', () => {
+ const scene: DisplayScene = {
+ ...baseScene,
+ renderables: [{ kind: 'WirePatch', faceId: 2, surfaceKind: 'Plane', status: 'WireframeOnly', patchKind: 'WirePatch', materializationLane: 'WirePatch', diagnostics: [], wires: [{ edgeId: 20, points: new Float32Array([0, 0, 0, 1, 0, 0]) }] }],
+ };
+ const { getAllByTestId } = render(<AetherisViewport displayScene={scene} sceneData={null} showGrid={false} showAxisGuide={false} />);
+ expect(getAllByTestId('line').length).toBeGreaterThan(0);
+ });
+
+ it('AcceptsDiagnosticOnlyFace', () => {
+ const scene: DisplayScene = {
+ ...baseScene,
+ displayStatus: 'Partial',
+ renderables: [{ kind: 'DiagnosticPatch', faceId: 3, surfaceKind: 'Plane', status: 'DiagnosticOnly', patchKind: 'DiagnosticPatch', materializationLane: 'DiagnosticOnly', diagnostics: [{ code: 'Viewer.Tessellation.Timeout', message: 'timeout', faceId: 3, surfaceKind: 'Plane', phase: 'test', suggestedNextAction: null }] }],
+ };
+ expect(() => render(<AetherisViewport displayScene={scene} sceneData={null} showGrid={false} showAxisGuide={false} />)).not.toThrow();
+ });
+});
diff --git a/aetheris.client/src/__tests__/App.test.tsx b/aetheris.client/src/__tests__/App.test.tsx
index de1b4a30..ab202652 100644
--- a/aetheris.client/src/__tests__/App.test.tsx
+++ b/aetheris.client/src/__tests__/App.test.tsx
@@ -35,8 +35,8 @@ vi.mock('../api/aetherisApi', async () => {
};
});
-vi.mock('../viewer/ViewerViewport', () => ({
- ViewerViewport: () => <div data-testid="viewer-viewport" />,
+vi.mock('../viewer/AetherisViewport', () => ({
+ AetherisViewport: () => <div data-testid="viewer-viewport" />,
}));
function setupDocumentApiMocks(): void {
diff --git a/aetheris.client/src/__tests__/displayRenderables.test.ts b/aetheris.client/src/__tests__/displayRenderables.test.ts
new file mode 100644
index 00000000..1bfd449f
--- /dev/null
+++ b/aetheris.client/src/__tests__/displayRenderables.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import type { DisplayPreparationResponseDto } from '../api/aetherisApi';
+import { mapDisplayFaceToRenderable, mapDisplayPreparationToDisplayScene } from '../viewer/displayRenderables';
+
+const diagnostic = { code: 'Viewer.Test', message: 'test', faceId: 4, surfaceKind: 'Plane', phase: 'test', suggestedNextAction: null };
+
+function prepWithFaces(faces: DisplayPreparationResponseDto['faces']): DisplayPreparationResponseDto {
+ return {
+ lane: 'fallback-only',
+ analyticPacket: { bodyId: 1, analyticFaces: [], fallbackFaces: [] },
+ tessellationFallback: null,
+ status: 'Partial',
+ sourceAuthority: 'BRep',
+ displayAuthority: 'DisplayIR',
+ lanes: ['AnalyticPatch', 'BoundedMesh', 'WirePatch', 'DiagnosticOnly'],
+ displayLanes: [],
+ diagnostics: [],
+ faces,
+ };
+}
+
+describe('DisplayIRMapper', () => {
+ it('DoesNotFlattenDiagnosticsIntoMesh', () => {
+ const renderable = mapDisplayFaceToRenderable({
+ faceId: 4,
+ shellId: 1,
+ surfaceKind: 'Plane',
+ status: 'DiagnosticOnly',
+ patchKind: 'DiagnosticPatch',
+ meshPatch: null,
+ analyticPatch: null,
+ wirePatch: null,
+ materializationLane: 'DiagnosticOnly',
+ diagnostics: [diagnostic],
+ });
+
+ expect(renderable.kind).toBe('DiagnosticPatch');
+ expect('mesh' in renderable).toBe(false);
+ expect(renderable.diagnostics).toEqual([diagnostic]);
+ });
+
+ it('PreservesMaterializationLane', () => {
+ const scene = mapDisplayPreparationToDisplayScene(prepWithFaces([
+ {
+ faceId: 1, shellId: 1, surfaceKind: 'Plane', status: 'Analytic', patchKind: 'AnalyticPatch', materializationLane: 'AnalyticPatch', diagnostics: [], meshPatch: null, wirePatch: null,
+ analyticPatch: { faceId: 1, shellId: 1, shellRole: 'Outer', surfaceGeometryId: 1, surfaceKind: 'Plane', loopCount: 1, domainHint: null, cylinderGeometry: null, coneGeometry: null, sphereGeometry: null, torusGeometry: null, planeGeometry: { origin: { x: 0, y: 0, z: 0 }, normal: { x: 0, y: 0, z: 1 }, uAxis: { x: 1, y: 0, z: 0 }, vAxis: { x: 0, y: 1, z: 0 }, outerBoundary: [{ x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 }, { x: 0, y: 1, z: 0 }] } },
+ },
+ {
+ faceId: 2, shellId: 1, surfaceKind: 'Plane', status: 'Mesh', patchKind: 'MeshPatch', materializationLane: 'BoundedMesh', diagnostics: [], analyticPatch: null, wirePatch: null,
+ meshPatch: { faceId: 2, positions: [{ x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 }, { x: 0, y: 1, z: 0 }], normals: [{ x: 0, y: 0, z: 1 }, { x: 0, y: 0, z: 1 }, { x: 0, y: 0, z: 1 }], triangleIndices: [0, 1, 2] },
+ },
+ {
+ faceId: 3, shellId: 1, surfaceKind: 'Plane', status: 'WireframeOnly', patchKind: 'WirePatch', materializationLane: 'WirePatch', diagnostics: [], meshPatch: null, analyticPatch: null,
+ wirePatch: { kind: 'WirePatch', source: 'BRepEdges', quality: 'PreviewPolyline', loops: [{ loopId: 1, role: 'Outer', edges: [{ edgeId: 30, points: [{ x: 0, y: 0, z: 0 }, { x: 1, y: 0, z: 0 }], sourceCurveKind: 'Line3', sampleCount: 2, diagnostics: [] }] }] },
+ },
+ { faceId: 4, shellId: 1, surfaceKind: 'Plane', status: 'DiagnosticOnly', patchKind: 'DiagnosticPatch', materializationLane: 'DiagnosticOnly', diagnostics: [diagnostic], meshPatch: null, analyticPatch: null, wirePatch: null },
+ ]));
+
+ expect(scene?.renderables.map((r) => [r.kind, r.materializationLane])).toEqual([
+ ['AnalyticPatch', 'AnalyticPatch'],
+ ['MeshPatch', 'BoundedMesh'],
+ ['WirePatch', 'WirePatch'],
+ ['DiagnosticPatch', 'DiagnosticOnly'],
+ ]);
+ expect(scene?.sourceAuthority).toBe('BRep');
+ expect(scene?.displayAuthority).toBe('DisplayIR');
+ });
+});
diff --git a/aetheris.client/src/viewer/ViewerViewport.tsx b/aetheris.client/src/viewer/AetherisViewport.tsx
similarity index 93%
rename from aetheris.client/src/viewer/ViewerViewport.tsx
rename to aetheris.client/src/viewer/AetherisViewport.tsx
index 62d43dbd..a0b109c2 100644
--- a/aetheris.client/src/viewer/ViewerViewport.tsx
+++ b/aetheris.client/src/viewer/AetherisViewport.tsx
@@ -4,6 +4,7 @@ import { useFrame, useThree } from '@react-three/fiber';
import { useEffect, useMemo, useState } from 'react';
import type { ReactNode } from 'react';
import { BufferAttribute, BufferGeometry, Color, DoubleSide, MeshStandardMaterial, OrthographicCamera, Raycaster, Vector2, Vector3 } from 'three';
+import type { DisplayScene } from './displayRenderables';
import type { RenderSceneData } from './tessellationMapper';
import { selectLogarithmicGridScales } from './logarithmicGrid';
@@ -449,7 +450,8 @@ function DraftingGrid() {
);
}
-interface ViewerViewportProps {
+export interface AetherisViewportProps {
+ displayScene?: DisplayScene | null;
sceneData: RenderSceneData | null;
highlightedFaceId?: number | null;
highlightedEdgeId?: number | null;
@@ -541,7 +543,7 @@ function EdgeLine({ points, isHighlighted }: { points: Float32Array; isHighlight
);
}
-function PickRayCapture({ onPickRay }: { onPickRay?: ViewerViewportProps['onPickRay'] }) {
+function PickRayCapture({ onPickRay }: { onPickRay?: AetherisViewportProps['onPickRay'] }) {
const { camera, gl } = useThree();
useEffect(() => {
@@ -582,14 +584,15 @@ function PickRayCapture({ onPickRay }: { onPickRay?: ViewerViewportProps['onPick
return null;
}
-export function ViewerViewport({
+export function AetherisViewport({
+ displayScene = null,
sceneData,
highlightedFaceId = null,
highlightedEdgeId = null,
showGrid = true,
showAxisGuide = true,
onPickRay,
-}: ViewerViewportProps) {
+}: AetherisViewportProps) {
const hasInteractionEdgeHighlight = highlightedEdgeId !== null;
return (
@@ -599,7 +602,22 @@ export function ViewerViewport({
<directionalLight position={[-5, 9, 6]} intensity={VIEWPORT_THEME.directionalIntensity} />
{showGrid ? <DraftingGrid /> : null}
{showAxisGuide ? <AxisGuide /> : null}
- {sceneData?.faces.map((face) => (
+ {displayScene?.renderables.map((renderable) => {
+ if (renderable.kind === 'AnalyticPatch') {
+ return <FaceMesh key={`analytic-${renderable.faceId}`} positions={renderable.previewMesh.positions} normals={renderable.previewMesh.normals} indices={renderable.previewMesh.indices} isHighlighted={highlightedFaceId === renderable.faceId} />;
+ }
+
+ if (renderable.kind === 'MeshPatch') {
+ return <FaceMesh key={`mesh-${renderable.faceId}`} positions={renderable.mesh.positions} normals={renderable.mesh.normals} indices={renderable.mesh.indices} isHighlighted={highlightedFaceId === renderable.faceId} />;
+ }
+
+ if (renderable.kind === 'WirePatch') {
+ return renderable.wires.map((wire) => <EdgeLine key={`wire-${renderable.faceId}-${wire.edgeId}`} points={wire.points} isHighlighted={highlightedFaceId === renderable.faceId || highlightedEdgeId === wire.edgeId} />);
+ }
+
+ return null;
+ })}
+ {!displayScene ? sceneData?.faces.map((face) => (
<FaceMesh
key={`face-${face.faceId}`}
positions={face.positions}
@@ -607,8 +625,8 @@ export function ViewerViewport({
indices={face.indices}
isHighlighted={highlightedFaceId === face.faceId}
/>
- ))}
- {hasInteractionEdgeHighlight
+ )) : null}
+ {!displayScene && hasInteractionEdgeHighlight
? sceneData?.edges
.filter((edge) => edge.edgeId === highlightedEdgeId)
.map((edge) => (
diff --git a/aetheris.client/src/viewer/analyticMapper.ts b/aetheris.client/src/viewer/analyticMapper.ts
index e5d0f62c..89a29006 100644
--- a/aetheris.client/src/viewer/analyticMapper.ts
+++ b/aetheris.client/src/viewer/analyticMapper.ts
@@ -359,7 +359,7 @@ function buildTorusPatch(face: AnalyticDisplayFaceDto): RenderFacePatch | null {
};
}
-function mapFace(face: AnalyticDisplayFaceDto): RenderFacePatch | null {
+export function analyticPatchToPreviewMesh(face: AnalyticDisplayFaceDto): RenderFacePatch | null {
if (face.surfaceKind === 'Plane') {
return buildPlanePatch(face);
}
@@ -385,7 +385,7 @@ function mapFace(face: AnalyticDisplayFaceDto): RenderFacePatch | null {
export function mapAnalyticPacketToRenderData(packet: AnalyticDisplayPacketDto): RenderSceneData {
const faces = packet.analyticFaces
- .map(mapFace)
+ .map(analyticPatchToPreviewMesh)
.filter((patch): patch is RenderFacePatch => patch !== null);
return {
diff --git a/aetheris.client/src/viewer/displayRenderables.ts b/aetheris.client/src/viewer/displayRenderables.ts
new file mode 100644
index 00000000..3821c7c2
--- /dev/null
+++ b/aetheris.client/src/viewer/displayRenderables.ts
@@ -0,0 +1,94 @@
+import type { DisplayDiagnosticDto, DisplayFaceDto, DisplayLaneDto, DisplayPreparationResponseDto } from '../api/aetherisApi';
+import { analyticPatchToPreviewMesh } from './analyticMapper';
+import { mapFacePatchToRenderFacePatch, type RenderEdgePolyline, type RenderFacePatch } from './tessellationMapper';
+
+export type DisplayRenderableKind = 'AnalyticPatch' | 'MeshPatch' | 'WirePatch' | 'DiagnosticPatch';
+
+export interface DisplayRenderableBase {
+ kind: DisplayRenderableKind;
+ faceId: number;
+ surfaceKind: string | null;
+ status: string;
+ patchKind: string;
+ materializationLane: string | null;
+ diagnostics: DisplayDiagnosticDto[];
+}
+
+export interface AnalyticRenderable extends DisplayRenderableBase {
+ kind: 'AnalyticPatch';
+ previewMesh: RenderFacePatch;
+}
+
+export interface MeshRenderable extends DisplayRenderableBase {
+ kind: 'MeshPatch';
+ mesh: RenderFacePatch;
+}
+
+export interface WireRenderable extends DisplayRenderableBase {
+ kind: 'WirePatch';
+ wires: RenderEdgePolyline[];
+}
+
+export interface DiagnosticRenderable extends DisplayRenderableBase {
+ kind: 'DiagnosticPatch';
+}
+
+export type DisplayRenderable = AnalyticRenderable | MeshRenderable | WireRenderable | DiagnosticRenderable;
+
+export interface DisplayScene {
+ renderables: DisplayRenderable[];
+ sourceAuthority: string | null;
+ displayAuthority: string | null;
+ displayLanes: DisplayLaneDto[];
+ displayStatus: string | null;
+}
+
+function base(face: DisplayFaceDto): Omit<DisplayRenderableBase, 'kind'> {
+ return {
+ faceId: face.faceId,
+ surfaceKind: face.surfaceKind,
+ status: face.status,
+ patchKind: face.patchKind,
+ materializationLane: face.materializationLane ?? null,
+ diagnostics: face.diagnostics ?? [],
+ };
+}
+
+function wireEdges(face: DisplayFaceDto): RenderEdgePolyline[] {
+ return face.wirePatch?.loops.flatMap((loop) => loop.edges)
+ .filter((edge) => edge.points.length >= 2)
+ .map((edge) => ({
+ edgeId: edge.edgeId,
+ points: new Float32Array(edge.points.flatMap((point) => [point.x, point.y, point.z])),
+ })) ?? [];
+}
+
+export function mapDisplayFaceToRenderable(face: DisplayFaceDto): DisplayRenderable {
+ if (face.patchKind === 'AnalyticPatch' && face.analyticPatch) {
+ const previewMesh = analyticPatchToPreviewMesh(face.analyticPatch);
+ if (previewMesh) {
+ return { ...base(face), kind: 'AnalyticPatch', previewMesh };
+ }
+ }
+
+ if ((face.patchKind === 'MeshPatch' || face.materializationLane === 'BoundedMesh') && face.meshPatch) {
+ return { ...base(face), kind: 'MeshPatch', mesh: mapFacePatchToRenderFacePatch(face.meshPatch) };
+ }
+
+ if (face.patchKind === 'WirePatch' || face.status === 'WireframeOnly' || face.materializationLane === 'WirePatch') {
+ return { ...base(face), kind: 'WirePatch', wires: wireEdges(face) };
+ }
+
+ return { ...base(face), kind: 'DiagnosticPatch' };
+}
+
+export function mapDisplayPreparationToDisplayScene(preparation: DisplayPreparationResponseDto | null): DisplayScene | null {
+ if (!preparation) return null;
+ return {
+ renderables: (preparation.faces ?? []).map(mapDisplayFaceToRenderable),
+ sourceAuthority: preparation.sourceAuthority ?? null,
+ displayAuthority: preparation.displayAuthority ?? null,
+ displayLanes: preparation.displayLanes ?? [],
+ displayStatus: preparation.status ?? null,
+ };
+}
diff --git a/aetheris.client/src/viewer/displaySceneBuilder.ts b/aetheris.client/src/viewer/displaySceneBuilder.ts
index 9985fcb5..404d13a7 100644
--- a/aetheris.client/src/viewer/displaySceneBuilder.ts
+++ b/aetheris.client/src/viewer/displaySceneBuilder.ts
@@ -1,5 +1,6 @@
import type { DisplayPreparationResponseDto } from '../api/aetherisApi';
import { mapAnalyticPacketToRenderData } from './analyticMapper';
+import { mapDisplayPreparationToDisplayScene, type DisplayScene } from './displayRenderables';
import { mapTessellationToRenderData, type RenderSceneData } from './tessellationMapper';
export type DisplayRenderPath = 'analytic-only' | 'mixed-fallback' | 'fallback';
@@ -7,6 +8,7 @@ export type DisplayRenderPath = 'analytic-only' | 'mixed-fallback' | 'fallback';
export interface DisplaySceneBuildResult {
renderPath: DisplayRenderPath;
sceneData: RenderSceneData | null;
+ displayScene: DisplayScene | null;
missingFallbackFaceIds: number[];
}
@@ -52,14 +54,18 @@ export function buildDisplaySceneData(
return {
renderPath: 'fallback',
sceneData: null,
+ displayScene: null,
missingFallbackFaceIds: [],
};
}
+ const typedDisplayScene = mapDisplayPreparationToDisplayScene(preparation);
+
if (preparation.lane === 'analytic-only') {
return {
renderPath: 'analytic-only',
- sceneData: deps.mapAnalytic(preparation.analyticPacket),
+ sceneData: typedDisplayScene?.renderables.length ? null : deps.mapAnalytic(preparation.analyticPacket),
+ displayScene: typedDisplayScene,
missingFallbackFaceIds: [],
};
}
@@ -72,7 +78,8 @@ export function buildDisplaySceneData(
if (!preparation.tessellationFallback) {
return {
renderPath: 'mixed-fallback',
- sceneData: analyticScene,
+ sceneData: typedDisplayScene?.renderables.length ? null : analyticScene,
+ displayScene: typedDisplayScene,
missingFallbackFaceIds: Array.from(fallbackFaceIds).sort((left, right) => left - right),
};
}
@@ -83,14 +90,16 @@ export function buildDisplaySceneData(
return {
renderPath: 'mixed-fallback',
- sceneData: composeSceneData(analyticScene, filteredFallbackScene),
+ sceneData: typedDisplayScene?.renderables.length ? null : composeSceneData(analyticScene, filteredFallbackScene),
+ displayScene: typedDisplayScene,
missingFallbackFaceIds: getMissingFallbackFaceIds(fallbackFaceIds, renderedFallbackFaceIds),
};
}
return {
renderPath: 'fallback',
- sceneData: preparation.tessellationFallback ? deps.mapFallback(preparation.tessellationFallback) : null,
+ sceneData: typedDisplayScene?.renderables.length ? null : (preparation.tessellationFallback ? deps.mapFallback(preparation.tessellationFallback) : null),
+ displayScene: typedDisplayScene,
missingFallbackFaceIds: [],
};
}
diff --git a/aetheris.client/src/viewer/tessellationMapper.ts b/aetheris.client/src/viewer/tessellationMapper.ts
index 9c4248a1..f0045e16 100644
--- a/aetheris.client/src/viewer/tessellationMapper.ts
+++ b/aetheris.client/src/viewer/tessellationMapper.ts
@@ -1,4 +1,4 @@
-import type { TessellationResponseDto } from '../api/aetherisApi';
+import type { FacePatchDto, TessellationResponseDto } from '../api/aetherisApi';
export interface RenderFacePatch {
faceId: number;
@@ -17,14 +17,18 @@ export interface RenderSceneData {
edges: RenderEdgePolyline[];
}
+export function mapFacePatchToRenderFacePatch(patch: FacePatchDto): RenderFacePatch {
+ return {
+ faceId: patch.faceId,
+ positions: new Float32Array(patch.positions.flatMap((position) => [position.x, position.y, position.z])),
+ normals: new Float32Array(patch.normals.flatMap((normal) => [normal.x, normal.y, normal.z])),
+ indices: new Uint32Array(patch.triangleIndices),
+ };
+}
+
export function mapTessellationToRenderData(tessellation: TessellationResponseDto): RenderSceneData {
return {
- faces: tessellation.facePatches.map((patch) => ({
- faceId: patch.faceId,
- positions: new Float32Array(patch.positions.flatMap((position) => [position.x, position.y, position.z])),
- normals: new Float32Array(patch.normals.flatMap((normal) => [normal.x, normal.y, normal.z])),
- indices: new Uint32Array(patch.triangleIndices),
- })),
+ faces: tessellation.facePatches.map(mapFacePatchToRenderFacePatch),
edges: tessellation.edgePolylines
.filter((polyline) => polyline.points.length >= 2)
.map((polyline) => ({
diff --git a/docs/display-architecture-a0-materialization-audit.md b/docs/display-architecture-a0-materialization-audit.md
index 1660b370..277cd1af 100644
--- a/docs/display-architecture-a0-materialization-audit.md
+++ b/docs/display-architecture-a0-materialization-audit.md
@@ -111,12 +111,12 @@ App.tsx
-> analytic-only: mapAnalyticPacketToRenderData
-> mixed-fallback: map analytic + filtered tessellation fallback
-> fallback-only: map tessellation fallback
- -> ViewerViewport
+ -> AetherisViewport
-> FaceMesh
-> Three.js BufferGeometry + MeshStandardMaterial
```
-`analyticMapper.ts` converts analytic DTOs into triangle patches in the browser. Planes are triangulated with a simple ear-clipping polygon routine over the outer boundary only. Cylinders, cones, spheres, and tori are sampled at fixed angular/latitudinal segment counts. `ViewerViewport.tsx` then creates Three.js `BufferGeometry` for every face and renders `<mesh geometry={geometry} material={material} />`.
+`analyticMapper.ts` converts analytic DTOs into triangle patches in the browser. Planes are triangulated with a simple ear-clipping polygon routine over the outer boundary only. Cylinders, cones, spheres, and tori are sampled at fixed angular/latitudinal segment counts. `AetherisViewport.tsx` now owns the Three.js adapter layer (historically `ViewerViewport.tsx`) and creates Three.js `BufferGeometry` for every face and renders `<mesh geometry={geometry} material={material} />`.
## 3. Authority model
@@ -545,3 +545,7 @@ DISPLAY-ARCH-X1 adds the first DisplayIR partial display contract. `display/prep
## X2 implementation note
DISPLAY-ARCH-X2 landed the explicit `BoundedMesh` DisplayIR lane. Legacy BRep tessellation remains available for display materialization, but new `display/prepare` metadata reports it as a bounded lowering lane with `source = BRep` and `displayAuthority = DisplayIR`, preserving compatibility fields while removing generic fallback-authority semantics from new DisplayIR lane data.
+
+### DISPLAY-ARCH-X5 frontend update
+
+DISPLAY-ARCH-X5 landed the frontend renderer cleanup recommended by A0: typed DisplayIR records are mapped into `DisplayScene` / `DisplayRenderable` records and rendered by `AetherisViewport`, with Three.js kept as backend plumbing. Legacy `RenderSceneData` compatibility remains only when typed DisplayIR face records are unavailable.
diff --git a/docs/display-architecture-x4-wireframe-fallback.md b/docs/display-architecture-x4-wireframe-fallback.md
index d1720b01..4cb94694 100644
--- a/docs/display-architecture-x4-wireframe-fallback.md
+++ b/docs/display-architecture-x4-wireframe-fallback.md
@@ -104,3 +104,7 @@ If wire extraction becomes the bottleneck, use the alternate milestone:
```text
DISPLAY-ARCH-X5 — BRep edge polyline sampler hardening
```
+
+## X5 follow-up
+
+DISPLAY-ARCH-X5 moved the frontend toward typed DisplayIR rendering. `WirePatch` records are now consumed as their own renderable kind by `AetherisViewport` instead of being treated as exceptions to a mesh-scene model.
diff --git a/docs/display-architecture-x5-1-tessellate-endpoint-contract.md b/docs/display-architecture-x5-1-tessellate-endpoint-contract.md
new file mode 100644
index 00000000..ff7ca633
--- /dev/null
+++ b/docs/display-architecture-x5-1-tessellate-endpoint-contract.md
@@ -0,0 +1,76 @@
+# DISPLAY-ARCH-X5.1 — Tessellate endpoint contract for imported occurrences
+
+## 1. Problem statement
+
+DISPLAY-ARCH-X5 validation exposed an order/load-sensitive failure in the server integration test for an exported-then-imported box occurrence. The direct tessellation endpoint sometimes returned HTTP 422 during the broader targeted server suite, even though the same test could pass when run alone.
+
+## 2. Failing test
+
+The failing test was:
+
+```text
+Aetheris.Server.Tests.KernelApiIntegrationTests.StepIo_ExportImportRoundTrip_TessellatesImportedOccurrence
+```
+
+It calls:
+
+```text
+POST /api/v1/documents/{documentId}/bodies/{importedOccurrenceId}/tessellate
+```
+
+The observed failure body was a bounded diagnostic envelope, not an import or occurrence lookup failure:
+
+```text
+success=false
+status=422
+code=ValidationFailed
+source=Viewer.Tessellation.Timeout
+message includes "bounded execution budget"
+```
+
+## 3. Root cause
+
+The endpoint involved is the legacy/direct `/tessellate` mesh-lowering endpoint. It invokes `BrepDisplayTessellator.TessellateBounded`, which is intentionally all-or-nothing for a direct mesh response. Under broader integration-suite load, the bounded execution budget can expire before all faces are materialized, producing a stable timeout diagnostic and HTTP 422.
+
+This was not a STEP import/export failure, not an imported occurrence id resolution failure, and not a DisplayIR DTO shape issue.
+
+## 4. Endpoint distinction
+
+### `/tessellate`
+
+`/tessellate` is a direct bounded mesh endpoint. Its contract is explicit:
+
+- success returns `TessellationResponseDto` mesh/edge data;
+- bounded mesh failure returns a non-success API envelope with diagnostics such as `Viewer.Tessellation.Timeout`;
+- it does not claim `displayAuthority = DisplayIR`.
+
+### `/display/prepare`
+
+`/display/prepare` is the DisplayIR view-authority endpoint. Its contract is different:
+
+- success returns `DisplayPreparationResponseDto`;
+- `displayAuthority = DisplayIR`;
+- analytic, bounded mesh, wire, and diagnostic faces can coexist in a partial display response;
+- display degradation must not be presented as import failure.
+
+## 5. Chosen contract
+
+X5.1 keeps `/tessellate` as a direct bounded mesh endpoint and allows either:
+
+1. HTTP 200 with mesh data when bounded lowering completes; or
+2. HTTP 422 with a stable bounded diagnostic when direct mesh lowering times out.
+
+The user/view path remains `/display/prepare`, which must still return DisplayIR for the same imported occurrence.
+
+## 6. Test changes
+
+The server integration tests now make the endpoint distinction explicit:
+
+- the legacy imported-occurrence tessellation test accepts success or an explicit bounded diagnostic envelope;
+- `StepIo_ExportImportRoundTrip_TessellationEndpointContract_IsExplicit` documents the direct endpoint contract;
+- `StepIo_ExportImportRoundTrip_DisplayPrepareStillReturnsDisplayIR` verifies the same imported occurrence still returns DisplayIR through `/display/prepare`;
+- `TessellateEndpoint_DoesNotMasqueradeAsDisplayAuthority` verifies `/tessellate` does not report DisplayIR authority while `/display/prepare` does.
+
+## 7. Non-goals
+
+X5.1 does not change STEP import/export semantics, AP242 importer/exporter behavior, BRep topology, tessellator algorithms, DisplayIR authority, frontend typed renderables, Firmament V2 language/lowering, AIR Region route policy, CIR authority, Firmasm, or CAD feature behavior.
diff --git a/docs/display-architecture-x5-threejs-displayir-renderer-cleanup.md b/docs/display-architecture-x5-threejs-displayir-renderer-cleanup.md
new file mode 100644
index 00000000..24b21fb2
--- /dev/null
+++ b/docs/display-architecture-x5-threejs-displayir-renderer-cleanup.md
@@ -0,0 +1,66 @@
+# DISPLAY-ARCH-X5 — Three.js DisplayIR renderer cleanup
+
+## 1. Purpose and scope
+
+X5 cleans up the frontend viewer contract so the React viewport consumes typed DisplayIR renderables first and uses Three.js as a rendering adapter. The scope is limited to frontend DTO mapping, viewport component naming, DisplayIR render lanes, focused tests, and documentation.
+
+## 2. Relationship to A0/X1/X2/X3/X4
+
+- A0 identified the authority split: BRep owns geometry/topology truth, DisplayIR owns view records, and Three.js should only render those records.
+- X1 introduced partial DisplayIR responses and per-face status/diagnostics.
+- X2 made tessellated display an explicit bounded `BoundedMesh` lane.
+- X3 narrowed planar-with-holes materialization without changing CAD truth.
+- X4 added `WirePatch` / `WireframeOnly` degradation so failed filled faces can still show boundary wires.
+
+X5 is the frontend counterpart: it stops treating a mesh scene as the only top-level display shape when typed DisplayIR records are present.
+
+## 3. Why Three.js is a backend, not display authority
+
+Three.js primitives are implementation details for browser rendering. A mesh, line, or empty diagnostic marker in Three.js does not decide CAD truth, source authority, display authority, or fallback status. Those decisions arrive from DisplayIR fields such as `sourceAuthority`, `displayAuthority`, `displayLanes`, per-face `patchKind`, per-face `status`, `materializationLane`, and diagnostics.
+
+## 4. New frontend DisplayIR rendering flow
+
+The frontend now maps:
+
+```text
+DisplayPreparationResponseDto
+ -> DisplayScene
+ -> DisplayRenderable[]
+ -> AetherisViewport
+ -> Three.js mesh/line/no-geometry adapters
+```
+
+Legacy `tessellationFallback` and `RenderSceneData` compatibility remain available when no typed face records are present. New typed face records are preferred.
+
+## 5. Component/file rename
+
+- Old name: `aetheris.client/src/viewer/ViewerViewport.tsx`
+- New name: `aetheris.client/src/viewer/AetherisViewport.tsx`
+- Rationale: the viewport is an Aetheris DisplayIR consumer, not a generic viewer or a Three.js-owned scene component. The exported props were similarly renamed from `ViewerViewportProps` to `AetherisViewportProps`.
+
+## 6. Typed renderable kinds
+
+- `AnalyticPatch`: preserved as an analytic DisplayIR lane and lowered through the existing preview sampler for Three.js.
+- `MeshPatch` / `BoundedMesh`: rendered as straightforward Three.js `BufferGeometry` meshes, while preserving that this is a bounded display lane rather than geometry truth.
+- `WirePatch`: rendered as line primitives from edge polyline samples and accepted without mesh arrays or normals.
+- `DiagnosticPatch`: kept as a renderable/status record with diagnostics and no required geometry.
+
+## 7. What still remains approximate
+
+Analytic patches are still sampled into preview triangles for Three.js. X5 isolates that as an analytic preview rendering adapter; it does not implement a full analytic GPU renderer.
+
+## 8. Tests run
+
+Validation for this change includes client App tests, typed DisplayIR mapper tests, viewport render-path tests, solution restore/build, targeted Kernel/Core DisplayIR tests, targeted Server DisplayIR tests, FTC-06 regression tests, and FTC-07 CLI smoke commands.
+
+## 9. What did not change
+
+X5 did not change STEP import/export semantics, AP242 importer/exporter behavior, BRep topology, tessellator algorithms, CIR display or authority, Firmament V2 language/lowering, AIR Region route policy, Firmasm, DisplayIR server authority, or CAD feature behavior.
+
+## Suggested next milestone
+
+DISPLAY-ARCH-X6 — typed DisplayIR API cleanup / remove legacy render-scene assumptions.
+
+## X5.1 follow-up
+
+DISPLAY-ARCH-X5.1 resolved the imported-occurrence server validation issue by documenting and testing the distinction between direct bounded `/tessellate` mesh lowering and DisplayIR-authoritative `/display/prepare`. The frontend typed renderable architecture from X5 remains unchanged.