BillboardMaterial

BillboardMaterialは、ビルボードレンダリング用のマテリアルを表します。

Properties

alphaTest

Type: number | undefined

Description: 画像の RGBA の A が閾値以下の場合はそのピクセルをレンダリングしないようになります。

Default: undefined

Example:

{
  billboard: {
    alphaTest: 0.5
  }
}

backfaceCulling

Type: boolean | undefined

Description: 裏側から見たときにビルボードを非表示にするかどうかを指定します。false の場合はビルボードの両面を描画し、true の場合は表側のみを描画します。

カメラに追従して立っているビルボード（デフォルト）は常に表側が見えるため、影響はありません。影響があるのは次の 2 つの場合です。rotateWithCamera が false のビルボードは裏側から見えることがあり、その場合は左右反転して表示されますが、この設定を有効にすると非表示になります。billboardFacing が "flat" のビルボードは地球の外側を表側としているため、この設定を有効にすると、大きなビルボードのうち地平線の向こう側に回り込んだ部分も非表示になります。

Default: false

Example:

{
  billboard: {
    billboardFacing: "flat",
    backfaceCulling: true
  }
}

center

Type: Vec2

Description: 中心からのシフト量を指定します。範囲は 0 から 1 の間です。

Default: Required

Example:

{
  billboard: {
    center: { x: 0.5, y: 0.5 }
  }
}

clampToGround

Type: boolean

Description: 地面に沿わせるかどうかを指定します。

Default: Required

Example:

{
  billboard: {
    clampToGround: true
  }
}

color

Type: Color

Description: ビルボードの色をColorインスタンスで指定します。

Default: Required

Example:

import { Color } from "@navaramap/three";

{
  billboard: {
    color: new Color().setHex(0xffffff)
  }
}

declutter

Type: boolean | undefined

Description: 画面空間でのデクラッター（重なり除去）に参加します。ラベルやスプライトが画面上で重なった場合、優先度の低いものが非表示になります。デフォルトで有効です。すべてのラベルを無条件に描画するには false を設定します。

Default: true

Example:

{
  billboard: {
    declutter: false
  }
}

declutterPriority

Type: number | undefined

Description: デクラッターの配置優先度です。値が大きいほど重なりの競合に勝ちます。declutter が有効な場合にのみ意味を持ちます。FeatureEvaluator.evaluate() で地物ごとに上書きできます。

Default: 0.0

Example:

{
  billboard: {
    declutter: true,
    declutterPriority: 1
  }
}

depthTest

Type: boolean

Description: 前面のモデルが背面のモデルを隠すかどうかを決定する変数です。

Default: true

Example:

{
  billboard: {
    depthTest: true
  }
}

effectIds

Type: string[] | undefined

Description: 適用する Selective Effect の ID を指定します（例: “bloom”, “outline”）。SelectiveBloomEffectDesc や SelectiveOutlineEffectDesc と連携して使用します。

Default: undefined

Example:

{
  billboard: {
    effectIds: ["bloom", "outline"]
  }
}

emissiveColor

Type: Color | undefined

Description: 発光色をColorインスタンスで指定します。

Default: undefined

Example:

import { Color } from "@navaramap/three";

{
  billboard: {
    emissiveColor: new Color().setHex(0xff0000)
  }
}

emissiveIntensity

Type: number | undefined

Description: 発光の強度を指定します。

Default: undefined

Example:

{
  billboard: {
    emissiveIntensity: 0.5
  }
}

geometryTypes

Type: ("point" | "line" | "polygon")[] | undefined

Description: このマテリアルが消費するソースジオメトリのカテゴリーです。"line" を含めるとラインの頂点ごとに、"polygon" を含めるとポリゴンリングの頂点ごとに 1 つのビルボードを描画します（リングを閉じる重複頂点はスキップされます）。配列を指定するとデフォルトは置き換えられるため、ポイントジオメトリも描画し続けたい場合は "point" を含めてください。このオプションはジオメトリ構築時に適用されます。レイヤー作成時に指定してください。layer.update() で変更しても読み込み済みのタイルには反映されず、変更後に読み込まれたタイルにのみ適用されます（すべてに反映するにはレイヤーを作り直してください）。

Default: ["point"]

Example:

{
  billboard: {
    geometryTypes: ["point", "line"]
  }
}

height

Type: number

Description: ビルボードの高さを指定します。単位はメートルです。

Default: Required

Example:

{
  billboard: {
    height: 100 // 100メートル
  }
}

offsetDepth

Type: boolean | undefined

Description: 地球表面との重なりを回避します。ビルボードが地球表面にめり込まないようにする場合に使用します。

Default: undefined

Example:

{
  billboard: {
    offsetDepth: true
  }
}

opacity

Type: number | undefined

Description: ビルボードの不透明度を指定します。有効範囲は 0.0（完全に透明）から 1.0（完全に不透明）です。

Default: 1.0

Example:

{
  billboard: {
    transparent: true,
    opacity: 0.5 // 50%の不透明度
  }
}

sizeInMeters

Type: boolean | undefined

Description: サイズをメートル単位で指定するかどうか。false の場合、サイズはピクセル単位です。

Default: true

Example:

{
  billboard: {
    sizeInMeters: true
  }
}

billboardFacing

Type: "upright" | "flat" | undefined

Description: ビルボードを立てて表示するか、地球表面に寝かせて表示するかを指定します。"upright" は立てた状態に保ちます。"flat" はアンカー位置の周辺で地球の曲率に沿って地表に配置するため、地表に描かれているように見え、カメラのピッチに応じて短縮されます。

rotateWithCamera との組み合わせで、次の 4 通りの表示になります。

`billboardFacing`	`rotateWithCamera`	表示
`"upright"`	`true`	画面に正対するビルボード。短縮されません（デフォルト）
`"upright"`	`false`	地表に立ち、方位は固定されます
`"flat"`	`true`	地表に描かれ、常に視点の方を向くように回転します
`"flat"`	`false`	地表に描かれ、北を上にして地図とともに回転します

FeatureEvaluator から facing として地物ごとに指定することもできます。

Default: "upright"

Example:

{
  billboard: {
    billboardFacing: "flat"
  }
}

rotateWithCamera

Type: boolean | undefined

Description: ビルボードをカメラに追従して回転させるかどうかを指定します。true の場合は常に視点の方を向きます。false の場合はアンカー位置のローカルな東・北・上の座標系に固定され、カメラを動かしても向きは変わりません。"upright" では地表に立って南を向くため、真上から見ると縁しか見えずに消え、裏側からは鏡像になります。

FeatureEvaluator から地物ごとに指定することもできます。

Default: true

Example:

{
  billboard: {
    billboardFacing: "upright",
    rotateWithCamera: false
  }
}

rotation

Type: number | undefined

Description: ビルボードを自身の平面内で、アンカー位置を中心に回転させる角度を度数で指定します。正面から見て時計回りです。回転は billboardFacing と rotateWithCamera で決まる向きに対して追加で適用されます。

回転の中心がビルボードのどこになるかは center で決まります。

FeatureEvaluator から地物ごとに指定できるため、レイヤー内のビルボードごとに異なる向きにできます。

Default: 0.0

Example:

{
  billboard: {
    rotation: 45
  }
}

show

Type: boolean | undefined

Description: ビルボードを表示するかどうかを指定します。

Default: undefined

Example:

{
  billboard: {
    show: true
  }
}

size

Type: number

Description: ビルボードのサイズを指定します。単位はメートルです。

Default: Required

Example:

{
  billboard: {
    size: 10 // 10メートル
  }
}

transparent

Type: boolean | undefined

Description: ビルボードの透過度を考慮するかどうかを指定します。true にするとエフェクトを有効にしたときにビルボードがうまく表示されないことがあるので注意してください。

Default: undefined

Example:

{
  billboard: {
    transparent: false
  }
}

url

Type: string | undefined

Description: オブジェクトの URL を指定します。画像ファイルをサポートします。これはレイヤー内のすべての地物に適用されるデフォルト画像です。FeatureEvaluator.evaluate() から image を返すことで、地物ごとに上書きできます。image: null を返すと、上書きした地物はこのデフォルトに戻ります。

Default: undefined

Example:

{
  billboard: {
    url: "https://example.com/icons/marker.png"
  }
}