map-zero 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+Initial alpha release.
+
+- Build `.mapzero` packages from OSM PBF extracts.
+- Store normalized map data in GeoPackage.
+- Serve dynamic MVT tiles locally.
+- Export static vector PMTiles.
+- Export Cesium 3D Tiles.
+- Provide OpenLayers and Cesium integration helpers.
+- Provide external JSON style presets and compact themes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcos Pérez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# map-zero
+
+Offline vector map packages from OpenStreetMap, ready for GeoPackage, PMTiles, and 3D Tiles.
+
+`map-zero` turns an OSM PBF extract into a portable `.mapzero` folder. The package keeps source data in GeoPackage, can export static PMTiles for fast web delivery, and can export Cesium 3D Tiles for 3D visualization. It is designed for local-first workflows: no API tokens, no hosted map service, no external data service at runtime.
+
+When you export PMTiles or 3D Tiles, the map can be hosted serverlessly as static files. The dynamic Node server is only needed for on-demand MVT generation from `data.gpkg` or for local inspection.
+
+> Early alpha. The format and APIs are usable, but still evolving.
+
+## What It Does
+
+- Builds offline map packages from `.osm.pbf`
+- Stores normalized OSM layers in `data.gpkg`
+- Serves dynamic MVT tiles locally
+- Exports static vector `tiles.pmtiles`
+- Exports Cesium `3dtiles/`
+- Includes a minimal OpenLayers viewer
+- Includes a minimal Cesium viewer
+- Provides framework-agnostic OpenLayers and Cesium helpers
+- Uses external JSON styles and compact themes
+
+Supported logical layers include `roads`, `buildings`, `water`, `landuse`, `railways`, `boundaries`, `pois`, and `aip` for aeronautical/AIP-style data. Older `aviation` layer names are still accepted as compatibility aliases.
+
+## Why
+
+Most map stacks assume online tiles, external APIs, or a heavier database/server setup. `map-zero` is for small-to-medium offline packages that should be easy to build, inspect, host, and embed:
+
+- one folder per map
+- GeoPackage as the editable/source container
+- PMTiles for static, serverless 2D vector maps
+- 3D Tiles for static, serverless Cesium scenes
+- OpenLayers and Cesium integration without owning your app
+
+## Quick Start
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Download an OSM PBF extract:
+
+```bash
+mkdir -p data
+wget https://download.geofabrik.de/europe/spain/madrid-latest.osm.pbf \
+  -O data/madrid.osm.pbf
+```
+
+Build a package:
+
+```bash
+node src/cli.js build ./data/madrid.osm.pbf --out ./madrid.mapzero
+```
+
+Serve it:
+
+```bash
+node src/cli.js serve ./madrid.mapzero --port 8080 --open
+```
+
+Open:
+
+```text
+http://localhost:8080
+```
+
+`serve` is mainly a local preview and inspection command. It is also useful when you want dynamic MVT generated directly from `data.gpkg`. It is not required to deploy a map after exporting PMTiles or 3D Tiles.
+
+By default, `build` infers the PBF bbox and extracts every supported layer. For a cropped package:
+
+```bash
+node src/cli.js build ./data/spain.osm.pbf \
+  --bbox -3.9,40.3,-3.5,40.6 \
+  --out ./madrid.mapzero
+```
+
+## Package Structure
+
+```text
+madrid.mapzero/
+  data.gpkg             # normalized OSM features
+  manifest.json         # package metadata
+  tiles.pmtiles         # optional static MVT archive
+  3dtiles/              # optional Cesium 3D Tiles
+  styles/
+    neon-dark.json
+```
+
+`data.gpkg` is the source for dynamic MVT, PMTiles export, and 3D Tiles export. Styles are JSON files outside the GeoPackage so the same data can be rendered by different viewers.
+
+## PMTiles
+
+Export static vector tiles:
+
+```bash
+node src/cli.js pmtiles ./madrid.mapzero
+```
+
+For large regional packages, keep max zoom lower:
+
+```bash
+node src/cli.js pmtiles ./andalucia.mapzero --minzoom 8 --maxzoom 12 --workers 4
+```
+
+When `tiles.pmtiles` is present in `manifest.json`, the built-in OpenLayers viewer uses it automatically. Without PMTiles, the server falls back to dynamic MVT generation from `data.gpkg`.
+
+PMTiles is a single static file with HTTP range requests. It can be served from static hosting, object storage, nginx, GitHub Pages-style hosting, or any CDN that supports range requests.
+
+Use `map-zero serve` to preview the package locally; use your normal static hosting stack to publish the generated PMTiles package.
+
+## 3D Tiles
+
+Export Cesium-ready 3D Tiles:
+
+```bash
+node src/cli.js 3dtiles ./madrid.mapzero
+```
+
+Buildings are extruded. Roads, railways, boundaries, water, landuse, and AIP/aeronautical features are exported as flat cartographic meshes. The Cesium viewer is available at:
+
+```text
+http://localhost:8080/cesium
+```
+
+3D Tiles are also static files. Once exported, they do not need the map-zero Node server; Cesium can load them from any normal static web server.
+
+Use `map-zero serve` to preview the Cesium output locally; use static hosting to publish the exported `3dtiles/` folder.
+
+## OpenLayers Usage
+
+Use `@map-zero/ol` to add a package to an existing OpenLayers map:
+
+```js
+import Map from 'ol/Map.js';
+import View from 'ol/View.js';
+import { addMapZeroToOpenLayers } from '@map-zero/ol';
+
+const map = new Map({
+  target: 'map',
+  layers: [],
+  view: new View({ center: [0, 0], zoom: 12 })
+});
+
+const controller = await addMapZeroToOpenLayers(map, {
+  id: 'madrid',
+  manifestUrl: './madrid.mapzero/manifest.json'
+});
+
+controller.setVisible('buildings', false);
+```
+
+The helper reuses the same MVT + WebGL rendering path as the built-in viewer. It supports dynamic HTTP MVT and static vector PMTiles.
+
+See [docs/openlayers.md](docs/openlayers.md).
+
+## Cesium Usage
+
+Use `@map-zero/cesium` to add exported 3D Tiles to an existing Cesium viewer:
+
+```js
+import { Viewer } from 'cesium';
+import { addMapZeroToCesium } from '@map-zero/cesium';
+
+const viewer = new Viewer('cesiumContainer');
+
+const controller = await addMapZeroToCesium(viewer, {
+  id: 'huelva',
+  manifestUrl: './huelva.mapzero/manifest.json',
+  style: 'cesium'
+});
+
+controller.setOpacity('buildings', 0.8);
+```
+
+The helper does not take over your Cesium scene. Lighting, terrain, atmosphere, fog, and background remain under application control unless you explicitly opt into map-zero scene defaults.
+
+See [docs/cesium.md](docs/cesium.md).
+
+## Styles And Themes
+
+Apply a bundled preset:
+
+```bash
+node src/cli.js style ./madrid.mapzero --preset neon-dark
+```
+
+Apply a compact theme:
+
+```bash
+node src/cli.js style ./madrid.mapzero --theme neon-dark
+```
+
+Most users should edit compact theme JSON instead of full renderer-ready style presets.
+
+See [docs/styles.md](docs/styles.md) and [docs/cartography.md](docs/cartography.md).
+
+## Documentation
+
+- [Architecture](docs/architecture.md)
+- [Styles and themes](docs/styles.md)
+- [Cartography and POIs](docs/cartography.md)
+- [OpenLayers integration](docs/openlayers.md)
+- [Cesium integration](docs/cesium.md)
+- [HTTP API](docs/api.md)
+
+## Current Limitations
+
+- Early alpha package format and APIs
+- Readonly packages; editing OSM data is not supported
+- Labels are available in the OpenLayers path but are still limited
+- PMTiles export is supported; MBTiles export is not
+- Cesium export is focused on extruded buildings and flat cartographic context layers
+- 3D Tiles labels, terrain clamping, advanced metadata, and regional LOD optimization are still future work
+- The built-in viewers still load OpenLayers/Cesium from public CDNs, although map data and PMTiles dependencies are local
+
+## License
+
+MIT

package/docs/api.md

@@ -0,0 +1,66 @@
+# HTTP API
+
+`map-zero serve` starts a readonly local server for one `.mapzero` package.
+
+```bash
+node src/cli.js serve ./madrid.mapzero --port 8080 --open
+```
+
+The HTTP API is only required for dynamic GeoPackage-backed serving and local inspection. If you export `tiles.pmtiles` or `3dtiles/`, those artifacts can be served as static files without the map-zero Node server.
+
+## Viewer Routes
+
+```text
+GET /
+GET /cesium
+```
+
+## Package Routes
+
+```text
+GET /manifest.json
+GET /styles/:name
+GET /tiles.pmtiles
+GET /3dtiles/:layer/tileset.json
+GET /3dtiles/:layer/tiles/:tile.b3dm
+```
+
+`tiles.pmtiles` is served with range request support.
+
+## Metadata Routes
+
+```text
+GET /api/info
+GET /api/layers
+```
+
+Examples:
+
+```bash
+curl http://127.0.0.1:8080/api/info
+curl http://127.0.0.1:8080/api/layers
+```
+
+## Dynamic MVT Routes
+
+Combined layers:
+
+```text
+GET /api/tiles/:z/:x/:y.mvt?layers=roads,water
+```
+
+Single layer:
+
+```text
+GET /api/tiles/:layer/:z/:x/:y.mvt
+```
+
+Example:
+
+```bash
+curl 'http://127.0.0.1:8080/api/tiles/14/8030/6165.mvt?layers=roads,water'
+```
+
+The dynamic tile path validates layers against the package manifest and uses the same MVT generation logic as PMTiles export.
+
+`aip` is the canonical aeronautical/AIP layer name. `aviation` remains accepted as a compatibility alias for older packages.

package/docs/architecture.md

@@ -0,0 +1,87 @@
+# Architecture
+
+`map-zero` separates the data pipeline from the rendering helpers:
+
+- OSM PBF is parsed into a normalized GeoPackage.
+- Dynamic MVT, PMTiles export, and 3D Tiles export read from that GeoPackage.
+- Styles live outside the GeoPackage as JSON.
+- OpenLayers and Cesium helpers add map-zero packages to existing viewers without owning the application.
+
+## Core Pipeline
+
+- `src/cli.js`: command wiring, argument parsing, terminal progress output.
+- `src/build.js`: package build orchestration and output folder creation.
+- `src/osm.js`: streamed OSM PBF scan, temporary SQLite build store, geometry extraction.
+- `src/layers.js`: logical layer definitions, OSM tag matching, layer property normalization.
+- `src/gpkg.js`: GeoPackage creation and incremental feature writes.
+- `src/gpkg-read.js`: readonly GeoPackage metadata and tile feature queries.
+- `src/geometry-read.js`: GeoPackage binary geometry decoding.
+
+## 2D Tile Pipeline
+
+- `src/mvt.js`: shared MVT generation, server-side filtering, detail policy, generalization.
+- `src/server.js`: readonly Fastify API, dynamic MVT routes, cache and viewer assets.
+- `src/tile-cache.js`: in-memory LRU cache and in-flight tile request coalescing support.
+- `src/export-pmtiles.js`: PMTiles export orchestration and progress.
+- `src/pmtiles-worker.js`: worker-thread tile generation for PMTiles export.
+- `src/pmtiles.js`: PMTiles archive writer utilities.
+
+Dynamic serving and PMTiles export both call the same `src/mvt.js` tile generation functions.
+
+## 3D Tiles Pipeline
+
+- `src/3dtiles/export.js`: 3D Tiles export orchestration.
+- `src/3dtiles/gpkg-buildings.js`: readonly building queries and height extraction.
+- `src/3dtiles/gpkg-features.js`: readonly feature queries for non-building layers.
+- `src/3dtiles/extrude.js`: building footprint extrusion.
+- `src/3dtiles/clipper-surfaces.js`: buffered/dissolved line surfaces for cartographic layers.
+- `src/3dtiles/flat.js`: flat polygon and point-derived surfaces.
+- `src/3dtiles/glb.js`: minimal unlit GLB generation.
+- `src/3dtiles/b3dm.js`: B3DM wrapper.
+- `src/3dtiles/tileset.js`: tileset JSON generation.
+
+The Cesium export currently favors top-down cartographic fidelity over street-level realism. Roads and other line layers are converted to flat surfaces rather than GPU-only line primitives so the output is portable 3D Tiles geometry.
+
+## Style And Rendering
+
+- `src/style-presets.js`: full preset loading and layer filtering.
+- `src/style-themes.js`: compact theme expansion into full style JSON.
+- `src/style.js`: compatibility re-export for style APIs.
+- `src/style-command.js`: `map-zero style` command implementation.
+- `styles/presets/*.json`: full renderer-ready style presets.
+- `styles/themes/*.theme.json`: compact user-editable themes.
+- `packages/ol/src/index.js`: framework-agnostic OpenLayers layer helper.
+- `packages/ol/src/labels.js`: optional OpenLayers text label layer.
+- `packages/cesium/src/index.js`: framework-agnostic Cesium helper.
+- `src/html.js`: built-in OpenLayers and Cesium viewer shells.
+
+## Package Layout
+
+```text
+example.mapzero/
+  data.gpkg
+  manifest.json
+  tiles.pmtiles
+  3dtiles/
+  styles/
+```
+
+`data.gpkg` is the source of truth after build. PMTiles and 3D Tiles can be regenerated from it without rebuilding from OSM.
+
+## Serving Modes
+
+`map-zero` supports two deployment models:
+
+- **Dynamic local server**: Node reads `data.gpkg` and generates MVT on demand.
+- **Static/serverless hosting**: exported `tiles.pmtiles` and `3dtiles/` are served as static files.
+
+PMTiles and 3D Tiles do not require a map-zero runtime server after export. The local server remains useful for inspection, development, and dynamic GeoPackage-backed tiles.
+
+## Refactor Notes
+
+- `src/mvt.js`: tile filtering, generalization and encoding are still coupled. A future refactor can split query filters, generalization and MVT encoding.
+- `src/osm.js`: streamed parser and disk-backed build pipeline are coupled. A future refactor can split temp-store access and geometry builders.
+- `src/export-pmtiles.js`: export planning, worker scheduling and PMTiles staging are coupled. A future refactor can split estimation/progress from worker orchestration.
+- `packages/ol/src/index.js`: source creation, style interpretation and layer creation are coupled. A future refactor can split source adapters from WebGL style generation.
+
+These are implementation notes, not public API.

package/docs/cartography.md

@@ -0,0 +1,77 @@
+# Cartography
+
+`map-zero` currently ships with tactical/neon-oriented styles. The defaults prioritize infrastructure and operational context over consumer map content.
+
+## Roads
+
+Road styling uses `highway=*` plus related properties such as `bridge`, `tunnel`, `layer`, `service`, and `access`.
+
+The default 2D style uses:
+
+- mostly uniform road widths
+- opaque casing/body strokes
+- hierarchy through color, brightness, min zoom, and subtle casing differences
+- limited major road labels
+
+This keeps roads visually connected without topology merging.
+
+## Labels
+
+OpenLayers labels are optional and sparse by default:
+
+- major road refs
+- AIP/aeronautical names/refs
+- selected operational POIs
+
+Local street labels are disabled by default. Labels are filtered to avoid raw OSM taxonomy values such as `yes`, `generator`, `tower`, `pharmacy`, or `fuel` appearing as text.
+
+## POI Categories
+
+The default presets treat POIs as operational infrastructure rather than a consumer city guide.
+
+Visible categories include:
+
+- `transport`: rail, subway, bus, ferry, airport, fuel/charging infrastructure
+- `emergency`: hospitals, clinics, police, fire stations, shelters
+- `government`: town halls, courts, prisons, embassies, government offices
+- `energy`: power plants, substations, generators, towers, transformers, lines
+- `communications`: communications towers, masts, antennas, radar-style infrastructure
+- `protected`: protected areas, nature reserves, national parks
+- `industrial`: industrial, logistics, refinery, depot, storage infrastructure
+- `military`: military-tagged sites, bunkers, barracks, checkpoints, airbases, naval bases
+
+Hidden by default:
+
+- restaurants, cafes, bars, pubs
+- shops and generic commercial POIs
+- hotels, attractions, generic tourism
+- generic leisure and entertainment
+
+Dynamic MVT serving applies POI category filtering before encoding. PMTiles exports use the same rules.
+
+## AIP / Aeronautical Data
+
+The `aip` layer extracts OSM `aeroway=*` nodes, ways, and simple polygon relations. It preserves:
+
+- `id`
+- `name`
+- `aeroway`
+- `ref`
+- `surface`
+- `width`
+- `length`
+
+Runways, taxiways, aprons, terminals, aerodromes, launchpads, and helipads are represented when present in OSM. Some OSM data lacks physical width tags; 3D export uses class-based fallback widths in those cases.
+
+Dense operational point classes such as navigation aids, gates, thresholds, windsocks, and towers are hidden by default in the 2D style to avoid clutter.
+
+`aviation` is still accepted as a compatibility alias for older packages and commands. The public layer name is now `aip`, which leaves room to merge richer aeronautical sources such as ARINC424-derived data into the same domain later.
+
+## Boundaries
+
+Boundary styling uses `admin_level` where available:
+
+- national and regional boundaries are stronger
+- local boundaries are subtle
+
+In Cesium, boundaries are exported as flat contour surfaces rather than filled administrative polygons.

package/docs/cesium.md

@@ -0,0 +1,107 @@
+# Cesium Integration
+
+The Cesium helper adds exported 3D Tiles to an existing Cesium viewer. It does not create or own the viewer.
+
+```js
+import { Viewer } from 'cesium';
+import { addMapZeroToCesium } from '@map-zero/cesium';
+
+const viewer = new Viewer('cesiumContainer');
+
+const controller = await addMapZeroToCesium(viewer, {
+  id: 'huelva',
+  manifestUrl: './huelva.mapzero/manifest.json',
+  style: 'cesium'
+});
+```
+
+## Export 3D Tiles
+
+```bash
+node src/cli.js 3dtiles ./huelva.mapzero
+```
+
+By default, the exporter writes all supported 3D layers:
+
+- `buildings`
+- `landuse`
+- `water`
+- `aip`
+- `railways`
+- `roads`
+- `boundaries`
+
+Use `--layers` for a smaller export:
+
+```bash
+node src/cli.js 3dtiles ./huelva.mapzero --layers buildings,roads
+```
+
+Buildings are extruded. Heights use `height`, then `building:levels * 3`, then the configured default height.
+
+Non-building layers are exported as flat cartographic meshes:
+
+- roads, railways, and boundaries become buffered/dissolved line surfaces
+- landuse, water, and AIP/aeronautical polygons become flat indexed surfaces
+- AIP points such as helipads can become small flat markers
+
+## Scene Configuration
+
+The helper does not change global Cesium scene settings by default. Applications control terrain, fog, atmosphere, lighting, and background.
+
+Optional tactical defaults:
+
+```js
+await addMapZeroToCesium(viewer, {
+  manifestUrl: './huelva.mapzero/manifest.json',
+  style: 'cesium',
+  applyDefaultSceneStyle: true
+});
+```
+
+You can also provide your own scene hook:
+
+```js
+await addMapZeroToCesium(viewer, {
+  manifestUrl: './huelva.mapzero/manifest.json',
+  configureScene(viewer) {
+    viewer.scene.fog.enabled = false;
+  }
+});
+```
+
+## Multiple Packages
+
+```js
+const madrid = await addMapZeroToCesium(viewer, {
+  id: 'madrid',
+  manifestUrl: './madrid.mapzero/manifest.json'
+});
+
+const huelva = await addMapZeroToCesium(viewer, {
+  id: 'huelva',
+  manifestUrl: './huelva.mapzero/manifest.json'
+});
+
+madrid.setVisible('buildings', false);
+huelva.destroy();
+```
+
+Each controller owns only its package primitives.
+
+## Controller
+
+```js
+controller.setVisible('buildings', true);
+controller.setOpacity('buildings', 0.7);
+controller.destroy();
+```
+
+The module exports:
+
+- `loadMapZeroManifest`
+- `loadMapZeroStyle`
+- `createMapZeroCesiumTilesets`
+- `addMapZeroToCesium`
+- `applyMapZeroCesiumSceneStyle`
+- `createMapZeroCesiumStyle`

package/docs/openlayers.md

@@ -0,0 +1,98 @@
+# OpenLayers Integration
+
+The OpenLayers helper adds a map-zero package to an existing map. It does not create or own the map.
+
+```js
+import Map from 'ol/Map.js';
+import View from 'ol/View.js';
+import { addMapZeroToOpenLayers } from '@map-zero/ol';
+
+const map = new Map({
+  target: 'map',
+  layers: [],
+  view: new View({ center: [0, 0], zoom: 12 })
+});
+
+const controller = await addMapZeroToOpenLayers(map, {
+  id: 'madrid',
+  manifestUrl: './madrid.mapzero/manifest.json'
+});
+```
+
+## Sources
+
+The helper supports:
+
+- PMTiles vector MVT when `manifest.tiles.format === "pmtiles"`
+- dynamic MVT from the map-zero server otherwise
+
+You can force a source mode:
+
+```js
+await addMapZeroToOpenLayers(map, {
+  manifestUrl: './madrid.mapzero/manifest.json',
+  source: 'pmtiles' // 'auto', 'pmtiles', or 'dynamic'
+});
+```
+
+## Multiple Packages
+
+Each call creates an isolated package instance:
+
+```js
+const madrid = await addMapZeroToOpenLayers(map, {
+  id: 'madrid',
+  manifestUrl: './madrid.mapzero/manifest.json',
+  zIndexBase: 1000
+});
+
+const huelva = await addMapZeroToOpenLayers(map, {
+  id: 'huelva',
+  manifestUrl: './huelva.mapzero/manifest.json',
+  zIndexBase: 2000
+});
+
+madrid.setVisible('roads', false);
+huelva.destroy();
+```
+
+Internal layer ids are namespaced by instance. The public controller still uses logical layer ids.
+
+## Shared Styles
+
+Style objects can be loaded once and reused:
+
+```js
+import { loadMapZeroStyle } from '@map-zero/ol';
+
+const style = await loadMapZeroStyle('./styles/neon-dark.json');
+
+await addMapZeroToOpenLayers(map, {
+  id: 'madrid',
+  manifestUrl: './madrid.mapzero/manifest.json',
+  style
+});
+
+await addMapZeroToOpenLayers(map, {
+  id: 'huelva',
+  manifestUrl: './huelva.mapzero/manifest.json',
+  style
+});
+```
+
+Shared style objects are treated as readonly.
+
+## Controller
+
+```js
+controller.setVisible('buildings', false);
+controller.setOpacity('roads', 0.8);
+controller.destroy();
+```
+
+The module exports:
+
+- `loadMapZeroManifest`
+- `loadMapZeroStyle`
+- `createMapZeroOpenLayersLayers`
+- `addMapZeroToOpenLayers`