SplatMeshDesc

SplatMeshDesc クラスは、3D Gaussian Splat アセット（.spz、.ply、.sog、.rad、.splat、.ksplat）を描画する Mesh Descriptor です。

DefaultPlugin により "splat" mesh キーで登録されているため、view.addMesh({ splat: { ... } }) 呼び出しはこの Descriptor にルーティングされます。

スプラットレンダラー（Spark）は、ページ読み込み時ではなく最初にスプラットメッシュを追加したときにダウンロードされます。addMesh は即座にハンドルを返し、レンダラーとアセットのロード完了後にスプラットが表示されます。レンダラーのロードに失敗した場合は error イベントで通知されます。

以下のプロパティに加えて、基底クラスの共通プロパティ（position、rotation、scale、matrix、matrixWorld、geodetic、visible）が利用できます。詳細は MeshDesc を参照してください。

Properties

url

Type: string

Description: 読み込む splat ファイルの URL。必須パラメータです。ライセンスが確認された外部ホストの URL を指定するか、プロジェクトの public/splat/ 配下にアセットを置いて /splat/your-asset.ply のように参照してください。

取得失敗時は console.warn が出力され、error イベントが発火します。例外は発生しません。必要に応じてアプリ側でリトライや fallback を実装してください。

Example:

{
  splat: {
    url: "/splat/your-asset.ply",
  }
}

lod

Type: boolean

Default: false

Description: Level-of-Detail 描画を有効化し、現在のカメラ距離で必要な splat のみを描画します。任意の 3DGS アセットに対して runtime で動作しますが、アセット作成時に LoD ツリーをプリビルドしておくと初回ロードが速くなり、runtime でのツリー構築を回避できます。

Example:

{
  splat: {
    url: "/splat/your-asset.ply",
    lod: true,
  }
}

originCellSize

Type: number

Default: 2000

Description: globe（ECEF）スケールで splat を数値的に安定させる floating origin のグリッドのセル辺長（メートル）です。Navara は splat を「カメラに追従し、このサイズのグリッドにスナップした原点」からの相対座標で描画するため、巨大な ECEF 座標が単精度演算に渡らず、カメラ移動時のサブメートルのジッターを防ぎます。この処理は自動で行われ、本プロパティはグリッドの調整のみを行います。小さくするとカメラ近傍の精度は上がりますが、セルを跨ぐたびの再ソート頻度が増えます。大きくすると再ソートは減ります。値は transparent シーン単位で共有され、最初に追加した splat の値がそのレンダラ上の全 splat に適用されます。通常は既定値を変更する必要はありません。

Example:

{
  splat: {
    url: "/splat/your-asset.ply",
    originCellSize: 500,
  }
}

url、lod、originCellSize は構築時に固定されます。handle.update() で異なる値を渡すと警告が出るので、Descriptor を作り直してください。

イベント

load

Description: splat ファイルの取得とパースが完了したときに発火します。読み込みに失敗した場合は発火しません（代わりに error イベントが発火します）。

Example:

splat.ref.on("load", () => {
  console.log("Splat loaded!");
});

error

Description: splat ファイルの取得またはパースに失敗したときに発火します。

Example:

splat.ref.on("error", (error) => {
  console.warn("Splat failed to load:", error);
});

Usage Examples

基本的な使い方

import ThreeView from "@navaramap/three";
import type { SplatMeshDesc } from "@navaramap/three-default-descs";
import {
  DefaultPlugin,
  type DefaultDescriptions,
} from "@navaramap/three-default-plugin";

const view = new ThreeView<DefaultDescriptions>();
view.addPlugin(new DefaultPlugin()); // "splat" → SplatMeshDesc を登録
await view.init();

const splat = view.addMesh<SplatMeshDesc>({
  splat: {
    url: "/splat/your-asset.ply",
  },
  geodetic: { lng: 139.8107, lat: 35.71, height: 10, scale: 30 },
});

逆さま表示の補正

Y-down で保存されたキャプチャはシーン上で逆さまに表示されます。geodetic の pitch を 180° にすると正立します:

view.addMesh<SplatMeshDesc>({
  splat: { url: "..." },
  geodetic: { lng: 139.8107, lat: 35.71, pitch: 180 },
});

対応仕様

Navara は以下の Gaussian Splatting フォーマットに対応しています。

ファイルフォーマット

ファイルフォーマット	説明
`.spz`	Niantic SPZ 形式
`.ply`	Gaussian Splatting データ
`.sog`	PlayCanvas Scene Optimized Gaussians
`.rad`	プリビルドされた LoD アセット（`build-lod` の出力）
`.splat`	antimatter15 splat 形式
`.ksplat`	mkkellogg GaussianSplats3D 形式

既知の制約

シーンライティング非対応: splat は照明をデータ内に焼き込んでおり、SunLight / AmbientLight などの影響を受けません。
shadow / selective effect / picking 非対応: splat は transparent パスで描画され、shadow、SelectiveBloomEffect / SelectiveOutlineEffect、Navara の picking パイプラインのいずれの対象にもなりません。
極端に大きい scale は不安定に見えることがある: scale を極端に大きくすると各 splat が広い world 領域に広がるため、僅かなカメラ移動で深度ソート順が急に入れ替わり「boiling（沸き立ち）」として見えることがあります。これは Gaussian Splatting 固有の挙動で、配置精度とは無関係です。大きく拡大するのではなく、アセットを意図する world サイズに近い状態で作成してください。