leaflet-city-mapper 0.0.9 → 0.1.0

package/src/camera/mapPanBy.js

@@ -1,8 +1,15 @@
-import { mapMethods } from '../globals/mapMethods.js';
-
-import { project } from '../projections/projectCameraPoint.js';
-import { pointOf } from '../projections/toPoint.js';
-
+import { mapMethods } from '../globals/mapMethods.js';
+import { project } from '../projections/projectCameraPoint.js';
+import { pointOf } from '../projections/toPoint.js';
+
+/**
+ * Convert a screen offset to ground pixels and pan this map.
+ *
+ * @param {L.Point|Array} offset Screen-space pan offset.
+ * @param {Object} options Leaflet pan options.
+ *
+ * @returns {L.Map} This map.
+ */
 export function mapPanBy(offset, options) {
   const half = this.getSize().divideBy(2);
   const ground = half.subtract(project(this, half.subtract(pointOf(offset)), true));

package/src/camera/mapPanInside.js

@@ -1,11 +1,17 @@
 import { mapMethods } from '../globals/mapMethods.js';
 import { cameraZeroPadding } from '../globals/cameraZeroPadding.js';
-
 import { mapGetPitch } from './mapGetPitch.js';
 import { mapGetBearing } from './mapGetBearing.js';
-
 import { pointOf } from '../projections/toPoint.js';
 
+/**
+ * Pan this map until a location lies inside the padded camera viewport.
+ *
+ * @param {L.LatLng|Array} latlng Geographic location.
+ * @param {Object} [options] Padding and pan options.
+ *
+ * @returns {L.Map} This map.
+ */
 export function mapPanInside(latlng, options = /* alloc */ {}) {
   if (!mapGetPitch(this) && !mapGetBearing(this)) return mapMethods.value.panInside.call(this, latlng, options);
   const min = pointOf(options.paddingTopLeft || options.padding || cameraZeroPadding);

package/src/camera/mapResetNorth.js

@@ -1,4 +1,12 @@
 import { cameraAnimatedOptions } from '../globals/cameraAnimatedOptions.js';
 import { mapSetBearing } from './mapSetBearing.js';
 
+/**
+ * Reset a map's bearing to north.
+ *
+ * @param {L.Map} map Map to update.
+ * @param {Object} [options] Camera animation options.
+ *
+ * @returns {L.Map} The updated map.
+ */
 export function mapResetNorth(map, options = cameraAnimatedOptions) { return mapSetBearing(map, 0, options); }

package/src/camera/mapResetNorthPitch.js

@@ -1,4 +1,12 @@
 import { cameraAnimatedOptions } from '../globals/cameraAnimatedOptions.js';
 import { mapAnimateCamera } from '../animations/mapAnimateCamera.js';
 
+/**
+ * Reset a map's bearing and pitch to zero.
+ *
+ * @param {L.Map} map Map to update.
+ * @param {Object} [options] Camera animation options.
+ *
+ * @returns {L.Map} The updated map.
+ */
 export function mapResetNorthPitch(map, options = cameraAnimatedOptions) { return mapAnimateCamera(map, 0, 0, options); }

package/src/camera/mapSetBearing.js

@@ -1,3 +1,13 @@
 import { mapAnimateCamera } from '../animations/mapAnimateCamera.js';
 import { mapGetPitch } from './mapGetPitch.js';
+
+/**
+ * Set or animate a map's bearing while retaining its current pitch.
+ *
+ * @param {L.Map} map Map to update.
+ * @param {number} bearing Target bearing in degrees.
+ * @param {Object} [options] Camera animation options.
+ *
+ * @returns {L.Map} The updated map.
+ */
 export function mapSetBearing(map, bearing, options) { return mapAnimateCamera(map, mapGetPitch(map), bearing, options); }

package/src/camera/mapSetPitch.js

@@ -1,3 +1,13 @@
 import { mapAnimateCamera } from '../animations/mapAnimateCamera.js';
 import { mapGetBearing } from './mapGetBearing.js';
+
+/**
+ * Set or animate a map's pitch while retaining its current bearing.
+ *
+ * @param {L.Map} map Map to update.
+ * @param {number} pitch Target pitch in degrees.
+ * @param {Object} [options] Camera animation options.
+ *
+ * @returns {L.Map} The updated map.
+ */
 export function mapSetPitch(map, pitch, options) { return mapAnimateCamera(map, pitch, mapGetBearing(map), options); }

package/src/camera/mapSetPitchAndBearing.js

@@ -1,12 +1,21 @@
 import { cameraBearingByMap } from '../weakmaps/cameraBearingByMap.js';
 import { cameraPitchByMap } from '../weakmaps/cameraPitchByMap.js';
-
-
 import { mapGetPitch } from './mapGetPitch.js';
 import { mapGetBearing } from './mapGetBearing.js';
-
 import { updateSky } from './updateSky.js';
 
+/**
+ * Set validated camera angles immediately and notify listeners of changes.
+ *
+ * @param {L.Map} map Map to update.
+ * @param {number} pitch Pitch in degrees.
+ * @param {number} bearing Bearing in degrees.
+ *
+ * @returns {L.Map} The updated map.
+ *
+ * @throws {TypeError} If either angle is not finite.
+ * @throws {TypeError} If maxPitch is not finite or is outside 0 to 180 degrees.
+ */
 export function mapSetPitchAndBearing(map, pitch, bearing) {
   if (!Number.isFinite(pitch) || !Number.isFinite(bearing)) throw /* alloc */ new TypeError('Camera angles must be finite numbers');
   if (!Number.isFinite(map.options.maxPitch) || map.options.maxPitch < 0 || map.options.maxPitch > 180) {

package/src/camera/mapSetZoomAround.js

@@ -1,9 +1,17 @@
 import { L } from '../globals/L.js';
 import { mapMethods } from '../globals/mapMethods.js';
-
 import { mapGetPitch } from './mapGetPitch.js';
 import { mapGetBearing } from './mapGetBearing.js';
 
+/**
+ * Zoom around a geographic location or screen point while preserving the camera anchor.
+ *
+ * @param {L.LatLng|L.Point} latlng Geographic location or container point.
+ * @param {number} zoom Target zoom.
+ * @param {Object} options Leaflet zoom options.
+ *
+ * @returns {L.Map} This map.
+ */
 export function mapSetZoomAround(latlng, zoom, options) {
   if (!mapGetPitch(this) && !mapGetBearing(this)) return mapMethods.value.setZoomAround.call(this, latlng, zoom, options);
   zoom = this._limitZoom(zoom);

package/src/camera/mapTryAnimatedPan.js

@@ -1,6 +1,13 @@
 import { mapMethods } from '../globals/mapMethods.js';
 
-
+/**
+ * Attempt an animated pan to a center using Leaflet's ground-space offset.
+ *
+ * @param {L.LatLng} center Target center.
+ * @param {Object} [options] Leaflet pan options.
+ *
+ * @returns {boolean} Whether the pan was started.
+ */
 export function mapTryAnimatedPan(center, options) {
   // Leaflet's geographic recentering already supplies ground pixels, not screen pixels.
   const offset = this._getCenterOffset(center)._trunc();

package/src/camera/mapUpdateCameraOverlays.js

@@ -1,4 +1,10 @@
 import { L } from '../globals/L.js';
+
+/**
+ * Refresh marker, popup and tooltip positions for a camera change.
+ *
+ * @param {L.Map} map Map containing the overlays.
+ */
 export function mapUpdateCameraOverlays(map) {
   let layer;
   for (layer of Object.values(map._layers)) {

package/src/camera/setBearing.js

@@ -1,5 +1,13 @@
 import { mapSetBearing } from './mapSetBearing.js';
 
+/**
+ * Set or animate this map's bearing.
+ *
+ * @param {number} bearing Target bearing in degrees.
+ * @param {Object} [options] Camera animation options.
+ *
+ * @returns {L.Map} This map.
+ */
 export function setBearing(bearing, options) {
   return mapSetBearing(this, bearing, options);
 }

package/src/camera/setPitch.js

@@ -1,5 +1,13 @@
 import { mapSetPitch } from './mapSetPitch.js';
 
+/**
+ * Set or animate this map's pitch.
+ *
+ * @param {number} pitch Target pitch in degrees.
+ * @param {Object} [options] Camera animation options.
+ *
+ * @returns {L.Map} This map.
+ */
 export function setPitch(pitch, options) {
   return mapSetPitch(this, pitch, options);
 }

package/src/camera/updateMapCamera.js

@@ -1,8 +1,6 @@
 import { cameraByLayer } from '../weakmaps/cameraByLayer.js';
 import { sceneOriginByLayer } from '../weakmaps/sceneOriginByLayer.js';
 import { cameraViewByMap } from '../weakmaps/cameraViewByMap.js';
-
-
 import { radians } from '../globals/radians.js';
 import { cameraFov } from '../globals/cameraFov.js';
 import { earthCirc } from '../globals/earthCirc.js';
@@ -11,11 +9,15 @@ import { mapMethods } from '../globals/mapMethods.js';
 import { walkByMap } from '../weakmaps/walkByMap.js';
 import { mapGetPitch } from './mapGetPitch.js';
 import { mapGetBearing } from './mapGetBearing.js';
-
 import { updateCamera } from "./updateSceneCamera.js";
-
 import { animationPoint } from '../projections/transformZoomAnimationPoint.js';
 
+/**
+ * Match the scene camera to the map view, terrain and active walker height.
+ *
+ * @param {L.Layer} layer Layer owning the camera and scene origin.
+ * @param {L.Point} size Viewport dimensions in pixels.
+ */
 export function updateMapCamera(layer, size) {
   const map = layer._map;
   // Match the map's perspective, including the intermediate view of an animated zoom.

package/src/camera/updateSceneCamera.js

@@ -1,6 +1,12 @@
 import { halfRadians } from '../globals/halfRadians.js';
-/** Orthonormal view basis plus perspective matrices, refreshed before projecting/drawing. */
 
+/**
+ * Refresh the camera's orthonormal view basis and perspective matrices.
+ *
+ * @param {Object} camera Camera position, target, up vector and matrix state.
+ *
+ * @throws {Error} If the view transform is singular.
+ */
 export function updateCamera(camera) {
   camera.x ||= /* alloc */ [0, 0, 0];
   camera.y ||= /* alloc */ [0, 0, 0];

package/src/camera/updateSky.js

@@ -1,11 +1,9 @@
 import { pitchSkyByMap } from '../weakmaps/pitchSkyByMap.js';
-
 import { L } from '../globals/L.js';
 import { radians } from '../globals/radians.js';
-
 import { mapGetPitch } from './mapGetPitch.js';
 
-
+/** Update this map's sky element to match the pitched horizon. */
 export function updateSky() {
   const height = this.getSize().y, pitch = mapGetPitch(this) * radians;
   const far = height * this.options.pitchMaxDistance, distance = height * 1.5;

package/src/cog/README.md

@@ -0,0 +1,29 @@
+# Cloud Optimized GeoTIFF
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Reads supported GeoTIFF metadata and byte ranges and decodes color or elevation
+tiles from COG sources. The same source can be used by raster and terrain paths.
+
+## Adapting a COG to tiles
+
+```mermaid
+flowchart LR
+  File["COG / PMTiles asset"] --> Open["Read TIFF directories"]
+  Open --> Adapter["Archive-compatible header + XYZ"]
+  Adapter --> Overview["Select zoom overview"]
+  Overview --> Color["Color blocks → image"]
+  Overview --> DEM["Elevation blocks → data"]
+  Color --> Raster["Raster"]
+  DEM --> Terrain["Terrain"]
+```
+
+Supports classic TIFF in EPSG:3857, not BigTIFF; requests outside coverage
+return no tile. Raster initialization uses a
+[worker-backed adapter](../workers/openCogInWorker.js).
+
+- [getCogHeader.js](./getCogHeader.js): obtain COG metadata.
+- [getColorTile.js](./getColorTile.js) and [getElevationTile.js](./getElevationTile.js): request tile data.
+- [decodeCogTile.js](./decodeCogTile.js): decode compressed tile bytes.
+
+Related: [archives](../archives/README.md), [terrain](../terrain/README.md), [workers](../workers/README.md).

package/src/cog/decodeCogTile.js

@@ -1,3 +1,16 @@
+/**
+ * Decode an uncompressed or deflate-compressed COG tile to its expected byte length.
+ *
+ * @param {ArrayBuffer} data Encoded tile data.
+ * @param {number} length Expected decoded byte length.
+ * @param {number} compression TIFF compression code.
+ *
+ * @returns {Promise<ArrayBuffer>} Decoded tile data.
+ *
+ * @throws {Error} If an uncompressed tile has the wrong size.
+ * @throws {Error} If decompressed data exceeds the expected size.
+ * @throws {Error} If decompressed data is shorter than expected.
+ */
 export async function decodeCogTile(data, length, compression) {
   if (compression === 1) {
     if (data.byteLength !== length) throw /* alloc */ new Error('Invalid uncompressed COG tile size');

package/src/cog/finiteCogValues.js

@@ -1,3 +1,10 @@
+/**
+ * Check whether all provided values are finite.
+ *
+ * @param {ArrayLike<number>} values Values to inspect, if present.
+ *
+ * @returns {boolean} Whether every value is finite.
+ */
 export function finiteCogValues(values) {
   let value;
   for (value of values || /* alloc */ []) if (!Number.isFinite(value)) return false;

package/src/cog/getCogAssetEntry.js

@@ -1,6 +1,17 @@
 import { decompress } from '../archives/decompress.js';
 import { readCog } from './readCog.js';
 
+/**
+ * Read and validate a named COG asset entry from PMTiles metadata.
+ *
+ * @param {Object} container Container byte source.
+ * @param {Object} header Decoded PMTiles header.
+ * @param {string} asset Asset name.
+ *
+ * @returns {Promise<Object>} Validated asset entry.
+ *
+ * @throws {Error} If metadata does not contain a valid bounded asset.
+ */
 export async function getCogAssetEntry(container, header, asset) {
   const metadata = JSON.parse(/* alloc */ new TextDecoder().decode(await decompress(
     await readCog(container, header.jsonMetadataOffset, header.jsonMetadataLength), header.internalCompression)));

package/src/cog/getCogBase.js

@@ -1,6 +1,18 @@
 import { hasCogProjection } from './hasCogProjection.js';
 import { validCogGeoArrays } from './validCogGeoArrays.js';
 
+/**
+ * Extract the base image's north-up Web Mercator georeferencing.
+ *
+ * @param {Map} tags TIFF tags.
+ * @param {number} width Base image width.
+ * @param {number} height Base image height.
+ * @param {boolean} elevation Whether the image stores elevation.
+ *
+ * @returns {Object} Base dimensions, resolution, origin and elevation flag.
+ *
+ * @throws {Error} If georeferencing is not north-up EPSG:3857 PixelIsArea.
+ */
 export function getCogBase(tags, width, height, elevation) {
   const keys = tags.get(34735), scale = tags.get(33550), tie = tags.get(33922);
   if (!validCogGeoArrays(keys, scale, tie) || !hasCogProjection(keys)) {

package/src/cog/getCogHeader.js

@@ -1,3 +1,10 @@
+/**
+ * Return the synthesized archive header for a COG source.
+ *
+ * @param {Object} source Open COG source.
+ *
+ * @returns {Object} Source header.
+ */
 export function getCogHeader(source) {
   return source.header;
 }

package/src/cog/getCogProfile.js

@@ -1,6 +1,15 @@
 import { validCogDimensions } from './validCogDimensions.js';
 import { validCogEncoding } from './validCogEncoding.js';
 
+/**
+ * Extract and validate a supported tiled color or elevation TIFF profile.
+ *
+ * @param {Map} tags TIFF tags.
+ *
+ * @returns {Object} Image dimensions, sample count and elevation flag.
+ *
+ * @throws {Error} If the TIFF dimensions or encoding are unsupported.
+ */
 export function getCogProfile(tags) {
   const width = tags.get(256)?.[0], height = tags.get(257)?.[0], samples = tags.get(277)?.[0] ?? 1;
   const bits = tags.get(258), format = tags.get(339) || /* alloc */ [1];

package/src/cog/getCogTile.js

@@ -2,6 +2,19 @@ import { getElevationTile } from './getElevationTile.js';
 import { getColorTile } from './getColorTile.js';
 import { validCogTileCoordinates } from './validCogTileCoordinates.js';
 
+/**
+ * Read an XYZ color or elevation tile from an open COG, if covered by a level.
+ *
+ * @param {Object} source Open COG source.
+ * @param {number} z Tile zoom.
+ * @param {number} x Tile column.
+ * @param {number} y Tile row.
+ * @param {AbortSignal} [signal] Request cancellation signal.
+ *
+ * @returns {Promise<Object|undefined>} Tile image or elevation data, if covered.
+ *
+ * @throws {Error} If tile coordinates are invalid.
+ */
 export async function getCogTile(source, z, x, y, signal) {
   signal?.throwIfAborted();
   if (!validCogTileCoordinates(z, x, y)) throw /* alloc */ new Error('Invalid COG tile coordinates');

package/src/cog/getColorTile.js

@@ -1,5 +1,18 @@
 import { readCogBlock } from './readCogBlock.js';
 
+/**
+ * Composite the COG color blocks overlapping an XYZ tile into an image bitmap.
+ *
+ * @param {Object} source Open COG source.
+ * @param {Object} level COG overview level.
+ * @param {number} x XYZ tile column.
+ * @param {number} y XYZ tile row.
+ * @param {AbortSignal} [signal] Request cancellation signal.
+ *
+ * @returns {Promise<Object>} Object containing the resulting image bitmap.
+ *
+ * @throws {Error} If a 2D canvas context cannot be created.
+ */
 export async function getColorTile(source, level, x, y, signal) {
   const canvas = /* alloc */ new OffscreenCanvas(256, 256), context = canvas.getContext('2d');
   if (!context) throw /* alloc */ new Error('Unable to create COG tile canvas');

package/src/cog/getElevationTile.js

@@ -1,5 +1,18 @@
 import { readCogBlock } from './readCogBlock.js';
 
+/**
+ * Read and validate the Float32 elevation samples for an XYZ tile.
+ *
+ * @param {Object} source Open COG source.
+ * @param {Object} level COG elevation level.
+ * @param {number} x XYZ tile column.
+ * @param {number} y XYZ tile row.
+ * @param {AbortSignal} [signal] Request cancellation signal.
+ *
+ * @returns {Promise<Object>} Object containing the elevation buffer.
+ *
+ * @throws {Error} If an elevation sample is non-finite or outside the supported range.
+ */
 export async function getElevationTile(source, level, x, y, signal) {
   const data = await readCogBlock(source, level, x - level.x, y - level.y, signal);
   signal?.throwIfAborted();

package/src/cog/hasCogProjection.js

@@ -1,3 +1,10 @@
+/**
+ * Check GeoTIFF keys for EPSG:3857 and PixelIsArea.
+ *
+ * @param {ArrayLike<number>} keys GeoKey directory values, if present.
+ *
+ * @returns {boolean} Whether both required keys are present.
+ */
 export function hasCogProjection(keys) {
   let projected = false, area = false, i;
   if (keys) for (i = 4; i < keys.length; i += 4) {

package/src/cog/initCog.js

@@ -1,6 +1,12 @@
 import { initRaster } from '../raster/initRaster.js';
 import { openCogInWorker } from '../workers/openCogInWorker.js';
 
+/**
+ * Initialize a raster layer backed by a COG archive or a worker-opened COG source.
+ *
+ * @param {L.Layer} layer Raster layer to initialize.
+ * @param {Object} options Layer and COG source options.
+ */
 export function initCog(layer, options) {
   initRaster(layer, /* alloc */ { ariaLabel: 'COG raster', ...options,
     archive: options.archive || openCogInWorker(layer, options) });

package/src/cog/invalidCogFullResponse.js

@@ -1,3 +1,10 @@
+/**
+ * Check whether a non-range COG response has an unsupported status or declared size.
+ *
+ * @param {Response} response HTTP response.
+ *
+ * @returns {boolean} Whether the full response is unacceptable.
+ */
 export function invalidCogFullResponse(response) {
   return response.status !== 200 || Number(response.headers.get('Content-Length')) > 32000000;
 }

package/src/cog/openCog.js

@@ -4,7 +4,17 @@ import { getCogTile } from './getCogTile.js';
 import { getCogHeader } from './getCogHeader.js';
 import { openCogAsset } from './openCogAsset.js';
 
-/** EPSG:3857 COGs, standalone or named assets in a PMTiles container. */
+/**
+ * Open an EPSG:3857 COG, standalone or as a named asset in a PMTiles container.
+ *
+ * @param {string} url COG or container URL.
+ * @param {string} [asset] Named COG asset in the container.
+ *
+ * @returns {Promise<Object>} Archive-compatible header and XYZ tile methods.
+ *
+ * @throws {Error} If TIFF byte order is invalid.
+ * @throws {Error} If the file is not classic TIFF.
+ */
 export async function openCog(url, asset) {
   const source = asset === undefined ? /* alloc */ { url } : await openCogAsset(url, asset);
   source.levels = /* alloc */ new Map();

package/src/cog/openCogAsset.js

@@ -3,6 +3,14 @@ import { readCog } from './readCog.js';
 import { validateCogContainer } from './validateCogContainer.js';
 import { getCogAssetEntry } from './getCogAssetEntry.js';
 
+/**
+ * Open a named COG asset within a PMTiles container as a bounded byte source.
+ *
+ * @param {string} url Container URL.
+ * @param {string} asset Asset name.
+ *
+ * @returns {Promise<Object>} COG source with container offset and size.
+ */
 export async function openCogAsset(url, asset) {
   const container = /* alloc */ { url };
   const header = decodeHeader(await readCog(container, 0, 127));

package/src/cog/readCog.js

@@ -2,6 +2,20 @@ import { validateCogRange } from './validateCogRange.js';
 import { validateCogResponse } from './validateCogResponse.js';
 import { readCogBody } from './readCogBody.js';
 
+/**
+ * Read a validated byte range from a COG source, caching an accepted full response.
+ *
+ * @param {Object} source COG byte source and response state.
+ * @param {number} offset Byte offset relative to the source.
+ * @param {number} length Number of bytes to read.
+ * @param {AbortSignal} [signal] Request cancellation signal.
+ *
+ * @returns {Promise<ArrayBuffer>} Requested bytes.
+ *
+ * @throws {Error} If the HTTP response is unsuccessful.
+ * @throws {Error} If a full PMTiles container response is truncated.
+ * @throws {Error} If the resulting byte range is truncated.
+ */
 export async function readCog(source, offset, length, signal) {
   signal?.throwIfAborted();
   validateCogRange(source, offset, length);

package/src/cog/readCogBlock.js

@@ -1,6 +1,17 @@
 import { readCog } from './readCog.js';
 import { decodeCogTile } from './decodeCogTile.js';
 
+/**
+ * Read and decode one TIFF tile block from a COG level.
+ *
+ * @param {Object} source Open COG byte source.
+ * @param {Object} level COG level with block offsets and lengths.
+ * @param {number} x Block column within the level.
+ * @param {number} y Block row within the level.
+ * @param {AbortSignal} [signal] Request cancellation signal.
+ *
+ * @returns {Promise<ArrayBuffer>} Decoded block data.
+ */
 export async function readCogBlock(source, level, x, y, signal) {
   const index = y * level.columns + x;
   return decodeCogTile(await readCog(source, level.offsets[index], level.lengths[index], signal),

package/src/cog/readCogBody.js

@@ -1,3 +1,13 @@
+/**
+ * Read a COG HTTP body while enforcing the range or full-response size limit.
+ *
+ * @param {Response} response HTTP response with a readable body.
+ * @param {number} length Expected byte length for a range response.
+ *
+ * @returns {Promise<Uint8Array>} Response bytes.
+ *
+ * @throws {Error} If the response exceeds its permitted size.
+ */
 export async function readCogBody(response, length) {
   const reader = response.body.getReader(), chunks = /* alloc */ [];
   let total = 0, part;

package/src/cog/readCogDirectories.js

@@ -1,6 +1,18 @@
 import { readCogDirectory } from './readCogDirectory.js';
 import { readCogLevel } from './readCogLevel.js';
 
+/**
+ * Read TIFF image directories and register contiguous COG zoom levels.
+ *
+ * @param {Object} source Open COG byte source.
+ * @param {number} offset First TIFF directory offset.
+ *
+ * @returns {Promise<Object>} Base image and minimum and maximum zoom.
+ *
+ * @throws {Error} If directories are cyclic or exceed the supported count.
+ * @throws {Error} If there is no image directory.
+ * @throws {Error} If overview zoom levels are not contiguous.
+ */
 export async function readCogDirectories(source, offset) {
   const state = /* alloc */ { base: null, minZoom: Infinity, maxZoom: -Infinity };
   const seen = /* alloc */ new Set();

package/src/cog/readCogDirectory.js

@@ -2,6 +2,19 @@ import { readCog } from './readCog.js';
 import { cogTags } from '../globals/cogTags.js';
 import { readCogTag } from './readCogTag.js';
 
+/**
+ * Read supported TIFF tags from one image directory.
+ *
+ * @param {Object} source Open COG byte source.
+ * @param {number} offset Directory byte offset.
+ *
+ * @returns {Promise<Object>} Tag map and next directory offset.
+ *
+ * @throws {Error} If the directory size is invalid.
+ * @throws {Error} If a nodata tag is present.
+ * @throws {Error} If an affine transformation tag is present.
+ * @throws {Error} If a supported tag is duplicated.
+ */
 export async function readCogDirectory(source, offset) {
   const little = source.little;
   const count = /* alloc */ new DataView(await readCog(source, offset, 2)).getUint16(0, little);

package/src/cog/readCogLevel.js

@@ -3,6 +3,15 @@ import { getCogBase } from './getCogBase.js';
 import { validCogGrid } from './validCogGrid.js';
 import { validateCogOffsets } from './validateCogOffsets.js';
 
+/**
+ * Validate and register one TIFF directory as a COG XYZ level.
+ *
+ * @param {Object} source Open COG source and level map.
+ * @param {Object} directory TIFF directory with parsed tags.
+ * @param {Object} state Mutable base image and zoom range.
+ *
+ * @throws {Error} If the level does not align with the supported Web Mercator grid.
+ */
 export function readCogLevel(source, directory, state) {
   const tags = directory.tags, profile = getCogProfile(tags);
   if (!state.base) state.base = getCogBase(tags, profile.width, profile.height, profile.elevation);

package/src/cog/readCogTag.js

@@ -1,5 +1,18 @@
 import { readCog } from './readCog.js';
 
+/**
+ * Read the numeric values of a supported TIFF directory entry.
+ *
+ * @param {Object} source Open COG byte source.
+ * @param {DataView} entries Directory entry data.
+ * @param {number} i Entry index.
+ * @param {number} tag TIFF tag number.
+ * @param {boolean} little Whether the TIFF uses little-endian byte order.
+ *
+ * @returns {Promise<Array<number>>} Decoded tag values.
+ *
+ * @throws {Error} If the tag type or value count is unsupported.
+ */
 export async function readCogTag(source, entries, i, tag, little) {
   const type = entries.getUint16(i * 12 + 2, little);
   const size = type === 3 ? 2 : type === 4 ? 4 : type === 12 ? 8 : 0;