@macrostrat/cesium-martini 1.4.0 → 1.5.0

package/.idea/misc.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectRootManager" version="2" languageLevel="JDK_21" default="true" project-jdk-name="21" project-jdk-type="JavaSDK">
+    <output url="file://$PROJECT_DIR$/out" />
+  </component>
+</project>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/cesium-martini.iml" filepath="$PROJECT_DIR$/.idea/cesium-martini.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/prettier.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="PrettierConfiguration">
+    <option name="myConfigurationMode" value="MANUAL" />
+    <option name="myRunOnSave" value="true" />
+    <option name="myFilesPattern" value="**/*.{js,ts,jsx,tsx,cjs,cts,mjs,mts,vue,astro,md}" />
+  </component>
+</project>

package/.idea/vcs.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="IssueNavigationConfiguration">
+    <option name="links">
+      <list>
+        <IssueNavigationLink>
+          <option name="issueRegexp" value="\(#(\d+)\)" />
+          <option name="linkRegexp" value="https://github.com/davenquinn/cesium-martini/issues/$1" />
+        </IssueNavigationLink>
+        <IssueNavigationLink>
+          <option name="issueRegexp" value="\(#(\d+)\)" />
+          <option name="linkRegexp" value="https://github.com/davenquinn/martini/issues/$1" />
+        </IssueNavigationLink>
+      </list>
+    </option>
+  </component>
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

package/.idea/workspace.xml

@@ -0,0 +1,125 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AutoImportSettings">
+    <option name="autoReloadType" value="SELECTIVE" />
+  </component>
+  <component name="ChangeListManager">
+    <list default="true" id="c63fbe16-a437-4e92-9177-f56de7f7200d" name="Changes" comment="">
+      <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/package.json" beforeDir="false" afterPath="$PROJECT_DIR$/package.json" afterDir="false" />
+    </list>
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="Git.Settings">
+    <option name="RECENT_BRANCH_BY_REPOSITORY">
+      <map>
+        <entry key="$PROJECT_DIR$" value="b35a980e6b6d6bdd4e6fe12f48dea9d5d1fee27a" />
+      </map>
+    </option>
+    <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
+  </component>
+  <component name="GitHubPullRequestSearchHistory">{
+  &quot;lastFilter&quot;: {
+    &quot;state&quot;: &quot;OPEN&quot;,
+    &quot;assignee&quot;: &quot;davenquinn&quot;
+  }
+}</component>
+  <component name="GithubPullRequestsUISettings">{
+  &quot;selectedUrlAndAccountId&quot;: {
+    &quot;url&quot;: &quot;https://github.com/davenquinn/cesium-martini.git&quot;,
+    &quot;accountId&quot;: &quot;52565d3a-d148-4d26-a021-78a3e61fe000&quot;
+  }
+}</component>
+  <component name="ProjectColorInfo">{
+  &quot;associatedIndex&quot;: 1
+}</component>
+  <component name="ProjectId" id="2scR6KJfXRgKYtH9HK3HqkyDJQi" />
+  <component name="ProjectViewState">
+    <option name="autoscrollToSource" value="true" />
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="openDirectoriesWithSingleClick" value="true" />
+    <option name="showExcludedFiles" value="false" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.git.unshallow": "true",
+    "git-widget-placeholder": "overscaled-tiles",
+    "kotlin-language-version-configured": "true",
+    "last_opened_file_path": "/Users/Daven/Projects/Macrostrat/Software/cesium-martini/examples/vite/src",
+    "node.js.detected.package.eslint": "true",
+    "node.js.detected.package.tslint": "true",
+    "node.js.selected.package.eslint": "(autodetect)",
+    "node.js.selected.package.tslint": "(autodetect)",
+    "nodejs_package_manager_path": "yarn",
+    "prettierjs.PrettierConfiguration.Package": "yarn:package.json:prettier",
+    "project.structure.last.edited": "Modules",
+    "project.structure.proportion": "0.0",
+    "project.structure.side.proportion": "0.0",
+    "settings.editor.selected.configurable": "settings.javascript.prettier",
+    "ts.external.directory.path": "yarn:examples/_webpack-config/package.json:typescript",
+    "vue.rearranger.settings.migration": "true"
+  }
+}]]></component>
+  <component name="RecentsManager">
+    <key name="CopyFile.RECENT_KEYS">
+      <recent name="$PROJECT_DIR$/examples/vite/src" />
+      <recent name="$PROJECT_DIR$/examples/vite-mapzen-worker" />
+      <recent name="$PROJECT_DIR$/examples" />
+      <recent name="$PROJECT_DIR$/examples/webpack-worker" />
+    </key>
+    <key name="MoveFile.RECENT_KEYS">
+      <recent name="$PROJECT_DIR$/examples/webpack" />
+      <recent name="$PROJECT_DIR$/examples/_shared" />
+      <recent name="$PROJECT_DIR$/examples/vite-mapzen-worker" />
+    </key>
+  </component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-jdk-9823dce3aa75-125ca727e0f0-intellij.indexing.shared.core-IU-243.23654.189" />
+        <option value="bundled-js-predefined-d6986cc7102b-822845ee3bb5-JavaScript-IU-243.23654.189" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="SpellCheckerSettings" RuntimeDictionaries="0" Folders="0" CustomDictionaries="0" DefaultDictionary="application-level" UseSingleDictionary="true" transferred="true" />
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="c63fbe16-a437-4e92-9177-f56de7f7200d" name="Changes" comment="" />
+      <created>1738752699502</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1738752699502</updated>
+      <workItem from="1738752700650" duration="46117000" />
+      <workItem from="1739406376299" duration="20669000" />
+    </task>
+    <servers />
+  </component>
+  <component name="TypeScriptGeneratedFilesManager">
+    <option name="version" value="3" />
+    <option name="exactExcludedFiles">
+      <list>
+        <option value="$PROJECT_DIR$/src/index.d.ts" />
+      </list>
+    </option>
+  </component>
+  <component name="Vcs.Log.Tabs.Properties">
+    <option name="TAB_STATES">
+      <map>
+        <entry key="MAIN">
+          <value>
+            <State />
+          </value>
+        </entry>
+      </map>
+    </option>
+  </component>
+  <component name="XSLT-Support.FileAssociations.UIState">
+    <expand />
+    <select />
+  </component>
+</project>

package/.prettierrc

@@ -0,0 +1,3 @@
+{
+  "proseWrap": "always"
+}

package/README.md

@@ -2,28 +2,30 @@
 
 **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)
+
 ![Himalayas](/img/himalayas.jpg)
 
 This package contains a Cesium
 [TerrainProvider](https://cesium.com/docs/cesiumjs-ref-doc/TerrainProvider.html)
 that uses right-triangular irregular networks (RTIN) pioneered by
-[Mapbox's Martini](https://observablehq.com/@mourner/martin-real-time-rtin-terrain-mesh) to
-transform [Terrain-RGB elevation tiles](https://blog.mapbox.com/global-elevation-data-6689f1d0ba65) into
-[quantized mesh terrain](https://github.com/CesiumGS/quantized-mesh),
-for rendering in the [CesiumJS digital globe](https://cesium.com).
-The module provides a general technique applicable to all raster imagery
-(although the Terrain-RGB format is near-ideal for streaming elevation data).
-Fixes for performance and better control of rendering quality are in progress.
-
-This module was created to support our geologic map visualization work
-at [Macrostrat](https://macrostrat.org) and as a building block
-for future rich geoscience visualizations.
-
+[Mapbox's Martini](https://observablehq.com/@mourner/martin-real-time-rtin-terrain-mesh)
+to transform
+[Terrain-RGB elevation tiles](https://blog.mapbox.com/global-elevation-data-6689f1d0ba65)
+into [quantized mesh terrain](https://github.com/CesiumGS/quantized-mesh), for
+rendering in the [CesiumJS digital globe](https://cesium.com). The module
+provides a general technique applicable to all raster imagery (although the
+Terrain-RGB format is near-ideal for streaming elevation data). Fixes for
+performance and better control of rendering quality are in progress.
+
+This module was created to support our geologic map visualization work at
+[Macrostrat](https://macrostrat.org) and as a building block for future rich
+geoscience visualizations.
 
 ## Installation
 
-This package is listed on NPM as `@macrostrat/cesium-martini`. It can be installed
-using the command
+This package is listed on NPM as `@macrostrat/cesium-martini`. It can be
+installed using the command
 
 ```
 npm install --save @macrostrat/cesium-martini
@@ -33,8 +35,8 @@ npm install --save @macrostrat/cesium-martini
 
 ## Development
 
-As of version `1.3.x`, `cesium-martini` development is tested with the Yarn package manager.
-Your mileage with `npm` may vary.
+As of version `1.3.x`, `cesium-martini` development is tested with the Yarn
+package manager. Your mileage with `npm` may vary.
 
 ### Quick start
 
@@ -47,12 +49,15 @@ After cloning this repository, you can build the module (using Rollup) with
 
 ### Example applications
 
-Several example applications are available in the [`examples/`](examples/) directory and runnable from the root project.
-The main example is built with Vite and others are built with Webpack v5. As well as showing how to use this module,
-these examples contain configuration for bundling Cesium in each packaging system.
+Several example applications are available in the [`examples/`](examples/)
+directory and runnable from the root project. The main example is built with
+Vite and others are built with Webpack v5. As well as showing how to use this
+module, these examples contain configuration for bundling Cesium in each
+packaging system.
 
-To run an example application, add `MAPBOX_API_TOKEN=<your-mapbox-token>` to a `.env` file.
-in the root of this repository, and then start the appropriate example:
+To run an example application, add `MAPBOX_API_TOKEN=<your-mapbox-token>` to a
+`.env` file. in the root of this repository, and then start the appropriate
+example:
 
 - `yarn run example` (Vite)
 - `yarn run example:mapzen` (Vite + Mapzen)
@@ -60,66 +65,77 @@ in the root of this repository, and then start the appropriate example:
 - `yarn run example:webpack-mapzen` (Webpack + Mapzen)
 - `yarn run example:webpack-react` (Webpack + React)
 
-Contributions in the form of bug reports and pull requests are welcome.
-These can be to add functionality (e.g. optional normal-map generation) or for
+Contributions in the form of bug reports and pull requests are welcome. These
+can be to add functionality (e.g. optional normal-map generation) or for
 performance. See list of [known limitations](#current-known-limitations) below.
 
 ## Motivation
 
 The Cesium digital globe is a powerful platform for visualization of geospatial
-data in 3D. Cesium maintains a global elevation dataset as a prebuilt terrain mesh,
-which caches the computationally-intensive step of meshing height-field data
-into a triangle irregular network (TIN). Unfortunately, this
-[quantized mesh](https://github.com/CesiumGS/quantized-mesh) format is relatively
-new, narrowly supported and tailored to Cesium itself. Going forward, supporting
-a TIN format for elevation datasets requires maintenance of significant single-purpose
-processing pipelines and storage resources.
+data in 3D. Cesium maintains a global elevation dataset as a prebuilt terrain
+mesh, which caches the computationally-intensive step of meshing height-field
+data into a triangle irregular network (TIN). Unfortunately, this
+[quantized mesh](https://github.com/CesiumGS/quantized-mesh) format is
+relatively new, narrowly supported and tailored to Cesium itself. Supporting a
+TIN format for elevation datasets requires maintenance of significant
+single-purpose processing pipelines and storage resources.
+
+### Fast raster meshing
 
 Mapbox maintains a multiscale global elevation dataset in their clever
 [terrain-RGB](https://blog.mapbox.com/global-elevation-data-6689f1d0ba65)
-format, which bridges web standard file formats (PNG images) with traditional raster GIS
-formats for representing terrain. Rasters are the standard representation of elevation data across the
-geosciences, and many pipelines are available to create and modify raster images.
-Basically any elevation dataset can be easily rescaled to the Terrain-RGB
-format, but the jump from there to a "Quantized mesh" is more complicated.
-
-Recently, the [MARTINI](https://github.com/mapbox/martini) project by
-[Vladimir Agafonkin](https://agafonkin.com/) at Mapbox demonstrated an
+format, which bridges web standard file formats (PNG images) with traditional
+raster GIS formats for representing terrain. Rasters are the standard
+representation of elevation data across the geosciences, and many pipelines are
+available to create and modify raster images. Basically any elevation dataset
+can be easily rescaled to the Terrain-RGB format, but the jump from there to a
+"Quantized mesh" is more complicated.
+
+More recently, [Vladimir Agafonkin](https://agafonkin.com/) at Mapbox
+demonstrated an
 [elegant algorithmic approach](https://observablehq.com/@mourner/martin-real-time-rtin-terrain-mesh)
-that sidesteps this issue.
-MARTINI meshes based on right-triangulated irregular networks (RTIN, _Evans et al., 1998_)
-and is far quicker than the traditional TIN generation techniques.
-
-A speedy meshing algorithm allows this data-preparation step to be handled
-in the browser after elevation tiles are loaded. Integrating this
-toolchain into the Cesium digital globe enables the usage of Mapbox global
-data and other raster terrain layers (e.g. planetary and bathymetric data!),
-without adding overhead of TIN processing and storage.
-
-## Current limitations
-
-### Lack of support for overzooming
-
-Cesium's implementations of the `TerrainProvider` interface are generally geared
-towards representing static terrain meshes. The RTIN algorithm used here can
-dynamically build meshes at a variety of error levels, and the input height
-field are data-dense and can represent extremely detailed meshes at a given zoom level. Currently,
-meshes are generated at levels of detail that undersample the available structure
-in a terrain tile — levels of detail are calibrated to what Cesium needs to
-render visually pleasing output at a given zoom level.
-
-A smarter and more parsimonious solution would use much lower zoom levels
-for terrain than imagery, using the full resolution of the dataset in
-mesh construction. Done correctly, this could lead to an extremely
-data-efficient and adaptive terrain render, but this seems to run somewhat
-counter to how Cesium internally manages levels of detail. Ideally, someone familiar with the inner workings
-of Cesium would provide some guidance here.
+that sidesteps this issue. His [MARTINI](https://github.com/mapbox/martini)
+project constructs meshes based on right-triangulated irregular networks (RTIN,
+_Evans et al., 1998_) and is far quicker than the traditional TIN generation
+techniques.
+
+A speedy meshing algorithm allows this data-preparation step to be handled in
+the browser after elevation tiles are loaded. Integrating this toolchain into
+the Cesium digital globe enables the usage of Mapbox global data and other
+raster terrain layers (e.g. planetary and bathymetric data!), without adding
+overhead of TIN processing and storage.
+
+### Progressive mesh enhancement (added in version `1.5.0`)
+
+Cesium `TerrainProvider`s are generally designed to represent static terrain
+meshes. The RTIN algorithm used here can dynamically build meshes at a variety
+of error levels, and the input height fields can represent extremely detailed
+meshes at a given zoom level.
+
+By default, meshes are generated at levels of detail that undersample the
+available structure in a terrain tile, calibrated to what Cesium needs to render
+visually pleasing output at a given zoom level. To more fully exploit the
+available data, we can generate meshes at progressively higher resolution from
+the same input data. This allows some zoom levels to be skipped, greatly
+increasing efficiency.
+
+This "overzooming" can be enabled using the `skipZoomLevels` configuration. For
+instance, the below function will refuse to load tiles except in
+
+```js
+function skipZoomLevels(z) {
+  return z % 3 != 0;
+}
+```
+
+The configuration also takes a single number and array.
 
 ### Outstanding bugs and issues
 
 - [x] High-resolution `@2x` tiles are notionally supported but not well-tested.
 - [ ] There is no formal testing framework to catch regressions.
-- [ ] TypeScript types are discarded on compilation rather than checked properly.
+- [x] TypeScript types are discarded on compilation rather than checked
+      properly.
 
 ## Prior art and relevant examples
 
@@ -132,35 +148,41 @@ of Cesium would provide some guidance here.
 - [Cesium globe materials example](https://sandcastle.cesium.com/?src=Globe%20Materials.html)
 - [Cesium sky/atmosphere example](https://sandcastle.cesium.com/?src=Sky%20Atmosphere.html)
 
-## TODO
-
-- Make compatible with Mapbox's new `terrain-dem` tileset if possible
-- Better masking of unavailable tiles
-- Bathymetry option
-- Tie to hillshade generator so the same tiles are loaded
+## Changelog
 
-Pull requests for any and all of these priorities are appreciated!
+### `[1.5.0]`: February 2025
 
-## Changelog
+- Allow overzooming of tiles when zoom levels are skipped
+- Improve and deduplicate examples
+- Fix typescript types
+- Improve some internal organization of code
 
 ### `[1.4.0]`: February 2025
 
-- Merge [**PR #10**](https://github.com/davenquinn/cesium-martini/pull/10) from [*Stuart Attenborrow*](https://github.com/stuarta0) to allow loading of non-Mapbox terrain tiles
-- Created Vite and Webpack examples of using the module with Mapzen Terrarium tiles
+- Merge [**PR #10**](https://github.com/davenquinn/cesium-martini/pull/10) from
+  [_Stuart Attenborrow_](https://github.com/stuarta0) to allow loading of
+  non-Mapbox terrain tiles
+- Created Vite and Webpack examples of using the module with Mapzen Terrarium
+  tiles
 - Migrated Vite examples to Vite 5
 - Upgraded `axios` dependency
-- Remove submodule dependency for `@mapbox/martini` in favor of directly importing from [my fork](https://github.com/davenquinn/martini)
+- Remove submodule dependency for `@mapbox/martini` in favor of directly
+  importing from [my fork](https://github.com/davenquinn/martini)
 - Upgrade `yarn` to `4.6.0`
 
 ### `[1.3.0]`: September 2023
 
-- Add compilation to ESModules, which allows the package to be used with modern bundlers like [**Vite**](https://vitejs.dev). *Contributed by [@fc](https://github.com/fc).*
-- Change latitude-based scaling factor for tile error to improve fidelity at high latitudes.
+- Add compilation to ESModules, which allows the package to be used with modern
+  bundlers like [**Vite**](https://vitejs.dev). _Contributed by
+  [@fc](https://github.com/fc)._
+- Change latitude-based scaling factor for tile error to improve fidelity at
+  high latitudes.
 - Remove `regenerator-runtime` from web-worker code, targeting modern platforms.
 
 #### Development environment
 
-We reorganized the development environment and examples for a more modern overall design.
+We reorganized the development environment and examples for a more modern
+overall design.
 
 - Switched to `yarn` from `npm` as the default package manager
 - Enabled Yarn Plug'n'Play for faster development
@@ -169,15 +191,15 @@ We reorganized the development environment and examples for a more modern overal
 - Moved all examples to the `examples/` directory as Yarn workspaces, enabling
   separation of dependencies
 
-
 ### `[1.2.0]`: November 2021
 
 - Globe caps! (disable using the `fillPoles` option).
 - Some fixes for efficiency
 - Fixed small errors in tile occlusion code
-- Added a `minZoom` configuration option to prevent excessive loading of low-resolution tiles
-- Four (!) pull requests from [@stuarta0](https://github.com/stuarta0) to improve loading of non-Mapbox tilesets
-
+- Added a `minZoom` configuration option to prevent excessive loading of
+  low-resolution tiles
+- Four (!) pull requests from [@stuarta0](https://github.com/stuarta0) to
+  improve loading of non-Mapbox tilesets
 
 ### `[1.1.3]`: June 2021
 
@@ -186,8 +208,8 @@ We reorganized the development environment and examples for a more modern overal
 ### `[1.1.2]`: May 2021
 
 - Fixed a bug with loading high-resolution tiles
-- Added a `skipOddLevels` option that significantly reduces the load of zooming through many terrain levels.
-  This is enabled by default.
+- Added a `skipOddLevels` option that significantly reduces the load of zooming
+  through many terrain levels. This is enabled by default.
 - Greatly increase skirt height
 
 ### `[1.1.0]`: May 2021

package/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: ["@babel/preset-env", "@babel/preset-typescript"],
+};