@macrostrat/cesium-martini 1.3.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,13 +35,12 @@ 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
 
 1. Clone the repository
-2. Run `git submodule update --init` to fetch the [martini](https://github.com/mapbox/martini) submodule
 2. Install dependencies with `yarn install`
 3. Build the package with `yarn run build`
 
@@ -48,76 +49,93 @@ 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 environment.
+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)
 - `yarn run example:webpack` (Webpack)
+- `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
 
@@ -130,26 +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
+## Changelog
 
-- 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
+### `[1.5.0]`: February 2025
 
-Pull requests for any and all of these priorities are appreciated!
+- Allow overzooming of tiles when zoom levels are skipped
+- Improve and deduplicate examples
+- Fix typescript types
+- Improve some internal organization of code
 
-## Changelog
+### `[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
+- 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)
+- 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 through a set of interrelated changes, 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
@@ -158,15 +191,15 @@ We reorganized the development environment and examples through a set of interre
 - 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
 
@@ -175,8 +208,8 @@ We reorganized the development environment and examples through a set of interre
 ### `[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"],
+};