init
This commit is contained in:
@@ -0,0 +1,301 @@
|
||||
# Implementation Reference — Reveal 3D Viewer
|
||||
|
||||
Full copy-paste ready implementations. Copy `skills/reveal-3d/code/reveal/` into an app-local feature folder first, typically `src/features/reveal-3d/`, then import from that local folder. **Pattern B (model browser — auto-loads models) is the default** — use it unless the data has explicit FDM → CAD node linkage.
|
||||
|
||||
---
|
||||
|
||||
## Pattern B (default) — model browser, auto-discovers models via `sdk.models3D.list()`
|
||||
|
||||
Canvas-only component — no providers. `CacheProvider`, `RevealKeepAlive`, and `RevealProvider` live in App.tsx.
|
||||
|
||||
```tsx
|
||||
import { useCallback, useMemo } from 'react';
|
||||
import {
|
||||
Reveal3DResources,
|
||||
RevealCanvas,
|
||||
type AddCadResourceOptions,
|
||||
} from '@/features/reveal-3d';
|
||||
|
||||
export interface ViewerContentProps {
|
||||
modelId: number;
|
||||
revisionId: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Canvas-only — no CacheProvider, RevealKeepAlive, or RevealProvider here.
|
||||
* All providers live in App.tsx so React StrictMode double-invoke completes
|
||||
* at startup before any model loading starts.
|
||||
*/
|
||||
export function ViewerContent({ modelId, revisionId }: ViewerContentProps) {
|
||||
// AddCadResourceOptions is just { modelId, revisionId } — no `type` field.
|
||||
// Do NOT use { type: 'cad', modelId, revisionId } — that is TaggedAddResourceOptions.
|
||||
const resources = useMemo<AddCadResourceOptions[]>(
|
||||
() => [{ modelId, revisionId }],
|
||||
[modelId, revisionId]
|
||||
);
|
||||
const onLoaded = useCallback(() => {}, []);
|
||||
|
||||
return (
|
||||
<RevealCanvas>
|
||||
<Reveal3DResources resources={resources} onModelsLoaded={onLoaded} />
|
||||
</RevealCanvas>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### src/App.tsx — providers + model browser
|
||||
|
||||
```tsx
|
||||
import { lazy, Suspense, useCallback, useEffect, useMemo, useState } from 'react';
|
||||
import * as THREE from 'three';
|
||||
import { useDune } from '@cognite/dune';
|
||||
import { useInfiniteQuery, useQuery } from '@tanstack/react-query';
|
||||
import type { Model3D, Revision3D } from '@cognite/sdk';
|
||||
import {
|
||||
CacheProvider,
|
||||
RevealKeepAlive,
|
||||
RevealProvider,
|
||||
type ViewerOptions,
|
||||
} from '@/features/reveal-3d';
|
||||
|
||||
// Lazy-load canvas content — providers are eagerly imported
|
||||
const ViewerContent = lazy(() =>
|
||||
import('./components/ViewerContent').then((m) => ({ default: m.ViewerContent }))
|
||||
);
|
||||
|
||||
// Module-level constants — stable references, never recreated on re-render
|
||||
const BG = new THREE.Color(0x1a1a2e);
|
||||
const VIEWER_OPTIONS: ViewerOptions = {
|
||||
loadingIndicatorStyle: { placement: 'topRight', opacity: 0.1 },
|
||||
antiAliasingHint: 'msaa2+fxaa',
|
||||
ssaoQualityHint: 'medium',
|
||||
};
|
||||
|
||||
type SelectedModel = { modelId: number; revisionId: number };
|
||||
|
||||
// --- Model discovery hooks ---
|
||||
|
||||
function useModels(query?: string) {
|
||||
const { sdk } = useDune();
|
||||
return useInfiniteQuery({
|
||||
queryKey: ['3d-models', query],
|
||||
queryFn: ({ pageParam }: { pageParam?: string }) =>
|
||||
sdk.models3D.list({ limit: 1000, cursor: pageParam }) as Promise<{
|
||||
items: Model3D[];
|
||||
nextCursor?: string;
|
||||
}>,
|
||||
initialPageParam: undefined as string | undefined,
|
||||
getNextPageParam: (page) => page.nextCursor,
|
||||
enabled: !!sdk,
|
||||
select: useCallback(
|
||||
(data: any) => ({
|
||||
...data,
|
||||
pages: data.pages.map((p: any) => ({
|
||||
...p,
|
||||
items: p.items
|
||||
.map((m: Model3D) => ({ ...m, name: m.name.trim() }))
|
||||
.filter((m: Model3D) =>
|
||||
query ? m.name.toLowerCase().includes(query.toLowerCase()) : true
|
||||
),
|
||||
})),
|
||||
}),
|
||||
[query]
|
||||
),
|
||||
});
|
||||
}
|
||||
|
||||
function useBestRevision(modelId?: number) {
|
||||
const { sdk } = useDune();
|
||||
return useQuery({
|
||||
queryKey: ['3d-revisions', modelId],
|
||||
queryFn: async () => {
|
||||
if (!modelId) return null;
|
||||
const all: Revision3D[] = await sdk.revisions3D
|
||||
.list(modelId)
|
||||
.autoPagingToArray({ limit: -1 });
|
||||
const published = all.filter((r) => r.published);
|
||||
const candidates = published.length ? published : all;
|
||||
return candidates.reduce((best, cur) =>
|
||||
best.createdTime > cur.createdTime ? best : cur
|
||||
) ?? null;
|
||||
},
|
||||
enabled: !!sdk && !!modelId,
|
||||
});
|
||||
}
|
||||
|
||||
// --- Model browser ---
|
||||
//
|
||||
// RULE 1: onSelect MUST be wrapped in useCallback at the call site.
|
||||
// An inline arrow `(m) => setSelected(m)` creates a new reference every render.
|
||||
// The useEffect([..., onSelect]) below fires on every render → infinite loop.
|
||||
//
|
||||
// RULE 2: call onSelect from useEffect, NOT during render.
|
||||
// An if-block during render calling onSelect also causes infinite loops.
|
||||
|
||||
function ModelBrowser({ onSelect }: { onSelect: (m: SelectedModel) => void }) {
|
||||
const [query, setQuery] = useState('');
|
||||
const [pendingId, setPendingId] = useState<number>();
|
||||
const { data } = useModels(query);
|
||||
const { data: revision } = useBestRevision(pendingId);
|
||||
const models = data?.pages.flatMap((p) => p.items) ?? [];
|
||||
|
||||
useEffect(() => {
|
||||
if (revision && pendingId) {
|
||||
onSelect({ modelId: pendingId, revisionId: revision.id });
|
||||
}
|
||||
}, [revision, pendingId, onSelect]);
|
||||
|
||||
return (
|
||||
<div>
|
||||
<input
|
||||
placeholder="Search models…"
|
||||
value={query}
|
||||
onChange={(e) => setQuery(e.target.value)}
|
||||
/>
|
||||
{models.map((m) => (
|
||||
<button key={m.id} onClick={() => setPendingId(m.id)}>
|
||||
{m.name}
|
||||
</button>
|
||||
))}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
// --- App ---
|
||||
|
||||
export default function App() {
|
||||
const { sdk: client, isLoading } = useDune();
|
||||
// Memoize on sdk.project — prevents RevealProvider from remounting on
|
||||
// unrelated sdk object reference changes
|
||||
const sdk = useMemo(() => client, [client.project]);
|
||||
|
||||
const [selected, setSelected] = useState<SelectedModel | null>(null);
|
||||
|
||||
// useCallback is mandatory — see ModelBrowser RULE 1 above
|
||||
const handleSelect = useCallback((m: SelectedModel) => {
|
||||
setSelected((prev) => (!prev || prev.modelId !== m.modelId ? m : prev));
|
||||
}, []);
|
||||
|
||||
if (isLoading) return <div>Connecting to CDF…</div>;
|
||||
|
||||
return (
|
||||
// CacheProvider + RevealKeepAlive always mounted → StrictMode double-invoke
|
||||
// completes at startup with no viewer to dispose.
|
||||
// RevealProvider conditionally mounts → finds stable RevealKeepAlive viewerRef.
|
||||
<CacheProvider>
|
||||
<RevealKeepAlive>
|
||||
<div style={{ display: 'flex', height: '100vh' }}>
|
||||
<aside style={{ width: 280, overflowY: 'auto' }}>
|
||||
<ModelBrowser onSelect={handleSelect} />
|
||||
</aside>
|
||||
<div style={{ flex: 1, position: 'relative' }}>
|
||||
{selected && (
|
||||
<RevealProvider sdk={sdk} color={BG} viewerOptions={VIEWER_OPTIONS}>
|
||||
<Suspense fallback={<div>Loading viewer…</div>}>
|
||||
<ViewerContent
|
||||
modelId={selected.modelId}
|
||||
revisionId={selected.revisionId}
|
||||
/>
|
||||
</Suspense>
|
||||
</RevealProvider>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
</RevealKeepAlive>
|
||||
</CacheProvider>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern A (fallback) — FDM auto-discover from an asset instance
|
||||
|
||||
Use only when you have a `DMInstanceRef` and the instance has `CogniteVisualizable.object3D → CogniteCADNode` linkage. Otherwise use Pattern B above.
|
||||
|
||||
### src/components/ViewerContent.tsx (FDM variant)
|
||||
|
||||
```tsx
|
||||
import { useCallback, useMemo, useState } from 'react';
|
||||
import type { DMInstanceRef } from '@cognite/reveal';
|
||||
import {
|
||||
Reveal3DResources,
|
||||
RevealCanvas,
|
||||
useModelsForInstanceQuery,
|
||||
type AddCadResourceOptions,
|
||||
type TaggedAddResourceOptions,
|
||||
} from '@/features/reveal-3d';
|
||||
|
||||
function pickFirstCad(models: TaggedAddResourceOptions[]): AddCadResourceOptions | undefined {
|
||||
const m = models[0];
|
||||
return m?.type === 'cad'
|
||||
? { ...m.addOptions, styling: { default: { renderGhosted: true } } }
|
||||
: undefined;
|
||||
}
|
||||
|
||||
export function ViewerContent({ instance }: { instance: DMInstanceRef }) {
|
||||
const { data: models, isLoading } = useModelsForInstanceQuery(instance);
|
||||
const [loaded, setLoaded] = useState(false);
|
||||
const selected = useMemo(() => pickFirstCad(models ?? []), [models]);
|
||||
const resources = useMemo(() => (selected ? [selected] : []), [selected]);
|
||||
const onLoaded = useCallback(() => setLoaded(true), []);
|
||||
|
||||
if (isLoading) return <div>Loading 3D model…</div>;
|
||||
if (!resources.length) return <div>No 3D data linked to this instance.</div>;
|
||||
|
||||
return (
|
||||
<RevealCanvas>
|
||||
<Reveal3DResources resources={resources} onModelsLoaded={onLoaded} />
|
||||
</RevealCanvas>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### src/App.tsx (FDM variant)
|
||||
|
||||
Same `CacheProvider` / `RevealKeepAlive` / `RevealProvider` structure as Pattern B.
|
||||
Pass `instance: DMInstanceRef` to `ViewerContent` instead of `modelId` / `revisionId`.
|
||||
|
||||
```tsx
|
||||
import { useMemo, useState } from 'react';
|
||||
import * as THREE from 'three';
|
||||
import { useDune } from '@cognite/dune';
|
||||
import type { DMInstanceRef } from '@cognite/reveal';
|
||||
import {
|
||||
CacheProvider,
|
||||
RevealKeepAlive,
|
||||
RevealProvider,
|
||||
type ViewerOptions,
|
||||
} from '@/features/reveal-3d';
|
||||
import { ViewerContent } from './components/ViewerContent';
|
||||
|
||||
const BG = new THREE.Color(0x1a1a2e);
|
||||
const OPTS: ViewerOptions = {
|
||||
loadingIndicatorStyle: { placement: 'topRight', opacity: 0.1 },
|
||||
antiAliasingHint: 'msaa2+fxaa',
|
||||
ssaoQualityHint: 'medium',
|
||||
};
|
||||
|
||||
export default function App() {
|
||||
const { sdk: client, isLoading } = useDune();
|
||||
const sdk = useMemo(() => client, [client.project]);
|
||||
// Replace with however you receive the instance ref (prop, route param, selection, etc.)
|
||||
const [instance] = useState<DMInstanceRef | null>(null);
|
||||
|
||||
if (isLoading) return <div>Connecting to CDF…</div>;
|
||||
|
||||
return (
|
||||
<CacheProvider>
|
||||
<RevealKeepAlive>
|
||||
<div style={{ width: '100%', height: '100vh', position: 'relative' }}>
|
||||
{instance && sdk.project && (
|
||||
<RevealProvider sdk={sdk} color={BG} viewerOptions={OPTS}>
|
||||
<ViewerContent instance={instance} />
|
||||
</RevealProvider>
|
||||
)}
|
||||
</div>
|
||||
</RevealKeepAlive>
|
||||
</CacheProvider>
|
||||
);
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user