map-zero 0.1.0 → 0.2.1

package/src/3dtiles/extrude.js

@@ -1,4 +1,12 @@
 import earcut from 'earcut';
+import { localizeEcefPositions } from './precision.js';
+
+/**
+ * Converts 2D building footprints in lon/lat coordinates into localized ECEF
+ * meshes suitable for Cesium 3D Tiles. This module owns the building-specific
+ * extrusion path: roof/bottom triangulation, wall generation, normals, and
+ * WGS84 coordinate conversion.
+ */
 
 const WGS84_A = 6378137.0;
 const WGS84_F = 1 / 298.257223563;
@@ -12,6 +20,7 @@ const WGS84_E2 = WGS84_F * (2 - WGS84_F);
  *   indices: Uint16Array | Uint32Array,
  *   min: [number, number, number],
  *   max: [number, number, number],
+ *   rtcCenter: [number, number, number],
  *   bbox: [number, number, number, number],
  *   maxHeight: number,
  *   featureCount: number
@@ -19,7 +28,11 @@ const WGS84_E2 = WGS84_F * (2 - WGS84_F);
  */
 
 /**
- * Build one merged mesh from building footprints.
+ * Build one localized mesh from many independent building footprints.
+ *
+ * Each footprint is extruded separately, then all vertices are merged before
+ * being shifted around a shared RTC center. The shared center keeps float32
+ * positions precise enough for Cesium at city scale.
  *
  * @param {Footprint[]} footprints
  * @param {{ baseHeight?: number }} [options]
@@ -55,19 +68,19 @@ export function buildMergedExtrudedPolygonMesh(footprints, options = {}) {
     return null;
   }
 
-  const positionArray = new Float32Array(positions);
+  const localized = localizeEcefPositions(positions);
   const normalArray = new Float32Array(normals);
-  const indexArray = positionArray.length / 3 > 65535
+  const indexArray = localized.positions.length / 3 > 65535
     ? new Uint32Array(indices)
     : new Uint16Array(indices);
-  const bounds = minMaxVec3(positionArray);
 
   return {
-    positions: positionArray,
+    positions: localized.positions,
     normals: normalArray,
     indices: indexArray,
-    min: bounds.min,
-    max: bounds.max,
+    min: localized.min,
+    max: localized.max,
+    rtcCenter: localized.rtcCenter,
     bbox: mergeBboxes(bboxes),
     maxHeight,
     featureCount
@@ -75,6 +88,12 @@ export function buildMergedExtrudedPolygonMesh(footprints, options = {}) {
 }
 
 /**
+ * Extrude one footprint ring into roof, bottom, and wall triangles.
+ *
+ * The input ring is expected in lon/lat degrees. Heights are meters above the
+ * ellipsoid. The returned positions remain absolute ECEF numbers; localization
+ * happens in buildMergedExtrudedPolygonMesh.
+ *
  * @param {Array<[number, number]>} ring
  * @param {number} baseHeight
  * @param {number} topHeight
@@ -137,6 +156,9 @@ export function buildExtrudedPolygonMesh(ring, baseHeight, topHeight) {
 }
 
 /**
+ * Normalize a polygon ring to finite lon/lat pairs and remove the repeated
+ * closing coordinate when present.
+ *
  * @param {Array<[number, number]>} ring
  * @returns {Array<[number, number]>}
  */
@@ -162,6 +184,9 @@ export function cleanRing(ring) {
 }
 
 /**
+ * Project lon/lat points around a local centroid into an approximate meter
+ * plane for earcut triangulation.
+ *
  * @param {Array<[number, number]>} points
  * @param {[number, number]} centroid
  * @returns {{ flat: number[] }}
@@ -178,6 +203,8 @@ function projectRing(points, centroid) {
 }
 
 /**
+ * Return a simple arithmetic lon/lat centroid for small local rings.
+ *
  * @param {Array<[number, number]>} points
  * @returns {[number, number]}
  */
@@ -192,6 +219,9 @@ function polygonCentroid(points) {
 }
 
 /**
+ * Compute a lon/lat bbox for a footprint and pad it slightly so child tile
+ * bounding volumes are not exactly coplanar with feature edges.
+ *
  * @param {Array<[number, number]>} points
  * @returns {[number, number, number, number]}
  */
@@ -211,6 +241,8 @@ function polygonBbox(points) {
 }
 
 /**
+ * Merge multiple lon/lat bounding boxes.
+ *
  * @param {Array<[number, number, number, number]>} bboxes
  * @returns {[number, number, number, number]}
  */
@@ -229,31 +261,31 @@ function mergeBboxes(bboxes) {
 }
 
 /**
- * @param {Float32Array} positions
- * @returns {{ min: [number, number, number], max: [number, number, number] }}
+ * Compute a unit normal from three ECEF triangle vertices.
+ *
+ * @param {[number, number, number]} a
+ * @param {[number, number, number]} b
+ * @param {[number, number, number]} c
+ * @returns {[number, number, number]}
  */
-function minMaxVec3(positions) {
-  const min = [Infinity, Infinity, Infinity];
-  const max = [-Infinity, -Infinity, -Infinity];
-  for (let i = 0; i < positions.length; i += 3) {
-    min[0] = Math.min(min[0], positions[i]);
-    min[1] = Math.min(min[1], positions[i + 1]);
-    min[2] = Math.min(min[2], positions[i + 2]);
-    max[0] = Math.max(max[0], positions[i]);
-    max[1] = Math.max(max[1], positions[i + 1]);
-    max[2] = Math.max(max[2], positions[i + 2]);
-  }
-  return { min, max };
-}
-
 function triangleNormal(a, b, c) {
   return normalize(cross(subtract(b, a), subtract(c, a)));
 }
 
+/**
+ * @param {[number, number, number]} a
+ * @param {[number, number, number]} b
+ * @returns {[number, number, number]}
+ */
 function subtract(a, b) {
   return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
 }
 
+/**
+ * @param {[number, number, number]} a
+ * @param {[number, number, number]} b
+ * @returns {[number, number, number]}
+ */
 function cross(a, b) {
   return [
     a[1] * b[2] - a[2] * b[1],
@@ -262,6 +294,10 @@ function cross(a, b) {
   ];
 }
 
+/**
+ * @param {[number, number, number]} vector
+ * @returns {[number, number, number]}
+ */
 function normalize(vector) {
   const length = Math.hypot(vector[0], vector[1], vector[2]);
   if (!Number.isFinite(length) || length === 0) {
@@ -270,6 +306,13 @@ function normalize(vector) {
   return [vector[0] / length, vector[1] / length, vector[2] / length];
 }
 
+/**
+ * Return the geodetic up vector for a lon/lat coordinate.
+ *
+ * @param {number} lonDeg
+ * @param {number} latDeg
+ * @returns {[number, number, number]}
+ */
 export function wgs84SurfaceNormal(lonDeg, latDeg) {
   const lonRad = degToRad(lonDeg);
   const latRad = degToRad(latDeg);
@@ -281,6 +324,14 @@ export function wgs84SurfaceNormal(lonDeg, latDeg) {
   ];
 }
 
+/**
+ * Convert lon/lat/height to Earth-Centered, Earth-Fixed coordinates.
+ *
+ * @param {number} lonDeg
+ * @param {number} latDeg
+ * @param {number} h
+ * @returns {[number, number, number]}
+ */
 export function wgs84ToEcef(lonDeg, latDeg, h) {
   const lonRad = degToRad(lonDeg);
   const latRad = degToRad(latDeg);
@@ -296,6 +347,10 @@ export function wgs84ToEcef(lonDeg, latDeg, h) {
   ];
 }
 
+/**
+ * @param {number} value
+ * @returns {number}
+ */
 function degToRad(value) {
   return value * Math.PI / 180;
 }

package/src/3dtiles/flat.js

@@ -1,6 +1,7 @@
 import earcut from 'earcut';
 
 import { cleanRing, wgs84SurfaceNormal, wgs84ToEcef } from './extrude.js';
+import { localizeEcefPositions } from './precision.js';
 
 /**
  * @typedef {{
@@ -9,6 +10,7 @@ import { cleanRing, wgs84SurfaceNormal, wgs84ToEcef } from './extrude.js';
  *   indices: Uint16Array,
  *   min: [number, number, number],
  *   max: [number, number, number],
+ *   rtcCenter: [number, number, number],
  *   bbox: [number, number, number, number],
  *   maxHeight: number,
  *   featureCount: number
@@ -176,20 +178,20 @@ function finishMesh(positions, normals, bboxes, height, featureCount, indices =
     return null;
   }
 
-  const positionArray = new Float32Array(positions);
+  const localized = localizeEcefPositions(positions);
   const normalArray = new Float32Array(normals);
   const indexArray = indices.length > 0
-    ? positionArray.length / 3 > 65535
+    ? localized.positions.length / 3 > 65535
       ? new Uint32Array(indices)
       : new Uint16Array(indices)
     : new Uint16Array(0);
-  const bounds = minMaxVec3(positionArray);
   return {
-    positions: positionArray,
+    positions: localized.positions,
     normals: normalArray,
     indices: indexArray,
-    min: bounds.min,
-    max: bounds.max,
+    min: localized.min,
+    max: localized.max,
+    rtcCenter: localized.rtcCenter,
     bbox: mergeBboxes(bboxes),
     maxHeight: height,
     featureCount
@@ -515,17 +517,3 @@ function mergeBboxes(bboxes) {
   }
   return [minLon, minLat, maxLon, maxLat];
 }
-
-function minMaxVec3(positions) {
-  const min = [Infinity, Infinity, Infinity];
-  const max = [-Infinity, -Infinity, -Infinity];
-  for (let i = 0; i < positions.length; i += 3) {
-    min[0] = Math.min(min[0], positions[i]);
-    min[1] = Math.min(min[1], positions[i + 1]);
-    min[2] = Math.min(min[2], positions[i + 2]);
-    max[0] = Math.max(max[0], positions[i]);
-    max[1] = Math.max(max[1], positions[i + 1]);
-    max[2] = Math.max(max[2], positions[i + 2]);
-  }
-  return { min, max };
-}

package/src/3dtiles/glb.js

@@ -1,4 +1,11 @@
 /**
+ * Minimal glTF/GLB writer used by the 3D Tiles exporter.
+ *
+ * It receives already-built mesh buffers and writes a single-scene, single-mesh
+ * GLB. The writer intentionally stays small: no animations, textures, feature
+ * tables, or material variants. Cesium styling is applied outside the GLB when
+ * possible.
+ *
  * @typedef {{
  *   positions: Float32Array,
  *   normals?: Float32Array,
@@ -9,19 +16,19 @@
  */
 
 /**
- * Build a minimal unlit GLB for one merged mesh.
+ * Build a minimal GLB for one merged mesh.
  *
  * @param {Mesh} mesh
- * @param {{ color?: [number, number, number, number], generator?: string, includeNormals?: boolean }} [options]
+ * @param {{ color?: [number, number, number, number], generator?: string, includeNormals?: boolean, quantizeNormals?: boolean, doubleSided?: boolean, unlit?: boolean }} [options]
  * @returns {Buffer}
  */
 export function buildGlbFromMesh(mesh, options = {}) {
-  const chunks = [];
+  const binBuilder = { chunks: [], byteLength: 0 };
   const bufferViews = [];
   const accessors = [];
   const attributes = {};
 
-  const positionView = appendBuffer(chunks, bufferFromTypedArray(mesh.positions), 4);
+  const positionView = appendBuffer(binBuilder, bufferFromTypedArray(mesh.positions), 4);
   bufferViews.push({ buffer: 0, byteOffset: positionView.byteOffset, byteLength: positionView.byteLength, target: 34962 });
   attributes.POSITION = accessors.length;
   accessors.push({
@@ -38,22 +45,26 @@ export function buildGlbFromMesh(mesh, options = {}) {
     && mesh.normals
     && mesh.normals.length === mesh.positions.length;
   if (includeNormals) {
-    const normalView = appendBuffer(chunks, bufferFromTypedArray(mesh.normals), 4);
+    const normals = options.quantizeNormals === false
+      ? mesh.normals
+      : quantizeNormals(mesh.normals);
+    const normalView = appendBuffer(binBuilder, bufferFromTypedArray(normals), 4);
     bufferViews.push({ buffer: 0, byteOffset: normalView.byteOffset, byteLength: normalView.byteLength, target: 34962 });
     attributes.NORMAL = accessors.length;
     accessors.push({
       bufferView: bufferViews.length - 1,
       byteOffset: 0,
-      componentType: 5126,
-      count: mesh.normals.length / 3,
-      type: 'VEC3'
+      componentType: normals instanceof Float32Array ? 5126 : 5120,
+      count: normals.length / 3,
+      type: 'VEC3',
+      ...(normals instanceof Float32Array ? {} : { normalized: true })
     });
   }
 
   const hasIndices = mesh.indices.length > 0;
   let indexAccessor = null;
   if (hasIndices) {
-    const indexView = appendBuffer(chunks, bufferFromTypedArray(mesh.indices), 4);
+    const indexView = appendBuffer(binBuilder, bufferFromTypedArray(mesh.indices), 4);
     bufferViews.push({ buffer: 0, byteOffset: indexView.byteOffset, byteLength: indexView.byteLength, target: 34963 });
     indexAccessor = accessors.length;
     accessors.push({
@@ -65,7 +76,7 @@ export function buildGlbFromMesh(mesh, options = {}) {
     });
   }
 
-  const bin = Buffer.concat(chunks);
+  const bin = Buffer.concat(binBuilder.chunks);
   const primitive = {
     attributes,
     material: 0
@@ -74,38 +85,47 @@ export function buildGlbFromMesh(mesh, options = {}) {
     primitive.indices = indexAccessor;
   }
 
+  const unlit = options.unlit !== false;
+  const material = {
+    pbrMetallicRoughness: {
+      baseColorFactor: options.color ?? [0, 1, 1, 1],
+      metallicFactor: 0,
+      roughnessFactor: 1
+    },
+    doubleSided: options.doubleSided === true
+  };
+  if (unlit) {
+    material.extensions = {
+      KHR_materials_unlit: {}
+    };
+  }
+
   const gltf = {
     asset: {
       version: '2.0',
       generator: options.generator ?? 'map-zero'
     },
-    extensionsUsed: ['KHR_materials_unlit'],
     scene: 0,
     scenes: [{ nodes: [0] }],
     nodes: [{ mesh: 0 }],
     meshes: [{
       primitives: [primitive]
     }],
-    materials: [{
-      pbrMetallicRoughness: {
-        baseColorFactor: options.color ?? [0, 1, 1, 1],
-        metallicFactor: 0,
-        roughnessFactor: 1
-      },
-      extensions: {
-        KHR_materials_unlit: {}
-      },
-      doubleSided: true
-    }],
+    materials: [material],
     buffers: [{ byteLength: bin.length }],
     bufferViews,
     accessors
   };
+  if (unlit) {
+    gltf.extensionsUsed = ['KHR_materials_unlit'];
+  }
 
   return buildGlb(gltf, bin);
 }
 
 /**
+ * Convert any typed array view into a Buffer over the same underlying memory.
+ *
  * @param {ArrayBufferView} typedArray
  * @returns {Buffer}
  */
@@ -114,6 +134,25 @@ function bufferFromTypedArray(typedArray) {
 }
 
 /**
+ * Store unit normals as normalized signed bytes. This keeps the lighting
+ * direction while cutting the normal attribute from 12 bytes to 3 bytes per
+ * vertex, which matters for dense building tiles.
+ *
+ * @param {Float32Array} normals
+ * @returns {Int8Array}
+ */
+function quantizeNormals(normals) {
+  const quantized = new Int8Array(normals.length);
+  for (let i = 0; i < normals.length; i++) {
+    const value = Math.max(-1, Math.min(1, Number.isFinite(normals[i]) ? normals[i] : 0));
+    quantized[i] = Math.round(value * 127);
+  }
+  return quantized;
+}
+
+/**
+ * Serialize a glTF JSON document and binary payload into GLB v2 layout.
+ *
  * @param {Record<string, unknown>} gltf
  * @param {Buffer} binBuffer
  * @returns {Buffer}
@@ -136,19 +175,27 @@ export function buildGlb(gltf, binBuffer) {
 }
 
 /**
- * @param {Buffer[]} chunks
+ * Append one binary buffer to the BIN chunk with the requested alignment.
+ *
+ * Tracking byteLength avoids repeatedly scanning all previous chunks while
+ * assembling large city tiles.
+ *
+ * @param {{ chunks: Buffer[], byteLength: number }} builder
  * @param {Buffer} buffer
  * @param {number} alignment
  * @returns {{ byteOffset: number, byteLength: number }}
  */
-function appendBuffer(chunks, buffer, alignment) {
-  const byteOffset = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+function appendBuffer(builder, buffer, alignment) {
+  const byteOffset = builder.byteLength;
   const paddedOffset = align(byteOffset, alignment);
   if (paddedOffset > byteOffset) {
-    chunks.push(Buffer.alloc(paddedOffset - byteOffset));
+    const padding = Buffer.alloc(paddedOffset - byteOffset);
+    builder.chunks.push(padding);
+    builder.byteLength += padding.length;
   }
 
-  chunks.push(buffer);
+  builder.chunks.push(buffer);
+  builder.byteLength += buffer.length;
   return {
     byteOffset: paddedOffset,
     byteLength: buffer.length
@@ -156,6 +203,8 @@ function appendBuffer(chunks, buffer, alignment) {
 }
 
 /**
+ * Pad a GLB chunk to the required byte alignment.
+ *
  * @param {Buffer} buffer
  * @param {number} alignment
  * @param {number} fill
@@ -169,6 +218,8 @@ function padBuffer(buffer, alignment, fill) {
 }
 
 /**
+ * Round a byte length up to the next multiple of alignment.
+ *
  * @param {number} value
  * @param {number} alignment
  * @returns {number}

package/src/3dtiles/gpkg-features.js

@@ -24,14 +24,14 @@ const LAYER_ALIASES = {
  */
 export function readLayerMetadata(db, manifest, layerId) {
   const manifestLayer = Array.isArray(manifest.layers)
-    ? manifest.layers.find((layer) => layer?.id === layerId) ??
-      manifest.layers.find((layer) => layer?.id === LAYER_ALIASES[layerId])
+    ? manifest.layers.find((layer) => layer === layerId) ??
+      manifest.layers.find((layer) => layer === LAYER_ALIASES[layerId])
     : null;
-  if (!manifestLayer?.table) {
+  if (!manifestLayer) {
     throw new Error(`manifest does not contain layer: ${layerId}`);
   }
 
-  const table = String(manifestLayer.table);
+  const table = String(manifestLayer);
   const geometry = db.prepare(`
     SELECT column_name
     FROM gpkg_geometry_columns

package/src/3dtiles/precision.js

@@ -0,0 +1,47 @@
+/**
+ * Convert absolute ECEF positions to local tile coordinates before storing them
+ * as Float32. Absolute ECEF values are around millions of meters, where Float32
+ * precision is too coarse for flat terrain meshes.
+ *
+ * @param {number[]} positions
+ * @returns {{ positions: Float32Array, min: [number, number, number], max: [number, number, number], rtcCenter: [number, number, number] }}
+ */
+export function localizeEcefPositions(positions) {
+  const absoluteBounds = minMaxVec3(positions);
+  const rtcCenter = [
+    (absoluteBounds.min[0] + absoluteBounds.max[0]) / 2,
+    (absoluteBounds.min[1] + absoluteBounds.max[1]) / 2,
+    (absoluteBounds.min[2] + absoluteBounds.max[2]) / 2
+  ];
+  const local = new Float32Array(positions.length);
+  for (let i = 0; i < positions.length; i += 3) {
+    local[i] = positions[i] - rtcCenter[0];
+    local[i + 1] = positions[i + 1] - rtcCenter[1];
+    local[i + 2] = positions[i + 2] - rtcCenter[2];
+  }
+  const localBounds = minMaxVec3(local);
+  return {
+    positions: local,
+    min: localBounds.min,
+    max: localBounds.max,
+    rtcCenter
+  };
+}
+
+/**
+ * @param {ArrayLike<number>} positions
+ * @returns {{ min: [number, number, number], max: [number, number, number] }}
+ */
+export function minMaxVec3(positions) {
+  const min = [Infinity, Infinity, Infinity];
+  const max = [-Infinity, -Infinity, -Infinity];
+  for (let i = 0; i < positions.length; i += 3) {
+    min[0] = Math.min(min[0], positions[i]);
+    min[1] = Math.min(min[1], positions[i + 1]);
+    min[2] = Math.min(min[2], positions[i + 2]);
+    max[0] = Math.max(max[0], positions[i]);
+    max[1] = Math.max(max[1], positions[i + 1]);
+    max[2] = Math.max(max[2], positions[i + 2]);
+  }
+  return { min, max };
+}

package/src/cli.js

@@ -6,7 +6,9 @@ import { Command, InvalidArgumentError } from 'commander';
 import { buildPackage } from './build.js';
 import { export3dTiles } from './3dtiles/export.js';
 import { exportPmtiles } from './export-pmtiles.js';
+import { createPackageFromBbox } from './from-bbox.js';
 import { LAYER_ALIASES, SUPPORTED_LAYERS } from './layers.js';
+import { packageMapZero } from './package.js';
 import { serveMapZero } from './server.js';
 import { availableStylePresets, availableStyleThemes, writePackageStyle } from './style-command.js';
 import { parseBbox, parseLayerList } from './utils.js';
@@ -55,6 +57,77 @@ program
     }
   });
 
+program
+  .command('from-bbox')
+  .description('Download an OSM extract and build a complete map-zero package for a bbox.')
+  .requiredOption('--bbox <bbox>', 'minLon,minLat,maxLon,maxLat', parseBboxOption)
+  .requiredOption('--out <output.mapzero>', 'output package folder')
+  .option('--layers <layers>', 'comma-separated logical layers; defaults to all supported layers', parseLayersOption)
+  .option('--minzoom <zoom>', 'minimum PMTiles zoom to export', parseZoomOption, 8)
+  .option('--maxzoom <zoom>', 'maximum PMTiles zoom to export', parseZoomOption, 16)
+  .option('--workers <count>', 'parallel PMTiles tile generation workers', parsePositiveIntegerOption, 1)
+  .option('--force-pmtiles', 'allow very large PMTiles exports')
+  .option('--cache-dir <dir>', 'OSM extract cache directory; defaults to ~/.cache/map-zero/osm')
+  .option('--provider-index-url <url>', 'Geofabrik-compatible index URL')
+  .option('--force-download', 're-download the selected OSM extract even if cached')
+  .option('--batch-size <count>', 'geometry build batch size', parsePositiveIntegerOption, 5000)
+  .option('--keep-temp', 'keep the temporary SQLite build database')
+  .option('--debug-build', 'show build memory usage in progress logs')
+  .option('--no-pmtiles', 'skip PMTiles export')
+  .option('--no-3dtiles', 'skip 3D Tiles export')
+  .option('--no-zip', 'skip portable zip creation')
+  .option('--include-gpkg', 'include data.gpkg in the portable zip')
+  .action(async (options) => {
+    const buildProgress = createBuildProgressReporter();
+    try {
+      const result = await createPackageFromBbox({
+        bbox: options.bbox,
+        out: options.out,
+        layers: options.layers ?? [...SUPPORTED_LAYERS],
+        minZoom: options.minzoom,
+        maxZoom: options.maxzoom,
+        workers: options.workers,
+        forcePmtiles: Boolean(options.forcePmtiles),
+        cacheDir: options.cacheDir,
+        providerIndexUrl: options.providerIndexUrl,
+        forceDownload: Boolean(options.forceDownload),
+        batchSize: options.batchSize,
+        keepTemp: Boolean(options.keepTemp),
+        debugBuild: Boolean(options.debugBuild),
+        pmtiles: options.pmtiles,
+        tiles3d: options.tiles3d,
+        zip: options.zip,
+        includeGpkg: Boolean(options.includeGpkg),
+        onStage(message) {
+          console.log(message);
+        },
+        onBuildProgress: buildProgress.update,
+        onPmtilesProgress: reportPmtilesProgress,
+        on3dTilesProgress: report3dTilesProgress
+      });
+      buildProgress.finish();
+
+      console.log(`Built ${result.outDir}`);
+      console.log(`  source: ${result.source.name} (${result.source.path})`);
+      for (const [layer, count] of Object.entries(result.counts)) {
+        console.log(`  ${layer}: ${count}`);
+      }
+      if (result.pmtiles) {
+        console.log(`  PMTiles: ${result.pmtiles.outPath} (${formatBytes(result.pmtiles.outputBytes)})`);
+      }
+      if (result.tiles3d) {
+        console.log(`  3D Tiles: ${result.tiles3d.tilesetPath} (${formatBytes(result.tiles3d.outputBytes)})`);
+      }
+      if (result.zip) {
+        console.log(`  ZIP: ${result.zip.outPath} (${formatBytes(result.zip.outputBytes)})`);
+      }
+    } catch (error) {
+      buildProgress.finish();
+      console.error(`map-zero: ${error instanceof Error ? error.message : String(error)}`);
+      process.exitCode = 1;
+    }
+  });
+
 program
   .command('pmtiles')
   .description('Export a .mapzero package to a static vector PMTiles archive.')
@@ -92,8 +165,8 @@ program
   .argument('<package.mapzero>', 'map-zero package folder')
   .option('--out <dir>', 'output 3D Tiles folder; defaults to <package>/3dtiles')
   .option('--layers <layers>', 'comma-separated 3D layers; defaults to all supported 3D layers', parse3dTilesLayersOption)
-  .option('--max-depth <count>', 'quadtree depth for building tiles', parseNonNegativeIntegerOption, 4)
-  .option('--max-features <count>', 'maximum features per leaf tile before subdivision', parsePositiveIntegerOption, 2500)
+  .option('--max-depth <count>', 'quadtree depth for building tiles', parseNonNegativeIntegerOption, 8)
+  .option('--max-features <count>', 'maximum features per leaf tile before subdivision', parsePositiveIntegerOption, 1500)
   .option('--default-height <meters>', 'fallback building height in meters', parsePositiveNumberOption, 8)
   .action(async (packageDir, options) => {
     try {
@@ -152,6 +225,31 @@ program
     }
   });
 
+program
+  .command('package')
+  .description('Create a portable zip with manifest, styles, PMTiles, and 3D Tiles.')
+  .argument('<package.mapzero>', 'map-zero package folder')
+  .option('--out <file.zip>', 'output zip path; defaults to <package>.zip')
+  .option('--include-gpkg', 'include the source GeoPackage in the zip')
+  .action(async (packageDir, options) => {
+    try {
+      const result = await packageMapZero({
+        packageDir,
+        out: options.out,
+        includeGpkg: Boolean(options.includeGpkg)
+      });
+
+      console.log(`Packaged ${result.outPath}`);
+      console.log(`  files: ${formatInteger(result.fileCount)}`);
+      console.log(`  input size: ${formatBytes(result.inputBytes)}`);
+      console.log(`  zip size: ${formatBytes(result.outputBytes)}`);
+      console.log(`  data.gpkg: ${result.includedGpkg ? 'included' : 'excluded'}`);
+    } catch (error) {
+      console.error(`map-zero: ${error instanceof Error ? error.message : String(error)}`);
+      process.exitCode = 1;
+    }
+  });
+
 program
   .command('serve')
   .description('Serve a .mapzero package with a readonly HTTP API and OpenLayers viewer.')