@macrostrat/cesium-martini 1.5.0 → 1.5.2

package/README.md

@@ -2,7 +2,7 @@
 
 **On-the-fly meshing of raster elevation tiles for the CesiumJS virtual globe**
 
-[![npm version](https://badge.fury.io/js/@macrostrat%2Fcesium-martini.svg)](https://badge.fury.io/js/@macrostrat%2Fcesium-martini)
+[![npm version](https://badge.fury.io/js/@macrostrat%2Fcesium-martini.svg?cache=none)](https://badge.fury.io/js/@macrostrat%2Fcesium-martini)
 
 ![Himalayas](/img/himalayas.jpg)
 
@@ -150,6 +150,10 @@ The configuration also takes a single number and array.
 
 ## Changelog
 
+### `[1.5.1]`: February 2025
+
+- Remove `.idea` files from bundle
+
 ### `[1.5.0]`: February 2025
 
 - Allow overzooming of tiles when zoom levels are skipped

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@macrostrat/cesium-martini",
-  "version": "1.5.0",
-  "description": "",
+  "version": "1.5.2",
+  "description": "On-the-fly meshing of raster elevation tiles for the CesiumJS virtual globe",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "source": "./src/index.ts",
   "exports": {
     ".": {
-      "typescript": "./src/index.ts",
+      "source": "./src/index.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     }
@@ -26,6 +26,10 @@
     "format": "prettier --write src/**/*.ts examples/**/*.ts",
     "check": "tsc --noEmit"
   },
+  "files": [
+    "dist",
+    "src"
+  ],
   "author": "",
   "license": "ISC",
   "dependencies": {

package/src/index.ts

@@ -0,0 +1,18 @@
+import "./module.d.ts";
+import DefaultHeightmapResource from "./resources/heightmap-resource";
+import MapboxTerrainResource from "./resources/mapbox-resource";
+import {
+  MartiniTerrainProvider,
+  StretchedTilingScheme,
+} from "./terrain-provider";
+import MapboxTerrainProvider from "./mapbox-terrain-provider";
+export * from "./worker/decoder";
+export * from "./worker/worker-util";
+
+export default MapboxTerrainProvider;
+export {
+  MartiniTerrainProvider,
+  DefaultHeightmapResource,
+  MapboxTerrainResource,
+  StretchedTilingScheme,
+};

package/src/mapbox-terrain-provider.ts

@@ -0,0 +1,25 @@
+import { TerrainProvider } from "cesium";
+import MapboxTerrainResource, {
+  MapboxTerrainResourceOpts,
+} from "./resources/mapbox-resource";
+import { MartiniTerrainOpts, MartiniTerrainProvider } from "./terrain-provider";
+import WorkerFarmTerrainDecoder from "./worker/decoder";
+import MapboxTerrainWorker from "web-worker:./worker/mapbox-worker";
+
+type MapboxTerrainOpts = Omit<MartiniTerrainOpts, "resource"> &
+  MapboxTerrainResourceOpts;
+
+export default class MapboxTerrainProvider extends MartiniTerrainProvider<TerrainProvider> {
+  constructor(opts: MapboxTerrainOpts = {}) {
+    const resource = new MapboxTerrainResource(opts);
+    const decoder = new WorkerFarmTerrainDecoder({
+      worker: new MapboxTerrainWorker(),
+    });
+
+    super({
+      ...opts,
+      resource,
+      decoder,
+    });
+  }
+}

package/src/module.d.ts

@@ -0,0 +1,4 @@
+declare module "web-worker:*" {
+  const value: new () => Worker;
+  export default value;
+}

package/src/resources/heightmap-resource.ts

@@ -0,0 +1,120 @@
+import { Resource, Credit } from "cesium";
+import { TileCoordinates } from "../terrain-data";
+
+export interface HeightmapResource {
+  credit?: Credit;
+  tileSize: number;
+  getTilePixels: (coords: TileCoordinates) => Promise<ImageData> | undefined;
+  getTileDataAvailable: (coords: TileCoordinates) => boolean;
+}
+
+interface CanvasRef {
+  canvas: HTMLCanvasElement;
+  context: CanvasRenderingContext2D;
+}
+export interface DefaultHeightmapResourceOpts {
+  url?: string;
+  // Legacy option, use skipZoomLevels instead
+  skipOddLevels?: boolean;
+  skipZoomLevels?: [number] | ((z: number) => boolean);
+  maxZoom?: number;
+  tileSize?: number;
+}
+
+export class DefaultHeightmapResource implements HeightmapResource {
+  resource: Resource = null;
+  tileSize: number = 256;
+  maxZoom: number;
+  skipZoomLevel: (z: number) => boolean;
+  contextQueue: CanvasRef[];
+
+  constructor(opts: DefaultHeightmapResourceOpts = {}) {
+    if (opts.url) {
+      this.resource = new Resource({ url: opts.url });
+    }
+    this.skipZoomLevel = () => false;
+    if (opts.skipZoomLevels) {
+      if (Array.isArray(opts.skipZoomLevels)) {
+        const _skipZoomLevels = opts.skipZoomLevels as [number];
+        this.skipZoomLevel = (z: number) => _skipZoomLevels.includes(z);
+      } else {
+        this.skipZoomLevel = opts.skipZoomLevels;
+      }
+    } else if (opts.skipOddLevels) {
+      this.skipZoomLevel = (z: number) => z % 2 == 1;
+    }
+
+    this.tileSize = opts.tileSize ?? 256;
+    this.maxZoom = opts.maxZoom ?? 15;
+    this.contextQueue = [];
+  }
+
+  getCanvas(): CanvasRef {
+    let ctx = this.contextQueue.pop();
+    if (ctx == null) {
+      const canvas = document.createElement("canvas");
+      canvas.width = this.tileSize;
+      canvas.height = this.tileSize;
+      const context = canvas.getContext("2d");
+      ctx = {
+        canvas,
+        context,
+      };
+    }
+    return ctx;
+  }
+
+  getPixels(img: HTMLImageElement | HTMLCanvasElement): ImageData {
+    const canvasRef = this.getCanvas();
+    const { context } = canvasRef;
+    //context.scale(1, -1);
+    // Chrome appears to vertically flip the image for reasons that are unclear
+    // We can make it work in Chrome by drawing the image upside-down at this step.
+    context.drawImage(img, 0, 0, this.tileSize, this.tileSize);
+    const pixels = context.getImageData(0, 0, this.tileSize, this.tileSize);
+    context.clearRect(0, 0, this.tileSize, this.tileSize);
+    this.contextQueue.push(canvasRef);
+    return pixels;
+  }
+
+  getTileResource(tileCoords: TileCoordinates) {
+    // reverseY for TMS tiling (https://gist.github.com/tmcw/4954720)
+    // See tiling schemes here: https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection/
+    const { z, y } = tileCoords;
+    return this.resource.getDerivedResource({
+      templateValues: {
+        ...tileCoords,
+        reverseY: Math.pow(2, z) - y - 1,
+      },
+      preserveQueryParameters: true,
+    });
+  }
+
+  getTilePixels(coords: TileCoordinates): Promise<ImageData> | undefined {
+    const resource = this.getTileResource(coords);
+    const request = resource.fetchImage({
+      preferImageBitmap: false,
+      // @ts-ignore
+      retryAttempts: 3,
+    });
+    if (request == null) return undefined;
+    return request.then((img: HTMLImageElement | ImageBitmap) =>
+      // @ts-ignore
+      this.getPixels(img),
+    );
+  }
+
+  getTileDataAvailable({ z }) {
+    if (z == this.maxZoom) return true;
+    /* Weird hack:
+    For some reason, request render mode breaks if zoom 1 tiles are disabled.
+    So we have to make sure that we always report zoom 1 tiles as available.
+    */
+    if (z < 2) return true;
+    if (this.skipZoomLevel(z)) return false;
+    if (z > this.maxZoom) return false;
+    return true;
+  }
+}
+
+export default DefaultHeightmapResource;

package/src/resources/mapbox-resource.ts

@@ -0,0 +1,53 @@
+import { Credit, Resource } from "cesium";
+import {
+  DefaultHeightmapResource,
+  DefaultHeightmapResourceOpts,
+} from "./heightmap-resource";
+
+export enum ImageFormat {
+  WEBP = "webp",
+  PNG = "png",
+  PNGRAW = "pngraw",
+}
+
+export type MapboxTerrainResourceOpts = {
+  highResolution?: boolean;
+  imageFormat?: ImageFormat;
+  accessToken?: string;
+  urlTemplate?: string;
+} & DefaultHeightmapResourceOpts;
+
+export class MapboxTerrainResource extends DefaultHeightmapResource {
+  resource: Resource = null;
+  credit = new Credit("Mapbox");
+
+  constructor(opts: MapboxTerrainResourceOpts = {}) {
+    super(opts);
+    const highResolution = opts.highResolution ?? false;
+    const format = opts.imageFormat ?? ImageFormat.WEBP;
+    const { urlTemplate } = opts;
+
+    // overrides based on highResolution flag
+    if (highResolution) {
+      if (opts.maxZoom === undefined) {
+        this.maxZoom = 14;
+      }
+      if (opts.tileSize === undefined) {
+        this.tileSize = 512;
+      }
+    }
+
+    const defaultURL = `https://api.mapbox.com/v4/mapbox.terrain-rgb/{z}/{x}/{y}${
+      highResolution ? "@2x" : ""
+    }.${format}`;
+
+    this.resource = new Resource({ url: urlTemplate ?? defaultURL });
+    if (opts.accessToken) {
+      this.resource.setQueryParameters({
+        access_token: opts.accessToken,
+      });
+    }
+  }
+}
+
+export default MapboxTerrainResource;

package/src/terrain-data.ts

@@ -0,0 +1,363 @@
+import {
+  QuantizedMeshTerrainData,
+  Rectangle,
+  Ellipsoid,
+  Cartographic,
+  BoundingSphere,
+  OrientedBoundingBox,
+  Cartesian3,
+  Credit,
+  TilingScheme,
+} from "cesium";
+import {
+  TerrainWorkerOutput,
+  emptyMesh,
+  subsetByWindow,
+  TerrainUpscaleInput,
+  QuantizedMeshResult,
+} from "./worker/worker-util";
+
+export interface TileCoordinates {
+  x: number;
+  y: number;
+  z: number;
+}
+
+interface QuantizedMeshTerrainOptions {
+  quantizedVertices: Uint16Array;
+  indices: Uint16Array | Uint32Array;
+  minimumHeight: number;
+  maximumHeight: number;
+  boundingSphere: BoundingSphere;
+  orientedBoundingBox?: OrientedBoundingBox;
+  horizonOcclusionPoint: Cartesian3;
+  westIndices: number[];
+  southIndices: number[];
+  eastIndices: number[];
+  northIndices: number[];
+  westSkirtHeight: number;
+  southSkirtHeight: number;
+  eastSkirtHeight: number;
+  northSkirtHeight: number;
+  childTileMask?: number;
+  createdByUpsampling?: boolean;
+  encodedNormals?: Uint8Array;
+  waterMask?: Uint8Array;
+  credits?: Credit[];
+}
+
+export interface TerrainMeshMeta {
+  errorLevel: number;
+  tileSize: number;
+  maxVertexDistance: number | null;
+  tileRect: Rectangle;
+  ellipsoid: Ellipsoid;
+  overscaleFactor: number;
+}
+
+export function createTerrainMesh(
+  data: TerrainWorkerOutput,
+  meta: TerrainMeshMeta,
+) {
+  const {
+    minimumHeight,
+    maximumHeight,
+    quantizedVertices,
+    indices,
+    westIndices,
+    southIndices,
+    eastIndices,
+    northIndices,
+    quantizedHeights,
+  } = data;
+
+  const {
+    errorLevel,
+    tileSize,
+    maxVertexDistance,
+    tileRect,
+    ellipsoid,
+    overscaleFactor,
+  } = meta;
+
+  const err = errorLevel;
+  const skirtHeight = err * 20;
+
+  // Check if tileRect is not NaNs
+  if (isNaN(tileRect.east) || isNaN(tileRect.north)) {
+    throw new Error("Invalid tile rect");
+  }
+
+  const center = Rectangle.center(tileRect);
+
+  // Calculating occlusion height is kind of messy currently, but it definitely works
+  const halfAngle = tileRect.width / 2;
+  const dr = Math.cos(halfAngle); // half tile width since our ref point is at the center
+
+  let occlusionHeight = dr * ellipsoid.maximumRadius + maximumHeight;
+  if (halfAngle > Math.PI / 4) {
+    occlusionHeight = (1 + halfAngle) * ellipsoid.maximumRadius;
+  }
+
+  const occlusionPoint = new Cartographic(
+    center.longitude,
+    center.latitude,
+    occlusionHeight,
+    // Scaling factor of two just to be sure.
+  );
+
+  const horizonOcclusionPoint = ellipsoid.transformPositionToScaledSpace(
+    Cartographic.toCartesian(occlusionPoint),
+  );
+
+  let orientedBoundingBox = OrientedBoundingBox.fromRectangle(
+    tileRect,
+    minimumHeight,
+    maximumHeight,
+    ellipsoid,
+  );
+  let boundingSphere =
+    BoundingSphere.fromOrientedBoundingBox(orientedBoundingBox);
+
+  return new RasterTerrainData({
+    minimumHeight,
+    maximumHeight,
+    quantizedVertices,
+    indices,
+    boundingSphere,
+    orientedBoundingBox,
+    horizonOcclusionPoint,
+    westIndices,
+    southIndices,
+    eastIndices,
+    northIndices,
+    westSkirtHeight: skirtHeight,
+    southSkirtHeight: skirtHeight,
+    eastSkirtHeight: skirtHeight,
+    northSkirtHeight: skirtHeight,
+    childTileMask: 15,
+    createdByUpsampling: overscaleFactor > 0,
+    errorLevel: err,
+    maxVertexDistance,
+    tileSize,
+    quantizedHeights,
+  });
+}
+
+interface EmptyMeshOptions {
+  tileRect: Rectangle;
+  tileCoord: TileCoordinates;
+  ellipsoid: Ellipsoid;
+  errorLevel: number;
+  tileSize: number;
+  maxVertexDistance?: number;
+}
+
+export function createEmptyMesh(
+  opts: EmptyMeshOptions,
+): QuantizedMeshTerrainData {
+  const { tileRect, tileCoord, errorLevel, ellipsoid, maxVertexDistance } =
+    opts;
+  const center = Rectangle.center(tileRect);
+  const { z } = tileCoord;
+
+  const latScalar = Math.min(Math.abs(Math.sin(center.latitude)), 0.995);
+  let v = Math.max(
+    Math.ceil((200 / (z + 1)) * Math.pow(1 - latScalar, 0.25)),
+    4,
+  );
+  const output = emptyMesh(v);
+  // We use zero for some undefined values
+  return createTerrainMesh(output, {
+    tileRect,
+    ellipsoid,
+    errorLevel,
+    overscaleFactor: 0,
+    maxVertexDistance,
+    tileSize: output.tileSize,
+  });
+}
+
+interface RasterParams {
+  quantizedHeights?: Float32Array;
+  errorLevel: number;
+  maxVertexDistance: number;
+  tileSize: number;
+}
+
+type RasterTerrainOptions = QuantizedMeshTerrainOptions & RasterParams;
+
+class UpsampleTracker {
+  ne: boolean;
+  nw: boolean;
+  se: boolean;
+  sw: boolean;
+
+  constructor() {
+    this.ne = false;
+    this.nw = false;
+    this.se = false;
+    this.sw = false;
+  }
+
+  finished() {
+    return this.ne && this.nw && this.se && this.sw;
+  }
+}
+
+export class RasterTerrainData
+  extends QuantizedMeshTerrainData
+  implements RasterParams
+{
+  quantizedHeights: Float32Array;
+  errorLevel: number;
+  maxVertexDistance: number;
+  tileSize: number;
+  private upsampleTracker: UpsampleTracker;
+
+  constructor(opts: RasterTerrainOptions) {
+    super(opts);
+    this.quantizedHeights = opts.quantizedHeights;
+    this.errorLevel = opts.errorLevel;
+    this.maxVertexDistance = opts.maxVertexDistance ?? opts.tileSize;
+    this.tileSize = opts.tileSize;
+    this.upsampleTracker = new UpsampleTracker();
+  }
+
+  upsample(
+    tilingScheme: TilingScheme,
+    thisX: number,
+    thisY: number,
+    thisLevel: number,
+    descendantX: number,
+    descendantY: number,
+    descendantLevel: number,
+  ) {
+    if (this.quantizedHeights == null) {
+      return super.upsample(
+        tilingScheme,
+        thisX,
+        thisY,
+        thisLevel,
+        descendantX,
+        descendantY,
+        descendantLevel,
+      );
+    } // Something wonky about our tiling scheme, perhaps
+    // 12/2215/2293 @2x
+    //const url = `https://a.tiles.mapbox.com/v4/mapbox.terrain-rgb/${z}/${x}/${y}${hires}.${this.format}?access_token=${this.accessToken}`;
+
+    const x = descendantX;
+    const y = descendantY;
+    const z = descendantLevel;
+
+    const tile = `${z}/${x}/${y}`;
+
+    //console.log(`Upsampling terrain data from zoom ${thisLevel} to ` + tile);
+
+    const dz = z - thisLevel;
+
+    const scalar = Math.pow(2, dz);
+
+    const ellipsoid = tilingScheme.ellipsoid;
+
+    const err = this.errorLevel / scalar;
+
+    const maxVertexDistance = Math.min(
+      this.maxVertexDistance * scalar,
+      this.tileSize,
+    );
+
+    const upscaledX = thisX * scalar;
+    const upscaledY = thisY * scalar;
+
+    const dx: number = x - upscaledX;
+    const dy: number = y - upscaledY;
+
+    const x0 = (dx * this.tileSize) / scalar;
+    const x1 = ((dx + 1) * this.tileSize) / scalar;
+    const y0 = (dy * this.tileSize) / scalar;
+    const y1 = ((dy + 1) * this.tileSize) / scalar;
+
+    const window = { x0, x1, y0, y1 };
+
+    const res = buildOverscaledTerrainTile({
+      tilingScheme,
+      heightData: subsetByWindow(this.quantizedHeights, window, true),
+      maxVertexDistance,
+      x,
+      y,
+      z,
+      errorLevel: err,
+      ellipsoidRadius: ellipsoid.maximumRadius,
+      tileSize: x1 - x0,
+      overscaleFactor: dz,
+    });
+    if (dz == 1) {
+      // If we've got a single child tile, we can track that we've upsampled the parent.
+      const quadrant = getQuadrant(dx as 0 | 1, dy as 0 | 1);
+      this.upsampleTracker[quadrant] = true;
+    }
+    if (this.upsampleTracker.finished()) {
+      // We've upsampled all child tiles and don't need to keep terrain data around anymore.
+      this.quantizedHeights = undefined;
+    }
+
+    return res;
+  }
+}
+
+function getQuadrant(dx: 0 | 1, dy: 0 | 1): "ne" | "nw" | "se" | "sw" {
+  if (dx == 0 && dy == 0) return "sw";
+  if (dx == 0 && dy == 1) return "nw";
+  if (dx == 1 && dy == 0) return "se";
+  if (dx == 1 && dy == 1) return "ne";
+  throw new Error("Invalid quadrant");
+}
+
+type OverscaleTerrainOptions = TerrainUpscaleInput & {
+  tilingScheme: TilingScheme;
+};
+
+async function buildOverscaledTerrainTile(opts: OverscaleTerrainOptions) {
+  const { tilingScheme, overscaleFactor, ...workerOpts } = opts;
+
+  const { x, y, z } = workerOpts;
+
+  const tileRect = tilingScheme.tileXYToRectangle(x, y, z);
+  const ellipsoid = tilingScheme.ellipsoid;
+
+  const { errorLevel, maxVertexDistance, tileSize } = workerOpts;
+
+  try {
+    const res = (await upsamplerFarm.scheduleTask(workerOpts, [
+      workerOpts.heightData.buffer,
+    ])) as QuantizedMeshResult;
+
+    return createTerrainMesh(res, {
+      tileRect,
+      ellipsoid,
+      errorLevel,
+      overscaleFactor,
+      tileSize,
+      // Maximum vertex distance
+      maxVertexDistance,
+    });
+  } catch (err) {
+    return createEmptyMesh({
+      tileRect,
+      errorLevel,
+      ellipsoid,
+      tileCoord: { x, y, z },
+      tileSize: 0,
+    });
+  }
+}
+
+import UpsamplerWorker from "web-worker:./worker/upsampler-worker";
+import WorkerFarm from "./worker/worker-farm";
+
+const upsamplerFarm = new WorkerFarm({
+  worker: new UpsamplerWorker(),
+  maxWorkers: 5,
+});