Reveal 3d

Reveal 3D Viewer

Add a Cognite Reveal 3D viewer to a Flows app using the published @cognite/reveal-widget npm package. Renders CAD models, point clouds, 360° image collections, and CDF scenes from CDF, with model browsing or direct model/revision IDs.

DM instance to visualize: $ARGUMENTS

Use This When

The user wants to embed an interactive Cognite Reveal viewer for CDF 3D content in a Flows app.

Do not use this skill for static diagrams, graph visualizations, or unrelated custom Three.js scenes.

Do not use the deprecated app-local "copy the bundle" approach — that pattern (a src/features/reveal-3d/ folder of copied provider/hook source) is replaced by installing @cognite/reveal-widget directly. If an app still has a copied bundle from a prior integration, migrate it to this package rather than extending it.

Prerequisites

• The app uses React + TypeScript and is wrapped in @cognite/app-sdk's CogniteSdkProvider (Flows auth), which supplies the CogniteClient (sdk) via useCogniteSdk() from @cognite/app-sdk/react. @cognite/dune is the CLI used to scaffold/deploy the app, not the runtime auth library — apps created with npx @cognite/dune apps create depend on @cognite/app-sdk for this, not @cognite/dune itself (the useDune()/@cognite/dune/auth hook only exists for legacy --classic scaffolds).
• The CDF project has 3D models, or the user has supplied direct model/revision IDs or a CDM (externalId/space) model reference.
• For DM-linked 3D, the instance/model must be identifiable via a CDM externalId/space pair or a classic modelId/revisionId; instance highlighting works once a model is loaded and the instance is contextualized (mapped) to it.
• Determine whether the project's 3D content lives in the Core Data Model or the classic 3D API before setting viewerOptions.useCoreDm — don't default it to true. There's no single flag for this; csp-and-fixes.md gives the exact SDK calls to check directly.

Integration Workflow

Follow these steps in order. Adapt paths to the target app's conventions instead of inventing new ones.

1. Inspect the target app. Read package.json, vite.config.ts, src/main.tsx, and the app's folder/alias conventions.
2. Install the package and peers with the app's package manager. See Dependencies. Reuse existing pinned React and SDK versions where they satisfy the peer ranges.
3. Configure Vite. Read vite-config.md and add the three/@cognite/reveal dedupe entry. No process/util/assert polyfills are needed — the package ships browser-ready.
4. Configure `manifest.json`'s CSP allowances for whatever the scene/model actually contains (scene ground-plane/skybox textures, 360° image collections). Read csp-and-fixes.md — it also covers the app-side fix point clouds need (manifest.json can't grant it directly) and a StrictMode gotcha, so read it even if the app has no scenes/360 content yet.
5. Add a controller class that wraps RevealWidgetController and drives it imperatively (load resources, style/highlight instances, control the camera) from your own event handlers — not from useEffect reacting to prop changes. See implementation.md.
6. Mount `RevealWidget` with viewerOptions={{ sdk, useCoreDm }} (set useCoreDm per the project, not hardcoded — see csp-and-fixes.md) and setControllerRef inside a container with an explicit height. RevealWidget manages its own internal Reveal context — do not wrap it in another provider from this package.
7. Choose the resource pattern. Use the model-browser pattern (sdk.models3D.list() + classic modelId/revisionId) as the default unless the user has already supplied a CDM externalId/space model reference. Full examples in implementation.md.
8. Clean up. Call .remove() on any Reveal3DResourceHandle returned by addResource when it's no longer needed (selection change, unmount).
9. Run typecheck and build (tsc --noEmit, pnpm build, etc.) and fix any dependency/peer-version issues.

Minimal Example

import { useRef } from 'react';
import type { CogniteClient } from '@cognite/sdk';
import {
  RevealWidget,
  type Reveal3DResourceHandle,
  type RevealWidgetController,
  type ThreeDResourceIdentifier,
} from '@cognite/reveal-widget';

class ThreeDViewerController {
  private model: Reveal3DResourceHandle | undefined;

  constructor(private readonly widgetController: RevealWidgetController) {}

  async loadModel(resource: ThreeDResourceIdentifier): Promise<void> {
    this.model = await this.widgetController.addResource(resource);
    this.widgetController.cameraController.focusModel(this.model);
  }

  dispose(): void {
    this.model?.remove();
  }
}

export function ViewerPage({
  sdk,
  resource,
}: {
  sdk: CogniteClient;
  resource: ThreeDResourceIdentifier;
}) {
  const viewerRef = useRef<ThreeDViewerController>();

  function handleWidgetController(widgetController: RevealWidgetController | undefined) {
    viewerRef.current?.dispose();

    if (widgetController === undefined) {
      viewerRef.current = undefined;
      return;
    }

    const viewer = new ThreeDViewerController(widgetController);
    void viewer.loadModel(resource);
    viewerRef.current = viewer;
  }

  return (
    <div style={{ width: '100%', height: '70vh', position: 'relative' }}>
      <RevealWidget
        viewerOptions={{ sdk, useCoreDm }} // set per the project — see csp-and-fixes.md
        setControllerRef={handleWidgetController}
      />
    </div>
  );
}

Dependencies

Suggested versions are starting points. If the target app already pins compatible versions, defer to the app.

Everything else (three, @tanstack/react-query, @base-ui/react, @floating-ui/react, @tabler/icons-react, dayjs, lodash-es, ml-matrix, random-seed, @cognite/aura, @cognite/reveal-components) is a transitive dependency of the package and installs automatically — do not add it manually unless the app needs to pin a version, or unless app code imports from it directly. The model-browser pattern in implementation.md does exactly that with @tanstack/react-query (useInfiniteQuery/useQuery) — add it as a direct dependency in that case, since importing from an undeclared transitive dependency breaks under strict package managers like pnpm.

Example install (pnpm; adapt to the app's package manager):

pnpm add @cognite/reveal-widget @cognite/reveal@4.36.0 @cognite/sdk react react-dom

@cognite/reveal-widget@0.2.0's own peer range still says @cognite/reveal@4.35.3, but its dependency @cognite/reveal-components hardcodes @cognite/reveal@4.36.0 internally. Pin the app to 4.36.0 and confirm the lockfile resolves a single @cognite/reveal version — the peer range is stale, and a real version split here (unlike a resolve.dedupe gap) breaks Reveal's shared viewer state silently.

Do not copy any source bundle into the app and do not install process, util, assert, ajv, or vite-plugin-node-polyfills for this package — none of that is needed.

Critical Rules