reveal-3d

Reveal 3D Viewer

バンドルされたソースを対象のアプリにコピーして、Cognite Reveal 3D ビューアーを Dune アプリに追加します。CDF の CAD モデルをレンダリングし、モデルの閲覧、モデル ID／リビジョン ID の直接指定、FDM にリンクされたアセットに対応します。

可視化する FDM インスタンス：$ARGUMENTS

こんな場合に使用します

ユーザーが、CDF の 3D／CAD コンテンツ用にインタラクティブな Cognite Reveal ビューアーを Dune アプリに埋め込みたい場合に使用します。

静的な図、グラフの可視化、または無関係なカスタム 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 ポリフィル、process／util／assert の手動エイリアス、three エイリアス、重複排除設定、worker.format: 'es' を適用します。

6. 実装パターンを選択します。 DMInstanceRef をすでに持っていて、Core DM の 3D リンクを確認済みでない限り、パターン B（モデルブラウザーまたはモデル ID の直接指定）を使用します。全例については、implementation.md を参照してください。

7. プロバイダーの配置を安定させます。 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 の依存関係向けブラウザー用ポリフィル
ajv	^8	モノレポで古い推移的 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 ピア要件を確認し、必要に応じて three のバージョンを合わせてください。

vite-plugin-node-polyfills はインストールしないでください。vite-config.md の明示的な Vite エイリアスを使用してください。

重要なルール

• ViewerContent に含めるのは RevealCanvas と Reveal3DResources のみです。プロバイダーは含めません。
• Reveal3DResources に渡す resources は useMemo でメモ化する必要があります。
• onModelsLoaded、onSelect などのコールバックは useCallback でメモ化する必要があります。
• RevealProvider に渡す SDK は、client.project をキーとして useMemo でメモ化する必要があります。
• RevealCanvas は親要素いっぱいに広がります。親要素には明示的な高さを指定する必要があります。
• ルート／ページを追加する際は、キャンバスの負荷が大きいビューアーのコンテンツを React.lazy と Suspense で遅延読み込みします。

高度なリファレンス

コピーしたバンドルの API とエクスポートについては、code/README.md をお読みください。

モデルブラウザーと FDM にリンクされた実装については、references/implementation.md をお読みください。

Vite、ワーカー、ポリフィル、トラブルシューティングの詳細については、references/vite-config.md をお読みください。

検証チェックリスト

• skills/reveal-3d/code/reveal/ のすべてのファイルを、アプリ内の機能フォルダーにコピーしました。
• インポート先がアプリ内のフォルダーを指しています（例：@/features/reveal-3d）。
• アプリは、旧外部パッケージから Reveal ヘルパーをインポートしていません。
• 必要な依存関係が package.json に含まれています。
• main.tsx は、ほかのインポートより前に process ポリフィルを読み込んでいます。
• vite.config.ts で、手動エイリアス、重複排除、three のシングルトンエイリアス、worker.format: 'es' を使用しています。
• CacheProvider と RevealKeepAlive は常にマウントされ、モデル選択が条件付きの場合は RevealProvider も条件付きでマウントされます。
• ビューアーコンテナーに明示的な高さが設定されています。
• 型チェックとビルドが成功します。