leaflet-city-mapper 0.0.0-stage → 0.0.2

package/src/utils/computeBounds.js

@@ -0,0 +1,17 @@
+/** Cache local AABB and center for ray picking and transparent mesh sorting. */
+
+export function computeBounds(geometry) {
+  const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity], data = geometry.attributes.position.data;
+  for (let i = 0; i < data.length; i++) {
+    min[i % 3] = Math.min(min[i % 3], data[i]);
+    max[i % 3] = Math.max(max[i % 3], data[i]);
+  }
+  const center = min.map((v, i) => (v + max[i]) / 2);
+  let radius = 0;
+  for (let i = 0; i < data.length; i += 3) {
+    radius = Math.max(radius, Math.hypot(
+      data[i] - center[0], data[i + 1] - center[1], data[i + 2] - center[2]
+    ));
+  }
+  geometry.bounds = { min, max, center, radius };
+}

package/src/utils/conformModelToTerrain.js

@@ -0,0 +1,69 @@
+import { computeBounds } from './computeBounds.js';
+import { getElevation } from './getElevation.js';
+import { update } from './update.js';
+import { updateWorldMatrix } from './updateWorldMatrix.js';
+import { vertexNormals } from './vertexNormals.js';
+
+const HEIGHT = 8;
+
+export function conformModelToTerrain(layer, terrain) {
+  if (!layer.model) return;
+  const meshes = [];
+  const visit = node => {
+    if (node.geometry?.attributes.position) meshes.push(node);
+    for (const child of node.children) visit(child);
+  };
+  visit(layer.model);
+  if (!terrain?._terrainReady || !layer.options.terrainConform) {
+    for (const mesh of meshes) {
+      const positions = mesh.geometry._terrainBasePositions;
+      if (!positions) continue;
+      const geometry = mesh.geometry, position = geometry.attributes.position;
+      position.data.set(positions);
+      mesh.device.queue.writeBuffer(position.buffer, 0, positions);
+      const normals = geometry._terrainBaseNormals;
+      if (normals) {
+        geometry.attributes.normal.data.set(normals);
+        mesh.device.queue.writeBuffer(geometry.attributes.normal.buffer, 0, normals);
+      }
+      computeBounds(geometry);
+    }
+    return;
+  }
+
+  updateWorldMatrix(layer.root);
+  const map = layer._map, crs = map.options.crs;
+  const origin = crs.project(layer._shared._sceneOrigin);
+  const metres = Math.cos(layer._shared._sceneOrigin.lat * Math.PI / 180);
+  const pixelScale = crs.scale(terrain._terrainZoom);
+
+  for (const mesh of meshes) {
+    const geometry = mesh.geometry, attribute = geometry.attributes.position;
+    geometry._terrainBasePositions ||= attribute.data.slice();
+    const normal = geometry.attributes.normal;
+    geometry._terrainBaseNormals ||= normal.data.slice();
+    attribute.data.set(geometry._terrainBasePositions);
+    const world = mesh.worldMatrix, inverse = new DOMMatrix(world).inverse().toFloat64Array();
+    for (let i = 0; i < attribute.data.length; i += 3) {
+      const x = attribute.data[i], y = attribute.data[i + 1], z = attribute.data[i + 2];
+      const worldY = world[1] * x + world[5] * y + world[9] * z + world[13];
+      const weight = Math.max(0, Math.min(1, 1 - (worldY - layer.root.position[1]) / HEIGHT));
+      if (!weight) continue;
+      const worldX = world[0] * x + world[4] * y + world[8] * z + world[12];
+      const worldZ = world[2] * x + world[6] * y + world[10] * z + world[14];
+      const point = crs.transformation.transform(new L.Point(
+        origin.x + worldX / metres, origin.y - worldZ / metres), pixelScale);
+      const elevation = getElevation(terrain, point);
+      if (!Number.isFinite(elevation)) continue;
+      const offset = (elevation - worldY) * weight;
+      attribute.data[i] += inverse[4] * offset;
+      attribute.data[i + 1] += inverse[5] * offset;
+      attribute.data[i + 2] += inverse[6] * offset;
+    }
+    mesh.device.queue.writeBuffer(attribute.buffer, 0, attribute.data);
+    normal.data.set(vertexNormals(attribute.data, geometry.attributes.index?.data));
+    mesh.device.queue.writeBuffer(normal.buffer, 0, normal.data);
+    computeBounds(geometry);
+  }
+  update(layer);
+}

package/src/utils/createMesh.js

@@ -0,0 +1,31 @@
+import { emptyNode } from './emptyNode.js';
+import { createProgram } from './createProgram.js';
+import { setParent } from './setParent.js';
+import { update } from './update.js';
+
+/**
+ * Add a non-indexed, vertex-coloured mesh from flat vec3 arrays `{ position, normal, color }` in layer-local metres.
+ * `usage` adds GPUBufferUsage flags to the vertex buffers (e.g. STORAGE for compute passes).
+ * A supplied `program` shares compiled shaders and pipelines across compatible meshes.
+ */
+
+export function createMesh(backend, data, material = {}, usage = 0, program) {
+  const { device } = backend.renderer, attributes = {};
+  for (const [name, values] of Object.entries(data)) {
+    const array = new Float32Array(values);
+    const size = name === 'uv' ? 2 : 3;
+    const buffer = device.createBuffer({ size: Math.max(4, array.byteLength), usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST | usage });
+    device.queue.writeBuffer(buffer, 0, array);
+    attributes[name] = { size, data: array, count: array.length / size, buffer };
+  }
+  const mesh = {
+    ...emptyNode(),
+    device,
+    geometry: { device, attributes, drawRange: { start: 0, count: attributes.position.count } },
+    program: program || createProgram(backend, { vertexColors: true, doubleSided: true, ...material }),
+    id: L.Layer._nextId++, renderOrder: 0, extras: {},
+  };
+  setParent(mesh, backend.root);
+  update(backend);
+  return mesh;
+}

package/src/utils/createProgram.js

@@ -0,0 +1,92 @@
+import { materialShaders } from './materialShaders.js';
+import { elevationWGSL } from './elevationWGSL.js';
+
+
+export function createProgram(backend, material = {}) {
+  const shaders = materialShaders(
+    material,
+    !!backend.options.nightSparkle,
+    material.terrain ? elevationWGSL : ''
+  );
+  const vertex = backend.renderer.device.createShaderModule({ code: shaders.vertex });
+  const fragment = backend.renderer.device.createShaderModule({ code: shaders.fragment });
+  Promise.all([
+    vertex.getCompilationInfo(),
+    fragment.getCompilationInfo()
+  ]).then(infos => {
+    const errors = infos.flatMap(info => info.messages).filter(message => message.type === 'error');
+    if (errors.length) {
+      backend.fire('error', {
+        error: new Error(`Unable to compile Layer3D WGSL: ${errors.map(error => error.message).join('\n')}`),
+      });
+    }
+  }).catch(error => backend.fire('error', { error }));
+  const vertexBuffers = [
+    { arrayStride: 12, attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }] },
+    { arrayStride: 12, attributes: [{ shaderLocation: 1, offset: 0, format: 'float32x3' }] },
+    material.vertexColors ? { arrayStride: 12, attributes: [{ shaderLocation: 2, offset: 0, format: 'float32x3' }] } : null,
+    shaders.textured ? { arrayStride: 8, attributes: [{ shaderLocation: 3, offset: 0, format: 'float32x2' }] } : null,
+  ];
+  const bindGroupEntries = [{
+    binding: 0,
+    visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+    buffer: { type: 'uniform', hasDynamicOffset: true },
+  }, {
+    binding: 1,
+    visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+    buffer: { type: 'uniform' },
+  }];
+  if (shaders.hasTerrain) {
+    bindGroupEntries.push({
+      binding: 2,
+      visibility: GPUShaderStage.VERTEX,
+      texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+    });
+  }
+  for (const texture of shaders.bindings) {
+    bindGroupEntries.push({
+      binding: texture.texture,
+      visibility: GPUShaderStage.FRAGMENT,
+      texture: { sampleType: 'float', viewDimension: '2d' },
+    });
+    bindGroupEntries.push({
+      binding: texture.sampler,
+      visibility: GPUShaderStage.FRAGMENT,
+      sampler: { type: 'filtering' },
+    });
+  }
+  const bindGroupLayout = backend.renderer.device.createBindGroupLayout({ entries: bindGroupEntries });
+  const pipelineLayout = backend.renderer.device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout, backend.renderer.sunlight.layout] });
+  return {
+    device: backend.renderer.device,
+    vertex,
+    fragment,
+    bindings: shaders.bindings,
+    vertexBuffers,
+    bindGroupLayout,
+    pipelineLayout,
+    pipelineCache: new Map(),
+    cullMode: material.doubleSided ? 'none' : 'back',
+    transparent: material.alphaMode === 'BLEND',
+    depthWrite: material.depthWrite ?? material.alphaMode !== 'BLEND',
+    depthTest: material.depthTest !== false,
+    terrain: material.terrain,
+    nightLight: Boolean(material.nightLight),
+    nightSparkle: !!backend.options.nightSparkle,
+    uniforms: {
+      baseColor: { value: material.color || [1, 1, 1] },
+      metallic: { value: material.metallic ?? 0 },
+      roughness: { value: material.roughness ?? 0.85 },
+      opacity: { value: material.opacity ?? 1 },
+      alphaCutoff: { value: material.alphaCutoff ?? 0.5 },
+      occlusionStrength: { value: material.occlusionStrength ?? 1 },
+      emissive: { value: material.emissive || [0, 0, 0] },
+      ...(material.baseTexture ? { baseTexture: { value: material.baseTexture } } : {}),
+      ...(material.metalTexture ? { metalTexture: { value: material.metalTexture } } : {}),
+      ...(material.emissiveTexture ? { emissiveTexture: { value: material.emissiveTexture } } : {}),
+      ...(material.occlusionTexture ? { occlusionTexture: { value: material.occlusionTexture } } : {}),
+      ...(material.roofTexture ? { roofTexture: { value: null } } : {}),
+    },
+    _layerMaterial: material,
+  };
+}

package/src/utils/decodeDirectory.js

@@ -0,0 +1,40 @@
+/** Decode delta/varint directory columns, rejecting malformed entries. */
+
+export function decodeDirectory(data) {
+  const bytes = new Uint8Array(data);
+  let cursor = 0;
+  const varint = () => {
+    let value = 0;
+    for (let factor = 1; factor <= 2 ** 49; factor *= 128) {
+      if (cursor >= bytes.length) throw new Error('Truncated PMTiles directory');
+      const byte = bytes[cursor++];
+      value += (byte & 127) * factor;
+      if (!Number.isSafeInteger(value)) throw new Error('Invalid PMTiles directory integer');
+      if (byte < 128) return value;
+    }
+    throw new Error('Invalid PMTiles directory integer');
+  };
+  const count = varint();
+  if (count > (bytes.length - cursor) / 4) throw new Error('Invalid PMTiles directory count');
+  const entries = [];
+  let tileId = 0;
+  for (let i = 0; i < count; i++) {
+    tileId += varint();
+    if (!Number.isSafeInteger(tileId) || (i && tileId <= entries[i - 1].tileId)) {
+      throw new Error('Invalid PMTiles directory tile IDs');
+    }
+    entries.push({ tileId });
+  }
+  for (const entry of entries) entry.runLength = varint();
+  for (const entry of entries) {
+    entry.length = varint();
+    if (!entry.length) throw new Error('Invalid PMTiles directory length');
+  }
+  entries.forEach((entry, i) => {
+    const value = varint();
+    if (!value && !i) throw new Error('Invalid PMTiles directory offset');
+    entry.offset = value ? value - 1 : entries[i - 1].offset + entries[i - 1].length;
+  });
+  if (cursor !== bytes.length) throw new Error('Trailing PMTiles directory data');
+  return entries;
+}

package/src/utils/decodeHeader.js

@@ -0,0 +1,15 @@
+/** Decode the PMTiles v3 header. */
+
+export function decodeHeader(data) {
+  if (data.byteLength < 127 || new TextDecoder().decode(new Uint8Array(data, 0, 7)) !== 'PMTiles' ||
+    new Uint8Array(data)[7] !== 3) throw new Error('Expected a PMTiles v3 archive');
+  const view = new DataView(data);
+  const header = {};
+  ['rootDirectoryOffset', 'rootDirectoryLength', 'jsonMetadataOffset', 'jsonMetadataLength', 'leafDirectoryOffset', 'leafDirectoryLength', 'tileDataOffset', 'tileDataLength', 'numAddressedTiles', 'numTileEntries', 'numTileContents'].forEach((name, i) => { header[name] = Number(view.getBigUint64(8 + i * 8, true)); });
+  ['clustered', 'internalCompression', 'tileCompression', 'tileType', 'minZoom', 'maxZoom'].forEach((name, i) => { header[name] = view.getUint8(96 + i); });
+  ['minLon', 'minLat', 'maxLon', 'maxLat'].forEach((name, i) => { header[name] = view.getInt32(102 + i * 4, true) / 1e7; });
+  header.centerZoom = view.getUint8(118);
+  header.centerLon = view.getInt32(119, true) / 1e7;
+  header.centerLat = view.getInt32(123, true) / 1e7;
+  return header;
+}

package/src/utils/decodeModel.js

@@ -0,0 +1,43 @@
+/** Decode a static glTF JSON document or GLB v2 container. */
+
+export function decodeModel(data) {
+  const view = new DataView(data), decoder = new TextDecoder();
+  let description;
+  if (view.getUint32(0, true) === 0x46546c67) {
+    // Decode GLB v2 chunks; unknown types are skipped.
+    if (view.getUint32(4, true) !== 2 || view.getUint32(8, true) !== data.byteLength) {
+      throw new Error('Invalid GLB header');
+    }
+    let binary;
+    for (let offset = 12; offset < data.byteLength;) {
+      if (offset + 8 > data.byteLength) {
+        throw new Error('Truncated GLB chunk');
+      }
+      const length = view.getUint32(offset, true), type = view.getUint32(offset + 4, true);
+      offset += 8;
+      if (offset + length > data.byteLength) {
+        throw new Error('Truncated GLB data');
+      }
+      const chunk = data.slice(offset, offset + length);
+      if (type === 0x4e4f534a) {
+        description = JSON.parse(decoder.decode(chunk));
+      }
+      if (type === 0x004e4942) {
+        binary = chunk;
+      }
+      offset += length;
+    }
+    if (!description) {
+      throw new Error('Missing GLB JSON');
+    }
+    if (binary) {
+      description.buffers[0].binary = binary;
+    }
+  } else {
+    description = JSON.parse(decoder.decode(data));
+  }
+  if (description.skins?.length || description.animations?.length || description.extensionsRequired?.length || description.meshes?.some(mesh => mesh.primitives.some(primitive => primitive.targets || (primitive.mode !== undefined && primitive.mode !== 4)))) {
+    throw new Error('Layer3D supports static triangle glTF models without required extensions');
+  }
+  return description;
+}

package/src/utils/decompress.js

@@ -0,0 +1,5 @@
+export async function decompress(data, compression) {
+  if (compression === 1) return data;
+  if (compression !== 2) throw new Error(`Unsupported PMTiles compression: ${compression}`);
+  return new Response(new Blob([data]).stream().pipeThrough(new DecompressionStream('gzip'))).arrayBuffer();
+}

package/src/utils/destroyTexture.js

@@ -0,0 +1,7 @@
+
+export function destroyTexture(layer, texture) {
+  layer.renderer.device.queue.onSubmittedWorkDone().then(() => texture.destroy(), error => {
+    layer.fire('error', { error });
+    texture.destroy();
+  });
+}

package/src/utils/disposeMesh.js

@@ -0,0 +1,13 @@
+import { setParent } from './setParent.js';
+import { update } from './update.js';
+
+export function disposeMesh(backend, mesh) {
+  if (!mesh) {
+    return;
+  }
+  setParent(mesh, null);
+  update(backend);
+  for (const attribute of Object.values(mesh.geometry.attributes)) {
+    attribute.buffer.destroy();
+  }
+}

package/src/utils/drawGeometry.js

@@ -0,0 +1,122 @@
+/** Upload retained CPU data and draw one mesh in the active WebGPU render pass. */
+
+export function drawGeometry(backend, mesh, pass, cullMode, frontFace) {
+  const { geometry, program } = mesh;
+  const device = backend.renderer.device;
+  const pipelineKey = `${cullMode}:${frontFace}`;
+  let pipeline = program.pipelineCache.get(pipelineKey);
+  if (!pipeline) {
+    pipeline = device.createRenderPipeline({
+      layout: program.pipelineLayout,
+      vertex: {
+        module: program.vertex,
+        entryPoint: 'vertexMain',
+        buffers: program.vertexBuffers,
+      },
+      fragment: {
+        module: program.fragment,
+        entryPoint: 'fragmentMain',
+        targets: [{
+          format: backend.renderer.format,
+          blend: program.transparent ? {
+            color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+          } : undefined,
+          writeMask: GPUColorWrite.ALL,
+        }],
+      },
+      primitive: { topology: 'triangle-list', cullMode, frontFace },
+      depthStencil: {
+        format: 'depth24plus',
+        depthWriteEnabled: program.depthWrite,
+        depthCompare: program.depthTest === false ? 'always' : 'less-equal',
+      },
+    });
+    program.pipelineCache.set(pipelineKey, pipeline);
+  }
+
+  const uniforms = program.uniforms;
+  const renderer = backend.renderer;
+  const offset = renderer.uniformSlot++ * 256;
+  const data = renderer.uniformData, base = offset / 4;
+  data.set(mesh.worldMatrix, base);
+  data.set(uniforms.baseColor.value, base + 16);
+  data[base + 19] = 1;
+  data[base + 20] = uniforms.metallic.value;
+  data[base + 21] = uniforms.roughness.value;
+  data[base + 22] = uniforms.opacity.value * (mesh.ground ? mesh._appearance ?? 1 : 1);
+  data[base + 23] = uniforms.alphaCutoff.value;
+  data.set(uniforms.emissive.value, base + 24);
+  data[base + 27] = uniforms.occlusionStrength.value;
+  data[base + 28] = mesh.terrain?.[0] ?? 0;
+  data[base + 29] = mesh.terrain?.[1] ?? 0;
+  data[base + 30] = mesh.terrain?.[2] ?? 0;
+  data[base + 31] = mesh.terrain?.[3] ?? 0;
+  data[base + 32] = mesh.highlight?.[0] ?? 0;
+  data[base + 33] = mesh.highlight?.[1] ?? 0;
+  data[base + 34] = program.nightSparkle ? data[55] : 0;
+  data[base + 35] = mesh.ground ? 1 : mesh._appearance ?? 1;
+
+  const textures = mesh._textures ||= [];
+  textures.length = 0;
+  for (const binding of program.bindings) {
+    const texture = uniforms[binding.name]?.value;
+    if (!texture) throw new Error(`Missing Layer3D texture: ${binding.name}`);
+    if (texture.uploaded !== texture.image) {
+      device.queue.copyExternalImageToTexture(
+        { source: texture.image, flipY: Boolean(texture.flipY) },
+        { texture: texture.texture },
+        [texture.image.width, texture.image.height]
+      );
+      texture.uploaded = texture.image;
+    }
+    textures.push(texture);
+  }
+  let bindingsChanged = !mesh.bindGroup || mesh.boundBuffer !== renderer.uniformBuffer ||
+    textures.length !== mesh.boundTextures.length;
+  for (let i = 0; !bindingsChanged && i < textures.length; i++) {
+    if (textures[i].texture !== mesh.boundTextures[i][0] ||
+      textures[i].sampler !== mesh.boundTextures[i][1]) bindingsChanged = true;
+  }
+  if (bindingsChanged) {
+    const entries = [
+      { binding: 0, resource: { buffer: renderer.uniformBuffer, size: 144 } },
+      { binding: 1, resource: { buffer: renderer.uniformBuffer, size: 240 } },
+    ];
+    if (program.terrain) entries.push({ binding: 2, resource: program.terrain.texture.createView() });
+    mesh.boundBuffer = renderer.uniformBuffer;
+    const boundTextures = mesh.boundTextures ||= [];
+    boundTextures.length = textures.length;
+    for (let i = 0; i < textures.length; i++) {
+      const binding = program.bindings[i], texture = textures[i];
+      entries.push({ binding: binding.texture, resource: texture.texture.createView() });
+      entries.push({ binding: binding.sampler, resource: texture.sampler });
+      boundTextures[i] ||= [];
+      boundTextures[i][0] = texture.texture;
+      boundTextures[i][1] = texture.sampler;
+    }
+    mesh.bindGroup = device.createBindGroup({
+      layout: program.bindGroupLayout,
+      entries,
+    });
+  }
+  pass.setPipeline(pipeline);
+  pass.setBindGroup(0, mesh.bindGroup, [offset]);
+  pass.setVertexBuffer(0, geometry.attributes.position.buffer);
+  pass.setVertexBuffer(1, geometry.attributes.normal.buffer);
+  if (geometry.attributes.color) pass.setVertexBuffer(2, geometry.attributes.color.buffer);
+  if (geometry.attributes.uv) pass.setVertexBuffer(3, geometry.attributes.uv.buffer);
+  for (const attribute of Object.values(geometry.attributes)) {
+    if (!attribute.needsUpdate) continue;
+    device.queue.writeBuffer(attribute.buffer, 0, attribute.data);
+    attribute.needsUpdate = false;
+    geometry.bounds = null;
+  }
+  const index = geometry.attributes.index;
+  if (index) {
+    pass.setIndexBuffer(index.buffer, index.indexFormat);
+    pass.drawIndexed(geometry.drawRange.count, 1, geometry.drawRange.start, 0, 0);
+  } else {
+    pass.draw(geometry.drawRange.count, 1, geometry.drawRange.start, 0);
+  }
+}

package/src/utils/elevationWGSL.js

@@ -0,0 +1,27 @@
+/**
+ * WGSL twin of getElevation for the vertex shader: bilinear DEM pixels, or the first valid
+ * neighbour near no-data (stored as -1e9), else `base`. Expects `dem: texture_2d<f32>`.
+ */
+export const elevationWGSL = `
+  fn demSample(pixel: vec2<i32>) -> f32 {
+    if (any(pixel < vec2<i32>(0)) || any(pixel >= vec2<i32>(textureDimensions(dem)))) { return -1e9; }
+    return textureLoad(dem, pixel, 0).r;
+  }
+  fn elevation(pixel: vec2<f32>, base: f32) -> f32 {
+    let p = pixel - vec2<f32>(0.5);
+    let f = fract(p);
+    let i = vec2<i32>(floor(p));
+    let v00 = demSample(i);
+    let v10 = demSample(i + vec2<i32>(1, 0));
+    let v01 = demSample(i + vec2<i32>(0, 1));
+    let v11 = demSample(i + vec2<i32>(1, 1));
+    if (v00 > -1000.0 && v10 > -1000.0 && v01 > -1000.0 && v11 > -1000.0) {
+      return mix(mix(v00, v10, f.x), mix(v01, v11, f.x), f.y);
+    }
+    if (v00 > -1000.0) { return v00; }
+    if (v10 > -1000.0) { return v10; }
+    if (v01 > -1000.0) { return v01; }
+    if (v11 > -1000.0) { return v11; }
+    return base;
+  }
+`;

package/src/utils/emptyNode.js

@@ -0,0 +1,9 @@
+/** A fresh, empty scene-graph node. */
+export const emptyNode = () => ({
+  position: [0, 0, 0],
+  rotation: [0, 0, 0],
+  scale: [1, 1, 1],
+  worldMatrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
+  children: [],
+  visible: true,
+});

package/src/utils/endZoom.js

@@ -0,0 +1,15 @@
+import { update } from "./update.js";
+
+/** Stop using the outgoing level after zoomend; the next redraw uses current tiles. */
+
+export function endZoom() {
+  const backend = this;
+  for (const animation of backend._zoomTransitions?.keys() || []) animation.finish();
+  backend._zoomTransitions = null;
+  backend._zoomView = null;
+  delete backend._map._cameraView;
+  backend._map.getContainer().classList.remove('leaflet-camera-zoom');
+  backend._map._updateCameraOverlays();
+  backend._zoomLevel = null;
+  update(backend);
+}

package/src/utils/findFeature.js

@@ -0,0 +1,49 @@
+import { raycast } from './raycast.js';
+
+/**
+ * Translate a geometry hit into a configured model or batched source feature.
+ * Sorted half-open face ranges permit binary search without a feature per triangle.
+ * @returns {PickedFeature|null}
+ */
+
+export function findFeature(backend, event) {
+  if (!backend.root || !backend.camera) {
+    return null;
+  }
+  for (const hit of raycast(backend, event, backend.root.children, Boolean(backend.model))) {
+    if (backend.model) {
+      let object = hit.object;
+      while (object && object !== backend.model) {
+        object = object.parent;
+      }
+      if (object === backend.model) {
+        return {
+          id: backend.model.id, properties: backend.model.extras,
+          model: backend.model, mesh: hit.object, point: hit.point
+        };
+      }
+    }
+    const ranges = hit.object.extras?.featureFaces;
+    if (!ranges) {
+      continue;
+    }
+    let low = 0,
+       high = ranges.length - 1;
+    while (low <= high) {
+      const middle = (low + high) >> 1;
+      const range = ranges[middle];
+      if (hit.faceIndex < range.faceStart) {
+        high = middle - 1;
+      } else if (hit.faceIndex >= range.faceEnd) {
+        low = middle + 1;
+      } else {
+        return {
+          ...range,
+          mesh: hit.object,
+          point: hit.point
+        };
+      }
+    }
+  }
+  return null;
+}

package/src/utils/geometry.js

@@ -0,0 +1,2 @@
+
+

package/src/utils/getElevation.js

@@ -0,0 +1,10 @@
+import { bridgeElevation } from './bridgeElevation.js';
+import { terrainElevation } from './terrainElevation.js';
+
+/** @param {L.LatLng|L.Point} location LatLng, or a pixel point at the terrain zoom. */
+
+export function getElevation(backend, location) {
+  if (!backend._map || !backend._terrainReady) return null;
+  const point = location instanceof L.Point ? location : backend._map.project(location, backend._terrainZoom);
+  return bridgeElevation(point, backend._bridges) ?? terrainElevation(point, backend._terrainTiles);
+}

package/src/utils/getHeader.js

@@ -0,0 +1,9 @@
+import { decodeHeader } from './decodeHeader.js';
+import { read } from './read.js';
+
+/** Cache header initialization; failures remain visible to all callers. */
+
+export function getHeader(backend) {
+  if (backend.options.archive && backend.options.archive !== backend) return backend.options.archive.getHeader();
+  return backend._header ||= read(backend, 0, 127).then(decodeHeader);
+}

package/src/utils/getZxy.js

@@ -0,0 +1,76 @@
+import { decodeDirectory } from './decodeDirectory.js';
+import { decompress } from './decompress.js';
+import { tileId } from './tileId.js';
+import { read } from './read.js';
+import { getHeader } from './getHeader.js';
+
+/** Nearest directory entry at/before the Hilbert ID, then follow leaf pointers. */
+
+export async function getZxy(backend, z, x, y, signal) {
+  if (backend.options.archive && backend.options.archive !== backend && backend.options.archive.getZxy) {
+    return backend.options.archive.getZxy(z, x, y, signal);
+  }
+  const id = tileId(z, x, y);
+  signal?.throwIfAborted();
+  const header = await getHeader(backend);
+  signal?.throwIfAborted();
+  if (z < header.minZoom || z > header.maxZoom) {
+    return;
+  }
+  let offset = header.rootDirectoryOffset, length = header.rootDirectoryLength;
+  const visited = new Set();
+  for (let depth = 0; depth < 4; depth++) {
+    if (visited.has(offset)) {
+      throw new Error('Cyclic PMTiles directory');
+    }
+    visited.add(offset);
+    const key = `${offset}:${length}`;
+    if (!backend._directories.has(key)) {
+      if (backend._directories.size >= 32) {
+        backend._directories.delete(backend._directories.keys().next().value);
+      }
+      const pending = read(backend, offset, length)
+        .then(data => decompress(data, header.internalCompression))
+        .then(decodeDirectory)
+        .catch(error => {
+          if (backend._directories.get(key) === pending) {
+            backend._directories.delete(key);
+          }
+          throw error;
+        });
+      backend._directories.set(key, pending);
+    }
+    const entries = await backend._directories.get(key);
+    signal?.throwIfAborted();
+    let low = 0, high = entries.length - 1;
+    while (low <= high) {
+      const mid = (low + high) >> 1;
+      if (entries[mid].tileId <= id) {
+        low = mid + 1;
+      } else {
+        high = mid - 1;
+      }
+    }
+    const entry = entries[high];
+    if (!entry) {
+      return;
+    }
+    if (entry.runLength) {
+      if (id - entry.tileId >= entry.runLength) {
+        return;
+      }
+      if (entry.offset + entry.length > header.tileDataLength) {
+        throw new Error('PMTiles tile outside data section');
+      }
+      const data = await decompress(await read(backend, header.tileDataOffset + entry.offset, entry.length, signal), header.tileCompression);
+      signal?.throwIfAborted();
+      return { data };
+    }
+    if (entry.offset + entry.length > header.leafDirectoryLength) {
+      throw new Error('PMTiles directory outside leaf section');
+    }
+    offset = header.leafDirectoryOffset + entry.offset;
+    length = entry.length;
+  }
+  throw new Error('PMTiles directory depth exceeds four levels');
+}