Tiles3DScene¶

OGC 3D Tiles シーン

1 つの 3D Tiles データセット (tileset.json) の表示を管理するクラス。このクラスの生成には mapray.B3dCollection.createTiles3DScene を使用する。

const provider = new mapray.StandardTiles3DProvider( { url: "https://example.com/tileset.json" } );
const scene = viewer.b3d_collection.createTiles3DScene( provider );

See¶

Extends¶

B3dSceneBase

Accessors¶

atmosphere_lighting_mode¶

get atmosphere_lighting_mode(): AtmosphereLightingMode

現在の大気ライティングモード (設定した値。INHERIT / AUTO を含む)。実際に使われるモードは描画時に決まる。

Returns¶

AtmosphereLightingMode

lod_factor¶

get lod_factor(): number

表示詳細度のためのパラメータ (無次元、下限は Tiles3DScene.MIN_LOD_FACTOR)

Returns¶

number

max_cache_bytes¶

get max_cache_bytes(): number

ロード済みタイルデータの保持量上限 (バイト)。

Returns¶

number

max_content_bytes¶

get max_content_bytes(): number

content 1 ファイルのサイズ上限 (バイト)。

Returns¶

number

max_distance¶

get max_distance(): number

このシーンを描く距離の上限 (メートル)。詳細は setDistanceRange

Returns¶

number

max_texture_size¶

get max_texture_size(): number

タイルのテクスチャの 1 辺の上限 (画素)。0 はアプリ側の上限なし (GPU の上限は常に適用)。

Returns¶

number

min_distance¶

get min_distance(): number

このシーンを描く距離の下限 (メートル)。詳細は setDistanceRange

Returns¶

number

provider¶

get provider(): Tiles3DProvider

3D Tiles プロバイダ

Returns¶

Tiles3DProvider

sse_threshold¶

get sse_threshold(): number

ScreenSpaceError の閾値 (ピクセル)

Returns¶

number

style¶

get style(): null | Tiles3DStyle

現在設定されている feature style (未設定なら null)。

setStyle に JSON を渡した場合は変換後の Tiles3DStyle を返す。

Returns¶

null | Tiles3DStyle

style_color_blend_amount¶

get style_color_blend_amount(): number

Tiles3DScene.StyleColorBlendMode.MIX で混ぜる割合。0 で元の色、1 でスタイルの色。値域は [0, 1]、既定は 0.5。

Returns¶

number

style_color_blend_mode¶

get style_color_blend_mode(): StyleColorBlendMode

スタイルの色の合成方法。既定は Tiles3DScene.StyleColorBlendMode.HIGHLIGHT。詳細は Tiles3DScene.setStyleColorBlendMode

Returns¶

StyleColorBlendMode

texture_compression¶

get texture_compression(): boolean

タイルのテクスチャを GPU 圧縮形式で持つか。

Returns¶

boolean

tileset_info¶

get tileset_info(): undefined | Readonly<TilesetInfo>

この tileset が使う拡張・形式と未対応分。tileset.json を読み終えるまで undefined (外部 tileset を読むたびに合算)

Returns¶

undefined | Readonly<TilesetInfo>

vertical_offset¶

get vertical_offset(): number

現在の鉛直オフセット (メートル)。

Returns¶

number

visibility¶

get visibility(): boolean

可視性フラグを取得

Default Value¶

true

See¶

mapray.B3dSceneBase.setVisibility

Returns¶

boolean

Methods¶

addEventListenerForLoadError()¶

addEventListenerForLoadError(listener): void

読み込み・描画の失敗を理由コード付きで通知するイベントを登録する。同じ (code, feature, url) の組は 1 回しか通知しない。

Parameters¶

Parameter	Type
`listener`	(`info`) => `void`

Returns¶

void

addEventListenerForMeshLoaded()¶

addEventListenerForMeshLoaded(event): void

メッシュが読み込まれた際に呼ばれるイベントを登録

Parameters¶

Parameter	Type	Description
`event`	(`meshes`, `metadata`?) => `void`	メッシュ配列と任意のメタデータを受け取る関数

Returns¶

void

Inherited from¶

B3dSceneBase.addEventListenerForMeshLoaded

addEventListenerForMeshUnloaded()¶

addEventListenerForMeshUnloaded(event): void

メッシュが削除された際に呼ばれるイベントを登録

Parameters¶

Parameter	Type	Description
`event`	(`meshes`) => `void`	削除されたメッシュ配列を受け取る関数

Returns¶

void

Inherited from¶

B3dSceneBase.addEventListenerForMeshUnloaded

addEventListenerForTileLoadFailed()¶

addEventListenerForTileLoadFailed(event): void

タイルの読み込みに失敗した際に呼ばれるイベントを登録

Parameters¶

Parameter	Type	Description
`event`	(`message`) => `void`	失敗メッセージを受け取る関数

Returns¶

void

Inherited from¶

B3dSceneBase.addEventListenerForTileLoadFailed

addEventListenerForUpdateAttributions()¶

addEventListenerForUpdateAttributions(event): void

表示するAttributionの更新が必要な場合に呼ばれるイベントを登録

発火するのは attribution を持つプロバイダの実装のみ (mapray.Tiles3DScene)。b3dtile 形式は発火しない。文字列は HTML エスケープせずそのまま渡す。show_attributions で出典欄に出すときは、HTML として解釈せず文字として出す。

Parameters¶

Parameter	Type	Description
`event`	(`attributions`) => `void`	著作権文字列の配列を受け取る関数

Returns¶

void

Inherited from¶

B3dSceneBase.addEventListenerForUpdateAttributions

clearFeatureStates()¶

clearFeatureStates(): void

すべての feature-state を解除し、state 抜きの色へ戻す。

Returns¶

void

getGpuResourceInfo()¶

getGpuResourceInfo(): GpuResourceInfo

ロード済みタイルが使用している GPU リソース量を取得する。

ロード済みのメッシュについて、テクスチャと頂点・インデックスバッファの合計バイト数と個数を集計する。共有されているテクスチャは 1 枚として数える。

テクスチャのバイト数は GPU 上の形式での推定値 (圧縮テクスチャは圧縮後、それ以外は RGBA 8bit)。集計に時間がかかるため、毎フレーム呼び出す用途は想定していない。

Returns¶

GpuResourceInfo

GPU リソースの集計結果

getRayIntersection()¶

getRayIntersection(ray, limit): null | object

シーンとレイの交点を探す

戻り値に含まれる feature ID のプロパティは形式ごとに異なる。b3dtile 形式は 64bit ID を feature_id: [lo, hi] で、3D Tiles 形式は tile_feature_id: number を tile_content と対で返す。

Parameters¶

Parameter	Type	Description
`ray`	`Ray`	半直線を表すレイ (GOCS)
`limit`	`number`	制限距離 (ray.direction の長さを単位)

Returns¶

null | object

交点の情報交点が見つからない場合は null を返す

Overrides¶

B3dSceneBase.getRayIntersection

getSceneTransform()¶

getSceneTransform(dst): Matrix

座標オフセット行列を取得

Parameters¶

Parameter	Type	Description
`dst`	`Matrix`	結果を格納するバッファ

Returns¶

Matrix

dst

getTextureSizeInfo()¶

getTextureSizeInfo(): TextureSizeInfo

データに入っていたテクスチャの寸法を取得する。

setMaxTextureSize で上限を決めるための材料。データセットが実際にどの解像度の画像を持っているかは tileset.json に書かれていないため、タイルを読み込みながら観測した結果を返す。

これまでに読み込んだタイルの範囲でしか判らない。 カメラが向いていない領域のタイルは含まれないので、データセット全体の最大値とは限らない。

sizes の寸法は縮小前の値で、downscaled_count は上限 (setMaxTextureSize と GPU の上限の小さい方) を超えて縮小した枚数。

Returns¶

TextureSizeInfo

観測した寸法の一覧 (枚数の多い順) と最大辺長

removeEventListenerForLoadError()¶

removeEventListenerForLoadError(listener): void

addEventListenerForLoadError で登録したイベントを削除する。

Parameters¶

Parameter	Type
`listener`	(`info`) => `void`

Returns¶

void

setAtmosphereLightingMode()¶

setAtmosphereLightingMode(mode): void

大気ライティングモードを設定 (advanced override)。

INHERIT の場合は viewer.atmosphere の全体デフォルトに追随。 PHYSICAL/SIMPLE/OFF を明示すると常にその mode で固定。

Parameters¶

Parameter	Type
`mode`	`AtmosphereLightingMode`

Returns¶

void

setDistanceRange()¶

setDistanceRange(min_distance, max_distance): void

このシーンを描く距離の範囲を設定する (メートル)。

カメラからタイルの境界箱までの距離が範囲に掛からないタイルは、要求も描画もしない。広域のデータセットで遠方のタイルを読まないようにする用途。判定はタイル単位なので、同じ建物を持つ 2 つのシーンをこの範囲で重ねると面が競合する。

Parameters¶

Parameter	Type	Description
`min_distance`	`number`	これより近い範囲に箱全体が収まるタイルは描かない (メートル)。既定 0
`max_distance`	`number`	これより遠いタイルは描かない (メートル)。既定は無制限

Returns¶

void

setFeatureState()¶

setFeatureState(content, feature_id, state): void

feature-state (hover/select 等) を設定する。

style の式から ${state.NAME} で参照され、動的なハイライトに使う。設定すると該当 feature だけを更新するので、毎フレームの hover でも軽い。 setStyle で state を参照するスタイルを適用しておくこと (適用していないと見た目に反映されない)。

scene.setStyle( { color: "${state.hover} === true ? color('yellow') : color('#8fb7d6')" } );
// pick 結果に対して
const result = viewer.pick( screen_position );
if ( result?.category === mapray.Viewer.Category.TILES_3D &&
     result.tile_content && result.tile_feature_id !== undefined ) {
    scene.setFeatureState( result.tile_content, result.tile_feature_id, { hover: true } );
}

このシーンに属さない content を渡した場合と、viewer.rendering_lost の後は何もしない。

Parameters¶

Parameter	Type	Description
`content`	`Tiles3DContent`	pick 結果の `tile_content` (所属 content)
`feature_id`	`number`	feature ID
`state`	`null` \| `State`	状態 (既存値へマージ)。`null` で当該 feature の state を解除。

Returns¶

void

setLodFactor()¶

setLodFactor(lod_factor): void

表示詳細度のためのパラメータを設定

ScreenSpaceError の閾値に乗算される係数。値が大きいほど閾値が上がり、粗いタイルが選ばれやすくなる。最小値は Tiles3DScene.MIN_LOD_FACTOR。

Parameters¶

Parameter	Type	Description
`lod_factor`	`number`	詳細度係数 (無次元、デフォルトは 1)。Tiles3DScene.MIN_LOD_FACTOR 未満は MIN_LOD_FACTOR に丸められる

Returns¶

void

Overrides¶

B3dSceneBase.setLodFactor

setMaxCacheBytes()¶

setMaxCacheBytes(bytes): void

ロード済みタイルデータの保持量上限を設定する (バイト)。

既定は上限なし (Tiles3DScene.DEFAULT_MAX_CACHE_BYTES)。読み込んだタイルは、再び画面に入ったとき読み直さずに済むよう保持し続ける。

上限を設定すると、保持量がこの値を超えたとき、表示に使われていないタイルデータを古く使われたものから解放する。表示中のタイルと、直近に使われたタイルは解放しないので、解放した瞬間に表示は変わらない。再びそのタイルへ近づくと読み直す (再取得が要る)。

表示中のタイルだけで上限を超える場合 (細かい視点 + 小さい上限) は上限を守れない。絵を壊さないことを優先する。上限は表示する範囲の常駐量より十分大きい値 (目安は 1.5 倍以上) にすること。

数えるのは読み込み済みのメッシュ・テクスチャとタイルのデータ。上限はシーン毎で、複数のシーンを表示する場合の合計はシーン数分になる。

Parameters¶

Parameter	Type	Description
`bytes`	`number`	保持量の上限 (バイト)。`Number.POSITIVE_INFINITY` で上限なし

Returns¶

void

setMaxContentBytes()¶

setMaxContentBytes(bytes): void

content 1 ファイルのサイズ上限を設定する。

タイル (glb / b3dm / gltf)、外部 tileset JSON、glTF の外部リソース (buffers / images) の 1 ファイルがこの値を超えていたら、解析せずに捨てて resource_limit で通知する (Tiles3DScene.LoadErrorCode.RESOURCE_LIMIT、feature は "content_bytes")。第三者が配信するデータで巨大なファイルを掴まされたとき、メモリの少ない端末でタブが異常終了する前に止めるためのもの。

判定は取得し終えてから行うので、通信量は減らない。subtree ファイルは対象外。

Parameters¶

Parameter	Type	Description
`bytes`	`number`	1 ファイルの上限 (バイト)。`Number.POSITIVE_INFINITY` で上限なし

Returns¶

void

setMaxTextureSize()¶

setMaxTextureSize(max_texture_size): void

タイルのテクスチャの 1 辺の上限を設定する (画素)。

タイルに含まれる画像がこの値より大きい場合、縦横比を保ったまま収まるように縮小してから GPU へ転送する。0 はアプリ側の上限なし (既定)。 GPU の上限 (MAX_TEXTURE_SIZE) は常に適用し、実際の上限はこの値と GPU の上限の小さい方になる。

PLATEAU の LOD2 テクスチャ付きデータセットには 4096x4096 の画像が含まれる。建物 1 棟がこの解像度を必要とすることはまれで、上限を設けると読み込み時間と GPU メモリの両方が減る。既に転送済みのタイルには適用されない (次に読み込むタイルから有効)。

Parameters¶

Parameter	Type	Description
`max_texture_size`	`number`	1 辺の上限 (画素)。0 はアプリ側の上限なし (GPU の上限は常に適用)

Returns¶

void

setSseThreshold()¶

setSseThreshold(sse_threshold): void

ScreenSpaceError の閾値を設定

ScreenSpaceError は、タイルの geometricError が画面に占める縦のピクセル数。カメラの縦の画角 (Camera.fov は対角の画角なので、画面の縦横比から求める) と描画先の高さで測る。値が大きいほど粗いタイルで細分を打ち切るため、表示の詳細度が低くなる (デフォルトは Tiles3DScene.DEFAULT_SSE_THRESHOLD)。

Parameters¶

Parameter	Type	Description
`sse_threshold`	`number`	閾値 (ピクセル)

Returns¶

void

setStyle()¶

setStyle(style): void

OGC 3D Tiles Style (feature 単位の宣言的スタイル) を設定する。

feature のプロパティ (Batch Table / EXT_structural_metadata) に基づき色・表示を切り替える。null で解除。スタイル JSON をそのまま渡すこともできる。 feature を持たないタイルは属性の無い 1 つの feature として評価し、その show / color をタイル全体に掛ける。

描画に適用されるのはスタイルの color と show だけで、pointSize / meta は評価されても描画には反映されない (mapray.Tiles3DStyle を参照)。

scene.setStyle( {
    color: "(${bldg:measuredHeight} >= 60) ? color('red') : color('#8fb7d6')",
    show:  "${bldg:measuredHeight} > 0",
} );

Parameters¶

Parameter	Type
`style`	`null` \| `Tiles3DStyle` \| `StyleJson`

Returns¶

void

setStyleColorBlendAmount()¶

setStyleColorBlendAmount(amount): void

Tiles3DScene.StyleColorBlendMode.MIX で混ぜる割合を設定する。

0 で元の色、1 でスタイルの色になる。既定は 0.5。[0, 1] にクランプする。

Parameters¶

Parameter	Type	Description
`amount`	`number`	混ぜる割合

Returns¶

void

setStyleColorBlendMode()¶

setStyleColorBlendMode(mode): void

スタイルの色と、タイルの元の色 (テクスチャ × 頂点色 × baseColorFactor) の合成方法を設定する。既定は Tiles3DScene.StyleColorBlendMode.HIGHLIGHT。

どの方法でも、スタイルの show が偽の feature は描かない。HIGHLIGHT / MIX ではスタイルのアルファを元のアルファに掛ける (REPLACE はスタイルのアルファで置き換える)。

Parameters¶

Parameter	Type	Description
`mode`	`StyleColorBlendMode`	合成方法

Returns¶

void

Throws¶

Error 未知の合成方法を指定した場合

setTextureCompression()¶

setTextureCompression(enabled): void

タイルのテクスチャを GPU 圧縮形式で持つかを設定する。

真 (既定) のとき、GPU メモリが非圧縮の約 1/8 になる。写真では見分けがつかないが、平坦な色はわずかに階調がずれる。アルファを持つ画像と PBR の各マップ (metallic-roughness・法線・遮蔽) は圧縮しない。GPU が圧縮形式に対応しない環境では設定に関わらず非圧縮で転送する。既に転送済みのタイルには適用されない。

Parameters¶

Parameter	Type	Description
`enabled`	`boolean`	圧縮するか

Returns¶

void

setVerticalOffset()¶

setVerticalOffset(meters): void

鉛直オフセット (メートル) を設定。

3D Tiles データセットは多くが WGS84 楕円体高で配置されているが、Mapray の terrain は orthometric (標高、ジオイド基準) のため、両者をきれいに合わせるにはジオイド高 N (geoid undulation) 分だけ 3D Tiles 側を下げる必要がある。

例: 日本上空では N はおよそ +37m なので setVerticalOffset(-37) で terrain と概ね合う。

タイルごとに、その箱の中心の鉛直上方向へ一律に動かす。隣り合うタイルは向きがわずかに違うので、境目にオフセット × タイル間の距離 ÷ 地球半径の段差が出る (-37m、1 km 離れたタイルで約 6 mm)。

値は scene 全体に一律で掛かる。N が大きく変わる範囲を跨ぐ場合は地域別に scene を分ける。

Parameters¶

Parameter	Type	Description
`meters`	`number`	正: 高く、負: 低く

Returns¶

void

setVisibility()¶

setVisibility(visibility): void

可視性フラグを設定

Parameters¶

Parameter	Type	Description
`visibility`	`boolean`	可視性フラグ

Returns¶

void

Inherited from¶

B3dSceneBase.setVisibility

See¶

mapray.B3dSceneBase.visibility