Class I3sBuildingLayer

constructor

• new I3sBuildingLayer(opts: I3sBuildingLayerOptions): I3sBuildingLayer

  Create the layer. No network happens until it is added to a map; loading starts in onAdd.

  Parameters

  • opts: I3sBuildingLayerOptions

    See I3sBuildingLayerOptions. Only id + url are required.

  Returns I3sBuildingLayer

  Example

  map.addLayer(new I3sBuildingLayer({ id: 'bsl', url: 'https://…/SceneServer/layers/0' }));
  Copy

Readonlyid

ReadonlyrenderingMode

Readonlytype

attributeFields

• attributeFields(): { name: string; numeric: boolean }[]

  The distinct filterable BIM attribute fields across all sublayers (e.g. for a filter dropdown). numeric distinguishes BldgLevel<=2 from Discipline='Architectural' in the value formatting.

  Returns { name: string; numeric: boolean }[]

clearSun

• clearSun(): void

  Revert to the default (no-sun) lighting — the clearSun half of SunLightable (used when the geo-sun system is disabled). Clearing lastSun also gates off the cast-shadow pass.

  Returns void

fieldValues

• fieldValues(field: string, max?: number): Promise<(string | number)[]>

  Sample DISTINCT values of field from currently-resident tiles (to populate a value dropdown). Capped at max; reuses the per-node attribute-column cache.

  Parameters

  • field: string
  • max: number = 40

  Returns Promise<(string | number)[]>

getAttribution

• getAttribution(): string | undefined

  The dataset's attribution string, if any.

  Returns string | undefined

  The attribution option, or undefined if none was set.

getBuilding

• getBuilding(): BuildingSceneLayer | null

  The building's parsed tree (for a discipline/sublayer UI), or null until loaded.

  Returns BuildingSceneLayer | null

getCenter

• getCenter(): [number, number] | null

  The building's camera target [lng, lat] (degrees) — handy for driving your own flyTo.

  Returns [number, number] | null

  [lng, lat] in degrees, or null until the building's anchor is known.

onAdd

• onAdd(map: Map$1, gl: WebGL2RenderingContext | WebGLRenderingContext): void

  MapLibre CustomLayerInterface hook — invoked when the layer is added with map.addLayer; initializes GL resources and begins streaming.

  Parameters

  • map: Map$1
  • gl: WebGL2RenderingContext | WebGLRenderingContext

  Returns void

onRemove

• onRemove(): void

  MapLibre CustomLayerInterface hook — invoked when the layer is removed with map.removeLayer; releases GL resources and stops streaming.

  Returns void

pickPosition

• pickPosition(x: number, y: number, snapRadiusPx?: number): PickedPosition | null

  Resolve a canvas point to the 3D geographic position of the frontmost rendered BSL surface — the screen→scene primitive behind measurement and slice placement (all visible sublayers are queried in one GPU pick pass, exactly the merged set render() draws).

  Parameters

  • x: number

    Canvas X in CSS pixels, top-left origin (e.g. a MapLibre click event's e.point.x).

  • y: number

    Canvas Y in CSS pixels, top-left origin.

  • snapRadiusPx: number = 0

    Snap radius in CSS pixels (default 0 = exact pixel): the nearest mesh hit within the radius wins, so a click slightly off an edge still lands on the mesh.

  Returns PickedPosition | null

  The picked position (lng/lat degrees, height metres above the rendered ground datum, plus the cross-layer-comparable depth01), or null on a miss / before the first frame.

prerender

• prerender(
      gl: WebGL2RenderingContext | WebGLRenderingContext,
      args: CustomRenderMethodInput,
  ): void

  Optional method called during a render frame to allow a layer to prepare resources or render into a texture.

  The layer cannot make any assumptions about the current GL state and must bind a framebuffer before rendering.

  Parameters

  • gl: WebGL2RenderingContext | WebGLRenderingContext
  • args: CustomRenderMethodInput

  Returns void

probeObstruction

• probeObstruction(
      opts: ObstructionProbeOptions,
  ): Float32Array<ArrayBufferLike> | null

  Nearest obstruction distance per height row through a forward corridor — ONE synthetic forward-looking orthographic pick pass over the walker's cross-section, merged across the visible sublayers. The ObstructionProbeable contract; see it for why an overhead height probe cannot tell a doorway from a wall.

  DOOR LEAVES AND RAILINGS ARE EXCLUDED — see DOOR_SUBLAYER_RE and RAILING_SUBLAYER_RE. Both are modelled as solid geometry filling the very opening a walker has to use (a leaf across the doorway, a rail overhanging the treads of the flight), so a probe that honoured them refuses every door and every staircase in the building. Matched by sublayer ROLE (a name test), because the discipline names differ between services; everything else visible counts, glazing included.

  Parameters

  • opts: ObstructionProbeOptions

    The corridor; see ObstructionProbeOptions.

  Returns Float32Array<ArrayBufferLike> | null

  Distance in metres per row (index 0 = lowest), NaN where clear, null when this layer cannot answer.

progress

• progress(): number

  Working-set load fraction (0–1) across every VISIBLE sublayer: drawn tiles over drawn plus still-pending. 1 once the current view is fully resolved.

  Returns number

  The fraction, or 0 before any sublayer is open.

render

• render(
      gl: WebGL2RenderingContext | WebGLRenderingContext,
      args: CustomRenderMethodInput,
  ): void

  Called during a render frame allowing the layer to draw into the GL context.

  The layer can assume blending and depth state is set to allow the layer to properly blend and clip other layers. The layer cannot make any other assumptions about the current GL state.

  If the layer needs to render to a texture, it should implement the prerender method to do this and only use the render method for drawing directly into the main framebuffer.

  The blend function is set to gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA). This expects colors to be provided in premultiplied alpha form where the r, g and b values are already multiplied by the a value. If you are unable to provide colors in premultiplied form you may want to change the blend function to gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA).

  Parameters

  • gl: WebGL2RenderingContext | WebGLRenderingContext
  • args: CustomRenderMethodInput

  Returns void

sampleSurfaceHeights

• sampleSurfaceHeights(
      points: readonly { lat: number; lng: number }[],
      opts?: SurfaceSampleOptions,
  ): (number | null)[]

  Sample the height of the building's topmost rendered surface at each position — ONE synthetic top-down orthographic pick pass over the stations' bbox, then a per-station grid lookup (the "buildings" line on an elevation profile; the surface probe behind first-person navigation). The SurfaceSampleable contract, like the mesh layers.

  All VISIBLE sublayers are sampled in one merged pass — exactly the set render() draws, so sublayers hidden via I3sBuildingLayer.setSublayerVisible (including the auto-hidden Overview shell) contribute nothing. Samples the currently-RESIDENT tiles; positions in unloaded areas return null. Note: individual features hidden by an attribute filter (I3sBuildingLayer.setFilter) still count as surface — the overhead pick pass, like I3sBuildingLayer.pickPosition, does not evaluate per-feature styles.

  Parameters

  • points: readonly { lat: number; lng: number }[]

    lng/lat in degrees.

  • Optionalopts: SurfaceSampleOptions

    Optional: gridPx sets the overhead pass's long-axis resolution (default 1024; small values like 64 for cheap point probes), marginM the padding around the stations, and maxHeightM a CUT so the reading is the highest surface BELOW it rather than the topmost — the difference between "the roof of this building" and "the floor I am standing on", and the reason a walker can read one storey of a BSL at all (see SurfaceSampleOptions.maxHeightM).

  Returns (number | null)[]

  Height in metres above the rendered ground datum per point, or null where this layer has no surface.

setBoundsOverlay

• setBoundsOverlay(on: boolean): void

  Toggle the DEBUG tile bounding-volume (OBB) wireframe overlay live (placement QA).

  Parameters

  • on: boolean

  Returns void

setClippingPlanes

• setClippingPlanes(planes: ClippingPlanesOptions | null): void

  Replace this layer's clipping planes at runtime. Planes are geographic (ClippingPlanesOptions) and survive re-anchors; null (or an empty or disabled set) removes clipping and restores byte-identical rendering.

  Parameters

  • planes: ClippingPlanesOptions | null

    The new plane set, or null to clear.

  Returns void

setFilter

• setFilter(expr: string | null, opts?: { mode?: "hide" | "xray" }): Promise<void>

  Filter the building by a BSL SQL predicate over per-feature BIM attributes — e.g. "Discipline='Architectural'", "BldgLevel<=2", "Category IN ('Walls','Doors')". Features that DON'T match are hidden (mode:'hide', default) or dimmed to a dark ghost (mode:'xray'). Compiled once; evaluated per feature only on change; the GPU pays one texture lookup at draw time.

  Parameters

  • expr: string | null

    A BSL SQL predicate string, or null / '' to clear the filter (show everything).

  • Optionalopts: { mode?: "hide" | "xray" }

    Filter display mode. mode:'hide' (default) removes non-matching features; mode:'xray' dims them so the surrounding context stays legible. Omit to keep the current mode.

  Returns Promise<void>

  A promise that resolves once every resident tile has been re-styled.

  Remarks

  X-ray DIMS; it does not make anything see-through. The per-feature style carries an alpha, but the building draws in the opaque pass (written unblended), so that alpha lands as a darkening multiply on the colour instead of compositing what is behind — the excluded parts read as a dark ghost of the model, still legible as context. Documented as-is rather than as-intended: the see-through version needs a blended pass (mesh KNOWN-GAPS §2), which this layer does not have.

setOpacity

• setOpacity(opacity: number): void

  Fade the whole building over the basemap (all sublayers together).

  Parameters

  • opacity: number

    0 (invisible) – 1 (opaque); clamped.

  Returns void

setShadows

• setShadows(on: boolean): void

  Toggle cast shadows at runtime (the setShadows half of SunLightable).

  Parameters

  • on: boolean

    true to cast shadows (needs a sun via I3sBuildingLayer.setSunState), false to disable.

  Returns void

setSharedDrape

• setSharedDrape(shared: SharedDrape | null): void

  Adopt (or clear) the shared vector-drape atlas — satisfies the DrapeReceiver contract, so enableVectorDrape drives this layer directly. Stashed until the renderer exists.

  Parameters

  • shared: SharedDrape | null

  Returns void

setSublayerVisible

• setSublayerVisible(id: number, visible: boolean): void

  Show/hide one BIM sublayer by id (re-renders without re-streaming).

  Parameters

  • id: number

    The sublayer id (from I3sBuildingLayer.getBuilding's sublayer tree).

  • visible: boolean

    true to show, false to hide.

  Returns void

setSunState

• setSunState(sun: SunState): void

  Light this layer from a SunState — satisfies @bitruvius/sdk-maplibre's SunLightable, so a GeoSunSystem / RendererSunController drives it directly.

  Parameters

  • sun: SunState

    The sun state (direction in ENU, altitude in degrees) to light + (if enabled) cast shadows from.

  Returns void

setVisible

• setVisible(visible: boolean): void

  Show/hide the whole building without removing the layer.

  Parameters

  • visible: boolean

    true to show, false to hide.

  Returns void

setWireframe

• setWireframe(mode: 0 | 1 | 2): void

  Wireframe render mode for the whole building (a BIM structure view). Edges come from the mesh triangles in-shader (no extra geometry); applies to the I3S PAA (non-indexed) sublayers these BSLs use — enable the I3sBuildingLayerOptions.wireframe option to make it work on Draco-served sublayers too.

  Parameters

  • mode: 0 | 1 | 2

    0 = off (solid), 1 = edges drawn over the solid, 2 = wireframe only.

  Returns void

stats

• stats(): {
      bytes: number;
      inFlight: number;
      loading: number;
      queued: number;
      rendered: number;
      resident: number;
      sublayers: number;
      visible: number;
  }

  Aggregate streaming stats across visible sublayers — drive a debug HUD / load indicator from it.

  Returns {
      bytes: number;
      inFlight: number;
      loading: number;
      queued: number;
      rendered: number;
      resident: number;
      sublayers: number;
      visible: number;
  }

  Counts of sublayers (total) and visible sublayers, plus tile totals across the visible ones: rendered (drawn this frame), resident (in VRAM), loading (decoding), inFlight (network), queued (waiting to load) and resident bytes.

sublayerStates

• sublayerStates(): BslSublayerState[]

  Every renderable sublayer with the state this layer ACTUALLY applied, and — when one is not drawn — why. Built for a sublayer show/hide UI: BslSublayer.visibility alone is the service's declared flag, which is only one of the three reasons a sublayer can be off, so a checklist seeded from it claims sublayers are on that the layer is correctly hiding.

  Distinguishing them matters: a service-hidden discipline and a user-hidden one look identical on screen, and reading "the publisher switched this off" as "the SDK lost my geometry" is how a correctly-rendered BSL gets reported as broken.

  Returns BslSublayerState[]

  One entry per renderable leaf in tree order (including non-3DObject leaves, which report opened: false / hiddenReason: 'not-renderable'). Empty until the building document has loaded — poll, or call it from your onLoad.

  Example

  for (const s of layer.sublayerStates()) {
    const badge = s.hiddenReason && s.hiddenReason !== 'user' ? ` — ${s.hiddenReason}` : '';
    console.log(`${s.visible ? '☑' : '☐'} ${s.name}${badge}`);
  }
  Copy