【Realsee開発者マニュアル】

3D空間アプリ開発の未来へFiveエンジン、Vreo、リアルタイムガイド機能を徹底解説
I. はじめに：Realseeが拓くVR空間再構築の世界
II. 核心技術：３Ｄ空間の再構築とFiveレンダリングエンジン
III. 空間情報の動的表現：Vreo（３Ｄ空間スクリプトプレイヤー）
IV. 豊富な空間インタラクション：@realsee/dnalogel
- 1. dnalogelの役割と抽象化
- 2. 使用方法と依存関係
  - プラグインの登録とメソッドの使用
  - データ依存関係の取得
V. リアルタイム通信と遠隔ガイド：オンラインガイドビューイング
- 1. オンラインガイドビューイングの技術基盤
- 2. 製品アーキテクチャの構成要素
VI. 端末統合とパフォーマンス最適化：VRWebViewと”橋”プロトコル
- 1. VRWebViewがサポートする機能
  - 端末能力の利用
  - 性能と体験の最適化
- 2. “橋”プロトコル（@realsee/jsbridge-x）
VII. 開発時の課題と解決策（FAQ）
VIII. まとめ

3D空間アプリ開発の未来へFiveエンジン、Vreo、リアルタイムガイド機能を徹底解説

I. はじめに：Realseeが拓くVR空間再構築の世界

近年、デジタルトランスフォーメーションの波は、物理空間のデジタル化、特に仮想現実（VR）空間の再構築へと及んでいます。Realsee（realsee.com）は、この VR空間再構築 の分野におけるリーダーとして、空間の取得、表示、再構築の能力を業界全体に提供し、低コストで効率的、かつ目的に合わせたVR空間アプリケーションのソリューションを確立しています。

開発者がRealseeの強力な技術基盤を活用し、独自の三次元空間VRアプリケーションを構築するための核となる要素が、本稿で紹介する一連のツールとサービス群です。これは、単なる静的な3D表示にとどまらず、動的な物語（Vreo）、リアルタイムな共同体験（オンラインガイドビューイング）、そして高度なインタラクションを実現するための土台となります。

この記事では、Realsee開発者プラットフォームの基礎となる技術から、高度な応用モジュールに至るまで、主要なセクションを深掘りしてご紹介します。

II. 核心技術：３Ｄ空間の再構築とFiveレンダリングエンジン

全ての応用の基盤となるのが、３Ｄ空間の再構築 技術と、それをウェブ上で実現する Fiveレンダリングエンジン です。

1. ３Ｄ空間の再構築 (3D Space Reconstruction)

３Ｄ空間の再構築は、Realseeのコア技術能力の一つです。これは、オフラインで収集された空間データに基づいています。Realseeのクラウドサーバーは、以下の技術を通じて、物理空間を正確に再現する三次元モデルを作成します。

自動モデリング (Automatic Modeling)
インテリジェントな空洞充填 (Intelligent Void Filling)
全自動データ抽出 (Fully Automatic Data Extraction)
HDR最適化 (HDR Optimization)

これらの技術により、全てのデータと画像テクスチャが三次元モデルに正確にマッピングされ、リアルな３Ｄ空間 が復元されます。

2. Workデータフォーマット：デジタル空間の記述

三次元空間を表示するための元となるデータが Work データです。

Work は、Realseeが独自に研究開発した ３Ｄ空間のデジタル化記述フォーマット です。このデータは、Realseeのスキャナー、Realsee Lite 全景カメラ、RealseeVR AppなどのRealseeハードウェアデバイスを使用して物理空間をスキャンし、処理した後に生成されます。

Workデータは JSON 形式として定義されており、後述の Five フレームワークがこれを解析することで、ウェブ上で三次元空間をレンダリングします。一つの Five インスタンスは、一度に一つの Work をロードして表示することができますが、異なる Work 間で動的に切り替えることも可能です。

3. Five：ブラウザベースの３Ｄ空間レンダリングエンジン

Five は、Realseeの3D空間レンダリングエンジンであり、Three.jsに基づいて実装され、ブラウザ環境で動作します。

開発者は Fiveエンジン を利用することで、Realseeの３Ｄ空間再構築能力を活用し、独自の３Ｄ空間VRアプリケーションを構築できます。

Fiveエンジンの機能概要

データ解析と描画： FiveはWorkデータを解析し、三次元情報をHTMLの <canvas> タグ内に描画します。
インタラクション： 描画された三次元モデルに対し、クリック、回転、ズーム、移動などのジェスチャーを通じて操作（インタラクション）を行うことができます。
二次開発のサポート： Fiveは、二次開発を容易にするための一連の 状態属性、メソッド、イベント「フック」、ライフサイクル関数 を提供しています。これにより、開発プロジェクトへの統合と拡張が容易になります。

予備知識の重要性： この開発ドキュメントでは、読者がHTML、CSS、JavaScriptに基本的な知識を持っていることを前提としています。もしフロントエンド開発に全く不慣れな場合は、まず基礎知識を習得することが推奨されています。

III. 空間情報の動的表現：Vreo（３Ｄ空間スクリプトプレイヤー）

静的な空間表示を超えて、空間に「物語」と「動き」を与えるのが Vreo (VR Video) です。

1. Vreoの定義と構成要素

Vreo は、Realseeの３Ｄ空間レンダリングエンジン Five と、ユーザーインターフェース構築ライブラリ React を基盤として実装された、Realsee ３Ｄ空間スクリプトプレイヤー です。

Vreoの核心概念は「スクリプト」であり、これは３Ｄ空間の動的な振る舞いを抽象化するものです。伝統的なスクリプトが物語の筋書きや人物像の構築に焦点を当てるのに対し、Vreoスクリプト は ３Ｄ空間情報の動的表現 に重点を置いています。

Vreoスクリプトには、伝統的なスクリプトにおける台詞と 舞台指示 に類似した概念が存在します。

舞台（Stage）： ３Ｄ空間をレンダリングすること自体が舞台となります。
台詞（Dialogue）： デジタルヒューマン（数字人）の題詞や字幕による解説が台詞に相当します。

2. 舞台指示の表現：スクリプトフレーム

伝統的なスクリプトの 舞台指示 は、人物の特徴、心理活動、感情変化、シーンや雰囲気の描写、時間・場所・動作の説明、照明・背景・音響効果の要求といった 叙述的な文字説明 で構成されます。

しかし、Vreoスクリプト では、叙述的な文字説明ではなく、スクリプトフレーム（Script Frame） の形式を用いて舞台指示を定義します。

スクリプトフレーム によって定義される動作には、以下のものが含まれます：

カメラの移動 (Camera Movement)
３Ｄ特殊効果 (3D Special Effects)
空間動作 (Spatial Actions)

Vreoの目的が３Ｄ空間情報の動的表現であるため、人物の形象特徴や心理活動、感情変化といった要求は含まれません。ただし、照明、背景、音響効果などに相当するモジュールは、３Ｄ空間内に類似の形で存在します。

3. Vreoの主な機能分類

Vreoは、３Ｄ空間の動的な動き（アニメーション）、モード切り替えなどの移動に加え、豊富な機能を提供します。

機能カテゴリ	詳細な機能例
カメラ移動 (Camera Movement)	３Ｄ空間のパノラマ遊走、回転、分鏡（シーン）切り替えなど、映画の移動に似た効果をサポートします。
定制モジュール (Custom Modules)	弾幕提詞（バレットスクリーン形式のナレーション）、全景タグ（パノラマタグ）、動画広告、空間テキストなどのモジュールをカスタマイズする機能を提供します。
ビルトインエフェクト (Built-in Effects)	パノラマ効果、住宅改修アニメーション、モデルエフェクトなど、多彩な動的効果を提供します。
独自の仮想イメージレンダリング能力	Webページ上で仮想イメージのシミュレーションをサポートします。音声解説、カメラ移動、カスタマイズされた特殊効果と連携し、インテリジェントな解説機能を実現できます。

注意点： Vreoスクリプトプレイヤーの機能は、Realsee３Ｄ空間能力に基づいて実現されているため、システムにRealsee３Ｄ空間能力がまだ統合されていない場合は、先にRealsee３Ｄ空間ドキュメントを参照する必要があります。

IV. 豊富な空間インタラクション：@realsee/dnalogel

Fiveエンジンが基盤を提供し、Vreoが動きを定義しますが、実際の開発者がカスタムのインタラクティブな機能を構築する際には、@realsee/dnalogel が重要な役割を果たします。

1. dnalogelの役割と抽象化

@realsee/dnalogel は、realsee.comの ３Ｄ空間インタラクション で常用される能力を凝縮し、FivePlugin 形式で抽象化したライブラリです。

このプラグインと、Realsee３ＤコントロールレンダリングSDKである Five SDK、そして Realseeオープンインターフェース を組み合わせることで、開発者は豊かで多様な３Ｄ空間アプリケーションを制作することができます。

2. 使用方法と依存関係

@realsee/dnalogelプラグインを利用するには、標準的なパッケージ管理ツール（npm、Yarn、pnpm）を使用してインストールを行います。

特に、2.xバージョン を使用する場合、svelte への依存関係があるため、@realsee/dnalogelと同時に svelte もインストールする必要があります。

プラグインの登録とメソッドの使用

プラグインの機能は、Fiveインスタンスの初期化時に登録されます。

登録後、各プラグインが提供する方法は、five.plugins.PluginNameを通じてアクセスされます。提供される一般的なメソッドには、データのロード (load(data))、機能の有効化 (enable())、無効化 (disable())、および破棄 (dispose()) などがありますが、具体的なメソッドはプラグインごとに異なります。

データ依存関係の取得

プラグインが依存するデータは、オープンAPI を通じて取得することができます。

V. リアルタイム通信と遠隔ガイド：オンラインガイドビューイング

三次元空間を単独で体験するだけでなく、ユーザー間でリアルタイムに共有し、ガイドすることを可能にするのがオンラインガイドビューイング機能です。

1. オンラインガイドビューイングの技術基盤

オンラインガイドビューイングは、Realseeが WebSocket と WebRTC をベースに実現した リアルタイム通信能力 です。

この機能により、開発者は、画面の同期表示 や リアルタイム音声 などの機能をサポートするアプリケーションを開発することができます。

2. 製品アーキテクチャの構成要素

オンラインガイドビューイングシステムは、クロスプラットフォームのビジネスシナリオをサポートするために、以下の主要なコンポーネントで構成されています。

ブラウザ SDK:
- @realsee/five (レンダリングエンジン)
- @realsee/live (帯看コントローラ)
- @realsee/jsbridge-x (“橋”プロトコル)
クライアントコンテナ SDK (cross-platform container):
- iOS用
- Android用
- WeChat MiniProgram用
サーバ API:
- HTTP
- WebSocket
- サーバ側のVRTCサービス (コア)

これらのツールとサービスを組み合わせることで、シームレスなクロスプラットフォームのリアルタイム共同体験が実現されます。

VI. 端末統合とパフォーマンス最適化：VRWebViewと”橋”プロトコル

Realseeの３Ｄ空間レンダリングは、現代のブラウザでは WebGL をベースにしていますが、モバイル端末（iOS/Android）やWeChatミニプログラムといった環境では、WebView にフロントエンドページを組み込む形式で統合されます。

このマルチプラットフォーム環境での性能と機能の最大限の活用を目指し、Realseeは公式に一連の VRWebView SDK を提供しています。

1. VRWebViewがサポートする機能

VRWebViewは、Webブラウザ単体では提供できない、端末固有の能力を補完します。

端末能力の利用

基礎機能： 全画面表示、振動、共有、権限チェック、アルバムへのアクセスなど、ブラウザ側では提供できない機能。
音声チャネル： WebRTCの互換性制約があるため、端末デバイスがWebRTCの能力を代理することができます。

性能と体験の最適化

プリロード能力： VRページを開く前に、データやテクスチャリソースの一部を事前に読み込むことができます。
初画面レンダリング（部分サポート）： 端末レンダリング能力を提供し、フロントエンドのレンダリングが完了した後、シームレスに切り替えることを実現します。
プロキシリクエスト（部分サポート）： クライアントの高性能な HTTP リクエスト能力を最大限に活用し、リクエスト結果をキャッシュすることで、後続の重複リクエストを回避します。

2. “橋”プロトコル（@realsee/jsbridge-x）

@realsee/jsbridge-x は、VRWebViewコンテナと、その中に埋め込まれたWebページとの間で、メッセージの受け渡し と データの交換 を実現するためのフロントエンドSDKです。

このプロトコルは、様々な端末の WebView の実装メカニズムの違い（iOS WKWebView、Android WebView、WeChatミニプログラム web-viewなど）を可能な限り吸収（抹平）しようと努めています。しかし、プラットフォームの差異性から、具体的な詳細については、各バージョンに対応するAPIを参照する必要があります。

VII. 開発時の課題と解決策（FAQ）

Realseeオープンプラットフォームの開発プロセス中に遭遇する可能性のある一般的な問題と、その解決策がまとめられています。事前にこれらの課題を把握しておくことで、開発の停滞を防ぐことができます。

問題カテゴリ	課題の具体例	推奨される解決策/原因
VRレンダリング失敗	VRが突然レンダリングに失敗し、原因が特定できない場合。	– 以前正常に動作していたものが突然失敗した場合の一般的な解決策を適用します。
Fiveデータ署名問題	Fiveデータが期限切れになった後も利用可能な問題。	– 署名検証に関する問題の特定と解決策を適用します。
単一デバイスでの署名検証エラー	特定のスマートフォンでのみ署名検証エラーによるブラックスクリーンが発生し、他のデバイスでは正常な場合。	– デバイス固有の署名検証エラーの特定と解決策を適用します。
初回VR進入時のブラックタイム延長	初回VRロードが遅くなり、ブラックスクリーンが明らかに長くなる場合。	– 通常、データ万象（Data Vientiane）が有効になっていないことが原因です。ドキュメントに従って `imageOptions` を設定する必要があります。
CDN移行後のCORS問題	自前のCDNに移行した後、エディタ/バックグラウンドでVRがロードできない場合 (CORSエラー)。	– `editor.realsee.cn` および `my.realsee.cn` のために、CORS許可オリジンホワイトリストを設定する必要があります。
textureOption設定の未適用	`textureOption` の設定が効かない場合。	– この設定は at3dタイプのモデルにのみ有効です。非at3dモデルには適用されません。

VIII. まとめ

Realseeの開発プラットフォームは、３Ｄ空間の再構築という強固な基盤（WorkデータとFiveエンジン）の上に、動的なコンテンツ制作（Vreo）、リッチなインタラクション（@realsee/dnalogel）、そしてリアルタイムのコミュニケーション（オンラインガイドビューイング）を実現するための包括的なツールキットを提供しています。さらに、VRWebViewと”橋”プロトコルによって、モバイル環境での統合と性能最適化にも配慮されています。

これらの技術要素は、まるで緻密に設計されたハイテクなオーケストラのようです。Fiveエンジンが舞台（3D空間）と指揮者（レンダリング）を務め、Workデータが楽譜を提供します。Vreoは演出家としてカメラワークと効果を指示し、dnalogelは観客（ユーザー）が楽器（インタラクション）を演奏することを可能にします。そして、オンラインガイドビューイングは、このパフォーマンスを地理的に離れた観客同士がリアルタイムに共有し、共に楽しむための通信インフラを提供しているのです。

提供された開発マニュアルは、これらの複雑な要素を統合し、次世代のVR空間アプリケーションを開発するための確かな道筋を示しています。

最近は、ブラウザ上でリアルタイム翻訳でも十分活用できるが、やはり細部まで行き届かないところがある。

日本語に翻訳したものを用意した。これで学びやすくなればとの思い。

また、gitで提供されているdnalogelも日本語にしたものがあります。希望者にはzipアーカイブでお渡しします。ローカル環境でサーバを起動し、ブラウザで確かめることができます。