{"_id":"@amjed-ali-k-2/maplibre-cog-protocol","_rev":"5-7e8e7c633a81a447487b0c8935bb6812","name":"@amjed-ali-k-2/maplibre-cog-protocol","dist-tags":{"latest":"0.11.1"},"versions":{"0.9.1":{"name":"@amjed-ali-k-2/maplibre-cog-protocol","version":"0.9.1","author":{"name":"Geomatico","email":"info@geomatico.es"},"license":"MIT","_id":"@amjed-ali-k-2/maplibre-cog-protocol@0.9.1","maintainers":[{"name":"amjed-ali-k-2","email":"amjed.mgm@gmail.com"}],"dist":{"shasum":"8db28606b6d71aa58f5bbe811b652146f472f793","tarball":"https://registry.npmjs.org/@amjed-ali-k-2/maplibre-cog-protocol/-/maplibre-cog-protocol-0.9.1.tgz","fileCount":35,"integrity":"sha512-8ebKOfKBainzOowWKvdEmLGT+GXj36Lj8iTuFUu7aUsZeyAGfGT+e3ev1F1hxMUu6REde0XZ9iHQWeew45u0vQ==","signatures":[{"sig":"MEQCIAWMPA+J2L4/ugGKdr0nqOcWXTidw//USxL9we59S5yBAiBTQ/XMj3y4FjxFeV8ig0Us0/TSE3HicF9tcDiEYmffWQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1453519},"main":"./dist/index.js","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","browser":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"389a26d68d4ac8fd2fe312403d52d905d89f76ef","scripts":{"lint":"eslint --max-warnings 0 --fix src/","test":"jest --coverage --verbose --runInBand","build":"npm run lint && npm run test && rimraf dist && concurrently --names 'UMD,ESM,TYPES' 'npm run build:umd' 'npm run build:esm' 'npm run build:types'","watch":"concurrently --names 'SRC,EXAMPLES' --prefix-colors 'yellow,blue' --kill-others 'npm run watch:src' 'npm run watch:examples'","test:ci":"jest --runInBand --coverage --verbose","build:esm":"tsc --outDir dist/esm","build:umd":"rollup -c rollup.config.mjs","watch:src":"rimraf dist && rollup -c rollup.config.mjs --environment DEV --watch","gh-publish":"rimraf examples/dist && npm run build && cp -r dist examples && gh-pages -d examples","build:types":"tsc --declaration --emitDeclarationOnly --outDir dist/types","watch:examples":"five-server"},"_npmUser":{"name":"amjed-ali-k-2","email":"amjed.mgm@gmail.com"},"_npmVersion":"10.9.3","description":"Custom protocol to load Cloud Optimized GeoTIFFs (COG) in Maplibre GL JS","directories":{},"_nodeVersion":"22.20.0","dependencies":{"geotiff":"^2.1.3","d3-scale":"^4.0.2","quick-lru":"^7.1.0","@mapbox/sphericalmercator":"^1.2.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.1.3","tslib":"^2.6.3","eslint":"^9.35.0","rimraf":"^6.0.1","rollup":"^4.27.3","globals":"^16.4.0","ts-jest":"^29.2.2","gh-pages":"^6.1.1","@eslint/js":"^9.7.0","typescript":"^5.5.3","@types/jest":"^30.0.0","five-server":"^0.4.4","concurrently":"^9.2.1","@types/d3-scale":"^4.0.8","typescript-eslint":"^8.44.0","eslint-plugin-jest":"^29.0.1","@rollup/plugin-terser":"^0.4.4","@rollup/plugin-commonjs":"^28.0.6","@rollup/plugin-typescript":"^12.1.4","@typescript-eslint/parser":"^8.44.0","@rollup/plugin-node-resolve":"^16.0.1","@types/mapbox__sphericalmercator":"^1.2.3","@typescript-eslint/eslint-plugin":"^8.44.0"},"peerDependencies":{"maplibre-gl":"^4.5.0 || ^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/maplibre-cog-protocol_0.9.1_1767104177258_0.893278060744102","host":"s3://npm-registry-packages-npm-production"}},"0.10.0":{"name":"@amjed-ali-k-2/maplibre-cog-protocol","version":"0.10.0","author":{"name":"Geomatico","email":"info@geomatico.es"},"license":"MIT","_id":"@amjed-ali-k-2/maplibre-cog-protocol@0.10.0","maintainers":[{"name":"amjed-ali-k-2","email":"amjed.mgm@gmail.com"}],"contributors":[{"name":"Amjed Ali","email":"sw-dev@skymul.com"}],"homepage":"https://github.com/amjed-ali-k/maplibre-cog-protocol#readme","bugs":{"url":"https://github.com/amjed-ali-k/maplibre-cog-protocol/issues"},"dist":{"shasum":"a2689a7fbf7010d3204849ca01694f68e8264a8b","tarball":"https://registry.npmjs.org/@amjed-ali-k-2/maplibre-cog-protocol/-/maplibre-cog-protocol-0.10.0.tgz","fileCount":37,"integrity":"sha512-rladEeMJfXwSgdv60jVPxdF0WP45cTfWrf/5Wj86fnKck86GCe8JkzJ3lQgI6m390YLnAon9cawGsu78Fk+SNQ==","signatures":[{"sig":"MEUCIAheOeG/oSE6lT8qB4YTgO6qPFDD+B5PiwN9W/3Vp9qIAiEAsrcYNHcWfyvhbC6hrFBQ8ZFbyxjW1GDx+TQb0Yh3FGI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2125591},"main":"./dist/index.js","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","browser":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"75455afe774994ef5c8652ae8cc6f08fd1201967","scripts":{"lint":"biome check --write src/","test":"npm run lint && vitest run --reporter=default --reporter=junit --outputFile=junit.xml --coverage","build":"rimraf dist && concurrently --names 'UMD,ESM,TYPES' 'npm run build:umd' 'npm run build:esm' 'npm run build:types'","watch":"concurrently --names 'SRC,EXAMPLES' --prefix-colors 'yellow,blue' --kill-others 'npm run watch:src' 'npm run watch:examples'","prepare":"husky","build:esm":"tsc --outDir dist/esm","build:umd":"rollup -c rollup.config.mjs","watch:src":"rimraf dist && rollup -c rollup.config.mjs --environment DEV --watch","gh-publish":"rimraf examples/dist && npm run build && cp -r dist examples && gh-pages -d examples","build:types":"tsc --declaration --emitDeclarationOnly --outDir dist/types","postversion":"git push --follow-tags","watch:examples":"five-server"},"_npmUser":{"name":"amjed-ali-k-2","email":"amjed.mgm@gmail.com"},"overrides":{"@emnapi/core":"^1.10.0","@emnapi/runtime":"^1.10.0"},"repository":{"url":"git+https://github.com/amjed-ali-k/maplibre-cog-protocol.git","type":"git"},"_npmVersion":"11.11.0","description":"Custom protocol to load Cloud Optimized GeoTIFFs (COG) in Maplibre GL JS","directories":{},"_nodeVersion":"24.14.1","dependencies":{"geotiff":"^3.0.5","d3-scale":"^4.0.2","quick-lru":"^7.1.0","@mapbox/sphericalmercator":"^2.0.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"husky":"^9.1.7","rimraf":"^6.0.1","rollup":"^4.27.3","vitest":"^4.1.7","gh-pages":"^6.1.1","typescript":"^6.0.3","five-server":"^0.5.0","concurrently":"^10.0.0","@biomejs/biome":"^2.4.16","@types/d3-scale":"^4.0.8","@vitest/coverage-v8":"^4.1.7","@rollup/plugin-terser":"^1.0.0","@rollup/plugin-commonjs":"^29.0.2","@rollup/plugin-typescript":"^12.1.4","@rollup/plugin-node-resolve":"^16.0.1"},"peerDependencies":{"maplibre-gl":"^4.5.0 || ^5.0.0 || ^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/maplibre-cog-protocol_0.10.0_1787075906731_0.03654436310046294","host":"s3://npm-registry-packages-npm-production"}},"0.11.0":{"name":"@amjed-ali-k-2/maplibre-cog-protocol","version":"0.11.0","author":{"name":"Geomatico","email":"info@geomatico.es"},"license":"MIT","_id":"@amjed-ali-k-2/maplibre-cog-protocol@0.11.0","maintainers":[{"name":"amjed-ali-k-2","email":"amjed.mgm@gmail.com"}],"contributors":[{"name":"Amjed Ali","email":"sw-dev@skymul.com"}],"homepage":"https://github.com/amjed-ali-k/maplibre-cog-protocol#readme","bugs":{"url":"https://github.com/amjed-ali-k/maplibre-cog-protocol/issues"},"dist":{"shasum":"fac24963a83498dd4ab65849f098270026f038e8","tarball":"https://registry.npmjs.org/@amjed-ali-k-2/maplibre-cog-protocol/-/maplibre-cog-protocol-0.11.0.tgz","fileCount":3,"integrity":"sha512-sUOYohBJrPoO3jHD3Vq5bnADAvD8TYAE2kgy4P/D33/zNPByb0/i23dMRA5f6+5K2UvzK256GoylUy9YrfjNEg==","signatures":[{"sig":"MEUCIA54NqiU3fBbrzQ1nLuiXcjjil8WK8NXCBMJ7RkBnxo/AiEA8T7s14d9ZRmtTxQHv4deSK/jJ/o8IWQHxdiqI+d+4Jc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":34094},"main":"./dist/index.js","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","browser":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"3b6f06543a99a234ac866ef3d041fac3caf300ce","scripts":{"lint":"biome check --write src/","test":"npm run lint && vitest run --reporter=default --reporter=junit --outputFile=junit.xml --coverage","build":"rimraf dist && concurrently --names 'UMD,ESM,TYPES' 'npm run build:umd' 'npm run build:esm' 'npm run build:types'","watch":"concurrently --names 'SRC,EXAMPLES' --prefix-colors 'yellow,blue' --kill-others 'npm run watch:src' 'npm run watch:examples'","prepare":"husky","build:esm":"tsc --outDir dist/esm","build:umd":"rollup -c rollup.config.mjs","watch:src":"rimraf dist && rollup -c rollup.config.mjs --environment DEV --watch","gh-publish":"rimraf examples/dist && npm run build && cp -r dist examples && gh-pages -d examples","build:types":"tsc --declaration --emitDeclarationOnly --outDir dist/types","postversion":"git push --follow-tags","watch:examples":"five-server"},"_npmUser":{"name":"amjed-ali-k-2","email":"amjed.mgm@gmail.com"},"overrides":{"@emnapi/core":"^1.10.0","@emnapi/runtime":"^1.10.0"},"repository":{"url":"git+https://github.com/amjed-ali-k/maplibre-cog-protocol.git","type":"git"},"_npmVersion":"11.11.0","description":"Custom protocol to load Cloud Optimized GeoTIFFs (COG) in Maplibre GL JS","directories":{},"_nodeVersion":"24.14.1","dependencies":{"geotiff":"^3.0.5","d3-scale":"^4.0.2","quick-lru":"^7.1.0","@mapbox/sphericalmercator":"^2.0.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"husky":"^9.1.7","rimraf":"^6.0.1","rollup":"^4.27.3","vitest":"^4.1.7","gh-pages":"^6.1.1","typescript":"^6.0.3","five-server":"^0.5.0","concurrently":"^10.0.0","@biomejs/biome":"^2.4.16","@types/d3-scale":"^4.0.8","@vitest/coverage-v8":"^4.1.7","@rollup/plugin-terser":"^1.0.0","@rollup/plugin-commonjs":"^29.0.2","@rollup/plugin-typescript":"^12.1.4","@rollup/plugin-node-resolve":"^16.0.1"},"peerDependencies":{"maplibre-gl":"^4.5.0 || ^5.0.0 || ^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/maplibre-cog-protocol_0.11.0_1787283791866_0.9133620706292256","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Published without dist/ — use 0.11.1"},"0.11.1":{"name":"@amjed-ali-k-2/maplibre-cog-protocol","version":"0.11.1","author":{"name":"Geomatico","email":"info@geomatico.es"},"license":"MIT","_id":"@amjed-ali-k-2/maplibre-cog-protocol@0.11.1","maintainers":[{"name":"amjed-ali-k-2","email":"amjed.mgm@gmail.com"}],"contributors":[{"name":"Amjed Ali","email":"sw-dev@skymul.com"}],"homepage":"https://github.com/amjed-ali-k/maplibre-cog-protocol#readme","bugs":{"url":"https://github.com/amjed-ali-k/maplibre-cog-protocol/issues"},"dist":{"shasum":"c17444af142c4b8fcc12e21a7a96469189faf6b5","tarball":"https://registry.npmjs.org/@amjed-ali-k-2/maplibre-cog-protocol/-/maplibre-cog-protocol-0.11.1.tgz","fileCount":39,"integrity":"sha512-iJGyAudhpSMg5jyKX7vAEPEIszdyxBDnrBAO9BAdAAIY1PFJEpRB6olCfE3dXPW+MyhnIEiIwtBewllarmJKtw==","signatures":[{"sig":"MEYCIQDvT8ASjxo6VwSiLasPIq2dA6IcV0BzXJdxGbgKenBQvgIhANQvEZcpzLOYj2tiG7XoiernpwCMDwXHNrPn3UXAFyIP","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2147953},"main":"./dist/index.js","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","browser":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"29aa6448f8501f102858e639fee0fcf7a22a1c14","scripts":{"lint":"biome check --write src/","test":"npm run lint && vitest run --reporter=default --reporter=junit --outputFile=junit.xml --coverage","build":"rimraf dist && concurrently --names \"UMD,ESM,TYPES\" \"npm run build:umd\" \"npm run build:esm\" \"npm run build:types\"","watch":"concurrently --names 'SRC,EXAMPLES' --prefix-colors 'yellow,blue' --kill-others 'npm run watch:src' 'npm run watch:examples'","prepare":"husky","build:esm":"tsc --outDir dist/esm","build:umd":"rollup -c rollup.config.mjs","watch:src":"rimraf dist && rollup -c rollup.config.mjs --environment DEV --watch","gh-publish":"rimraf examples/dist && npm run build && cp -r dist examples && gh-pages -d examples","build:types":"tsc --declaration --emitDeclarationOnly --outDir dist/types","postversion":"git push --follow-tags","prepublishOnly":"npm run build","watch:examples":"five-server"},"_npmUser":{"name":"amjed-ali-k-2","email":"amjed.mgm@gmail.com"},"overrides":{"@emnapi/core":"^1.10.0","@emnapi/runtime":"^1.10.0"},"repository":{"url":"git+https://github.com/amjed-ali-k/maplibre-cog-protocol.git","type":"git"},"_npmVersion":"11.11.0","description":"Custom protocol to load Cloud Optimized GeoTIFFs (COG) in Maplibre GL JS","directories":{},"_nodeVersion":"24.14.1","dependencies":{"geotiff":"^3.0.5","d3-scale":"^4.0.2","quick-lru":"^7.1.0","@mapbox/sphericalmercator":"^2.0.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"husky":"^9.1.7","rimraf":"^6.0.1","rollup":"^4.27.3","vitest":"^4.1.7","gh-pages":"^6.1.1","typescript":"^6.0.3","five-server":"^0.5.0","concurrently":"^10.0.0","@biomejs/biome":"^2.4.16","@types/d3-scale":"^4.0.8","@vitest/coverage-v8":"^4.1.7","@rollup/plugin-terser":"^1.0.0","@rollup/plugin-commonjs":"^29.0.2","@rollup/plugin-typescript":"^12.1.4","@rollup/plugin-node-resolve":"^16.0.1"},"peerDependencies":{"maplibre-gl":"^4.5.0 || ^5.0.0 || ^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/maplibre-cog-protocol_0.11.1_1787284016651_0.6909101127127231","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-12-30T14:16:17.119Z","modified":"2026-08-21T03:47:20.933Z","0.9.1":"2025-12-30T14:16:17.426Z","0.10.0":"2026-08-18T17:58:26.962Z","0.11.0":"2026-08-21T03:43:12.020Z","0.11.1":"2026-08-21T03:46:56.824Z"},"bugs":{"url":"https://github.com/amjed-ali-k/maplibre-cog-protocol/issues"},"author":{"name":"Geomatico","email":"info@geomatico.es"},"license":"MIT","homepage":"https://github.com/amjed-ali-k/maplibre-cog-protocol#readme","repository":{"url":"git+https://github.com/amjed-ali-k/maplibre-cog-protocol.git","type":"git"},"description":"Custom protocol to load Cloud Optimized GeoTIFFs (COG) in Maplibre GL JS","contributors":[{"name":"Amjed Ali","email":"sw-dev@skymul.com"}],"maintainers":[{"name":"amjed-ali-k-2","email":"amjed.mgm@gmail.com"}],"readme":"# MapLibre COG Protocol — Display Cloud Optimized GeoTIFFs in MapLibre GL JS\r\n\r\n> **Note:** this package (`@amjed-ali-k-2/maplibre-cog-protocol`) is a fork of\r\n> [geomatico/maplibre-cog-protocol](https://github.com/geomatico/maplibre-cog-protocol), kept in\r\n> sync with upstream. See [What this fork adds](#what-this-fork-adds).\r\n\r\n**MapLibre COG Protocol** is an open source JavaScript library for loading and visualizing\r\n[Cloud Optimized GeoTIFFs](https://cogeo.org/) directly in [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/).\r\n\r\nIt adds a custom `cog://` protocol that lets MapLibre applications display large raster datasets\r\nstraight from cloud storage using HTTP range requests, without a traditional raster tile server in\r\nbetween. Only the parts of the file needed by the current map view are fetched and decoded, in the\r\nbrowser, using [geotiff.js](https://geotiffjs.github.io/).\r\n\r\nThe library renders RGB and grayscale imagery, digital elevation models, 3D terrain and hillshading,\r\nand applies color ramps to single-band rasters. It also lets you write your own per-pixel coloring\r\nfunctions, so the bands of a multispectral satellite image can be combined in the browser to derive\r\nindicators such as NDVI on the fly, with no preprocessing and no derived files to store.\r\n\r\n\r\n## Why use MapLibre COG Protocol?\r\n\r\nTraditional web raster architectures require preprocessing your data into tiles and running a\r\ndedicated tile server to publish them. Cloud Optimized GeoTIFFs remove that step: the file itself is\r\norganized so a client can request just the byte ranges it needs. This library brings that serverless\r\nraster workflow to MapLibre GL JS, which helps you:\r\n\r\n* Publish large rasters from plain object storage (S3, GCS, Azure Blob, or any HTTP server supporting range requests).\r\n* Cut raster infrastructure, preprocessing and hosting costs.\r\n* Display multi-gigabyte GeoTIFFs in the browser without downloading them whole.\r\n* Visualize satellite imagery, elevation models and other scientific rasters.\r\n* Apply color ramps and band arithmetic client-side, with no server round trip.\r\n* Derive indices from multispectral imagery on the fly, instead of precomputing and storing a raster per index.\r\n* Change the formula, thresholds or palette of an indicator without regenerating any data.\r\n* Keep control of your stack with open source geospatial software.\r\n\r\n\r\n## Main features\r\n\r\n* Direct COG visualization in MapLibre GL JS, via a `cog://` URL prefix.\r\n* Imagery rendering driven by the COG's own `PhotometricInterpretation`: RGB, grayscale, paletted, CMYK, YCbCr and CIELab.\r\n* Digital elevation model visualization, as hillshading or 3D terrain.\r\n* ColorBrewer and CARTOColors color ramps for single-band rasters, continuous or discrete.\r\n* Custom per-pixel coloring functions, with full access to every band of the pixel.\r\n* Band arithmetic on multispectral rasters, to compute and symbolize indices such as NDVI in the browser.\r\n* Masking with GeoJSON polygons, and support for the COG's internal mask band.\r\n* Raster metadata access, and pixel value queries at any location, with or without a map.\r\n* Custom HTTP request headers, for COGs behind authentication.\r\n* Works with vanilla JavaScript and with React Map GL.\r\n\r\n\r\n## Typical use cases\r\n\r\n* Satellite and aerial imagery viewers.\r\n* Remote sensing analysis on multispectral imagery, computing indices such as NDVI, NDWI or NDBI directly in the map.\r\n* Environmental and climate monitoring applications.\r\n* Digital elevation models and terrain visualization.\r\n* Precision agriculture and vegetation index maps.\r\n* Multitemporal raster animation.\r\n* Serverless geospatial data portals, and large scale raster publication without a map server.\r\n\r\n\r\n## Live examples\r\n\r\nInteractive demos covering RGB imagery, color ramps, NDVI on a multiband Sentinel-2 image, GeoJSON\r\nmasking, and a 12 GB digital elevation model covering Catalonia at 2 m/pixel:\r\n\r\n* [MapLibre COG Protocol demo page](https://labs.geomatico.es/maplibre-cog-protocol/) — all the examples in this repository, running live.\r\n* [Advanced sample viewer](https://labs.geomatico.es/maplibre-cog-protocol-examples/) — load and inspect your own COG URLs.\r\n* [Serverless rasters in MapLibre: the COG protocol extension](https://geomatico.es/en/serverless-rasters-in-maplibre-the-cog-protocol-extension/) — article explaining the approach and why we built it.\r\n\r\n\r\n## What this fork adds\r\n\r\n`@amjed-ali-k-2/maplibre-cog-protocol` tracks\r\n[geomatico/maplibre-cog-protocol](https://github.com/geomatico/maplibre-cog-protocol) and is merged\r\nwith upstream as it releases. Everything upstream does works here unchanged; the differences are:\r\n\r\n* **Transparent out-of-range values** — the `t` modifier on `#color:` makes values outside the\r\n  `min`/`max` range transparent instead of clamping them to the end colors of the ramp. See\r\n  [Apply ColorBrewer or CARTOColor ramp to a single-band COG](#apply-colorbrewer-or-cartocolor-ramp-to-a-single-band-cog).\r\n\r\n* **Opt-in decoded-tile cache** — [`configureTileCache`](#cache-decoded-source-tiles). A COG's\r\n  overview levels are rarely aligned with the web mercator tile grid, so one 256×256 map tile\r\n  straddles several source tiles and neighbouring map tiles keep re-decoding the same ones. Measured\r\n  over a full-extent pan, that costs 3.69 decodes per map tile on a Float32 DSM at z20 and 1.78 on\r\n  an 8-bit RGB ortho; with the cache enabled it drops to 1.00 and 0.17. Decoding is the expensive\r\n  part — in the browser each one is a `Blob` → `createImageBitmap` → `drawImage` → `getImageData`\r\n  round trip — and caching bytes does not help, because `geotiff.js` already coalesces the byte\r\n  ranges into a handful of requests. Off by default, so enabling it is your call.\r\n\r\n* **Transient read failures recover** — the caches store the in-flight promise so concurrent callers\r\n  share one request. Upstream keeps that promise even when it rejects, so a single reset connection\r\n  leaves that tile blank for the full hour the cache entry lives, and retrying returns the same\r\n  cached rejection. Here a rejected entry is dropped, so the next request re-reads.\r\n\r\nVersions follow this fork's own release history and do not line up with upstream's.\r\n\r\n\r\n## Installation\r\n\r\n```shell\r\nnpm install @amjed-ali-k-2/maplibre-cog-protocol\r\n```\r\n\r\nOr load it from a CDN with a `<script>` tag, pinned to a version:\r\n\r\n```html\r\n<script src=\"https://unpkg.com/@amjed-ali-k-2/maplibre-cog-protocol@0.11.0/dist/index.js\"></script>\r\n```\r\n\r\nDropping `@0.11.0` always serves the latest release, which is convenient for a quick try but means\r\nyour page changes when the package does. The [vanilla HTML example](#vanilla-html--js) below uses\r\nthe unpinned form for brevity.\r\n\r\n\r\n## Requirements\r\n\r\n* MapLibre GL JS `^4.5.0`, `^5.0.0` or `^6.0.0` (peer dependency), except for `locationValues` and `getCogMetadata`, which work standalone. Note that MapLibre 6 dropped its UMD build, so it has to be loaded as an ES module, as in the example below.\r\n* COGs **must** be in EPSG:3857 (Web Mercator). This library does not reproject; reading a COG in any other projection throws an error. See [COG generation tips](#cog-generation-tips).\r\n\r\n## Usage\r\n\r\nFor better quality, use always `tileSize: 256` to match the size of tiles delivered by the custom protocol.\r\n\r\n### Vanilla HTML & JS\r\n\r\n```html\r\n<!DOCTYPE html>\r\n<html lang=\"en\">\r\n<head>\r\n  <link rel=\"stylesheet\" href=\"https://unpkg.com/maplibre-gl@^6.0.0/dist/maplibre-gl.css\">\r\n  <script src=\"https://unpkg.com/@amjed-ali-k-2/maplibre-cog-protocol/dist/index.js\"></script>\r\n</head>\r\n<body>\r\n<div id=\"map\" style=\"width: 600px; height: 400px\"></div>\r\n<script type=\"module\">\r\n  import * as maplibregl from 'https://unpkg.com/maplibre-gl@^6.0.0/dist/maplibre-gl.mjs';\r\n\r\n  let map = new maplibregl.Map({\r\n    container: 'map',\r\n    style: 'https://geoserveis.icgc.cat/contextmaps/icgc_mapa_base_gris_simplificat.json',\r\n    center: [1.83369, 41.5937],\r\n    zoom: 14\r\n  });\r\n\r\n  maplibregl.addProtocol('cog', MaplibreCOGProtocol.cogProtocol);\r\n\r\n  map.on('load', () => {\r\n    map.addSource('imageSource', {\r\n      type: 'raster',\r\n      url: 'cog://https://labs.geomatico.es/maplibre-cog-protocol/data/image.tif',\r\n      tileSize: 256\r\n    });\r\n\r\n    map.addLayer({\r\n      id: 'imageLayer',\r\n      source: 'imageSource',\r\n      type: 'raster'\r\n    });\r\n  });\r\n</script>\r\n</body>\r\n</html>\r\n```\r\n\r\n### With React Map GL\r\n\r\n`npm install @amjed-ali-k-2/maplibre-cog-protocol`\r\n\r\n```tsx\r\nimport maplibregl from 'maplibre-gl';\r\nimport {cogProtocol} from '@amjed-ali-k-2/maplibre-cog-protocol';\r\nimport Map from 'react-map-gl/maplibre';\r\n\r\nmaplibregl.addProtocol('cog', cogProtocol);\r\n\r\nconst App = () =>\r\n  <Map\r\n    style={{width: 600, height: 400}}\r\n    mapStyle=\"https://geoserveis.icgc.cat/contextmaps/icgc_mapa_base_gris_simplificat.json\"\r\n    initialViewState={{longitude: 1.83369, latitude: 41.5937, zoom: 14}}\r\n  >\r\n    <Source id=\"imageSource\" type=\"raster\" url=\"cog://https://labs.geomatico.es/maplibre-cog-protocol/data/image.tif\" tileSize={256}>\r\n      <Layer id=\"imageLayer\" type=\"raster\"/>\r\n    </Source>\r\n  </Map>;\r\n```\r\n\r\n\r\n## API\r\n\r\n### Display image COGs\r\n\r\nCOGs are displayed as images according to their `PhotometricInterpretation` TIFF tag. Supported\r\ninterpretations are `WhiteIsZero`, `BlackIsZero` (grayscale), `RGB`, `Palette` (using the COG's own\r\ncolor map), `CMYK`, `YCbCr` and `CIELab`. Any other value throws an error.\r\n\r\n* Use a `raster` source with the url prepended with `cog://`\r\n* Use a `raster` layer.\r\n\r\n```javascript\r\n  map.addSource('sourceId', {\r\n    type: 'raster',\r\n    url: 'cog://https://labs.geomatico.es/maplibre-cog-protocol/data/image.tif',\r\n    tileSize: 256\r\n  });\r\n\r\n  map.addLayer({\r\n    id: 'imageId',\r\n    source: 'sourceId',\r\n    type: 'raster'\r\n  });\r\n```\r\n\r\nTransparency comes from the COG's `noData` value: pixels whose color bands all equal `noData` are\r\nrendered fully transparent. A separate alpha band is not read, so generate your COGs with\r\n`-co ADD_ALPHA=NO`, as in the [GDAL commands below](#cog-generation-tips). Beware that a COG\r\ndeclaring no `noData` value at all falls back to treating 0 as transparent, which also makes\r\ngenuinely black pixels disappear; set an explicit `noData` to avoid this.\r\n\r\nIf instead you need transparency driven by a vector geometry, see\r\n[Mask COG rendering with a GeoJSON polygon](#mask-cog-rendering-with-a-geojson-polygon).\r\n\r\n### Display Digital Elevation Model COGs\r\n\r\nSingle-band COGs can be interpreted as DEMs. Elevations are taken from the first band, with the\r\nCOG's `scale` and `offset` applied, and encoded into RGB using the Mapbox Terrain-RGB scheme that\r\nMapLibre expects.\r\n\r\n#### As Hillshading\r\n\r\n* Use a `raster-dem` source with the url prepended with `cog://` and appended with `#dem`\r\n* Use a `hillshade` layer.\r\n\r\n```javascript\r\n  map.addSource('sourceId', {\r\n    type: 'raster-dem',\r\n    url: 'cog://https://cdn.geomatico.es/pirineo_dem_cog_256.tif#dem',\r\n    tileSize: 256\r\n  });\r\n\r\n  map.addLayer({\r\n    id: 'hillshadeId',\r\n    source: 'sourceId',\r\n    type: 'hillshade'\r\n  });\r\n```\r\n\r\n#### As 3D Terrain\r\n\r\n* Use a `raster-dem` source with the url prepended with `cog://` and appended with `#dem`, same as above.\r\n* Set it as the terrain.\r\n\r\n```javascript\r\n  map.addSource('sourceId', {\r\n    type: 'raster-dem',\r\n    url: 'cog://https://cdn.geomatico.es/pirineo_dem_cog_256.tif#dem',\r\n    tileSize: 256\r\n  });\r\n\r\n  map.setTerrain({\r\n    source: 'sourceId'\r\n  });\r\n```\r\n\r\n\r\n### Apply ColorBrewer or CARTOColor ramp to a single-band COG\r\n\r\nCOGs with a single band can be also converted to images applying a color ramp. Values are read from\r\nthe first band with `scale` and `offset` applied; `noData`, `NaN` and `Infinity` pixels are rendered\r\ntransparent.\r\n\r\n* Use a `raster` source with the url prepended with `cog://` and appended with `#color:` and the color ramp specification.\r\n* Use a `raster` layer.\r\n\r\n```javascript\r\n  map.addSource('sourceId', {\r\n    type: 'raster',\r\n    url: 'cog://https://labs.geomatico.es/maplibre-cog-protocol/data/kriging.tif#color:BrewerSpectral9,1.7,1.8,c',\r\n    tileSize: 256\r\n  });\r\n\r\n  map.addLayer({\r\n    id: 'imageId',\r\n    source: 'sourceId',\r\n    type: 'raster'\r\n  });\r\n```\r\n\r\nThe syntax for the `#color` parameter is `#color:<colorScheme>,<minValue>,<maxValue>,<modifiers>`, where:\r\n\r\n* `<colorScheme>`: Mandatory parameter. One of the built-in color ramps, see the list of possible values in [Color Ramp cheatsheet](https://labs.geomatico.es/maplibre-cog-protocol/color-cheatsheet.html).\r\n* `<minValue>, <maxValue>`: Define the data range for color mapping, should map your data's actual range. These are required if we want predictable results, as we can't rely on COG \"stats\" metadata (not always provided or correctly informed) and cannot read the whole file to get them (that's the point of the library, not having to).\r\n* `<modifiers>`: Some characters representing additional configuration. We support:\r\n  * `c` continuous color interpolation (vs discrete).\r\n  * `-` reverse scale.\r\n  * `t` transparent out-of-range values. When enabled, values below `<minValue>` or above `<maxValue>` will be rendered as transparent instead of using the min/max colors from the spectrum.\r\n\r\nSome examples:\r\n\r\n* Apply discrete `CartoEarth` ramp between 1 and 100: `#color:CartoEarth,1,100`\r\n* Apply continuous `BrewerYlOrRd7` ramp between -1 and 1: `#color:BrewerYlOrRd7,-1,1,c`\r\n* Same as above, reversed (so colors go red-orange-yellow instead of yellow-orange-red): `#color:CartoEarth,-1,1,c-`\r\n* Apply continuous `BrewerSpectral9` ramp with transparent out-of-range values: `#color:BrewerSpectral9,1.7,1.8,ct`\r\n\r\nSee other usages in [examples](examples). If you need more flexibility, use a Custom Color Function.\r\n\r\n\r\n### Apply a Custom Color Function to any COG\r\n\r\nIn case you want to apply any other coloring logic, you can provide a function that\r\nconverts pixel values to RGBA color values, and assign it to the COG URL where it needs\r\nto be applied.\r\n\r\nUse the `setColorFunction` method, which needs two arguments:\r\n* `cogUrl`: the COG to which the custom color function will be applied. Don't prepend the `cog://` protocol here.\r\n* `colorFunction`: A function that maps pixel values to color values, whose arguments are:\r\n    * `pixel`: A [TypedArray](src/types.ts#L45) with the raw pixel data as read from the geotiff, one value per band.\r\n    * `color`: An Uint8ClampedArray of exactly 4 elements. Set the pixel color by setting the first, second, third and fourth element to `red`, `green`, `blue` and `alpha` values respectively.\r\n    * `metadata`: [CogMetadata](src/types.ts#L27) structure with information about the COG, such as `noData`, `offset` or `scale` values.\r\n\r\nNote that `pixel` holds the values as stored in the file: unlike `#dem` and `#color`, `scale` and\r\n`offset` are **not** applied for you, so use `metadata.scale` and `metadata.offset` if your COG\r\ndeclares them. A custom color function takes precedence over any `#dem` or `#color` hash on the URL.\r\n\r\nThe following example paints values below a given threshold as red, and green otherwise: \r\n\r\n```javascript\r\n  const cogUrl = 'https://labs.geomatico.es/maplibre-cog-protocol/data/kriging.tif';\r\n  const threshold = 1.75;\r\n  \r\n  // Function is called for every pixel, keep it fast!\r\n  MaplibreCOGProtocol.setColorFunction(cogUrl, (pixel, color, metadata) => {\r\n    if (pixel[0] === metadata.noData) {\r\n      color.set([0, 0, 0, 0]);     // Transparent\r\n    } else if (pixel[0] < threshold) {\r\n      color.set([255, 0, 0, 255]); // Red\r\n    } else {\r\n      color.set([0, 255, 0, 255]); // Green\r\n    }\r\n  });\r\n\r\n  map.addSource('sourceId', {\r\n    type: 'raster',\r\n    url: `cog://${cogUrl}`, // Use the same URL as in setColorFunction, preppended with \"cog://\".\r\n    tileSize: 256\r\n  });\r\n\r\n  map.addLayer({\r\n    id: 'imageId',\r\n    source: 'sourceId',\r\n    type: 'raster'\r\n  });\r\n```\r\n\r\nThis function will be called for each pixel, keep it as fast as possible!\r\n\r\nSome other interesting usages: \r\n\r\n* Apply other color scales not listed in the builtin standard ColorBrewer or CartoColors catalog. \r\n* Use custom breakpoints or interpolations.\r\n* Display other bands.\r\n* Combine bands of a multispectral image to calculate indicators on the fly.\r\n\r\n\r\n#### Band arithmetic on multispectral rasters\r\n\r\nBecause the `pixel` argument holds every band of the pixel, a color function can compute an index\r\nfrom several bands and symbolize the result, without precomputing a derived raster. The following\r\nexample calculates NDVI from a 12-band Sentinel-2 COG and paints it with a d3 threshold scale:\r\n\r\n```javascript\r\nimport {scaleThreshold} from 'd3-scale';\r\n\r\nconst url = './data/sentinel2.tif';\r\n\r\nconst ndviColorScale = scaleThreshold()\r\n  .domain([-1.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8])\r\n  .range([\r\n    [0x00, 0x00, 0x00, 0xFF], //         NDVI < -1.0\r\n    [0x2C, 0x7B, 0xB6, 0xFF], // -1.0 <= NDVI <  0.1\r\n    [0xFD, 0xAE, 0x61, 0xFF], //  0.1 <= NDVI <  0.2\r\n    [0xFE, 0xE0, 0x8B, 0xFF], //  0.2 <= NDVI <  0.3\r\n    [0xFF, 0xFF, 0xBF, 0xFF], //  0.3 <= NDVI <  0.4\r\n    [0xD9, 0xEF, 0x8B, 0xFF], //  0.4 <= NDVI <  0.5\r\n    [0xA6, 0xD9, 0x6A, 0xFF], //  0.5 <= NDVI <  0.6\r\n    [0x66, 0xBD, 0x63, 0xFF], //  0.6 <= NDVI <  0.7\r\n    [0x1A, 0x98, 0x50, 0xFF], //  0.7 <= NDVI <  0.8\r\n    [0x00, 0x68, 0x37, 0xFF]  //         NDVI >= 0.8\r\n  ])\r\n  .unknown([0x00, 0x00, 0x00, 0x00]); // NaN or undefined => transparent\r\n\r\nsetColorFunction(url, (pixel, color) => {\r\n  const [B01, B02, B03, B04, B05, B06, B07, B08, B09, B11, B12, B8A] = pixel;\r\n  const NDVI = (B8A - B04) / (B8A + B04);\r\n\r\n  color.set(ndviColorScale(NDVI));\r\n});\r\n```\r\n\r\nThe same arithmetic works for any other index (NDWI, NDBI, burn severity...), and changing the\r\nformula, the thresholds or the palette only requires reloading the layer, never regenerating data.\r\nPair it with [`locationValues`](#get-pixel-values-for-a-given-location) to read the index value under\r\nthe cursor.\r\n\r\nSee the [custom color example](examples/custom-color.html) for the full working demo, which does\r\nexactly this over a Sentinel-2 image and shows the NDVI value on mouse hover.\r\n\r\nTo remove a previously set color function and go back to the default rendering, pass `undefined` as\r\nthe second argument:\r\n\r\n```javascript\r\nsetColorFunction(cogUrl, undefined);\r\n```\r\n\r\nChanging the color function only affects tiles rendered from then on, as MapLibre keeps already\r\nrendered tiles. To force a refresh, remove and re-add the layer:\r\n\r\n```javascript\r\nsetColorFunction(cogUrl, newColorFunction);\r\nmap.removeLayer('imageLayer');\r\nmap.addLayer({id: 'imageLayer', source: 'sourceId', type: 'raster'});\r\n```\r\n\r\nThe [timeseries example](examples/timeseries.html) uses this to animate through the bands of a\r\nmulti-band COG.\r\n\r\n\r\n### Reuse the built-in color ramps\r\n\r\nThe color ramps used by `#color:` are also exported, so a custom color function can reuse them:\r\n\r\n* `colorSchemeNames`: array with the names of every built-in ramp.\r\n* `colorScale({colorScheme, min, max, isContinuous, isReverse})`: returns an interpolator function\r\n  mapping a value to an `[r, g, b]` array. `isContinuous` and `isReverse` default to `false` and are\r\n  the equivalent of the `c` and `-` URL modifiers. Alternatively to `colorScheme`, a `customColors`\r\n  array of at least two hex colors can be given.\r\n\r\n```javascript\r\nimport {colorScale, setColorFunction} from '@amjed-ali-k-2/maplibre-cog-protocol';\r\n\r\nconst interpolate = colorScale({colorScheme: 'BrewerRdYlBu10', min: 1, max: 7, isContinuous: true});\r\n\r\nsetColorFunction(url, (pixel, color, {noData, scale, offset}) => {\r\n  const value = pixel[0];\r\n  if (value === noData) {\r\n    color[3] = 0;\r\n  } else {\r\n    color.set([...interpolate(value * scale + offset), 224]); // 224 = semi-transparent\r\n  }\r\n});\r\n```\r\n\r\nThe [Color Ramp cheatsheet](examples/color-cheatsheet.html) is built with these two exports.\r\n\r\n\r\n### Transparency from the COG's internal mask band\r\n\r\nNo API needed: if the COG contains an internal mask band (a TIFF image whose `NewSubfileType` has\r\nthe mask bit set), it is read alongside the data and pixels masked out in the file are rendered\r\nfully transparent. This applies to every rendering mode, custom color functions included.\r\n\r\nGDAL carries such a band over when the source dataset already has one.\r\n\r\n\r\n### Mask COG rendering with a GeoJSON polygon\r\n\r\nUse `setMask` to restrict rendering to the area covered by a GeoJSON `FeatureCollection` of `Polygon` or `MultiPolygon` features. Pixels outside the mask are set to transparent. Other geometry types in the collection are ignored.\r\n\r\nUse `clearMask` (or `setMask(undefined)`) to remove the mask.\r\n\r\nThe mask is global and applies to every COG source currently on the map. As with color functions, it\r\ntakes effect on tiles rendered from then on, so set it before adding the source, or force a refresh\r\nby removing and re-adding the layer. Masking relies on `OffscreenCanvas`; where that is unavailable,\r\ntiles are rendered unmasked.\r\n\r\n```javascript\r\nimport {setMask, clearMask} from '@amjed-ali-k-2/maplibre-cog-protocol';\r\n\r\nconst mask = {\r\n  type: 'FeatureCollection',\r\n  features: [{\r\n    type: 'Feature',\r\n    geometry: {\r\n      type: 'Polygon',\r\n      coordinates: [[[2.0, 41.0], [3.0, 41.0], [3.0, 42.0], [2.0, 42.0], [2.0, 41.0]]]\r\n    },\r\n    properties: {}\r\n  }]\r\n};\r\n\r\nsetMask(mask);   // apply mask\r\nclearMask();     // remove mask\r\n```\r\n\r\nSee [masking example](examples/masking.html) for a full working demo.\r\n\r\n\r\n### [unstable] Get COG metadata\r\n\r\nUse the `getCogMetadata(url)` to obtain metadata about a COG file. It returns a promise resolving to:\r\n\r\n* `offset`, `scale`: GDAL offset and scale for the first band, defaulting to `0.0` and `1.0`.\r\n* `noData`: noData value for the first band, or `undefined`.\r\n* `bbox`: `[west, south, east, north]` bounds, in geographic coordinates.\r\n* `artist`: the TIFF `Artist` tag, if present.\r\n* `photometricInterpretation`, `bitsPerSample`, `colorMap`: raw TIFF tags used for rendering.\r\n* `images`: one entry per image in the file (full resolution, overviews and masks), each with its\r\n  `zoom` level and the `isOverview` / `isMask` flags.\r\n\r\nThese are internals that may change in future releases, so use with caution. The promise rejects if\r\nthe COG is not in EPSG:3857.\r\n\r\nUsage example:\r\n\r\n```javascript\r\nMaplibreCOGProtocol.getCogMetadata(url).then(metadata => console.log(metadata.bbox));\r\n```\r\n\r\nSee the [metadata example](examples/metadata.html) for an interactive version.\r\n\r\n\r\n### Get pixel values for a given location\r\n\r\nThe `locationValues(url, location, zoom?)` method reads pixel values for a given location, with the COG's `scale` and `offset` applied. It returns an array of numbers, one for each band in the COG. NaNs are returned when querying outside of the image, or for `noData` pixels. If zoom is indicated, it will query the nearest overview corresponding to that zoom level; otherwise the full resolution image is used.\r\n\r\nExample usage in conjunction with maplibre API to get COG values on mouse hover:\r\n\r\n```javascript\r\nimport {locationValues} from '@amjed-ali-k-2/maplibre-cog-protocol';\r\n\r\nmap.on('mousemove', ({lngLat}) => {\r\n  locationValues(\r\n    './data/kriging.tif',\r\n    {latitude: lngLat.lat, longitude: lngLat.lng},\r\n    map.getZoom()\r\n  ).then(console.log);\r\n});\r\n```\r\n\r\n`locationValues` doesn't depend on MapLibre API or the CogProtocol, so it can be used to query raster values in applications without a map:\r\n\r\n```javascript\r\nimport {locationValues} from '@amjed-ali-k-2/maplibre-cog-protocol';\r\n\r\nconst url = 'https://labs.geomatico.es/maplibre-cog-protocol/data/kriging.tif';\r\nlocationValues(url, {latitude: 41.656278, longitude: 0.501394}).then(console.log);\r\n```\r\n\r\n\r\n### Send custom request headers\r\n\r\nUse `setRequestHeaders(headers)` to add HTTP headers to the requests made to fetch COGs, for\r\ninstance to read from a server requiring authentication:\r\n\r\n```javascript\r\nimport {setRequestHeaders} from '@amjed-ali-k-2/maplibre-cog-protocol';\r\n\r\nsetRequestHeaders({Authorization: 'Bearer <token>'});\r\n```\r\n\r\nThe headers are global, applying to every COG read afterwards, including `locationValues` and\r\n`getCogMetadata`. Because opened files are cached, call this before the COG is first requested; a\r\nlater call won't affect files already opened.\r\n\r\n### Cache decoded source tiles\r\n\r\nOff by default. `configureTileCache({enabled: true})` turns on an in-memory, byte-bounded LRU over\r\nthe *decoded source tiles* of every open COG, which cuts the amount of decoding a pan or zoom costs:\r\n\r\n```javascript\r\nimport {configureTileCache, clearTileCache, getTileCacheStats} from '@amjed-ali-k-2/maplibre-cog-protocol';\r\n\r\nconfigureTileCache({enabled: true, maxBytes: 256 * 1024 * 1024}); // 256 MB is the default budget\r\n\r\ngetTileCacheStats(); // {entries, bytes, hits, misses}\r\nclearTileCache();    // drop everything and reset the counters\r\n```\r\n\r\nWhy it helps: a COG's overview levels are usually not aligned with the web mercator tile grid, so a\r\nsingle 256×256 map tile straddles several source tiles, and neighbouring map tiles keep re-decoding\r\nthe same ones. Decoding is the expensive part — in the browser each one is a\r\n`Blob` → `createImageBitmap` → `drawImage` → `getImageData` round trip — and it is not fixed by\r\ncaching bytes, since `geotiff.js` already coalesces the byte ranges into a handful of requests.\r\n\r\nMeasured over a full-extent pan of two 3857 COGs, counting decodes of source tiles per map tile\r\ndelivered:\r\n\r\n| COG                                    | zoom | default | cache enabled |\r\n|----------------------------------------|------|---------|---------------|\r\n| ortho (8-bit RGB, JPEG)                | 19   | 1.71    | 0.21          |\r\n| ortho (8-bit RGB, JPEG)                | 20   | 1.78    | 0.17          |\r\n| DSM (Float32, Deflate + predictor)     | 19   | 3.18    | 0.86          |\r\n| DSM (Float32, Deflate + predictor)     | 20   | 3.69    | 1.00          |\r\n\r\nNotes:\r\n\r\n* The cache is global, shared by every open COG, and `maxBytes` is one budget across all of them.\r\n  Resident bytes never exceed it; once the budget is reached the least recently used tiles are\r\n  evicted, so a budget smaller than the working set degrades gradually rather than failing. In the\r\n  DSM measurement above, a full viewport needed ~41 MB and a 4 MB budget still cut decodes per map\r\n  tile from 3.69 to 1.89.\r\n* Concurrent reads of the same source tile share one decode.\r\n* `configureTileCache({enabled: false})` releases everything the cache is holding.\r\n* This is separate from the caches described under [Notes](#notes), which are always on and hold\r\n  opened files, their metadata, and finished map tiles.\r\n\r\n\r\n## Notes\r\n\r\n* **Attribution**: the TIFF `Artist` tag of the COG, if present, is exposed as the source\r\n  attribution, and thus shown in MapLibre's attribution control.\r\n* **Zoom range**: the source's `maxzoom` is derived from the resolution of the COG's own overviews,\r\n  and `minzoom` is always 0. Zooming beyond the COG's resolution upsamples the highest resolution\r\n  image available.\r\n* **Caching**: opened files, their metadata and the decoded tiles are cached in memory, keyed by\r\n  URL, and expire after an hour. Requesting a tile that is already cached issues no network request.\r\n  Decoded *source* tiles can additionally be cached with\r\n  [`configureTileCache`](#cache-decoded-source-tiles), which is off by default.\r\n  The decoded map tile cache is bounded by entry count (1024), not by bytes, so its footprint grows\r\n  with the sample count and bit depth of the COGs in use: roughly 190 KB per entry for 8-bit RGB and\r\n  260 KB for single-band Float32.\r\n\r\n\r\n## COG generation tips\r\n\r\nCOG should be in EPSG:3857 (Google Mercator) projection, as this library doesn't reproject and won't understand any other projection.\r\n\r\nFor better performance, use the Google Maps tiling scheme with 256x256 blocksize.\r\n\r\nFor RGB images, JPEG yCbCr (lossy) compression is recommended.\r\nFor lossless compression, deflate gives good decoding performance on the browser.\r\n\r\nSample GDAL commands (using docker for convenience, but not needed):\r\n\r\n#### RGB Image (lossy compression)\r\n\r\n```bash\r\ndocker run --rm -v .:/srv ghcr.io/osgeo/gdal:alpine-small-3.9.1 gdalwarp /srv/<source>.tif /srv/<target>.tif -of COG -co BLOCKSIZE=256 -co TILING_SCHEME=GoogleMapsCompatible -co COMPRESS=JPEG -co OVERVIEWS=IGNORE_EXISTING -co ADD_ALPHA=NO -dstnodata NaN\r\n```\r\n\r\n#### Digital Elevation Model\r\n\r\n```bash\r\ndocker run --rm -v .:/srv ghcr.io/osgeo/gdal:alpine-small-3.9.1 gdalwarp /srv/<source>.tif /srv/<target>.tiff -of COG -co BLOCKSIZE=256 -co TILING_SCHEME=GoogleMapsCompatible -co COMPRESS=DEFLATE -co RESAMPLING=BILINEAR -co OVERVIEW_RESAMPLING=NEAREST -co OVERVIEWS=IGNORE_EXISTING -co ADD_ALPHA=NO -dstnodata NaN\r\n```\r\n\r\n## For developers\r\n\r\nNode version is the one in `.nvmrc`.\r\n\r\n```bash\r\nnpm install\r\nnpm test          # lint and run the test suite with coverage\r\nnpm run watch     # rebuild dist/ and serve examples/ with live reload\r\n```\r\n\r\nBreaking changes between versions are documented in [MIGRATIONS.md](MIGRATIONS.md).\r\n\r\n### Making a new release\r\n\r\n```\r\nnpm version [patch | minor | major]   # bumps, commits, tags, and pushes (postversion hook)\r\n\r\nnpm run build\r\nnpm publish --access public\r\n\r\nnpm run gh-publish  # publish examples to labs.geomatico.es\r\n```\r\n\r\nPushing the tag triggers a GitHub Actions workflow that creates the GitHub Release with\r\nauto-generated notes from merged PRs.\r\n\r\n\r\n## About Geomatico\r\n\r\nMapLibre COG Protocol is developed and maintained by [Geomatico](https://geomatico.es/en/), an open\r\nsource geospatial software development and GIS consulting company.\r\n\r\nWe build custom web mapping platforms, raster processing workflows and geospatial applications using\r\nMapLibre, TypeScript, PostGIS, GDAL, GeoServer and cloud native spatial data formats, with a focus on\r\ngeographic information analysis and publishing, mobility and the environment.\r\n\r\nNeed to publish satellite imagery, elevation models or other large raster datasets on the web?\r\n[Talk to Geomatico](https://geomatico.es/en/).\r\n\r\n\r\n## License\r\n\r\n[MIT](LICENSE)\r\n","readmeFilename":"README.md"}