Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add M18.5 viewer picking debug integration

Yuechen Li80fe6a699e74
diff --git a/aetheris.client/src/App.tsx b/aetheris.client/src/App.tsx
index 9bdffbac..5e599d88 100644
--- a/aetheris.client/src/App.tsx
+++ b/aetheris.client/src/App.tsx
@@ -5,8 +5,10 @@ import {
createBox,
createDocument,
getDocumentSummary,
+ pickBody,
tessellateBody,
type DiagnosticDto,
+ type PickHitDto,
type TessellationResponseDto,
} from './api/aetherisApi';
import { ViewerViewport } from './viewer/ViewerViewport';
@@ -22,6 +24,10 @@ function App() {
const [status, setStatus] = useState<RequestStatus>('idle');
const [statusMessage, setStatusMessage] = useState<string>('Ready. Create a document to begin.');
const [diagnostics, setDiagnostics] = useState<DiagnosticDto[]>([]);
+ const [pickStatus, setPickStatus] = useState<RequestStatus>('idle');
+ const [pickMessage, setPickMessage] = useState<string>('Click in the viewport to run nearest-hit pick.');
+ const [pickDiagnostics, setPickDiagnostics] = useState<DiagnosticDto[]>([]);
+ const [pickHits, setPickHits] = useState<PickHitDto[]>([]);
const runAction = useCallback(async (actionName: string, action: () => Promise<void>) => {
setStatus('loading');
@@ -49,6 +55,10 @@ function App() {
setBodyIds([]);
setActiveBodyId(null);
setTessellation(null);
+ setPickStatus('idle');
+ setPickMessage('Click in the viewport to run nearest-hit pick.');
+ setPickDiagnostics([]);
+ setPickHits([]);
});
}, [runAction]);
@@ -65,6 +75,10 @@ function App() {
setBodyIds(summary.bodyIds);
setActiveBodyId(created.bodyId);
setTessellation(tessellated);
+ setPickStatus('idle');
+ setPickMessage('Click in the viewport to run nearest-hit pick.');
+ setPickDiagnostics([]);
+ setPickHits([]);
});
}, [documentId, runAction]);
@@ -78,12 +92,55 @@ function App() {
setTessellation(tessellated);
});
}, [activeBodyId, documentId, runAction]);
+
+ const handlePickRay = useCallback(async (origin: { x: number; y: number; z: number }, direction: { x: number; y: number; z: number }) => {
+ if (!documentId || !activeBodyId) {
+ setPickStatus('error');
+ setPickMessage('Cannot pick before a document and active body exist.');
+ setPickDiagnostics([]);
+ setPickHits([]);
+ return;
+ }
+
+ setPickStatus('loading');
+ setPickMessage('Picking (nearest-only)...');
+ setPickDiagnostics([]);
+
+ try {
+ const pickResponse = await pickBody(documentId, activeBodyId, {
+ origin,
+ direction,
+ tessellationOptions: null,
+ pickOptions: {
+ nearestOnly: true,
+ },
+ });
+
+ setPickStatus('success');
+ setPickHits(pickResponse.hits);
+ setPickMessage(pickResponse.hits.length === 0
+ ? 'No hit for current click ray.'
+ : `Picked ${pickResponse.hits[0].entityKind} (nearest hit).`);
+ } catch (error) {
+ const apiError = error instanceof ApiError
+ ? error
+ : new ApiError((error as Error).message || 'Unexpected pick error.', []);
+ setPickStatus('error');
+ setPickMessage(apiError.message);
+ setPickDiagnostics(apiError.diagnostics);
+ setPickHits([]);
+ }
+ }, [activeBodyId, documentId]);
+
const sceneData = useMemo(() => (tessellation ? mapTessellationToRenderData(tessellation) : null), [tessellation]);
+ const nearestHit = pickHits[0] ?? null;
+ const highlightedFaceId = nearestHit?.entityKind === 'Face' ? nearestHit.faceId : null;
+ const highlightedEdgeId = nearestHit?.entityKind === 'Edge' ? nearestHit.edgeId : null;
return (
<div className="app-shell">
<header className="toolbar">
- <h1>Aetheris Viewer Shell (M18)</h1>
+ <h1>Aetheris Viewer Shell (M18.5)</h1>
<div className="toolbar-actions">
<button type="button" onClick={() => void handleCreateDocument()}>
Create Document
@@ -98,7 +155,12 @@ function App() {
</header>
<main className="main-grid">
- <ViewerViewport sceneData={sceneData} />
+ <ViewerViewport
+ sceneData={sceneData}
+ highlightedFaceId={highlightedFaceId}
+ highlightedEdgeId={highlightedEdgeId}
+ onPickRay={(origin, direction) => void handlePickRay(origin, direction)}
+ />
<aside className="debug-panel">
<h2>Debug / Status</h2>
<p><strong>Request status:</strong> {status}</p>
@@ -111,6 +173,37 @@ function App() {
</ul>
<p><strong>Face patches:</strong> {tessellation?.facePatches.length ?? 0}</p>
<p><strong>Edge polylines:</strong> {tessellation?.edgePolylines.length ?? 0}</p>
+ <h3>Pick Behavior (M18.5)</h3>
+ <p>Single left click in viewport sends world-space camera ray to backend.</p>
+ <p>Pick mode: nearest-only. Backface handling: backend default (not overridden).</p>
+ <p><strong>Pick status:</strong> {pickStatus}</p>
+ <p><strong>Pick message:</strong> {pickMessage}</p>
+ <p><strong>Pick hits:</strong> {pickHits.length}</p>
+ {nearestHit ? (
+ <ul>
+ <li><strong>Kind:</strong> {nearestHit.entityKind}</li>
+ <li><strong>Face ID:</strong> {nearestHit.faceId ?? 'n/a'}</li>
+ <li><strong>Edge ID:</strong> {nearestHit.edgeId ?? 'n/a'}</li>
+ <li><strong>t:</strong> {nearestHit.t.toFixed(5)}</li>
+ <li><strong>Point:</strong> ({nearestHit.point.x.toFixed(5)}, {nearestHit.point.y.toFixed(5)}, {nearestHit.point.z.toFixed(5)})</li>
+ <li>
+ <strong>Normal:</strong>{' '}
+ {nearestHit.normal
+ ? `(${nearestHit.normal.x.toFixed(5)}, ${nearestHit.normal.y.toFixed(5)}, ${nearestHit.normal.z.toFixed(5)})`
+ : 'n/a'}
+ </li>
+ </ul>
+ ) : <p>No nearest hit to display.</p>}
+ <h3>Pick Diagnostics</h3>
+ {pickDiagnostics.length === 0 ? <p>None</p> : (
+ <ul>
+ {pickDiagnostics.map((diagnostic, index) => (
+ <li key={`pick-${diagnostic.code}-${index}`}>
+ [{diagnostic.severity}] {diagnostic.code}: {diagnostic.message}
+ </li>
+ ))}
+ </ul>
+ )}
<h3>Diagnostics</h3>
{diagnostics.length === 0 ? <p>None</p> : (
<ul>
diff --git a/aetheris.client/src/__tests__/aetherisApi.test.ts b/aetheris.client/src/__tests__/aetherisApi.test.ts
index 8e879f46..a13b212b 100644
--- a/aetheris.client/src/__tests__/aetherisApi.test.ts
+++ b/aetheris.client/src/__tests__/aetherisApi.test.ts
@@ -1,5 +1,5 @@
-import { describe, expect, it } from 'vitest';
-import { ApiError, parseEnvelope } from '../api/aetherisApi';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ApiError, parseEnvelope, pickBody } from '../api/aetherisApi';
describe('parseEnvelope', () => {
it('returns data when envelope success is true', async () => {
@@ -34,3 +34,41 @@ describe('parseEnvelope', () => {
}]));
});
});
+
+describe('pickBody', () => {
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ });
+
+ it('posts pick payload and parses nearest-hit response envelope', async () => {
+ const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({
+ success: true,
+ data: {
+ hits: [{
+ t: 1.25,
+ point: { x: 0, y: 0, z: 1 },
+ normal: { x: 0, y: 0, z: 1 },
+ entityKind: 'Face',
+ faceId: 2,
+ edgeId: null,
+ bodyId: null,
+ sourcePatchIndex: 0,
+ sourcePrimitiveIndex: 1,
+ }],
+ },
+ diagnostics: [],
+ }), { status: 200 }));
+ vi.stubGlobal('fetch', fetchMock);
+
+ const response = await pickBody('doc-1', 'body-1', {
+ origin: { x: 1, y: 2, z: 3 },
+ direction: { x: 0, y: 0, z: -1 },
+ tessellationOptions: null,
+ pickOptions: { nearestOnly: true },
+ });
+
+ expect(fetchMock).toHaveBeenCalledWith('/api/v1/documents/doc-1/bodies/body-1/pick', expect.objectContaining({ method: 'POST' }));
+ expect(response.hits[0].entityKind).toBe('Face');
+ expect(response.hits[0].faceId).toBe(2);
+ });
+});
diff --git a/aetheris.client/src/api/aetherisApi.ts b/aetheris.client/src/api/aetherisApi.ts
index d53c0705..32d69971 100644
--- a/aetheris.client/src/api/aetherisApi.ts
+++ b/aetheris.client/src/api/aetherisApi.ts
@@ -62,6 +62,37 @@ export interface TessellationResponseDto {
edgePolylines: EdgePolylineDto[];
}
+export interface PickOptionsDto {
+ nearestOnly?: boolean;
+ includeBackfaces?: boolean;
+ edgeTolerance?: number;
+ sortTieTolerance?: number;
+ maxDistance?: number;
+}
+
+export interface PickRequestDto {
+ origin: Point3Dto;
+ direction: Vector3Dto;
+ tessellationOptions: null;
+ pickOptions: PickOptionsDto;
+}
+
+export interface PickHitDto {
+ t: number;
+ point: Point3Dto;
+ normal: Vector3Dto | null;
+ entityKind: 'Face' | 'Edge';
+ faceId: number | null;
+ edgeId: number | null;
+ bodyId: number | null;
+ sourcePatchIndex: number | null;
+ sourcePrimitiveIndex: number | null;
+}
+
+export interface PickResponseDto {
+ hits: PickHitDto[];
+}
+
export class ApiError extends Error {
public readonly diagnostics: DiagnosticDto[];
@@ -129,4 +160,11 @@ export async function tessellateBody(documentId: string, bodyId: string): Promis
});
}
+export async function pickBody(documentId: string, bodyId: string, pickRequest: PickRequestDto): Promise<PickResponseDto> {
+ return request<PickResponseDto>(`/api/v1/documents/${documentId}/bodies/${bodyId}/pick`, {
+ method: 'POST',
+ body: JSON.stringify(pickRequest),
+ });
+}
+
export { parseEnvelope };
diff --git a/aetheris.client/src/viewer/ViewerViewport.tsx b/aetheris.client/src/viewer/ViewerViewport.tsx
index cb7a67b3..eba70363 100644
--- a/aetheris.client/src/viewer/ViewerViewport.tsx
+++ b/aetheris.client/src/viewer/ViewerViewport.tsx
@@ -1,14 +1,18 @@
import { Line, OrbitControls } from '@react-three/drei';
import { Canvas } from '@react-three/fiber';
-import { useMemo } from 'react';
-import { BufferAttribute, BufferGeometry, DoubleSide, MeshStandardMaterial } from 'three';
+import { useThree } from '@react-three/fiber';
+import { useEffect, useMemo } from 'react';
+import { BufferAttribute, BufferGeometry, DoubleSide, MeshStandardMaterial, Raycaster, Vector2 } from 'three';
import type { RenderSceneData } from './tessellationMapper';
interface ViewerViewportProps {
sceneData: RenderSceneData | null;
+ highlightedFaceId?: number | null;
+ highlightedEdgeId?: number | null;
+ onPickRay?: (origin: { x: number; y: number; z: number }, direction: { x: number; y: number; z: number }) => void;
}
-function FaceMesh({ positions, normals, indices }: { positions: Float32Array; normals: Float32Array; indices: Uint32Array }) {
+function FaceMesh({ positions, normals, indices, isHighlighted }: { positions: Float32Array; normals: Float32Array; indices: Uint32Array; isHighlighted: boolean }) {
const geometry = useMemo(() => {
const meshGeometry = new BufferGeometry();
meshGeometry.setAttribute('position', new BufferAttribute(positions, 3));
@@ -18,12 +22,15 @@ function FaceMesh({ positions, normals, indices }: { positions: Float32Array; no
return meshGeometry;
}, [indices, normals, positions]);
- const material = useMemo(() => new MeshStandardMaterial({ color: '#8db8ff', metalness: 0.1, roughness: 0.75, side: DoubleSide }), []);
+ const material = useMemo(
+ () => new MeshStandardMaterial({ color: isHighlighted ? '#f59e0b' : '#8db8ff', metalness: 0.1, roughness: 0.75, side: DoubleSide }),
+ [isHighlighted],
+ );
return <mesh geometry={geometry} material={material} />;
}
-function EdgeLine({ points }: { points: Float32Array }) {
+function EdgeLine({ points, isHighlighted }: { points: Float32Array; isHighlighted: boolean }) {
const linePoints = useMemo(() => {
const vertices: [number, number, number][] = [];
@@ -34,10 +41,51 @@ function EdgeLine({ points }: { points: Float32Array }) {
return vertices;
}, [points]);
- return <Line points={linePoints} color="#111827" lineWidth={1} />;
+ return <Line points={linePoints} color={isHighlighted ? '#dc2626' : '#111827'} lineWidth={isHighlighted ? 3 : 1} />;
+}
+
+function PickRayCapture({ onPickRay }: { onPickRay?: ViewerViewportProps['onPickRay'] }) {
+ const { camera, gl } = useThree();
+
+ useEffect(() => {
+ if (!onPickRay) {
+ return;
+ }
+
+ const raycaster = new Raycaster();
+ const pointer = new Vector2();
+
+ const handleClick = (event: MouseEvent) => {
+ if (event.button !== 0) {
+ return;
+ }
+
+ const rect = gl.domElement.getBoundingClientRect();
+ pointer.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
+ pointer.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
+ raycaster.setFromCamera(pointer, camera);
+ onPickRay(
+ {
+ x: raycaster.ray.origin.x,
+ y: raycaster.ray.origin.y,
+ z: raycaster.ray.origin.z,
+ },
+ {
+ x: raycaster.ray.direction.x,
+ y: raycaster.ray.direction.y,
+ z: raycaster.ray.direction.z,
+ },
+ );
+ };
+
+ gl.domElement.addEventListener('click', handleClick);
+ return () => gl.domElement.removeEventListener('click', handleClick);
+ }, [camera, gl.domElement, onPickRay]);
+
+ return null;
}
-export function ViewerViewport({ sceneData }: ViewerViewportProps) {
+export function ViewerViewport({ sceneData, highlightedFaceId = null, highlightedEdgeId = null, onPickRay }: ViewerViewportProps) {
return (
<div className="viewport-shell">
<Canvas camera={{ position: [4, 4, 4], fov: 50 }}>
@@ -52,14 +100,17 @@ export function ViewerViewport({ sceneData }: ViewerViewportProps) {
positions={face.positions}
normals={face.normals}
indices={face.indices}
+ isHighlighted={highlightedFaceId === face.faceId}
/>
))}
{sceneData?.edges.map((edge) => (
<EdgeLine
key={`edge-${edge.edgeId}`}
points={edge.points}
+ isHighlighted={highlightedEdgeId === edge.edgeId}
/>
))}
+ <PickRayCapture onPickRay={onPickRay} />
<OrbitControls makeDefault enablePan enableZoom />
</Canvas>
</div>
diff --git a/docs/milestones.md b/docs/milestones.md
index d3449340..1c916ce0 100644
--- a/docs/milestones.md
+++ b/docs/milestones.md
@@ -163,3 +163,11 @@
- [x] Add a simple debug/status panel showing document/body state, request status, and surfaced diagnostics.
- [x] Keep scope intentionally narrow: viewer/debug shell + primitive creation integration only.
- [x] Defer rich modeling workflows, selection UX, editing manipulators/gizmos, undo/redo, and persisted documents.
+
+## M18.5 — Viewer Picking Integration Debug Slice
+
+- [x] Extend the React viewer API client with typed `/api/v1/documents/{documentId}/bodies/{bodyId}/pick` support using the M17 response envelope.
+- [x] Add viewport click-to-ray mapping and nearest-only pick requests against the backend endpoint (backend semantics remain source of truth).
+- [x] Surface pick status, hit details (kind, IDs, t, point, normal), and diagnostics/no-hit feedback in the debug panel.
+- [x] Add minimal debug highlighting for nearest picked face/edge using tessellation topology IDs.
+- [x] Defer full selection UX/tooling architecture (multi-select, inspectors, manipulators, hover/tool systems) to M19+.