reveal-3d

Reveal 3D Viewer

公開済みの @cognite/reveal-widget npm パッケージを使って、Flows アプリに Cognite Reveal 3D ビューアーを追加します。CDF の CAD モデル、点群、360°画像コレクション、CDF シーンを表示でき、モデルの参照、またはモデル／リビジョン ID の直接指定に対応しています。

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

Use This When

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

静的な図、グラフの可視化、または無関係なカスタム Three.js シーンには、このスキルを使用しないでください。

非推奨のアプリ内「バンドルをコピーする」方式は使用しないでください。この方式（プロバイダー／フックのソースをコピーした src/features/reveal-3d/ フォルダー）は、@cognite/reveal-widget を直接インストールする方式に置き換えられています。以前の統合でコピーしたバンドルが残っているアプリでは、拡張するのではなく、このパッケージに移行してください。

Prerequisites

• アプリで React + TypeScript を使用し、@cognite/app-sdk の CogniteSdkProvider（Flows 認証）でラップされている必要があります。これにより、@cognite/app-sdk/react の useCogniteSdk() を通じて CogniteClient（sdk）が提供されます。@cognite/cli はアプリのスキャフォールディング／デプロイに使う CLI であり、実行時の認証ライブラリではありません。npx @cognite/cli apps create で作成されたアプリでは、この用途に @cognite/cli 自体ではなく @cognite/app-sdk が依存関係として含まれます（useDune()／@cognite/dune/auth フックは、レガシーな --classic スキャフォールドにのみ存在します）。
• CDF プロジェクトに 3D モデルがあるか、ユーザーからモデル／リビジョン ID、または CDM のモデル参照（externalId／space）が提供されている必要があります。
• DM に関連付けられた 3D では、CDM の externalId／space のペア、または従来の modelId／revisionId を使って、インスタンス／モデルを特定できる必要があります。モデルを読み込み、インスタンスがモデルにコンテキスト化（マッピング）されると、インスタンスのハイライト表示が機能します。
• viewerOptions.useCoreDm を設定する前に、プロジェクトの 3D コンテンツが Core Data Model と従来の 3D API のどちらに存在するかを確認してください。これをデフォルトで true にしないでください。これを判定する単一のフラグはありません。csp-and-fixes.md に、直接確認するための正確な SDK 呼び出しが記載されています。

統合ワークフロー

以下の手順を順番に実行してください。新しいパスを独自に作るのではなく、対象アプリの規約に合わせてパスを調整してください。

1. 対象アプリを調査します。 package.json、vite.config.ts、src/main.tsx、およびアプリのフォルダー／エイリアスの規約を確認します。
2. アプリのパッケージマネージャーを使ってパッケージとピア依存関係をインストールします。Dependenciesを参照してください。既存の固定済み React と SDK のバージョンがピア依存関係の範囲を満たす場合は、それらを再利用します。
3. Vite を設定します。 vite-config.mdを確認し、three／@cognite/reveal の重複排除エントリーを追加します。プロセス／ユーティリティ／アサートのポリフィルは不要です。パッケージはブラウザー対応済みです。
4. manifest.json の CSP 許可設定を、シーン／モデルに実際に含まれるもの（シーンの地面／スカイボックスのテクスチャ、360°画像コレクション）に合わせて設定します。 csp-and-fixes.mdを確認してください。点群に必要なアプリ側の修正箇所（manifest.json では直接許可できません）と StrictMode の注意点も説明されているため、アプリにシーンや360°コンテンツがまだなくても必ず確認してください。
5. コントローラークラスを追加します。 RevealWidgetController をラップし、useEffect でプロパティの変更に反応させるのではなく、独自のイベントハンドラーから命令的に操作（リソースの読み込み、インスタンスのスタイル設定／ハイライト表示、カメラの制御）します。implementation.mdを参照してください。
6. RevealWidget をマウントします。 viewerOptions={{ sdk, useCoreDm }}（useCoreDm はハードコードせず、プロジェクトに合わせて設定します。csp-and-fixes.mdを参照してください）、setControllerRef、ホストアプリを識別する文字列である必須の appIdentifier を指定し、高さを明示的に設定したコンテナー内に配置します。RevealWidget は内部の Reveal コンテキストを独自に管理するため、このパッケージの別のプロバイダーでラップしないでください。
7. リソースのパターンを選択します。 ユーザーから CDM の externalId／space モデル参照がすでに提供されている場合を除き、モデルブラウザーパターン（sdk.models3D.list() と従来の modelId／revisionId）をデフォルトとして使用します。詳しい例はimplementation.mdを参照してください。
8. クリーンアップします。 不要になった addResource の戻り値である Reveal3DResourceHandle に対して .remove() を呼び出します（選択の変更時、アンマウント時）。
9. 型チェックとビルドを実行し（tsc --noEmit、pnpm build など）、依存関係やピア依存関係のバージョンに関する問題を修正します。

最小限の例

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}
        appIdentifier="my-flows-app"
      />
    </div>
  );
}

依存関係

推奨バージョンは開始時の目安です。対象アプリですでに互換性のあるバージョンが固定されている場合は、アプリの設定を優先してください。

パッケージ	推奨バージョン	用途
@cognite/reveal-widget	^0.3.0	RevealWidget コンポーネントとその型
react / react-dom	^18.3.1（peer）	UI フレームワーク — ピア依存関係であり、アプリと一致させる必要があります
@cognite/reveal	4.36.0	Reveal ビューアーのランタイム — 完全一致が必要です。@cognite/reveal-widget 自身が宣言しているピア依存関係の範囲にある 4.35.3 ではなく、4.36.0 に固定してください。下記の注を参照してください。
@cognite/sdk	^10.14.0（peer）	CDF API クライアント — ピア依存関係です

その他すべて（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）はこのパッケージの推移的依存関係であり、自動的にインストールされます。アプリでバージョンを固定する必要がある場合、またはアプリのコードから直接インポートする場合を除き、手動で追加しないでください。implementation.md のモデルブラウザーのパターンでは、@tanstack/react-query（useInfiniteQuery／useQuery）を実際に直接インポートしています。この場合は直接依存関係として追加してください。宣言されていない推移的依存関係からのインポートは、pnpm のような厳格なパッケージマネージャーでは問題が発生するためです。

インストール例（pnpm の場合。アプリのパッケージマネージャーに合わせてください）：

pnpm add @cognite/reveal-widget @cognite/[email protected] @cognite/sdk react react-dom

@cognite/[email protected] 自身が指定するピア依存関係の範囲は、引き続き @cognite/[email protected] となっています。しかし、依存関係にある @cognite/reveal-components は、内部で @cognite/[email protected] をハードコードしています。アプリでは 4.36.0 に固定し、ロックファイルで @cognite/reveal のバージョンが1つだけ解決されていることを確認してください。ピア依存関係の範囲は古くなっています。また、ここで実際にバージョンが分かれると（resolve.dedupe の不足とは異なり）、Reveal の共有ビューアー状態が気付かないうちに壊れます。

このパッケージでは、ソースバンドルをアプリにコピーしないでください。また、process、util、assert、ajv、vite-plugin-node-polyfills もインストールしないでください。いずれも必要ありません。

重要なルール

• setControllerRef で取得した RevealWidgetController を使って、ウィジェットを命令的に操作してください。Reveal の以前の宣言的なプロバイダーツリー（CacheProvider／RevealProvider／RevealCanvas／Reveal3DResources）を再構築しようとしないでください。この API は古いバンドルをコピーする方式向けであり、このパッケージが公開しているものではありません。
• RevealWidget は内部で独自の Reveal コンテキストをラップします。このパッケージの別のプロバイダーの内側にネストしないでください。
• setControllerRef 内で新しいコントローラークラスのインスタンスを作成する前に、以前のインスタンスを破棄（追跡中のハンドルに対して .remove() を呼び出す .dispose()）してください。また、widgetController が undefined になったとき（アンマウント時）にも破棄してください。
• addResource に渡すリソースは、type／sourceType の組み合わせに対応する識別子の正確な形式である必要があります（implementation.md を参照）。classic と CDM のフィールドを混在させると、型エラーになります。
• インスタンスのハイライトは、読み込み済みモデルにコンテキスト化（マッピング）されているインスタンスにのみ適用されます。先にモデルを読み込み、その後で styleByInstance／focusInstances を呼び出してください。
• RevealWidget のコンテナーには明示的な高さが必要です。ウィジェットは親要素いっぱいに広がります。
• ルート／ページを追加する際は、キャンバスを多用するビューアーコンテンツを React.lazy と Suspense で遅延読み込みしてください。
• useCoreDm は true をデフォルトとして使わず、プロジェクトに合わせる必要があります。そうしないと、誤った 401 エラーや、360 コレクションの処理がエラーを表示せず失敗する問題が発生します。アプリを React.StrictMode でラップしないでください。開発環境で読み込み中に RevealWidget のビューアーを破棄してしまい、本番環境では発生しないエラーが出るためです。ポイントクラウドには、アプリ側で同一オリジンの修正が必要です。manifest.json では、本来必要となる data: の CSP 許可を設定できないためです。これら3点については、csp-and-fixes.md を参照してください。
• appIdentifier（ホストアプリの名前を指定する文字列）は、@cognite/[email protected] 以降、必須のプロパティです。これを指定せずに RevealWidget をマウントすると、型エラーになります。デフォルトでは、ウィジェットは匿名の利用状況メトリクス（リソースの追加やカメラの移動など、どの機能が使われたか）を専用の mixpanel-browser インスタンスに送信します。これを変更するには、任意の tracking プロパティを渡してください。送信を完全に停止するには tracking={{ disabled: true }} を、別の Mixpanel プロジェクトに送信するには tracking={{ mixpanelToken }} を指定します。

詳細リファレンス

リソース識別子の全カタログ（CAD、ポイントクラウド、360画像、シーン）、インスタンスのハイライト、カメラ制御については、implementation.md を参照してください。

Vite／重複排除の設定については、vite-config.md を参照してください。

CSP／manifest.json の許可設定、useCoreDm／StrictMode に関する注意点、ポイントクラウドのアプリ側修正、360 コレクションのトラブルシューティングについては、csp-and-fixes.md を参照してください。

検証チェックリスト

• @cognite/reveal-widget が、互換性のあるバージョンの依存パッケージ（react、react-dom、@cognite/reveal、@cognite/sdk）とともにインストールされています。
• アプリの @cognite/reveal は 4.36.0 に固定されています（@cognite/reveal-widget のピア依存関係の範囲にある古い 4.35.3 ではありません）。また、ロックファイルで解決される @cognite/reveal のバージョンは 1 つだけです。
• ソースバンドルはアプリにコピーされていません。すべてのインポート元は @cognite/reveal-widget であり、アプリのコードから @cognite/reveal-components を直接インポートしていません。
• vite.config.ts に resolve.dedupe: ['three', '@cognite/reveal'] が含まれています（アプリに既存の dedupe エントリーがある場合は、それらも含めます）。
• このパッケージのために process／util／assert のポリフィルや vite-plugin-node-polyfills を追加していません。
• RevealWidget は 1 回だけマウントされ、別の Reveal プロバイダーの内側にネストされていません。コンテナには明示的な高さが設定され、必須の appIdentifier 文字列プロパティが渡されています。
• viewerOptions.useCoreDm は、対象プロジェクトが実際に Core-Data-Model ベースかどうかと一致しています。
• アプリを React.StrictMode でラップしていません。
• アプリが地面や空の背景を含むシーンを読み込む場合、manifest.json で https://*.cognitedata.com に対する img-src が許可されています。また、360° 画像コレクションを読み込む場合は、CSP 違反から確認した実際の署名付き URL のホストに対する connect-src が許可されています。アプリでポイントクラウドのサポートが必要な場合は、同一オリジンの Blob パッチによる修正を適用し、検証済みです。
• コントローラークラスが RevealWidgetController をラップし、setControllerRef 経由で取得して、addResource／styleByInstance／focusInstances／cameraController を命令的に操作しています。
• 新しいコントローラーが設定されたときとアンマウント時（widgetController === undefined）の両方で、コントローラークラスを破棄し、追跡中のリソースハンドルに対して .remove() を呼び出しています。
• リソース識別子では、読み込むモデルに適した type／sourceType の形式を使用しています。
• 型チェックとビルドが成功します。