# 空間 UI プラグインを追加する — Dnalogel

読み込み済み Five SDK シーンに Dnalogel のタグ、計測、カメラ操作を登録します。

Canonical: https://developer.realsee.ai/ja/docs/dnalogel/quickstart
Source: https://developer.realsee.ai/ja/docs/dnalogel/quickstart.md
Language: ja

# 空間 UI プラグインを追加する

[Five SDK クイックスタート](https://developer.realsee.ai/ja/docs/five-sdk/quickstart) から始め、公開デモが **Ready** になることを確認してからプラグインを追加します。ネットワークや Work 読み込みの問題を先に解消してください。

<span id="run-the-maintained-public-browser-demo" class="docs-anchor-alias" aria-hidden="true"></span><span id="run-the-public-browser-demo" class="docs-anchor-alias" aria-hidden="true"></span>

## 公開ブラウザーデモを実行する

[リリースマニフェスト](https://developer.realsee.ai/starters/react-five/manifest.json) または上の「サンプルをダウンロード」から公式 ZIP を取得します。新しいディレクトリに展開し、`realsee-react-five/extensions` でターミナルを開きます。この任意プロジェクトは独立した依存関係とロックファイルを持ちます：

```bash
npm ci
npm run check
npm run build
npm run dev
```

表示されたローカル URL（通常 `http://127.0.0.1:4188`）を開きます。公開版 `@realsee/open-works@0.1.1` を使い、WebGL とアセットへの接続が必要ですが認証情報や Team API は不要です。下記と同じタスク関数を使い、メインスターターの依存関係を変えずに実行できます。

Ready の後に **Add text hotspot** と **Start measurement** を使います。画面上で点を追加して計測を完了し、ホットスポットを削除して cleanup を確認します。

<span id="keep-a-compatible-dependency-set" class="docs-anchor-alias" aria-hidden="true"></span>

## 互換性のある依存関係を保つ

Five SDK 6.9.2、React 18.3.1、Three.js 0.117.1、Dnalogel 3.81.10 が対象です。互換性のある新しいスターター内で実行します：

```bash
npm install --save-exact @realsee/dnalogel@3.81.10
npm run check
npm run build
```

別プロジェクトに追加する場合は先に `package.json` を確認します。Five SDK・React・Three.js が異なる場合は停止して整合させてください。`--force`、peer 検証の回避、ロックファイルの置換は行いません。Vreo が必要とする Dnalogel 3.81.10 を無断で 3.81.12 に上げないでください。

同梱の `extensions` は互換バージョンを使用済みです。ロックファイルを保持し `npm ci` を使ってください。上の install は自分の互換プロジェクトに追加するためのものです。

スターターを拡張する際は `@realsee/five` → `protobufjs` 8.8.1 の npm override を保持します。`extensions` にも同じ指定があります。

<span id="register-the-concrete-plugins" class="docs-anchor-alias" aria-hidden="true"></span>

## 具体的なプラグインを登録する

コンテナーに 0 でない幅と高さを指定します。Five SDK ガイドと同じ解析済みでブラウザーに渡せる `Work` を使い、同じコンテナーに別の Five を作らず、この関数を 1 回呼びます。

```ts title="examples/sdk-guides/src/dnalogel/viewer.ts"
import { Five, type Work } from '@realsee/five'
import { CameraMovementPlugin, MeasurePlugin, PanoTagPlugin } from '@realsee/dnalogel'

export async function createSpatialInterface(container: HTMLElement, work: Work) {
  const five = new Five({ plugins: [
    [PanoTagPlugin, 'tags', {}],
    [MeasurePlugin, 'measure', { unit: 'm', precision: 2 }],
    [CameraMovementPlugin, 'camera', {}]
  ] })
  five.appendTo(container, { width: container.clientWidth, height: container.clientHeight })
  const resize = new ResizeObserver(() => five.refresh({ width: container.clientWidth, height: container.clientHeight }))
  resize.observe(container)
  try {
    await five.load(work, 'initial')
    await five.ready()
  } catch (error) {
    resize.disconnect()
    five.dispose()
    throw error
  }
  return {
    five,
    tags: five.plugins.tags as ReturnType<typeof PanoTagPlugin>,
    measure: five.plugins.measure as ReturnType<typeof MeasurePlugin>,
    camera: five.plugins.camera as ReturnType<typeof CameraMovementPlugin>,
    dispose() { resize.disconnect(); five.dispose() }
  }
}
```

生成関数は Five の設置、サイズ監視、Work 読み込み、準備完了待ちを行い、3 つのコントローラーと cleanup を返します。シーン交換やアンマウント時は `dispose()` を呼び、次の Work には新しく生成します。

<span id="add-one-task" class="docs-anchor-alias" aria-hidden="true"></span>

## タスクを追加する

- [パノラマタグ](https://developer.realsee.ai/ja/docs/dnalogel/panorama-tags) の `addTextHotspot(result.tags, position)` を呼びます。
- [計測](https://developer.realsee.ai/ja/docs/dnalogel/measure) の `bindMeasurement(result.measure, report)` にボタンを接続します。
- [カメラ移動](https://developer.realsee.ai/ja/docs/dnalogel/camera-flows) の `moveAndLook(result.five, result.camera, panoIndex)` を呼びます。

座標と index は現在の Work に属します。別シーンの座標を公開サンプルに流用できるとは限りません。Team の Work とプラグイン用データはバックエンドで取得し、SK をブラウザーに含めないでください。

<span id="verify" class="docs-anchor-alias" aria-hidden="true"></span>

## 確認する

サイズ変更、準備完了、プラグインの結果、再マウント時の cleanup を確認します。

ほかのコントローラーは [公開エクスポートの型定義](https://unpkg.com/@realsee/dnalogel@3.81.10/libs/index.d.ts) を参照してください。