reveal-3d

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reveal 3D Viewer

Reveal 3D查看器

Add a Cognite Reveal 3D viewer to a Flows app by copying the bundled source into the target app. Renders CAD models from CDF, with support for model browsing, direct model/revision IDs, or FDM-linked assets.

FDM instance to visualize: $ARGUMENTS

通过将打包后的源代码复制到目标应用中，为Flows应用添加Cognite Reveal 3D查看器。可渲染来自CDF的CAD模型，支持模型浏览、直接模型/版本ID或FDM关联资产。

要可视化的FDM实例：$ARGUMENTS

Use This When

适用场景

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

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

用户希望在Flows应用中嵌入用于CDF 3D/CAD内容的交互式Cognite Reveal查看器时。

请勿将此技能用于静态图表、图形可视化或无关的自定义Three.js场景。

Prerequisites

前提条件

The app uses React + TypeScript and is wrapped in
```
@cognite/dune
```
auth (Flows auth).

The app has a

QueryClientProvider

from

@tanstack/react-query

The CDF project has 3D models, or the user has supplied direct model/revision IDs.
For FDM-linked 3D, the instance must be linked through Core DM (
```
CogniteVisualizable.object3D
```
->
```
CogniteCADNode
```
).

应用使用React + TypeScript，并通过
```
@cognite/dune
```
认证（Flows认证）。

应用包含来自

@tanstack/react-query

的

QueryClientProvider

。

CDF项目拥有3D模型，或用户已提供直接的模型/版本ID。
对于FDM关联的3D模型，实例必须通过Core DM（
```
CogniteVisualizable.object3D
```
->
```
CogniteCADNode
```
）建立关联。

Integration Workflow

集成流程

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

Inspect the target app. Read
```
package.json
```
,
```
vite.config.ts
```
,
```
src/main.tsx
```
, and the app's folder/alias conventions.
Install missing dependencies with the app's package manager. See Dependencies. Reuse existing pinned React, Flows, SDK, and React Query versions.
Copy the bundle into the app. Copy every file from
```
skills/reveal-3d/code/reveal/
```
into an app-local feature folder, typically:
text
```
src/features/reveal-3d/
```
Import from the local folder, never from the skill directory or the old external package. With a typical
```
@/*
```
alias:
tsx
```
import { CacheProvider, RevealKeepAlive, RevealProvider } from '@/features/reveal-3d';
```
Configure Vite and
main.tsx
. Read vite-config.md and apply the process polyfill, manual
```
process
```
/
```
util
```
/
```
assert
```
aliases,
```
three
```
alias, dedupe settings, and
```
worker.format: 'es'
```
.
Choose the implementation pattern. Use Pattern B (model browser or direct model ID) unless you already have a
```
DMInstanceRef
```
and confirmed Core DM 3D linkage. For full examples, read implementation.md.
Keep provider placement stable.
```
CacheProvider
```
and
```
RevealKeepAlive
```
are always mounted at page/app level.
```
RevealProvider
```
is conditional, only when a model is selected or linked.
Run typecheck and build (
```
tsc --noEmit
```
,
```
pnpm build
```
, etc.) and fix any copied-import or dependency issues.

按以下顺序执行步骤。根据目标应用的约定调整路径，而非创建新路径。

检查目标应用。阅读
```
package.json
```
、
```
vite.config.ts
```
、
```
src/main.tsx
```
以及应用的文件夹/别名约定。
使用应用的包管理器安装缺失的依赖。参见依赖项。复用已有的固定版本React、Flows、SDK和React Query。
将包复制到应用中。将
```
skills/reveal-3d/code/reveal/
```
中的所有文件复制到应用本地的功能文件夹中，通常为：
text
```
src/features/reveal-3d/
```
从本地文件夹导入，绝不要从技能目录或旧的外部包导入。使用典型的
```
@/*
```
别名：
tsx
```
import { CacheProvider, RevealKeepAlive, RevealProvider } from '@/features/reveal-3d';
```
配置Vite和
main.tsx
。阅读vite-config.md并应用process polyfill、手动的
```
process
```
/
```
util
```
/
```
assert
```
别名、
```
three
```
别名、去重设置以及
```
worker.format: 'es'
```
。
选择实现模式。除非您已经拥有
```
DMInstanceRef
```
并确认Core DM 3D关联，否则使用模式B（模型浏览器或直接模型ID）。完整示例请阅读implementation.md。
保持Provider位置稳定。
```
CacheProvider
```
和
```
RevealKeepAlive
```
始终挂载在页面/应用级别。
```
RevealProvider
```
是条件性的，仅在选择或关联模型时挂载。
运行类型检查和构建（
```
tsc --noEmit
```
、
```
pnpm build
```
等）并修复任何复制导入或依赖问题。

Minimal Example

最简示例

tsx

import { useCallback, useMemo } from 'react';
import type { CogniteClient } from '@cognite/sdk';
import {
  CacheProvider,
  Reveal3DResources,
  RevealCanvas,
  RevealKeepAlive,
  RevealProvider,
  type AddCadResourceOptions,
} from '@/features/reveal-3d';

type SelectedModel = { modelId: number; revisionId: number };

function ViewerContent({ modelId, revisionId }: SelectedModel) {
  const resources = useMemo<AddCadResourceOptions[]>(
    () => [{ modelId, revisionId }],
    [modelId, revisionId]
  );
  const onLoaded = useCallback(() => {}, []);

  return (
    <RevealCanvas>
      <Reveal3DResources resources={resources} onModelsLoaded={onLoaded} />
    </RevealCanvas>
  );
}

export function ViewerPage({
  sdk,
  selected,
}: {
  sdk: CogniteClient;
  selected: SelectedModel | null;
}) {
  const memoizedSdk = useMemo(() => sdk, [sdk.project]);

  return (
    <CacheProvider>
      <RevealKeepAlive>
        <div style={{ width: '100%', height: '70vh', position: 'relative' }}>
          {selected && (
            <RevealProvider sdk={memoizedSdk}>
              <ViewerContent
                modelId={selected.modelId}
                revisionId={selected.revisionId}
              />
            </RevealProvider>
          )}
        </div>
      </RevealKeepAlive>
    </CacheProvider>
  );
}

tsx

import { useCallback, useMemo } from 'react';
import type { CogniteClient } from '@cognite/sdk';
import {
  CacheProvider,
  Reveal3DResources,
  RevealCanvas,
  RevealKeepAlive,
  RevealProvider,
  type AddCadResourceOptions,
} from '@/features/reveal-3d';

type SelectedModel = { modelId: number; revisionId: number };

function ViewerContent({ modelId, revisionId }: SelectedModel) {
  const resources = useMemo<AddCadResourceOptions[]>(
    () => [{ modelId, revisionId }],
    [modelId, revisionId]
  );
  const onLoaded = useCallback(() => {}, []);

  return (
    <RevealCanvas>
      <Reveal3DResources resources={resources} onModelsLoaded={onLoaded} />
    </RevealCanvas>
  );
}

export function ViewerPage({
  sdk,
  selected,
}: {
  sdk: CogniteClient;
  selected: SelectedModel | null;
}) {
  const memoizedSdk = useMemo(() => sdk, [sdk.project]);

  return (
    <CacheProvider>
      <RevealKeepAlive>
        <div style={{ width: '100%', height: '70vh', position: 'relative' }}>
          {selected && (
            <RevealProvider sdk={memoizedSdk}>
              <ViewerContent
                modelId={selected.modelId}
                revisionId={selected.revisionId}
              />
            </RevealProvider>
          )}
        </div>
      </RevealKeepAlive>
    </CacheProvider>
  );
}

Dependencies

依赖项

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

Package	Suggested version	Purpose
`react` / `react-dom`	app version	UI framework
`@cognite/dune`	app version	Authenticated SDK via `useDune()`
`@cognite/reveal`	`^4.30.0`	Reveal viewer runtime
`@cognite/sdk`	`^10.0.0`	CDF API client
`@tanstack/react-query`	`^5.90.21`	Reveal/FDM data fetching hooks
`three`	`^0.180.0`	Three.js singleton used by Reveal
`process` , `util` , `assert`	latest	Browser polyfills for Reveal dependencies
`ajv`	`^8`	Avoids older transitive AJV resolution in monorepos
`@types/three`	latest dev dep	TypeScript types

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

bash

pnpm add @cognite/reveal @cognite/sdk @tanstack/react-query three process util assert ajv
pnpm add -D @types/three

After install, check

@cognite/reveal

three

peer requirement and align

three

if needed.

Do not install

vite-plugin-node-polyfills

; use the explicit Vite aliases in vite-config.md.

建议版本为起始参考值。如果目标应用已固定兼容版本，请以应用为准。

包	建议版本	用途
`react` / `react-dom`	应用版本	UI框架
`@cognite/dune`	应用版本	通过 `useDune()` 实现认证SDK
`@cognite/reveal`	`^4.30.0`	Reveal查看器运行时
`@cognite/sdk`	`^10.0.0`	CDF API客户端
`@tanstack/react-query`	`^5.90.21`	Reveal/FDM数据获取钩子
`three`	`^0.180.0`	Reveal使用的Three.js单例
`process` , `util` , `assert`	最新版本	Reveal依赖的浏览器polyfill
`ajv`	`^8`	避免单体仓库中旧版本的传递性AJV解析
`@types/three`	最新开发依赖	TypeScript类型定义

示例安装（使用pnpm；根据应用的包管理器调整）：

bash

pnpm add @cognite/reveal @cognite/sdk @tanstack/react-query three process util assert ajv
pnpm add -D @types/three

安装后，检查

@cognite/reveal

的

three

peer依赖要求，必要时调整

three

版本。

请勿安装

vite-plugin-node-polyfills

；使用vite-config.md中的显式Vite别名。

Critical Rules

关键规则

ViewerContent

contains only

RevealCanvas

and

Reveal3DResources

; no providers.

```
resources
```
passed to
```
Reveal3DResources
```
must be memoized with
```
useMemo
```
.
```
onModelsLoaded
```
,
```
onSelect
```
, and similar callbacks must be memoized with
```
useCallback
```
.
The SDK passed to
```
RevealProvider
```
must be memoized with
```
useMemo
```
keyed on
```
client.project
```
.
```
RevealCanvas
```
fills its parent; the parent must have an explicit height.
Lazy-load canvas-heavy viewer content with
```
React.lazy
```
+
```
Suspense
```
when adding a route/page.

ViewerContent

仅包含

RevealCanvas

和

Reveal3DResources

；不包含Provider。

传递给
```
Reveal3DResources
```
的
```
resources
```
必须使用
```
useMemo
```
进行记忆化。
```
onModelsLoaded
```
、
```
onSelect
```
及类似回调必须使用
```
useCallback
```
进行记忆化。
传递给
```
RevealProvider
```
的SDK必须使用
```
useMemo
```
并以
```
client.project
```
为键进行记忆化。
```
RevealCanvas
```
填充其父容器；父容器必须有明确的高度。
添加路由/页面时，使用
```
React.lazy
```
+
```
Suspense
```
懒加载占用大量画布资源的查看器内容。

Advanced Reference

进阶参考

For the copied bundle API and exports, read

code/README.md

For model browser and FDM-linked implementations, read

references/implementation.md

For Vite, worker, polyfill, and troubleshooting details, read

references/vite-config.md

关于复制包的API和导出，请阅读

code/README.md

。

关于模型浏览器和FDM关联实现，请阅读

references/implementation.md

。

关于Vite、worker、polyfill和故障排除细节，请阅读

references/vite-config.md

。

Verification Checklist

验证清单

All files from
```
skills/reveal-3d/code/reveal/
```
were copied into an app-local feature folder.
Imports point to the app-local folder (e.g.
```
@/features/reveal-3d
```
).
The app does not import Reveal helpers from the old external package.
Required dependencies are present in
```
package.json
```
.
```
main.tsx
```
starts with the
```
process
```
polyfill before other imports.
```
vite.config.ts
```
uses manual aliases, dedupe,
```
three
```
singleton alias, and
```
worker.format: 'es'
```
.
```
CacheProvider
```
and
```
RevealKeepAlive
```
are always mounted;
```
RevealProvider
```
is conditional when model selection is conditional.
The viewer container has an explicit height.
Typecheck and build pass.

已将
```
skills/reveal-3d/code/reveal/
```
中的所有文件复制到应用本地的功能文件夹中。
导入指向应用本地文件夹（例如
```
@/features/reveal-3d
```
）。
应用未从旧的外部包导入Reveal工具。
```
package.json
```
中包含所需的依赖项。
```
main.tsx
```
在其他导入之前启动process polyfill。
```
vite.config.ts
```
使用手动别名、去重、
```
three
```
单例别名以及
```
worker.format: 'es'
```
。
```
CacheProvider
```
和
```
RevealKeepAlive
```
始终挂载；当模型选择为条件性时，
```
RevealProvider
```
为条件性挂载。
查看器容器有明确的高度。
类型检查和构建通过。