reveal-3d

Reveal 3D Viewer

将捆绑的源代码复制到目标应用，即可在 Dune 应用中添加 Cognite Reveal 3D 查看器。此查看器可渲染来自 CDF 的 CAD 模型，并支持浏览模型、直接指定模型 ID／修订版 ID，或使用关联到 FDM 的资产。

要可视化的 FDM 实例：$ARGUMENTS

适用场景

当用户希望在 Dune 应用中嵌入交互式 Cognite Reveal 查看器，以展示 CDF 3D／CAD 内容时使用。

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

前提条件

• 应用使用 React + TypeScript，并由 @cognite/dune 进行身份验证包装。
• 应用已配置来自 @tanstack/react-query 的 QueryClientProvider。
• CDF 项目中有 3D 模型，或用户已提供直接的模型 ID／修订版 ID。
• 对于关联到 FDM 的 3D 内容，实例必须通过 Core DM 建立关联（CogniteVisualizable.object3D -> CogniteCADNode）。

集成工作流

按顺序执行以下步骤。根据目标应用的惯例调整路径，不要凭空创建新路径。

1. 检查目标应用。 阅读 package.json、vite.config.ts、src/main.tsx，以及应用的文件夹和别名惯例。

2. 安装缺失的依赖项，使用应用的包管理器。参见依赖项。复用现有锁定版本的 React、Dune、SDK 和 React Query。

3. 将代码包复制到应用中。 将 skills/reveal-3d/code/reveal/ 中的所有文件复制到应用本地的功能目录，通常为：

   src/features/reveal-3d/
   

4. 从本地目录导入，切勿从技能目录或旧的外部包导入。使用常见的 @/* 别名时：

   import { CacheProvider, RevealKeepAlive, RevealProvider } from '@/features/reveal-3d';
   

5. 配置 Vite 和 main.tsx。 阅读 vite-config.md，并应用 process polyfill、手动配置的 process／util／assert 别名、three 别名、去重设置以及 worker.format: 'es'。

6. 选择实现模式。 除非已有 DMInstanceRef 且已确认 Core DM 3D 关联，否则使用模式 B（模型浏览器或直接指定模型 ID）。完整示例请阅读 implementation.md。

7. 保持 Provider 的位置稳定。 CacheProvider 和 RevealKeepAlive 始终在页面／应用级别挂载。仅在选中模型或已关联模型时，才有条件地挂载 RevealProvider。

8. 运行类型检查和构建（tsc --noEmit、pnpm build 等），并解决复制代码的导入或依赖项问题。

最小示例

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>
  );
}

依赖项

建议版本仅供起步参考。如果目标应用已锁定兼容版本，以应用中的版本为准。

包	建议版本	用途
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	避免在 monorepo 中解析到较旧的传递依赖 AJV
@types/three	最新开发依赖	TypeScript 类型

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

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 别名。

关键规则

• ViewerContent 仅包含 RevealCanvas 和 Reveal3DResources；不要包含 Provider。
• 传给 Reveal3DResources 的 resources 必须使用 useMemo 进行记忆化。
• onModelsLoaded、onSelect 等回调必须使用 useCallback 进行记忆化。
• 传给 RevealProvider 的 SDK 必须使用 useMemo 进行记忆化，并以 client.project 为依赖项。
• RevealCanvas 会填满其父元素；父元素必须显式设置高度。
• 添加路由／页面时，如果查看器内容占用大量画布资源，请使用 React.lazy + Suspense 延迟加载。

高级参考

有关复制的 bundle API 和导出内容，请阅读 code/README.md。

有关模型浏览器和 FDM 关联实现，请阅读 references/implementation.md。

有关 Vite、worker、polyfill 和故障排查的详细信息，请阅读 references/vite-config.md。

验证清单

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