ol-stac 1.5.1 → 1.6.0

package/layer/STAC.js

@@ -22,12 +22,14 @@ import { PMTilesRasterSource, PMTilesVectorSource } from 'ol-pmtiles';
 import * as pmtiles from 'pmtiles';
 import create, { Asset } from 'stac-js';
 import { fixGeoJson, toGeoJSON, unionBoundingBox } from 'stac-js/src/geo.js';
-import { geojsonMediaType, geotiffMediaTypes, wozMediaTypes, } from 'stac-js/src/mediatypes.js';
+import { geojsonMediaType, geotiffMediaTypes, wozMediaTypes, zarrMediaTypes, } from 'stac-js/src/mediatypes.js';
 import { isObject } from 'stac-js/src/utils.js';
 import ErrorEvent from '../events/ErrorEvent.js';
+import { createImageLoadFunction, createTileLoadFunction } from '../http.js';
 import { getProjection } from '../proj.js';
 import SourceType from '../source/type.js';
-import { LABEL_EXTENSION, defaultBoundsStyle, defaultCollectionStyle, getBoundsStyle, getClassificationStyle, getGeoTiffSourceInfoFromAsset, getGeoZarrSourceOptionsFromAsset, getSpecificWebMapUrl, isScalar, toContinuousBBox, toOlExtent, } from '../util.js';
+import { LABEL_EXTENSION, defaultBoundsStyle, defaultCollectionStyle, exceedsDisplayLimit, getBoundsStyle, getDisplayPixels, getGeoTiffSourceInfoFromAsset, getGeoTiffStyleFromAsset, getGeoZarrSourceOptionsFromAsset, getGeoZarrStyleFromAsset, getSpecificWebMapUrl, isScalar, toContinuousBBox, toOlExtent, } from '../util.js';
+import LayerType from './type.js';
 /**
  * @typedef {import("ol/extent.js").Extent} Extent
  */
@@ -55,6 +57,18 @@ import { LABEL_EXTENSION, defaultBoundsStyle, defaultCollectionStyle, getBoundsS
 /**
  * @typedef {import('../source/type.js').SourceOptions} SourceOptions
  */
+/**
+ * @typedef {import('./type.js').LayerOptions} LayerOptions
+ */
+/**
+ * @typedef {import('../http.js').GetHeadersFn} GetHeadersFn
+ */
+/**
+ * @typedef {import('../http.js').OnErrorFn} OnErrorFn
+ */
+/**
+ * @typedef {function((import("ol/Image.js").default|import("ol/Tile.js").default), string): void} LoadFunction
+ */
 /**
  * @typedef {Object} Options
  * @property {string} [url] The STAC URL. Any of `url` and `data` must be provided.
@@ -75,8 +89,15 @@ import { LABEL_EXTENSION, defaultBoundsStyle, defaultCollectionStyle, getBoundsS
  * Optional function that can be used to configure the underlying sources. The function can do any additional work
  * and return the completed options or a promise for the same. The function will be called with the current source options
  * and the STAC Asset or Link.
- * This can be useful for adding auth information such as an API token, either via query parameter or HTTP headers.
- * Please be aware that sending HTTP headers may not be supported by all sources.
+ * This can be useful for advanced per-source customization such as signed URLs.
+ * To add credentials via query parameters, use the `getRequestUrl` option instead;
+ * to send credentials via HTTP headers, use the `getRequestHeaders` option instead.
+ * @property {function(LayerType, LayerOptions, (Asset|Link)):(LayerOptions|Promise<LayerOptions>)} [getLayerOptions]
+ * Optional function that can be used to configure the individual layers that are created for the assets and links.
+ * The function can do any additional (asynchronous) work and return the completed options or a promise for the same.
+ * The function will be called with the layer type, the current layer options and the STAC Asset or Link.
+ * This can be useful to customize the layers, e.g. to apply a style to a GeoTIFF or GeoZarr layer that is
+ * loaded from the STAC metadata.
  * @property {boolean} [displayFootprint=true] Allows to hide the footprints (bounding box/geometry) of the STAC object
  * by default.
  * @property {boolean} [displayGeoTiffByDefault=false] Allow to choose non-cloud-optimized GeoTiffs as default image to show,
@@ -85,8 +106,16 @@ import { LABEL_EXTENSION, defaultBoundsStyle, defaultCollectionStyle, getBoundsS
  * i.e. assets with any of the roles `thumbnail`, `overview`, or a link with relation type `preview`.
  * The previews are usually not covering the full extents and as such may be placed incorrectly on the map.
  * For performance reasons, it is recommended to enable this option if you pass in STAC API Items instead of `displayOverview`.
- * @property {boolean} [displayOverview=true] Allow to display COGs/WOZs and, if `displayGeoTiffByDefault` is enabled, GeoTiffs,
+ * @property {boolean} [displayOverview=true] Allow to display COGs, Zarr and, if `displayGeoTiffByDefault` is enabled, GeoTiffs,
  * usually an asset with role `overview` or `visual`.
+ * Zarr assets other than Web-Optimized Zarr are only displayed if the STAC metadata declares what to render
+ * (see the datacube extension) and the store is within the `maxDisplayPixels` limit.
+ * @property {number} [maxDisplayPixels=16777216] The maximum number of pixels the coarsest resolution level
+ * of a GeoTIFF or Zarr asset may have to be displayed client-side, as displaying the full extent of an asset
+ * loads every tile of that level. Files without (sufficient) overviews can easily exceed this limit.
+ * Larger assets are not chosen for the default visualization, and selecting one explicitly through `assets`
+ * reports an error through the `error` event (or renders through the tile server if `buildTileUrlTemplate`
+ * and `useTileLayerAsFallback` are set). Set to `Infinity` to display assets of any size.
  * @property {string|boolean|Array<Link|string>} [displayWebMapLink=false] Allow to display a layer
  * based on the information provided through the web map links extension.
  * If an array of links or link ids (property `id` in a Link Object) is provided, all corresponding layers will be shown.
@@ -94,13 +123,19 @@ import { LABEL_EXTENSION, defaultBoundsStyle, defaultCollectionStyle, getBoundsS
  * it lets this library choose a web map link to show, but only if no other data is shown.
  * To disable the functionality set this to `false`.
  * @property {import("ol/layer/WebGLTile.js").Style|null} [style=null] The style for GeoTIFF and GeoZarr layers (WebGLTileLayer style).
+ * @property {Array<import("ol/color.js").Color|string>|null} [defaultColormap=null] The colors of the colormap
+ * that is used for continuous single-band data when neither the STAC metadata nor the `style` option define
+ * a coloring. The colors are evenly distributed over the value range of the data (e.g. from the STAC
+ * `statistics`). If not set, the data is stretched to grayscale.
  * @property {Style} [boundsStyle] The style for the overall bounds / footprint.
  * @property {Style} [collectionStyle] The style for individual children in a list of STAC Items or Collections.
  * @property {null|string} [crossOrigin] For thumbnails: The `crossOrigin` attribute for loaded images / tiles.
  * See https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image for more detail.
- * @property {function((Asset|Link)):Promise<string>|string|null} [buildTileUrlTemplate=null] A function that generates a URL template for a tile server (XYZ),
+ * @property {function((Asset|Link)):Promise<string|null>|string|null} [buildTileUrlTemplate=null] A function that generates a URL template for a tile server (XYZ),
  * which will be used instead of the client-side GeoTIFF rendering (except if `useTileLayerAsFallback` is `true`).
  * The function provided can return a promise (i.e. be async) or a string.
+ * The function can return `null` to not pass the given asset or link to the tile server,
+ * e.g. to filter by media type or protocol. In this case client-side rendering is used instead.
  * @property {boolean} [useTileLayerAsFallback=false] Uses the given URL template only when the client-side GeoTIFF rendering fails.
  * @property {number} [opacity=1] Opacity (0, 1).
  * @property {boolean} [visible=true] Visibility.
@@ -124,6 +159,22 @@ import { LABEL_EXTENSION, defaultBoundsStyle, defaultCollectionStyle, getBoundsS
  * @property {function(string,string):(*)} [httpRequestFn=null] Sets a custom function to make HTTP requests with.
  * The first parameter is the URL to request and the output is a promise that resolves with the response body.
  * The second parameter is the return type, either `json` (default) or `text`.
+ * The STAC Asset or Link the request is made for is passed as third parameter, if available.
+ * @property {Object<string, string>|function((Asset|Link|STACObject|null), string):(Object<string, string>|null)} [getRequestHeaders=null]
+ * The HTTP headers (e.g. for authentication) to send with the requests made by this layer,
+ * either as a plain object or as a function that returns the headers (or `null` for none) and
+ * is called with the STAC Asset or Link that is shown (if available) and the URL that is requested.
+ * Use a function to restrict the headers to specific hosts, as tile server URLs and asset URLs
+ * may point to hosts that should not receive the credentials.
+ * The headers are attached to requests made by the default `httpRequestFn`, to GeoTIFF, GeoZarr
+ * and PMTiles requests, and via image/tile load functions (through the Fetch API and object URLs)
+ * to preview images and XYZ, TileJSON, WMS and WMTS tiles.
+ * @property {function((Asset|Link|STACObject|null), string):(string|null)} [getRequestUrl=null]
+ * Rewrites a URL before a request is made or a source is created, e.g. to append query
+ * parameters for authentication (signed URLs, API keys). The function is called with the
+ * STAC Asset or Link that is shown (if available) and the URL, and returns the new URL or
+ * `null` to keep the URL unchanged. The rewrite is applied before `getSourceOptions` is called.
+ * For tiled sources the tile URL template is rewritten, not the individual tile URLs.
  */
 /**
  * @classdesc
@@ -159,6 +210,21 @@ class STACLayer extends LayerGroup {
          * @private
          */
         this.getSourceOptions_ = options.getSourceOptions;
+        /**
+         * @type {function(LayerType, LayerOptions, (Asset|Link)):(LayerOptions|Promise<LayerOptions>)}
+         * @private
+         */
+        this.getLayerOptions_ = options.getLayerOptions;
+        /**
+         * @type {Object<string, string>|function((Asset|Link|STACObject|null), string):(Object<string, string>|null)|null}
+         * @private
+         */
+        this.getRequestHeaders_ = options.getRequestHeaders || null;
+        /**
+         * @type {function((Asset|Link|STACObject|null), string):(string|null)|null}
+         * @private
+         */
+        this.getRequestUrl_ = options.getRequestUrl || null;
         /**
          * @type {Array<STAC>|null}
          * @private
@@ -209,7 +275,12 @@ class STACLayer extends LayerGroup {
          */
         this.displayWebMapLink_ = options.displayWebMapLink || false;
         /**
-         * @type {function((Asset|Link)):Promise<string>|string|null}
+         * @type {number|undefined}
+         * @private
+         */
+        this.maxDisplayPixels_ = options.maxDisplayPixels;
+        /**
+         * @type {function((Asset|Link)):Promise<string|null>|string|null}
          * @private
          */
         this.buildTileUrlTemplate_ = options.buildTileUrlTemplate || null;
@@ -223,6 +294,11 @@ class STACLayer extends LayerGroup {
          * @private
          */
         this.style_ = options.style || null;
+        /**
+         * @type {Array<import("ol/color.js").Color|string>|null}
+         * @private
+         */
+        this.defaultColormap_ = options.defaultColormap || null;
         /**
          * @type {Style}
          * @private
@@ -268,19 +344,70 @@ class STACLayer extends LayerGroup {
         if (!options.url) {
             throw new Error('Either url or data must be provided');
         }
-        this.fetch_(options.url)
+        this.fetch_(this.getRequestUrlFor_(options.url))
             .then((data) => this.configure_(data, options.url, options.children, options.assets, options.bands))
             .catch((error) => this.handleError_(error));
     }
+    /**
+     * Rewrites the given URL based on the `getRequestUrl` option.
+     *
+     * @param {string} url The URL that is requested.
+     * @param {Asset|Link|STACObject|null} [ref] The STAC Asset or Link that is shown, if available.
+     * @return {string} The rewritten URL, or the given URL if it is not rewritten.
+     */
+    getRequestUrlFor_(url, ref = null) {
+        if (typeof this.getRequestUrl_ === 'function' && typeof url === 'string') {
+            const newUrl = this.getRequestUrl_(ref, url);
+            if (typeof newUrl === 'string' && newUrl.length > 0) {
+                return newUrl;
+            }
+        }
+        return url;
+    }
+    /**
+     * Returns the HTTP headers to send for the given URL, based on the
+     * `getRequestHeaders` option.
+     *
+     * @param {string} url The URL that is requested.
+     * @param {Asset|Link|STACObject|null} [ref] The STAC Asset or Link that is shown, if available.
+     * @return {Object<string, string>|null} The headers, or `null` if there are none.
+     */
+    getRequestHeadersFor_(url, ref = null) {
+        let headers = this.getRequestHeaders_;
+        if (typeof headers === 'function') {
+            headers = headers(ref, url);
+        }
+        if (isObject(headers) && Object.keys(headers).length > 0) {
+            return /** @type {Object<string, string>} */ (headers);
+        }
+        return null;
+    }
+    /**
+     * Creates a load function for images or tiles that attaches the headers
+     * from the `getRequestHeaders` option and reports errors through the
+     * layer's error event, or `undefined` if no headers are configured.
+     *
+     * @param {function(GetHeadersFn, OnErrorFn=):LoadFunction} factory `createImageLoadFunction` or `createTileLoadFunction`.
+     * @param {Asset|Link|STACObject|null} ref The STAC Asset or Link that is shown, if available.
+     * @return {LoadFunction|undefined} The load function.
+     */
+    createLoadFunction_(factory, ref) {
+        if (!this.getRequestHeaders_) {
+            return undefined;
+        }
+        return factory((url) => this.getRequestHeadersFor_(url, ref), (error) => this.handleError_(error));
+    }
     /**
      * Default function make HTTP requests with.
      *
      * @param {string} url The URL to request and the output is a promise that resolves with the response body.
      * @param {string} responseType The return type, either `json` (default) or `text`.
+     * @param {Asset|Link|STACObject|null} [ref] The STAC Asset or Link the request is made for, if available.
      * @return {Promise<*>} The (parsed) response body.
      */
-    async fetch_(url, responseType = 'json') {
-        const response = await fetch(url);
+    async fetch_(url, responseType = 'json', ref = null) {
+        const headers = this.getRequestHeadersFor_(url, ref);
+        const response = await fetch(url, headers ? { headers } : undefined);
         if (!response.ok) {
             throw new Error(`Unexpected response from ${url}: ${response.status}`);
         }
@@ -478,18 +605,21 @@ class STACLayer extends LayerGroup {
          * @type {import("ol/source/ImageStatic.js").Options}
          */
         let options = {
-            url: image.getAbsoluteUrl(),
+            url: this.getRequestUrlFor_(image.getAbsoluteUrl(), image),
             projection,
             imageExtent: toOlExtent(bbox, projection),
             crossOrigin: this.crossOrigin_,
         };
+        const imageLoadFunction = this.createLoadFunction_(createImageLoadFunction, image);
+        if (imageLoadFunction) {
+            options.imageLoadFunction = imageLoadFunction;
+        }
         if (this.getSourceOptions_) {
             // @ts-ignore
             options = await this.getSourceOptions_(SourceType.ImageStatic, options, image);
         }
-        const layer = new ImageLayer({
-            source: new StaticImage(options),
-        });
+        const layerOptions = await this.updateLayerOptions_(LayerType.Image, { source: new StaticImage(options) }, image);
+        const layer = new ImageLayer(layerOptions);
         this.addLayer_(layer, image);
         return layer;
     }
@@ -503,16 +633,21 @@ class STACLayer extends LayerGroup {
      */
     async addLayerForLink(link) {
         // Replace any occurances of {s} if possible, otherwise return
-        const url = getSpecificWebMapUrl(link);
+        let url = getSpecificWebMapUrl(link);
         if (!url) {
             return;
         }
+        url = this.getRequestUrlFor_(url, link);
         const options = {
             attributions: link.getMetadata('attribution') ||
                 this.getData().getMetadata('attribution'),
             crossOrigin: this.crossOrigin_,
             url,
         };
+        const tileLoadFunction = this.createLoadFunction_(createTileLoadFunction, link);
+        if (tileLoadFunction && link.rel !== 'pmtiles') {
+            options.tileLoadFunction = tileLoadFunction;
+        }
         const updateOptions = async (type, options) => {
             if (this.getSourceOptions_) {
                 options = await this.getSourceOptions_(type, options, link);
@@ -521,28 +656,82 @@ class STACLayer extends LayerGroup {
         };
         const sources = [];
         switch (link.rel) {
-            case 'pmtiles':
-                const p = new pmtiles.PMTiles(options.url);
-                const headers = await p.getHeader();
-                let source;
-                switch (headers.tileType) {
+            case 'pmtiles': {
+                const snapshot = JSON.stringify(options);
+                /** @type {*} */
+                let pmOptions = await updateOptions(SourceType.PMTiles, options);
+                // Whether getSourceOptions reacted to SourceType.PMTiles,
+                // see the backward compatibility handling below
+                const handled = JSON.stringify(pmOptions) !== snapshot;
+                const headers = this.getRequestHeadersFor_(pmOptions.url, link);
+                const withHeaders = (url) => headers && typeof url === 'string'
+                    ? new pmtiles.FetchSource(url, new Headers(headers))
+                    : url;
+                let pmtilesHeader;
+                try {
+                    const p = new pmtiles.PMTiles(withHeaders(pmOptions.url));
+                    pmtilesHeader = await p.getHeader();
+                }
+                catch (error) {
+                    this.handleError_(error);
+                    return;
+                }
+                let type;
+                switch (pmtilesHeader.tileType) {
                     case pmtiles.TileType.Mvt:
-                        source = new PMTilesVectorSource(await updateOptions(SourceType.PMTilesVector, options));
+                        type = SourceType.PMTilesVector;
                         break;
                     case pmtiles.TileType.Avif:
                     case pmtiles.TileType.Jpeg:
                     case pmtiles.TileType.Png:
                     case pmtiles.TileType.Webp:
-                        source = new PMTilesRasterSource(await updateOptions(SourceType.PMTilesRaster, options));
+                        type = SourceType.PMTilesRaster;
                         break;
                     default:
                         return; // Unsupported
                 }
+                if (!handled) {
+                    // Backward compatibility for getSourceOptions callbacks that don't
+                    // handle SourceType.PMTiles yet: call them with the deprecated
+                    // type-specific source type once the tile type is known.
+                    // As before v1.6.0, these rewrites don't apply to the tile type
+                    // sniff above. TODO: Remove in 2.0.0
+                    pmOptions = await updateOptions(type, pmOptions);
+                }
+                pmOptions.url = withHeaders(pmOptions.url);
+                const source = type === SourceType.PMTilesVector
+                    ? new PMTilesVectorSource(pmOptions)
+                    : new PMTilesRasterSource(pmOptions);
                 sources.push(source);
                 break;
-            case 'tilejson':
-                sources.push(new TileJSON(await updateOptions(SourceType.TileJSON, options)));
+            }
+            case 'tilejson': {
+                /** @type {*} */
+                const tjOptions = await updateOptions(SourceType.TileJSON, options);
+                if (tjOptions.jsonp || tjOptions.tileJSON) {
+                    // Let the source load the manifest itself (e.g. via JSONP)
+                    sources.push(new TileJSON(tjOptions));
+                    break;
+                }
+                // Load the manifest through the request function so that
+                // credentials are attached
+                let tileJSON;
+                try {
+                    tileJSON = await this.fetch_(tjOptions.url, 'json', link);
+                }
+                catch (error) {
+                    this.handleError_(error);
+                    return;
+                }
+                if (isObject(tileJSON) && Array.isArray(tileJSON.tiles)) {
+                    // The tile templates from the manifest must be rewritten as well
+                    tileJSON.tiles = tileJSON.tiles.map((template) => this.getRequestUrlFor_(template, link));
+                }
+                delete tjOptions.url;
+                tjOptions.tileJSON = tileJSON;
+                sources.push(new TileJSON(tjOptions));
                 break;
+            }
             case 'wms':
                 if (!Array.isArray(link['wms:layers'])) {
                     break;
@@ -569,7 +758,7 @@ class STACLayer extends LayerGroup {
                 }
                 break;
             case 'wmts':
-                const wmtsCapabilities = await this.getWmtsCapabilities_(url, link['wmts:encoding']);
+                const wmtsCapabilities = await this.getWmtsCapabilities_(url, link, link['wmts:encoding']);
                 if (!wmtsCapabilities) {
                     return;
                 }
@@ -593,6 +782,10 @@ class STACLayer extends LayerGroup {
                     if (opts === null) {
                         continue;
                     }
+                    if (wmtsOptions.tileLoadFunction) {
+                        // Not passed through by optionsFromCapabilities
+                        opts.tileLoadFunction = wmtsOptions.tileLoadFunction;
+                    }
                     if (typeof link.uriTemplate === 'string') {
                         let uriTemplate = link.uriTemplate;
                         const vars = isObject(link.variables) ? link.variables : {};
@@ -616,7 +809,7 @@ class STACLayer extends LayerGroup {
                             }
                         }
                         delete opts.urls;
-                        opts.url = uriTemplate;
+                        opts.url = this.getRequestUrlFor_(uriTemplate, link);
                     }
                     sources.push(new WMTS(opts));
                 }
@@ -627,34 +820,42 @@ class STACLayer extends LayerGroup {
             default:
                 return;
         }
-        return sources.map((source) => {
+        return await Promise.all(sources.map(async (source) => {
             let layer;
             if (source instanceof VectorTileSource) {
-                layer = new VectorTileLayer({
-                    source,
-                    declutter: true,
-                });
+                const layerOptions = await this.updateLayerOptions_(LayerType.VectorTile, { source, declutter: true }, link);
+                layer = new VectorTileLayer(layerOptions);
             }
             else if (source instanceof PMTilesRasterSource) {
-                layer = new WebGLTileLayer({ source });
+                const layerOptions = await this.updateLayerOptions_(LayerType.WebGLTile, { source }, link);
+                layer = new WebGLTileLayer(layerOptions);
             }
             else {
-                layer = new TileLayer({ source });
+                const layerOptions = await this.updateLayerOptions_(LayerType.Tile, { source }, link);
+                layer = new TileLayer(layerOptions);
             }
             this.addLayer_(layer, link);
             return layer;
-        });
+        }));
     }
     /**
      * @param {Asset} [asset] A STAC Asset
+     * @param {boolean} [autoDisplay] Whether the asset was chosen automatically
+     * (not explicitly requested): skip it silently instead of reporting an
+     * error when it can't be displayed within the configured limits.
      * @return {Promise<Layer|undefined>} Resolves with a Layer or undefined when complete.
      * @private
      */
-    async addGeoTiff_(asset) {
+    async addGeoTiff_(asset, autoDisplay = false) {
         if (this.buildTileUrlTemplate_ && !this.useTileLayerAsFallback_) {
-            return await this.addTileLayerForImagery_(asset);
+            const layer = await this.addTileLayerForImagery_(asset);
+            // If no tile server URL was provided for the asset, continue with client-side rendering
+            if (layer) {
+                return layer;
+            }
         }
         const sourceInfo = getGeoTiffSourceInfoFromAsset(asset, this.bands_);
+        sourceInfo.url = this.getRequestUrlFor_(sourceInfo.url, asset);
         /**
          * @type {import("ol/source/GeoTIFF.js").Options}
          */
@@ -667,10 +868,14 @@ class STACLayer extends LayerGroup {
         if (projection) {
             options.projection = projection;
         }
-        const classificationStyle = getClassificationStyle(asset, sourceInfo.bands);
-        if (classificationStyle) {
+        const metadataStyle = getGeoTiffStyleFromAsset(asset, sourceInfo, this.defaultColormap_);
+        if (metadataStyle) {
             options.normalize = false;
         }
+        const headers = this.getRequestHeadersFor_(sourceInfo.url, asset);
+        if (headers) {
+            options.sourceOptions = { headers };
+        }
         if (this.getSourceOptions_) {
             // @ts-ignore
             options = await this.getSourceOptions_(SourceType.GeoTIFF, options, asset);
@@ -690,34 +895,51 @@ class STACLayer extends LayerGroup {
         });
         try {
             await status;
-            const layerOptions = { source };
+            if (this.checkDisplayLimit_(source, asset, autoDisplay)) {
+                return;
+            }
+            /**
+             * @type {import("ol/layer/WebGLTile.js").Options}
+             */
+            let layerOptions = { source };
             if (this.style_) {
                 layerOptions.style = this.style_;
             }
-            else if (classificationStyle) {
-                layerOptions.style = classificationStyle;
+            else if (metadataStyle) {
+                layerOptions.style = metadataStyle;
             }
+            layerOptions = await this.updateLayerOptions_(LayerType.WebGLTile, layerOptions, asset);
             const layer = new WebGLTileLayer(layerOptions);
             this.addLayer_(layer, asset);
             return layer;
         }
         catch (error) {
             if (this.useTileLayerAsFallback_) {
-                return await this.addTileLayerForImagery_(asset);
+                const layer = await this.addTileLayerForImagery_(asset);
+                if (layer) {
+                    return layer;
+                }
             }
             this.handleError_(error);
         }
     }
     /**
      * @param {Asset|Link} [data] A STAC Asset or Link
-     * @return {Promise<TileLayer>} Resolves with a TileLayer when complete.
+     * @return {Promise<TileLayer|undefined>} Resolves with a TileLayer, or undefined if no tile server URL was provided.
      * @private
      */
     async addTileLayerForImagery_(data) {
+        if (typeof this.buildTileUrlTemplate_ !== 'function') {
+            return;
+        }
         let url = this.buildTileUrlTemplate_(data);
         if (url instanceof Promise) {
             url = await url;
         }
+        if (!url) {
+            return;
+        }
+        url = this.getRequestUrlFor_(url, data);
         /**
          * @type {import("ol/source/XYZ.js").Options}
          */
@@ -725,15 +947,33 @@ class STACLayer extends LayerGroup {
             crossOrigin: this.crossOrigin_,
             url,
         };
+        const tileLoadFunction = this.createLoadFunction_(createTileLoadFunction, data);
+        if (tileLoadFunction) {
+            options.tileLoadFunction = tileLoadFunction;
+        }
         if (this.getSourceOptions_) {
             options = await this.getSourceOptions_(SourceType.XYZ, options, data);
         }
-        const layer = new TileLayer({
-            source: new XYZ(options),
-        });
+        const layerOptions = await this.updateLayerOptions_(LayerType.Tile, { source: new XYZ(options) }, data);
+        const layer = new TileLayer(layerOptions);
         this.addLayer_(layer, data);
         return layer;
     }
+    /**
+     * Passes the layer options through the `getLayerOptions` function, if given.
+     *
+     * @param {LayerType} type The type of the layer that is going to be created.
+     * @param {LayerOptions} options The layer options.
+     * @param {Asset|Link} reference The STAC Asset or Link the layer is created for.
+     * @return {Promise<*>} The updated layer options.
+     * @private
+     */
+    async updateLayerOptions_(type, options, reference) {
+        if (this.getLayerOptions_) {
+            options = await this.getLayerOptions_(type, options, reference);
+        }
+        return options;
+    }
     /**
      * @param {Layer|LayerGroup} [layer] A Layer to add to the LayerGroup
      * @param {STACObject} [data] The STAC object, can be any class exposed by stac-js
@@ -766,7 +1006,7 @@ class STACLayer extends LayerGroup {
             geojson = data.toGeoJSON(fixAntimeridian);
         }
         if (geojson) {
-            const layer = this.createGeoJsonLayer_(geojson, getBoundsStyle(this.boundsStyle_, this), this.displayFootprint_);
+            const layer = new VectorLayer(this.getGeoJsonLayerOptions_(geojson, getBoundsStyle(this.boundsStyle_, this), this.displayFootprint_));
             layer.set('bounds', true);
             layer.on('change', () => this.setMap_(layer.getMapInternal()));
             this.addLayer_(layer, data, 1);
@@ -781,8 +1021,9 @@ class STACLayer extends LayerGroup {
      */
     async addGeoJson_(asset) {
         try {
-            const geojson = await this.fetch_(asset.getAbsoluteUrl());
-            const layer = this.createGeoJsonLayer_(geojson);
+            const geojson = await this.fetch_(this.getRequestUrlFor_(asset.getAbsoluteUrl(), asset), 'json', asset);
+            const layerOptions = await this.updateLayerOptions_(LayerType.Vector, this.getGeoJsonLayerOptions_(geojson), asset);
+            const layer = new VectorLayer(layerOptions);
             this.addLayer_(layer, asset);
             return layer;
         }
@@ -791,15 +1032,15 @@ class STACLayer extends LayerGroup {
         }
     }
     /**
-     * Creates a GeoJSON vector layer from the given GeoJSON object.
+     * Creates the options for a GeoJSON vector layer from the given GeoJSON object.
      *
      * @param {GeoJSON} [geojson] The GeoJSON object.
      * @param {Style} [style] The style for the layer.
      * @param {boolean} [visible] Whether the layer is visible.
-     * @return {VectorLayer} The new vector layer.
+     * @return {import("ol/layer/Vector.js").Options} The vector layer options.
      * @private
      */
-    createGeoJsonLayer_(geojson, style = null, visible = true) {
+    getGeoJsonLayerOptions_(geojson, style = null, visible = true) {
         const format = new GeoJSON();
         const source = new VectorSource({
             format,
@@ -814,7 +1055,7 @@ class STACLayer extends LayerGroup {
         if (!style) {
             style = defaultCollectionStyle;
         }
-        return new VectorLayer({ source, style, visible });
+        return { source, style, visible };
     }
     /**
      * Adds GeoJSON labels and GeoTIFF source imagery to the map based on the label extension.
@@ -849,7 +1090,7 @@ class STACLayer extends LayerGroup {
         if (labelAsset && sourceLinks.length > 0) {
             const promises = sourceLinks.map(async (link) => {
                 try {
-                    const response = await this.fetch_(link.getAbsoluteUrl());
+                    const response = await this.fetch_(this.getRequestUrlFor_(link.getAbsoluteUrl(), link), 'json', link);
                     const stac = create(response);
                     return stac;
                 }
@@ -869,17 +1110,78 @@ class STACLayer extends LayerGroup {
             this.handleError_(error);
         }
     }
-    async addGeoZarr_(asset) {
+    /**
+     * Checks the `maxDisplayPixels` limit for the given source.
+     * Returns `true` when the layer must not be added: automatically chosen
+     * assets are limited silently, for explicitly requested assets an error
+     * is thrown so that callers can fall back or report it.
+     * @param {import('ol/source/Tile.js').default} source The configured (ready) source.
+     * @param {Asset} asset The asset the source was created for.
+     * @param {boolean} autoDisplay Whether the asset was chosen automatically.
+     * @return {boolean} `true` if the asset must not be displayed.
+     * @private
+     */
+    checkDisplayLimit_(source, asset, autoDisplay) {
+        if (!exceedsDisplayLimit(source, this.maxDisplayPixels_)) {
+            return false;
+        }
+        if (!autoDisplay) {
+            const megapixels = Math.ceil(getDisplayPixels(source) / 1048576);
+            const error = new Error(`Asset ${asset.getKey()} is too large to display safely` +
+                ` (~${megapixels} megapixels at the coarsest resolution);` +
+                ` set the maxDisplayPixels option to display it anyway`);
+            // Allows applications to detect the error without matching the message
+            error.name = 'DisplayLimitError';
+            throw error;
+        }
+        return true;
+    }
+    /**
+     * Adds a layer for a GeoZarr asset.
+     * @param {Asset} asset The Zarr asset to show.
+     * @param {boolean} [autoDisplay] Whether the asset was chosen automatically
+     * (not explicitly requested): skip it silently instead of reporting an
+     * error when it doesn't declare what to render or can't be displayed
+     * within the configured limits.
+     * @return {Promise<Layer|undefined>} The layer, if one was added.
+     * @private
+     */
+    async addGeoZarr_(asset, autoDisplay = false) {
         if (this.buildTileUrlTemplate_ && !this.useTileLayerAsFallback_) {
-            return await this.addTileLayerForImagery_(asset);
+            const layer = await this.addTileLayerForImagery_(asset);
+            // If no tile server URL was provided for the asset, continue with client-side rendering
+            if (layer) {
+                return layer;
+            }
         }
         let options = getGeoZarrSourceOptionsFromAsset(asset, this.bands_);
+        // Web-Optimized Zarr describes its bands in the store metadata,
+        // everything else must declare what to render in the STAC metadata
+        // (or provide it through getSourceOptions for explicitly selected assets)
+        const declaresRendering = () => asset.isType(wozMediaTypes) ||
+            Boolean(options.variable) ||
+            Boolean(options.bands && options.bands.length > 0);
+        if (autoDisplay && !declaresRendering()) {
+            return;
+        }
+        options.url = this.getRequestUrlFor_(options.url, asset);
+        const projection = await getProjection(asset);
+        if (projection) {
+            options.projection = projection;
+        }
+        const headers = this.getRequestHeadersFor_(options.url, asset);
+        if (headers) {
+            options.storeOptions = { headers };
+        }
         if (this.getSourceOptions_) {
             // @ts-ignore
             options = await this.getSourceOptions_(SourceType.GeoZarr, options, asset);
         }
         try {
-            const GeoZarr = (await import('ol/source/GeoZarr.js')).default;
+            if (!declaresRendering()) {
+                throw new Error(`Asset ${asset.getKey()} declares neither bands nor a datacube variable to render`);
+            }
+            const GeoZarr = (await import('../source/GeoZarr.js')).default;
             const source = new GeoZarr(options);
             await new Promise((resolve, reject) => {
                 source.on('change', () => {
@@ -891,17 +1193,33 @@ class STACLayer extends LayerGroup {
                     }
                 });
             });
-            const layerOptions = { source };
+            if (this.checkDisplayLimit_(source, asset, autoDisplay)) {
+                return;
+            }
+            /**
+             * @type {import("ol/layer/WebGLTile.js").Options}
+             */
+            let layerOptions = { source };
             if (this.style_) {
                 layerOptions.style = this.style_;
             }
+            else {
+                const style = getGeoZarrStyleFromAsset(asset, options, this.defaultColormap_);
+                if (style) {
+                    layerOptions.style = style;
+                }
+            }
+            layerOptions = await this.updateLayerOptions_(LayerType.WebGLTile, layerOptions, asset);
             const layer = new WebGLTileLayer(layerOptions);
             this.addLayer_(layer, asset);
             return layer;
         }
         catch (error) {
             if (this.useTileLayerAsFallback_) {
-                return await this.addTileLayerForImagery_(asset);
+                const layer = await this.addTileLayerForImagery_(asset);
+                if (layer) {
+                    return layer;
+                }
             }
             this.handleError_(error);
         }
@@ -946,7 +1264,7 @@ class STACLayer extends LayerGroup {
                 if (ref.isType(geotiffMediaTypes)) {
                     return await this.addGeoTiff_(ref);
                 }
-                if (ref.isType(wozMediaTypes)) {
+                if (ref.isType(zarrMediaTypes)) {
                     return await this.addGeoZarr_(ref);
                 }
                 if (ref.canBrowserDisplayImage()) {
@@ -978,14 +1296,13 @@ class STACLayer extends LayerGroup {
                     // Find a GeoTiff asset that we can visualize
                     const geotiff = data.getDefaultGeoFile('geotiff', true, !this.displayGeoTiffByDefault_);
                     if (geotiff) {
-                        layer = await this.addGeoTiff_(geotiff);
+                        layer = await this.addGeoTiff_(geotiff, true);
                     }
                 }
                 if (this.displayOverview_ && !layer) {
-                    // Find a Web-Optimized GeoZarr asset that we can visualize
-                    const geozarr = data.getDefaultGeoFile('geozarr', true, true);
+                    const geozarr = data.getDefaultGeoFile('geozarr', true, false);
                     if (geozarr) {
-                        layer = await this.addGeoZarr_(geozarr);
+                        layer = await this.addGeoZarr_(geozarr, true);
                     }
                 }
                 // Show web map links if available
@@ -1071,6 +1388,26 @@ class STACLayer extends LayerGroup {
             }
         }
     }
+    /**
+     * Set the colors of the colormap that is used for continuous single-band
+     * data when neither the STAC metadata nor the `style` option define a
+     * coloring. The colors are evenly distributed over the value range of the
+     * data (e.g. from the STAC `statistics`). Set to `null` to stretch the
+     * data to grayscale instead.
+     * @param {Array<import("ol/color.js").Color|string>|null} colormap The colors of the colormap.
+     * @return {Promise} Resolves once the layers are updated.
+     * @api
+     */
+    async setDefaultColormap(colormap) {
+        if (colormap === this.defaultColormap_) {
+            return;
+        }
+        this.defaultColormap_ = colormap || null;
+        // The layers are recreated, as switching between a styled and an
+        // unstyled visualization also changes how the sources are configured
+        // (e.g. the normalization of GeoTIFF sources)
+        await this.updateLayers();
+    }
     /**
      * Update the assets to be rendered.
      * @param {Array<string|Asset>|null} assets The assets to show.
@@ -1244,18 +1581,19 @@ class STACLayer extends LayerGroup {
     /**
      * Gets the WMTS capabilities from the given web-map-links URL.
      * @param {string} url Base URL for the WMTS
+     * @param {Link} link The web map link the request is made for.
      * @param {string} [encoding] The request encoding, either `kvp` (default) or `rest`.
      * @return {Promise<Object|null>} Resolves with the WMTS Capabilities object
      * @private
      */
-    async getWmtsCapabilities_(url, encoding = 'kvp') {
+    async getWmtsCapabilities_(url, link, encoding = 'kvp') {
         try {
             const urlObj = new URL(url);
             if (encoding !== 'rest') {
                 urlObj.searchParams.set('service', 'wmts');
                 urlObj.searchParams.set('request', 'GetCapabilities');
             }
-            const response = await this.fetch_(urlObj.toString(), 'text');
+            const response = await this.fetch_(urlObj.toString(), 'text', link);
             return new WMTSCapabilities().read(response);
         }
         catch (_) {