@tomtom-org/maps-sdk-plugin-landmarks-3d 0.0.4 → 0.0.6

package/dist/index.d.ts

@@ -1,343 +1,355 @@
-import { AmbientLight } from 'three';
-import { Camera } from 'three';
-import { CustomLayerInterface } from 'maplibre-gl';
-import { CustomRenderMethodInput } from 'maplibre-gl';
-import { DirectionalLight } from 'three';
-import { Group } from 'three';
-import { Map as Map_2 } from 'maplibre-gl';
-import { Mesh } from 'three';
-import { Scene } from 'three';
-import { ShaderMaterial } from 'three';
-import { Texture } from 'three';
-import { TomTomMap } from '../../map/dist';
-import { WebGLRenderer } from 'three';
-
-/**
- * Builds the TomTom Orbis 3D Landmarks tile URL template.
- *
- * @remarks
- * The API serves meshopt-compressed GLB tiles with KTX2/Basis textures and requires
- * an API key with Orbis 3D Landmarks entitlements (still in Private Preview).
- *
- * @group Landmarks 3D
- */
-export declare const buildLandmarksTileURL: () => string;
-
-/**
- * Alpha mask carried over from a landmark mesh's as-authored texture.
- *
- * Landmark meshes are coarse hulls (e.g. a wall is one rectangle) whose realistic
- * silhouette is carved out by the texture's alpha channel. Untextured shading must keep
- * sampling that alpha and discard the carved-away fragments, otherwise the raw hull
- * shape gets coloured in.
- *
- * @group Landmarks 3D
- */
-declare type FillExtrusionAlphaMask = {
-    /** Texture whose alpha channel carves the mesh silhouette (the mesh's base colour map). */
-    map: Texture;
-    /** Fragments with alpha below this are discarded. */
-    cutoff: number;
-};
-
-/**
- * Material that shades untextured landmark meshes exactly like maplibre-gl shades
- * `fill-extrusion` buildings, so they blend in with the basemap building layer.
- *
- * Colour and opacity premultiply like maplibre's `v_color *= u_opacity`, paired with
- * (ONE, ONE_MINUS_SRC_ALPHA) blending. Backfaces are culled like maplibre's extrusion
- * rendering, except for alpha-masked meshes whose cutout surfaces must stay visible from
- * both sides; pair with {@link FillExtrusionDepthMaterial} as a depth prepass so that
- * translucent landmarks blend with the basemap exactly once per pixel.
- *
- * @group Landmarks 3D
- */
-declare class FillExtrusionMaterial extends ShaderMaterial {
-    constructor(alphaMask?: FillExtrusionAlphaMask);
-    /**
-     * Copies the shading uniforms (colour, light, layer opacity) from another instance,
-     * bringing a freshly created alpha-masked variant up to date with the shared material.
-     */
-    copyShadingFrom(source: FillExtrusionMaterial): void;
-    /**
-     * Sets the building colour from a CSS colour string, stored as raw sRGB
-     * components — maplibre shades paint colours in sRGB space, not linear.
-     */
-    setDiffuseColor(cssColor: string): void;
-    setLayerOpacity(opacity: number): void;
-    /**
-     * Mirrors maplibre's fill-extrusion light uniforms: the style light position is
-     * rotated by the map bearing for viewport-anchored lights and the light vector is
-     * deliberately left unnormalised, exactly like maplibre's `u_lightpos`.
-     *
-     * @param position - The style light position, in maplibre's y-south axes.
-     * @param bearingInRadians - Map bearing to rotate by; pass `0` for map-anchored lights.
-     * @param intensity - The style light intensity.
-     * @param color - The style light colour.
-     */
-    setLight(position: {
-        x: number;
-        y: number;
-        z: number;
-    }, bearingInRadians: number, intensity: number, color: {
-        r: number;
-        g: number;
-        b: number;
-    }): void;
-}
-
-/**
- * Renders TomTom Orbis 3D Landmarks (high-detail building meshes) on a {@link TomTomMap}.
- *
- * The plugin streams GLB tiles from the Orbis 3D Landmarks API (Private Preview),
- * renders them with Three.js via a MapLibre custom layer, filters overlapping
- * extruded basemap buildings out of the style, and keeps everything restored
- * across map style changes.
- *
- * @remarks
- * Requires an API key with Orbis 3D Landmarks entitlements and a map style that
- * shows extruded 3D buildings for the exclusion filter and `inherited` mode to
- * have an effect.
- *
- * @example
- * ```typescript
- * import { Landmarks3D } from '@tomtom-org/maps-sdk-plugin-landmarks-3d';
- *
- * // assume `map` is your initialized TomTomMap instance
- * const landmarks = new Landmarks3D(map);
- *
- * await landmarks.setDisplayMode('inherited');
- * ```
- *
- * @group Landmarks 3D
- */
-export declare class Landmarks3D {
-    private readonly map;
-    private readonly layerID;
-    private readonly basemapBuildingLayerID;
-    private readonly modelsLayer;
-    private readonly layerMinZoom?;
-    private readonly layerMaxZoom?;
-    private displayMode;
-    /**
-     * Creates the plugin bound to a TomTom map and starts rendering landmarks
-     * as soon as the map is ready.
-     *
-     * @param map - The TomTom map instance to render landmarks on.
-     * @param options - Optional configuration.
-     */
-    constructor(map: TomTomMap, options?: Landmarks3DOptions);
-    private installWhenReady;
-    /**
-     * The underlying MapLibre custom layer, for advanced use beyond this facade.
-     */
-    get layer(): ModelsLayer;
-    /**
-     * The currently applied display mode.
-     */
-    getDisplayMode(): Landmarks3DDisplayMode;
-    /**
-     * Changes how landmarks are rendered relative to the base map.
-     *
-     * @param mode - The display mode to apply.
-     * @returns A promise that resolves once the mode has been applied.
-     */
-    setDisplayMode(mode: Landmarks3DDisplayMode): Promise<void>;
-    /**
-     * Whether the landmarks are currently visible.
-     */
-    isVisible(): boolean;
-    /**
-     * Shows or hides the landmarks layer.
-     *
-     * @param visible - `true` to show landmarks, `false` to hide them.
-     * @returns A promise that resolves once the visibility has been applied.
-     */
-    setVisible(visible: boolean): Promise<void>;
-    private install;
-    private landmarkInsertBeforeID;
-    private alignZoomRangeWithBasemapBuildings;
-    private excludeLandmarkBuildingsFromBasemap;
-    private readBasemapBuildingMaterial;
-    private resolveCurrentMaterialState;
-    private applyDisplayMode;
-}
-
-/**
- * How 3D landmarks are shaded relative to the base map. Every mode renders the
- * landmarks as maplibre-style fill-extrusion buildings:
- * - `inherited`: mirrors the colour and opacity of the basemap 3D building layer (default).
- * - `dark`: uses the 3D building look of the SDK's standard dark style.
- * - `light`: uses the 3D building look of the SDK's standard light style.
- *
- * @group Landmarks 3D
- */
-export declare type Landmarks3DDisplayMode = 'inherited' | 'dark' | 'light';
-
-/**
- * Configuration for the {@link Landmarks3D} plugin.
- *
- * @group Landmarks 3D
- */
-export declare type Landmarks3DOptions = {
-    /**
-     * Initial display mode for the landmarks. Can also be changed at runtime with
-     * {@link Landmarks3D.setDisplayMode}.
-     * @defaultValue `'inherited'`
-     */
-    displayMode?: Landmarks3DDisplayMode;
-    /**
-     * Whether the landmarks are initially visible. Can also be changed at runtime with
-     * {@link Landmarks3D.setVisible}.
-     * @defaultValue `true`
-     */
-    visible?: boolean;
-    /**
-     * Minimum zoom at which landmarks are rendered.
-     * @defaultValue The basemap 3D building layer's minimum zoom, so landmarks appear together
-     * with it (falls back to `10` when that layer is absent).
-     */
-    minZoom?: number;
-    /**
-     * Maximum zoom at which landmarks are rendered.
-     * @defaultValue The basemap 3D building layer's maximum zoom, so landmarks disappear together
-     * with it (falls back to `22` when that layer is absent).
-     */
-    maxZoom?: number;
-    /**
-     * Send `credentials: 'include'` with each tile request so a proxy session
-     * cookie travels with it. By default this tracks the SDK's proxy config, so
-     * tiles behave like every other SDK request; set it explicitly only to
-     * override that.
-     * @defaultValue Auto-detected — `true` when the SDK is configured for a
-     * credentialed proxy (no `apiKey` + non-default `commonBaseURL`).
-     */
-    withCredentials?: boolean;
-};
-
-/**
- * MapLibre custom layer that renders tiled glTF/GLB models with Three.js.
- *
- * The layer owns a {@link ModelsSource} that streams model tiles for the current
- * viewport, renders them as maplibre-style fill-extrusion buildings, and keeps its
- * lighting in sync with the map style light.
- *
- * @group Landmarks 3D
- */
-export declare class ModelsLayer implements CustomLayerInterface {
-    id: string;
-    type: "custom";
-    renderingMode: "3d";
-    renderer: WebGLRenderer;
-    scene: Scene;
-    camera: Camera;
-    tiles: Group;
-    directionalLight: DirectionalLight;
-    ambientLight: AmbientLight;
-    map: Map_2;
-    source: ModelsSource;
-    minzoom: number;
-    maxzoom: number;
-    visible: boolean;
-    diffuseColor: string;
-    private readonly fillExtrusionMaterial;
-    private readonly depthPrepassMaterial;
-    private readonly maskedFillExtrusionMaterials;
-    constructor(options: ModelsLayerSpecification, source: ModelsSourceSpecification);
-    updateProperties(options: ModelsLayerSpecification): void;
-    setDirectionalLight(radius: number, phi: number, theta: number): void;
-    onAdd(map: Map_2, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
-    render(_gl: WebGLRenderingContext | WebGL2RenderingContext, options: CustomRenderMethodInput): void;
-    private alignCameraToMap;
-    private needsTranslucentPrepass;
-    private renderDepthPrepass;
-    setOpacity(value: number): void;
-    getMaterial(mesh: Mesh): FillExtrusionMaterial;
-    private maskedFillExtrusionVariant;
-    private forEachFillExtrusionMaterial;
-    private syncLighting;
-    private applyMaterials;
-}
-
-/**
- * Style-like specification for a {@link ModelsLayer}, mirroring the shape of a
- * MapLibre layer definition so 3D model layers can be configured declaratively.
- *
- * @group Landmarks 3D
- */
-export declare interface ModelsLayerSpecification {
-    id: string;
-    type: 'models';
-    source: string;
-    before?: string;
-    minzoom?: number;
-    maxzoom?: number;
-    paint?: {
-        'models-base-color'?: string;
-    };
-    layout?: {
-        visibility?: 'visible' | 'none';
-    };
-}
-
-/**
- * Source of tiled glTF/GLB models for a {@link ModelsLayer}.
- *
- * Tracks the tiles covering the current viewport, fetches each tile's models once
- * and keeps them in a Three.js {@link Group} that the owning layer renders.
- *
- * @group Landmarks 3D
- */
-export declare class ModelsSource {
-    type: "models";
-    id: string;
-    minzoom: number;
-    maxzoom: number;
-    map: Map_2;
-    tiles: Array<string>;
-    scene: Group;
-    loadedTiles: Set<string>;
-    /** Optional consumer callback fired once per successful tile load. */
-    onTileLoaded?: (scene: Group, key: string) => void;
-    private readonly ktx2Loader;
-    private readonly gltfLoader;
-    private readonly specification;
-    private readonly withCredentials;
-    constructor(id: string, options: ModelsSourceSpecification);
-    onAdd(map: Map_2, renderer: WebGLRenderer): void;
-    updateTiles(): void;
-    private coveringTiles;
-    private loadTile;
-    private fetchTile;
-}
-
-/**
- * Style-like specification for a {@link ModelsSource}: a tiled source of
- * glTF/GLB models, mirroring the shape of a MapLibre raster/vector source definition.
- *
- * @group Landmarks 3D
- */
-export declare interface ModelsSourceSpecification {
-    type: 'models';
-    tiles: Array<string>;
-    bounds?: [number, number, number, number];
-    scheme?: 'xyz' | 'tms';
-    minzoom?: number;
-    maxzoom?: number;
-    attribution?: string;
-    /**
-     * Base path of the Basis Universal transcoder used to decode KTX2 textures.
-     * Defaults to the three.js examples CDN path on unpkg; point this at a
-     * self-hosted copy when external CDNs are not an option (e.g. strict CSP).
-     */
-    transcoderPath?: string;
-    /**
-     * Send `credentials: 'include'` with each tile request so a session cookie
-     * (e.g. the demo-BFF proxy's) travels with it. Leave off for direct
-     * `api.tomtom.com` access, where credentialed CORS would fail.
-     * @defaultValue `false`
-     */
-    withCredentials?: boolean;
-}
-
-export { }
+import { TomTomMap } from "@tomtom-org/maps-sdk/map";
+import { CustomLayerInterface, CustomRenderMethodInput, Map } from "maplibre-gl";
+import { AmbientLight, Camera, DirectionalLight, Group, Mesh, Scene, ShaderMaterial, Texture, WebGLRenderer } from "three";
+//#region src/displayMode.d.ts
+/**
+ * How 3D landmarks are shaded relative to the base map. Every mode renders the
+ * landmarks as maplibre-style fill-extrusion buildings:
+ * - `inherited`: mirrors the colour, opacity and vertical gradient of the basemap 3D building layer (default).
+ * - `dark`: uses the 3D building look of the SDK's standard dark style.
+ * - `light`: uses the 3D building look of the SDK's standard light style.
+ *
+ * @group Landmarks 3D
+ */
+type Landmarks3DDisplayMode = 'inherited' | 'dark' | 'light';
+//#endregion
+//#region src/FillExtrusionMaterial.d.ts
+/**
+ * Alpha mask carried over from a landmark mesh's as-authored texture.
+ *
+ * Landmark meshes are coarse hulls (e.g. a wall is one rectangle) whose realistic
+ * silhouette is carved out by the texture's alpha channel. Untextured shading must keep
+ * sampling that alpha and discard the carved-away fragments, otherwise the raw hull
+ * shape gets coloured in.
+ *
+ * @group Landmarks 3D
+ */
+type FillExtrusionAlphaMask = {
+  /** Texture whose alpha channel carves the mesh silhouette (the mesh's base colour map). */
+  map: Texture;
+  /** Fragments with alpha below this are discarded. */
+  cutoff: number;
+};
+/**
+ * Material that shades untextured landmark meshes exactly like maplibre-gl shades
+ * `fill-extrusion` buildings, so they blend in with the basemap building layer.
+ *
+ * Colour and opacity premultiply like maplibre's `v_color *= u_opacity`, paired with
+ * (ONE, ONE_MINUS_SRC_ALPHA) blending. Backfaces are culled like maplibre's extrusion
+ * rendering, except for alpha-masked meshes whose cutout surfaces must stay visible from
+ * both sides; pair with {@link FillExtrusionDepthMaterial} as a depth prepass so that
+ * translucent landmarks blend with the basemap exactly once per pixel.
+ *
+ * @group Landmarks 3D
+ */
+declare class FillExtrusionMaterial extends ShaderMaterial {
+  constructor(alphaMask?: FillExtrusionAlphaMask);
+  /**
+   * Copies the shading uniforms (colour, light, layer opacity, vertical gradient) from another
+   * instance, bringing a freshly created alpha-masked variant up to date with the shared material.
+   */
+  copyShadingFrom(source: FillExtrusionMaterial): void;
+  /**
+   * Sets the building colour from a CSS colour string, stored as raw sRGB
+   * components — maplibre shades paint colours in sRGB space, not linear.
+   */
+  setDiffuseColor(cssColor: string): void;
+  setLayerOpacity(opacity: number): void;
+  /** Enables or disables maplibre's `fill-extrusion-vertical-gradient` wall darkening. */
+  setVerticalGradient(enabled: boolean): void;
+  /**
+   * Mirrors maplibre's fill-extrusion light uniforms: the style light position is
+   * rotated by the map bearing for viewport-anchored lights and the light vector is
+   * deliberately left unnormalised, exactly like maplibre's `u_lightpos`.
+   *
+   * @param position - The style light position, in maplibre's y-south axes.
+   * @param bearingInRadians - Map bearing to rotate by; pass `0` for map-anchored lights.
+   * @param intensity - The style light intensity.
+   * @param color - The style light colour.
+   */
+  setLight(position: {
+    x: number;
+    y: number;
+    z: number;
+  }, bearingInRadians: number, intensity: number, color: {
+    r: number;
+    g: number;
+    b: number;
+  }): void;
+}
+//#endregion
+//#region src/types/modelsSpecifications.d.ts
+/**
+ * Style-like specification for a {@link ModelsLayer}, mirroring the shape of a
+ * MapLibre layer definition so 3D model layers can be configured declaratively.
+ *
+ * @group Landmarks 3D
+ */
+interface ModelsLayerSpecification {
+  id: string;
+  type: 'models';
+  source: string;
+  before?: string;
+  minzoom?: number;
+  maxzoom?: number;
+  paint?: {
+    'models-base-color'?: string;
+  };
+  layout?: {
+    visibility?: 'visible' | 'none';
+  };
+}
+/**
+ * Style-like specification for a {@link ModelsSource}: a tiled source of
+ * glTF/GLB models, mirroring the shape of a MapLibre raster/vector source definition.
+ *
+ * @group Landmarks 3D
+ */
+interface ModelsSourceSpecification {
+  type: 'models';
+  tiles: Array<string>;
+  bounds?: [number, number, number, number];
+  scheme?: 'xyz' | 'tms';
+  minzoom?: number;
+  maxzoom?: number;
+  attribution?: string;
+  /**
+   * Base path of the Basis Universal transcoder used to decode KTX2 textures.
+   * Defaults to the three.js examples CDN path on unpkg; point this at a
+   * self-hosted copy when external CDNs are not an option (e.g. strict CSP).
+   */
+  transcoderPath?: string;
+  /**
+   * Send `credentials: 'include'` with each tile request so a session cookie
+   * (e.g. the demos proxy's) travels with it. Leave off for direct
+   * `api.tomtom.com` access, where credentialed CORS would fail.
+   * @defaultValue `false`
+   */
+  withCredentials?: boolean;
+}
+//#endregion
+//#region src/ModelsSource.d.ts
+/**
+ * Source of tiled glTF/GLB models for a {@link ModelsLayer}.
+ *
+ * Tracks the tiles covering the current viewport, fetches each tile's models once
+ * and keeps them in a Three.js {@link Group} that the owning layer renders.
+ *
+ * @group Landmarks 3D
+ */
+export declare class ModelsSource {
+  type: "models";
+  id: string;
+  minzoom: number;
+  maxzoom: number;
+  map: Map;
+  tiles: Array<string>;
+  scene: Group;
+  loadedTiles: Set<string>;
+  /**
+   * EPSG:3857 origin subtracted from all mesh positions: absolute coordinates (~6·10⁶ m) exceed
+   * float32 precision (~0.5 m), which makes landmark edges tremble while zooming. `null` until the
+   * first tile with meshes loads.
+   */
+  sceneOrigin: {
+    x: number;
+    y: number;
+  } | null;
+  /** Optional consumer callback fired once per successful tile load. */
+  onTileLoaded?: (scene: Group, key: string) => void;
+  private readonly ktx2Loader;
+  private readonly gltfLoader;
+  private readonly specification;
+  private readonly withCredentials;
+  constructor(id: string, options: ModelsSourceSpecification);
+  onAdd(map: Map, renderer: WebGLRenderer): void;
+  updateTiles(): void;
+  private showCoveringTilesOnly;
+  private coveringTiles;
+  private loadTile;
+  private rebaseToSceneOrigin;
+  private fetchTile;
+}
+//#endregion
+//#region src/ModelsLayer.d.ts
+/**
+ * MapLibre custom layer that renders tiled glTF/GLB models with Three.js.
+ *
+ * The layer owns a {@link ModelsSource} that streams model tiles for the current
+ * viewport, renders them as maplibre-style fill-extrusion buildings, and keeps its
+ * lighting in sync with the map style light.
+ *
+ * @group Landmarks 3D
+ */
+export declare class ModelsLayer implements CustomLayerInterface {
+  id: string;
+  type: "custom";
+  renderingMode: "3d";
+  renderer: WebGLRenderer;
+  scene: Scene;
+  camera: Camera;
+  tiles: Group;
+  directionalLight: DirectionalLight;
+  ambientLight: AmbientLight;
+  map: Map;
+  source: ModelsSource;
+  minzoom: number;
+  maxzoom: number;
+  visible: boolean;
+  diffuseColor: string;
+  private readonly fillExtrusionMaterial;
+  private readonly depthPrepassMaterial;
+  private readonly maskedFillExtrusionMaterials;
+  constructor(options: ModelsLayerSpecification, source: ModelsSourceSpecification);
+  updateProperties(options: ModelsLayerSpecification): void;
+  setDirectionalLight(radius: number, phi: number, theta: number): void;
+  onAdd(map: Map, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
+  render(_gl: WebGLRenderingContext | WebGL2RenderingContext, options: CustomRenderMethodInput): void;
+  private groundLandmarksOnTerrain;
+  private groundMeshOnTerrain;
+  private terrainSamplePoints;
+  private alignCameraToMap;
+  private get sceneOrigin();
+  private needsTranslucentPrepass;
+  private renderDepthPrepass;
+  setOpacity(value: number): void;
+  /** Mirrors the basemap's fill-extrusion-vertical-gradient on the landmark shading. */
+  setVerticalGradient(enabled: boolean): void;
+  getMaterial(mesh: Mesh): FillExtrusionMaterial;
+  private maskedFillExtrusionVariant;
+  private forEachFillExtrusionMaterial;
+  private syncLighting;
+  private applyMaterials;
+}
+//#endregion
+//#region src/Landmarks3D.d.ts
+/**
+ * Configuration for the {@link Landmarks3D} plugin.
+ *
+ * @group Landmarks 3D
+ */
+type Landmarks3DOptions = {
+  /**
+   * Initial display mode for the landmarks. Can also be changed at runtime with
+   * {@link Landmarks3D.setDisplayMode}.
+   * @defaultValue `'inherited'`
+   */
+  displayMode?: Landmarks3DDisplayMode;
+  /**
+   * Whether the landmarks are initially visible. Can also be changed at runtime with
+   * {@link Landmarks3D.setVisible}.
+   * @defaultValue `true`
+   */
+  visible?: boolean;
+  /**
+   * Minimum zoom at which landmarks are rendered.
+   * @defaultValue The basemap 3D building layer's minimum zoom, so landmarks appear together
+   * with it (falls back to `10` when that layer is absent).
+   */
+  minZoom?: number;
+  /**
+   * Maximum zoom at which landmarks are rendered.
+   * @defaultValue The basemap 3D building layer's maximum zoom, so landmarks disappear together
+   * with it (falls back to `22` when that layer is absent).
+   */
+  maxZoom?: number;
+  /**
+   * Send `credentials: 'include'` with each tile request so a proxy session
+   * cookie travels with it. By default this tracks the SDK's proxy config, so
+   * tiles behave like every other SDK request; set it explicitly only to
+   * override that.
+   * @defaultValue Auto-detected — `true` when the SDK is configured for a
+   * credentialed proxy (no `apiKey` + non-default `commonBaseURL`).
+   */
+  withCredentials?: boolean;
+};
+/**
+ * Renders TomTom Orbis 3D Landmarks (high-detail building meshes) on a {@link TomTomMap}.
+ *
+ * The plugin streams GLB tiles from the Orbis 3D Landmarks API (Private Preview),
+ * renders them with Three.js via a MapLibre custom layer, filters overlapping
+ * extruded basemap buildings out of the style, and keeps everything restored
+ * across map style changes.
+ *
+ * @remarks
+ * Requires an API key with Orbis 3D Landmarks entitlements and a map style that
+ * shows extruded 3D buildings for the exclusion filter and `inherited` mode to
+ * have an effect.
+ *
+ * @example
+ * ```typescript
+ * import { Landmarks3D } from '@tomtom-org/maps-sdk-plugin-landmarks-3d';
+ *
+ * // assume `map` is your initialized TomTomMap instance
+ * const landmarks = new Landmarks3D(map);
+ *
+ * await landmarks.setDisplayMode('inherited');
+ * ```
+ *
+ * @group Landmarks 3D
+ */
+export declare class Landmarks3D {
+  private readonly map;
+  private readonly layerID;
+  private readonly basemapBuildingLayerID;
+  private readonly modelsLayer;
+  private readonly layerMinZoom?;
+  private readonly layerMaxZoom?;
+  private displayMode;
+  /**
+   * Creates the plugin bound to a TomTom map and starts rendering landmarks
+   * as soon as the map is ready.
+   *
+   * @param map - The TomTom map instance to render landmarks on.
+   * @param options - Optional configuration.
+   */
+  constructor(map: TomTomMap, options?: Landmarks3DOptions);
+  private installWhenReady;
+  /**
+   * The underlying MapLibre custom layer, for advanced use beyond this facade.
+   */
+  get layer(): ModelsLayer;
+  /**
+   * The currently applied display mode.
+   */
+  getDisplayMode(): Landmarks3DDisplayMode;
+  /**
+   * Changes how landmarks are rendered relative to the base map.
+   *
+   * @param mode - The display mode to apply.
+   * @returns A promise that resolves once the mode has been applied.
+   */
+  setDisplayMode(mode: Landmarks3DDisplayMode): Promise<void>;
+  /**
+   * Whether the landmarks are currently visible.
+   */
+  isVisible(): boolean;
+  /**
+   * Shows or hides the landmarks layer.
+   *
+   * @param visible - `true` to show landmarks, `false` to hide them.
+   * @returns A promise that resolves once the visibility has been applied.
+   */
+  setVisible(visible: boolean): Promise<void>;
+  private install;
+  private landmarkInsertBeforeID;
+  private alignZoomRangeWithBasemapBuildings;
+  private excludeLandmarkBuildingsFromBasemap;
+  private readBasemapBuildingMaterial;
+  private resolveCurrentMaterialState;
+  private applyDisplayMode;
+}
+//#endregion
+//#region src/landmarksTileURL.d.ts
+/**
+ * Builds the TomTom Orbis 3D Landmarks tile URL template.
+ *
+ * @remarks
+ * The API serves meshopt-compressed GLB tiles with KTX2/Basis textures and requires
+ * an API key with Orbis 3D Landmarks entitlements (still in Private Preview).
+ *
+ * @group Landmarks 3D
+ */
+export declare const buildLandmarksTileURL: () => string;
+//#endregion
+export type { Landmarks3DDisplayMode, Landmarks3DOptions, ModelsLayerSpecification, ModelsSourceSpecification };