BillboardMaterial

BillboardMaterial represents a material for billboard rendering.

Properties

alphaTest

Type: number | undefined

Description: Pixels with an RGBA alpha value below this threshold will not be rendered.

Default: undefined

Example:

{
  billboard: {
    alphaTest: 0.5
  }
}

backfaceCulling

Type: boolean | undefined

Description: Whether the billboard is hidden when seen from behind. When false, both sides of the billboard are drawn. When true, only its front is drawn.

It has no effect on an upright billboard that follows the camera (the default), which always shows its front. It matters in two cases. With rotateWithCamera set to false, the billboard can be seen from behind, where it appears mirrored, and turning this on hides it instead. With billboardFacing set to "flat", its front faces away from the globe, so turning this on also hides the parts of a large billboard that wrap over the horizon.

Default: false

Example:

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

center

Type: Vec2

Description: Specifies the shift amount from the center. The range is between 0 and 1.

Default: Required

Example:

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

clampToGround

Type: boolean

Description: Specifies whether to clamp the billboard to the ground.

Default: Required

Example:

{
  billboard: {
    clampToGround: true
  }
}

color

Type: Color

Description: Specifies the billboard color as a Color instance.

Default: Required

Example:

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

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

declutter

Type: boolean | undefined

Description: Participate in screen-space decluttering: when labels/sprites overlap on screen, lower-priority ones are hidden. Enabled by default. Set to false to draw every label unconditionally.

Default: true

Example:

{
  billboard: {
    declutter: false
  }
}

declutterPriority

Type: number | undefined

Description: Placement priority for decluttering. Higher wins. Only meaningful when declutter is enabled. Can be overridden per feature via FeatureEvaluator.evaluate().

Default: 0.0

Example:

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

depthTest

Type: boolean

Description: A variable that determines whether front-facing models occlude back-facing models.

Default: true

Example:

{
  billboard: {
    depthTest: true
  }
}

effectIds

Type: string[] | undefined

Description: Specifies the IDs of selective effects to apply (e.g., “bloom”, “outline”). Used in conjunction with SelectiveBloomEffectDesc or SelectiveOutlineEffectDesc.

Default: undefined

Example:

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

emissiveColor

Type: Color | undefined

Description: Specifies the emissive color as a Color instance.

Default: undefined

Example:

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

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

emissiveIntensity

Type: number | undefined

Description: Specifies the emissive intensity.

Default: undefined

Example:

{
  billboard: {
    emissiveIntensity: 0.5
  }
}

geometryTypes

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

Description: Source geometry categories this material consumes. Adding "line" emits one billboard per line-string vertex, and adding "polygon" emits one billboard per polygon-ring vertex (the closing duplicate vertex is skipped). Setting the array replaces the default, so include "point" when point geometry should keep rendering. This option applies when the layer’s geometry is built: set it at layer creation. layer.update() applies a new value only to tiles loaded afterwards, so already-loaded tiles keep their previous geometry until the layer is re-created.

Default: ["point"]

Example:

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

height

Type: number

Description: Specifies the height of the billboard. The unit is meters.

Default: Required

Example:

{
  billboard: {
    height: 100 // 100 meters
  }
}

offsetDepth

Type: boolean | undefined

Description: Avoids overlap with the earth’s surface. Use this to prevent the billboard from clipping into the earth’s surface.

Default: undefined

Example:

{
  billboard: {
    offsetDepth: true
  }
}

opacity

Type: number | undefined

Description: Specifies the opacity of the billboard. Valid range is 0.0 (fully transparent) to 1.0 (fully opaque).

Default: 1.0

Example:

{
  billboard: {
    transparent: true,
    opacity: 0.5 // 50% opacity
  }
}

sizeInMeters

Type: boolean | undefined

Description: Whether the size is specified in meters. If false, the size is in pixels.

Default: true

Example:

{
  billboard: {
    sizeInMeters: true
  }
}

billboardFacing

Type: "upright" | "flat" | undefined

Description: Whether the billboard stands up or lies on the globe surface. "upright" keeps it standing. "flat" lays it on the globe surface around its anchor, following the globe’s curvature, so it reads as painted onto the surface and foreshortens with camera pitch.

Combine with rotateWithCamera for four behaviours:

`billboardFacing`	`rotateWithCamera`	Result
`"upright"`	`true`	Screen-aligned billboard, never foreshortened (the default)
`"upright"`	`false`	Standing on the surface at a fixed bearing
`"flat"`	`true`	Painted on the surface, turned to keep facing the viewer
`"flat"`	`false`	Painted on the surface, north-up, turning with the map

Can also be set per feature from a feature evaluator as facing.

Default: "upright"

Example:

{
  billboard: {
    billboardFacing: "flat"
  }
}

rotateWithCamera

Type: boolean | undefined

Description: Whether the billboard turns to follow the camera. When true, it always faces the viewer. When false, it is fixed in its anchor’s local east/north/up frame, and moving the camera never reorients it. With "upright", it stands on the surface facing south, so it is seen edge-on from directly above and mirrored from behind.

Can also be set per feature from a feature evaluator.

Default: true

Example:

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

rotation

Type: number | undefined

Description: Rotates the billboard within its own plane around its anchor point, in degrees, clockwise as seen from the front. The rotation is applied on top of the orientation that billboardFacing and rotateWithCamera resolve to.

center decides where inside the billboard the pivot sits.

Can also be set per feature from a feature evaluator, so every billboard in a layer can point a different way.

Default: 0.0

Example:

{
  billboard: {
    rotation: 45
  }
}

show

Type: boolean | undefined

Description: Specifies whether to show the billboard.

Default: undefined

Example:

{
  billboard: {
    show: true
  }
}

size

Type: number

Description: Specifies the size of the billboard. The unit is meters.

Default: Required

Example:

{
  billboard: {
    size: 10 // 10 meters
  }
}

transparent

Type: boolean | undefined

Description: Specifies whether to consider the billboard’s transparency. Note that setting this to true may cause the billboard to not display correctly when effects are enabled.

Default: undefined

Example:

{
  billboard: {
    transparent: false
  }
}

url

Type: string | undefined

Description: Specifies the URL of the object. Supports image files. This is the default image for every feature in the layer. Individual features can override it by returning image from FeatureEvaluator.evaluate(), and returning image: null reverts an overridden feature to this default.

Default: undefined

Example:

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