ビューアの埋め込み
SuperSplat Viewerはnpmで@playcanvas/supersplat-viewerとして公開されています。ビルド済みのビューアをホストしてURLパラメータで設定する、ビューアを含むページを生成する、自分のウェブアプリ内でビューアを作成する、といった使い方ができます。
スプラットがすでにsuperspl.atで公開されている場合、最も簡単な埋め込み方法は、そのシーンページのEmbedダイアログから取得できる<iframe>です。
方法の選択
| 方法 | 使うべき場面 |
|---|---|
| ビルド済みビューアをホストする | ビューアの静的ファイルを配信してスプラットとsettings.jsonを指定し、各ページをURLパラメータで設定したいとき。 |
renderViewerHtmlでページを生成する | サーバーやビルドが、アセットのURLと設定を埋め込んだHTMLページを書き出すとき。 |
createViewerでページ内にビューアを作成する | 自分のウェブアプリがページを管理し、ビューアの作成・制御・破棄を自ら行うとき。 |
インストール
npm install @playcanvas/supersplat-viewer
パッケージには次のエントリポイントがあります:
| インポート | 提供するもの |
|---|---|
@playcanvas/supersplat-viewer | renderViewerHtmlと、ビューアのスタイルシートおよびバンドルを文字列にしたcssとjs |
@playcanvas/supersplat-viewer/viewer | createViewer。playcanvas(2.24.1以降)がピア依存関係です |
@playcanvas/supersplat-viewer/viewer.css | createViewerに必要なスタイルシート |
@playcanvas/supersplat-viewer/settings | 設定の型、デフォルト、検証、マイグレーション。Experience Settingsを参照してください。 |
メインのエントリポイントは、ビューアのページを文字列htmlとしてもエクスポートしていますが、これは非推奨です。フォーマットがリリースごとに変わるため、代わりにrenderViewerHtmlを使ってください。
ビルド済みビューアのホスティング
パッケージのpublic/フォルダーには、スタンドアロンのビューア(index.html、index.js、index.cssと、一部の形式に必要なWebAssemblyデコーダーの.wasmファイル)が入っています。このフォルダーをウェブサーバーにコピーし、index.htmlを開きます。パラメータを指定しない場合は、同じ場所にある./settings.jsonと./scene.compressed.plyを読み込みます。
.wasmファイルは、バージョン4の.spzファイルなど、それを必要とするコンテンツでのみ取得されます。application/wasmとして配信してください。
URLパラメータ
各ページはクエリパラメータで設定します(例:index.html?content=./museum/lod-meta.json&settings=./museum/settings.json)。これらのパラメータはビューアの進化に伴って変更される可能性があります。現在のセットと、開発者向けのいくつかの追加パラメータについては、プロジェクトREADMEを参照してください。
コンテンツ
| パラメータ | 説明 | デフォルト |
|---|---|---|
settings | Experience Settings JSONファイルのURL | ./settings.json |
content | スプラットのURL。対応コンテンツを参照してください。 | ./scene.compressed.ply |
skybox | エクイレクタンギュラースカイボックス画像のURL | (なし) |
poster | シーンの読み込み中に、ぼかして表示する画像のURL | (なし) |
collision | ウォークモード用のコリジョンデータのURL:.voxel.jsonファイル(.voxel.binを同じ場所に置きます)、または.glbメッシュ。voxelはエイリアスです。 | (なし) |
UI
| パラメータ | 説明 |
|---|---|
noui | ビューアの組み込みUIを非表示 |
noanim | カメラアニメーションを一時停止状態で開始 |
reticle | マウスがキャプチャされている間、フライモードとウォークモードで画面中央にレティクルを表示 |
ministats | ランタイムのCPU/GPUパフォーマンスグラフを表示 |
lang | UIの言語:de、en、es、fr、ja、ko、pt-BR、ru、zh-CNのいずれか。デフォルトはブラウザの言語です。 |
vr | VRが利用可能な場合、シーンの読み込み中にTap to enter VRプロンプトを表示します。VRとARでの表示を参照してください。 |
レンダリング
| パラメータ | 説明 |
|---|---|
webgl | WebGLを使用します。デフォルトでは、WebGPUが利用可能な場合はWebGPUを使用します。 |
aa | アンチエイリアシング付きでトレーニングされたスプラット向けのアンチエイリアシング補正を強制します:aa、aa=1、aa=true、aa=enableですべてのスプラットに対してオンになり、それ以外の値ではオフになります。指定しない場合は、各スプラットファイル自体のトレーニングモードに従います。 |
hpr | 設定のhighPrecisionRenderingを上書きします:hpr、hpr=1、hpr=true、hpr=enableでオン、それ以外の値でオフになります。 |
nofx | ポストエフェクトをオフにします |
budget | ガウシアンバジェット(100万単位)。すべてのQuality段階の値を上書きします |
fullload | 最初のフレームの前に、ストリーミングシーンのディテールをすべて読み込みます |
stochastic | 実験的機能です。Performance Modeが使う確率的スプラットレンダラーを強制します:stochasticでピクセル単位のモード、stochastic=mobileでスマートフォンとヘッドセット向けのモードになり、stochastic=offでは標準のレンダラーを使い続けます。いずれを指定しても、Performance Mode設定は非表示になります。WebGPUのみ対応しています。 |
colorize | レベルオブディテールごとにガウシアンを色分けします |
heatmap | コリジョンオーバーレイをヒートマップとして描画します。WebGPUとボクセルコリジョンが必要です。オーバーレイはShow CollisionまたはVでオンにします。 |
debug | 読み込み時に開発者用デバッグパネルを開きます(Ctrl+Shift+Dで切り替え) |
対応コンテンツ
ビューアは、コンテンツのファイル名からフォーマットを判断します:
| フォーマット | ファイル |
|---|---|
| PLY | .ply、.compressed.ply |
| SOG | .sog、または非バンドルSOGのmeta.json |
| Streamed SOG | lod-meta.json |
| SPZ | .spz(バージョン3と4) |
| XGRIDS LCC2 | .lcc2。Streamed SOGと同様に、必要に応じてストリーミングされます |
splat-transform 3.11.0または3.11.1で書き出されたSOG v3ファイルは、ビューアが現在は読み込まない以前のレイアウトを使用しています。最新のsplat-transformで再変換してください。
ページの生成
サーバーやビルドでビューアを含むページを生成する場合は、renderViewerHtmlを使います。アセットのURLと設定を1つのJSONブロックにまとめて埋め込んだ、完全なHTMLドキュメントを返します:
import { renderViewerHtml } from '@playcanvas/supersplat-viewer';
const page = renderViewerHtml({
bootstrap: {
settings, // オブジェクト。省略してsettingsUrlを設定することもできます
contentUrl: 'scene.sog',
posterUrl: 'poster.jpg'
},
baseHref: '/viewer/', // サブパスから配信する場合
backgroundColor: [0, 0, 0], // 各成分は0..255ではなく0..1
headExtras: '<script src="analytics.js"></script>',
inlineCss: true // 隣にindex.cssを置く必要がなくなります
});
| オプション | 説明 |
|---|---|
bootstrap | ページのアセットと設定:settingsまたはsettingsUrl、contentUrl、contentFilename、posterUrl、skyboxUrl、collisionUrl、zstdDecoderUrl |
baseHref | ページのベースURL。ビューアをサブパスから配信する場合に使います |
backgroundColor | 最初のフレームが描画されるまでのページ背景。設定のbackground.colorと同じく、0~1のRGBで指定します |
headExtras / bodyStartExtras | <head>内、または<body>の先頭に追加するマークアップ |
inlineCss / inlineJs | ページの隣からindex.cssやindex.jsを読み込む代わりに、スタイルシートやバンドルをインライン化します |
オプションなしで呼び出すと、パッケージに含まれるページをそのまま返します。配信されたページのURLパラメータは引き続きbootstrapのアセットURLを上書きするため、各インスタンスは設定可能なままです。ただし、インラインのsettingsは例外で、?settings=よりも優先されます。
自己完結した単一ファイルにするには、inlineCssとinlineJsの両方を設定し、設定をインラインで渡し、スプラットをdata: URIとしてcontentUrlに渡します。data: URIにはファイル名がないため、contentFilenameでコンテンツに名前(scene.sogなど)を付けます:
const page = renderViewerHtml({
bootstrap: {
settings,
contentUrl: sogDataUri,
contentFilename: 'scene.sog'
},
inlineCss: true,
inlineJs: true
});
バージョン4の.spzファイルを読み込む単一ファイルのページでは、デコーダーもインラインにする必要があります。zstdDecoderUrlに、zstd-decoder.wasmをdata: URLにしたものを設定してください。zstdDecoderUrlに対応するURLパラメータはありません。もしあれば、リンク1つでページのオリジン上で任意のWebAssemblyを実行できてしまうためです。
自分のページ内でのビューアの作成
自分のウェブアプリがページを管理している場合は、その要素の1つの中にビューアを作成します:
import { createViewer } from '@playcanvas/supersplat-viewer/viewer';
import '@playcanvas/supersplat-viewer/viewer.css';
const viewer = await createViewer({
container: document.getElementById('viewer'),
settings: './settings.json',
contentUrl: './scene.sog'
});
// 後で
viewer.destroy();
返されるハンドルで、読み込み、再生、カメラ、注釈、フルスクリーン、XRを制御できます。また、組み込みUIはスタイルを変更したり、置き換えたりできます。ビューアAPIを参照してください。
Settings JSON
settingsパラメータまたはオプションは、Experience Settings v2ドキュメントを指します。これはStudioが保存するのと同じJSONフォーマットです。以下は、defaultSettings()(@playcanvas/supersplat-viewer/settingsが提供)が生成する完全なドキュメントです:
{
"version": 2,
"tonemapping": "linear",
"highPrecisionRendering": false,
"background": {
"color": [0, 0, 0]
},
"postEffectSettings": {
"sharpness": { "enabled": false, "amount": 0 },
"bloom": { "enabled": false, "intensity": 0.1, "blurLevel": 2 },
"grading": { "enabled": false, "brightness": 1, "contrast": 1, "saturation": 1, "tint": [1, 1, 1] },
"vignette": { "enabled": false, "intensity": 0.5, "inner": 0.3, "outer": 0.75, "curvature": 1 },
"fringing": { "enabled": false, "intensity": 0.5 }
},
"animTracks": [],
"cameras": [
{ "initial": { "position": [0, 2, 0], "target": [2, 2, 0], "fov": 85 } }
],
"annotations": [],
"startMode": "default"
}
このカメラは、キャプチャした空間をその内側から見渡します。一方、defaultSettings('object')は被写体を外側からフレーミングします。すべてのフィールド、作成時の制限、設定の生成・検証・マイグレーションのためのヘルパーについては、Experience Settingsリファレンスを参照してください。
プログラム的な公開
Editorを使わずに独自のパイプラインからsuperspl.atへスプラットを公開するには、SuperSplat APIを使用します。この方法で公開したシーンはデフォルトの設定で始まり、その閲覧体験はStudioで整えます。
関連項目
- SuperSplat Viewerの概要 — ビューアとは何か、いつ使うか
- ビューアAPI —
createViewerとビューアハンドル - Self-Hosting — Editorからの単一ファイルHTMLエクスポート
- Experience Settings — ビューアが読むJSONコントラクト
- API & Integrations — 独自のコードからsuperspl.atへスプラットを公開する