Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

feat(raster-tile): Support STAC 1.1.0 core bands, description fallback, and tile debug borders (#3366)

Igor Dykhta0c8c8592a278
diff --git a/docs/user-guides/c-types-of-layers/n-raster-tile-layer.md b/docs/user-guides/c-types-of-layers/n-raster-tile-layer.md
index 4a39514e6..63b290110 100644
--- a/docs/user-guides/c-types-of-layers/n-raster-tile-layer.md
+++ b/docs/user-guides/c-types-of-layers/n-raster-tile-layer.md
@@ -6,16 +6,28 @@ Use Raster Tile layer to visualize satellite/aerial imagery from raster pmtiles
2. Select Raster Tile tileset type.
3. Paste URL to the tileset:
- pmtiles (raster format): provide a direct HTTPS URL to a .pmtiles file containing raster imagery. Raster pmtiles don't require dedicated raster tile servers, unless you want to use elevation meshes.
- - STAC Item/Collection (COGs): provide a HTTPS URL to a STAC Item or Collection (v1.0.0+ with EO + Raster extensions). For this option you need to provide a [compatible raster tile server](https://github.com/igorDykhta/kepler-raster-server).
+ - COG (.tif): provide a direct HTTPS URL to a Cloud Optimized GeoTIFF. The public [TiTiler](https://titiler.xyz) service is used automatically for metadata and tile serving. Elevation is not supported in this mode.
+ - STAC Item/Collection (COGs): provide a HTTPS URL to a STAC Item or Collection. Both STAC 1.0.x (with EO + Raster extensions) and STAC 1.1.0+ (with core `bands`) are supported. For this option you need to provide a [compatible raster tile server](https://github.com/igorDykhta/kepler-raster-server).
4. Click Add.
5. Style band selection and opacity as needed in Layers panel.
Important notes for COGs via STAC:
-- The STAC Item/Collection must include EO and Raster extensions with `eo:bands` and `raster:bands` .
+- **STAC 1.0.x:** The STAC Item/Collection must include EO and Raster extensions with `eo:bands` and `raster:bands`.
+- **STAC 1.1.0+:** Items using the core `bands` field (where band metadata lives directly on each asset instead of separate `eo:bands`/`raster:bands` extensions) are also supported. Each band object should include `data_type` and optionally `eo:common_name` and `statistics`.
+- Both formats can coexist within a single STAC item (some assets using legacy extensions, others using core `bands`).
- COG assets must be publicly accessible over HTTPS.
- You must run your own raster tile server (e.g., TiTiler). Example implementation that supports collections and elevations: [kepler-raster-server](https://github.com/igorDykhta/kepler-raster-server).
+# Loading standalone COG (.tif) files
+
+You can load a Cloud Optimized GeoTIFF directly by pasting its URL (ending in `.tif` or `.tiff`) into the "Tileset metadata URL" field. When a COG URL is detected, kepler.gl automatically fetches STAC metadata from the public [TiTiler](https://titiler.xyz) service (`/cog/stac` endpoint) and sets `https://titiler.xyz` as the raster tile server.
+
+- **No self-hosted server required** — the public TiTiler instance handles both metadata and tile serving.
+- **Elevation is not available** when using the public TiTiler service.
+- The COG file must be publicly accessible over HTTPS.
+- If the "Raster tile servers" field is empty when you paste a `.tif` URL, it will be auto-filled with `https://titiler.xyz`.
+
# Elevation
To enable elevation rendering, you must provide one or more compatible raster tile servers when adding the tileset. Enter them in the "Raster tile servers" field of the Add Tileset form.
diff --git a/src/components/src/modals/tilesets-modals/tileset-raster-form.tsx b/src/components/src/modals/tilesets-modals/tileset-raster-form.tsx
index ed6f61d98..f2727bbd2 100644
--- a/src/components/src/modals/tilesets-modals/tileset-raster-form.tsx
+++ b/src/components/src/modals/tilesets-modals/tileset-raster-form.tsx
@@ -30,6 +30,46 @@ const TilesetInputDescription = styled.div`
font-size: 11px;
`;
+const ExampleUrlsContainer = styled.div`
+ text-align: left;
+ color: ${props => props.theme.AZURE200};
+ font-size: 11px;
+`;
+
+const ExampleTabs = styled.div`
+ display: flex;
+ gap: 6px;
+ margin-top: 6px;
+ margin-bottom: 6px;
+ flex-wrap: wrap;
+`;
+
+const ExampleTab = styled.div<{active: boolean}>`
+ padding: 3px 8px;
+ border-radius: 3px;
+ cursor: pointer;
+ font-size: 11px;
+ white-space: nowrap;
+ background: ${props => (props.active ? props.theme.AZURE400 : 'transparent')};
+ color: ${props => (props.active ? props.theme.WHITE : props.theme.AZURE200)};
+ border: 1px solid ${props => props.theme.AZURE400};
+
+ &:hover {
+ background: ${props => (props.active ? props.theme.AZURE400 : props.theme.AZURE500)};
+ }
+`;
+
+const ExampleUrl = styled.div`
+ word-break: break-all;
+ cursor: pointer;
+ color: ${props => props.theme.AZURE200};
+ font-size: 11px;
+
+ &:hover {
+ color: ${props => props.theme.AZURE100};
+ }
+`;
+
const LabelRow = styled.div`
display: flex;
align-items: center;
@@ -90,6 +130,46 @@ const InfoIconLink = styled.a`
const RASTER_TILE_DOCUMENTATION_URL =
'https://docs.kepler.gl/docs/user-guides/c-types-of-layers/n-raster-tile-layer';
+const TITILER_BASE_URL = 'https://titiler.xyz';
+
+function isCOGUrl(url: string): boolean {
+ if (!url) return false;
+ try {
+ const pathname = new URL(url).pathname.toLowerCase().replace(/\/+$/, '');
+ return pathname.endsWith('.tif') || pathname.endsWith('.tiff');
+ } catch {
+ const cleaned = url.trim().toLowerCase().split(/[?#]/)[0].replace(/\/+$/, '');
+ return cleaned.endsWith('.tif') || cleaned.endsWith('.tiff');
+ }
+}
+
+function getCOGMetadataUrl(cogUrl: string): string {
+ return `${TITILER_BASE_URL}/cog/stac?url=${encodeURIComponent(cogUrl)}`;
+}
+
+const RASTER_TILE_EXAMPLES = [
+ {
+ label: 'COG',
+ name: 'Africa Farms',
+ url: 'https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/36/Q/WD/2020/7/S2A_36QWD_20200701_0_L2A/TCI.tif'
+ },
+ {
+ label: 'PMTiles',
+ name: 'Mt Whitney',
+ url: 'https://pmtiles.io/usgs-mt-whitney-8-15-webp-512.pmtiles'
+ },
+ {
+ label: 'PMTiles',
+ name: 'Swiss Historical',
+ url: 'https://public-bucket-for-tests.s3.us-east-1.amazonaws.com/historic-swis-18xx.pmtiles'
+ },
+ {
+ label: 'STAC Collection',
+ name: 'Sentinel-2 L1C',
+ url: 'https://earth-search.aws.element84.com/v1/collections/sentinel-2-l1c'
+ }
+];
+
const parseMetadataAllowCollections = (
metadata: JsonObjectOrArray | PMTilesMetadata,
{metadataUrl, rasterTileType}: {metadataUrl: string; rasterTileType: RasterTileType}
@@ -108,10 +188,32 @@ const RasterTileForm: React.FC<RasterTileFormProps> = ({setResponse}) => {
const [rasterTileServerUrls, setRasterTileServerUrls] = useState<string>(
(getApplicationConfig().rasterServerUrls || []).join(',')
);
+ const [exampleTab, setExampleTab] = useState(0);
// Remove trailing slash to prevent issues with raster tile servers
const clearedMetadataUrl = metadataUrl.endsWith('/') ? metadataUrl.slice(0, -1) : metadataUrl;
+ const isCOG = isCOGUrl(clearedMetadataUrl);
+ const effectiveMetadataUrl = isCOG ? getCOGMetadataUrl(clearedMetadataUrl) : clearedMetadataUrl;
+ const effectiveRasterTileServerUrls = isCOG ? TITILER_BASE_URL : rasterTileServerUrls;
+
+ const defaultServerUrls = (getApplicationConfig().rasterServerUrls || []).join(',');
+
+ const onExampleClick = useCallback(
+ (url: string, name: string) => {
+ setMetadataUrl(url);
+ setTileName(name);
+ setTileNameWasModified(false);
+
+ if (isCOGUrl(url)) {
+ setRasterTileServerUrls(TITILER_BASE_URL);
+ } else {
+ setRasterTileServerUrls(defaultServerUrls);
+ }
+ },
+ [defaultServerUrls]
+ );
+
const onTileNameChange = useCallback(
(event: React.ChangeEvent<HTMLInputElement>) => {
event.preventDefault();
@@ -127,11 +229,15 @@ const RasterTileForm: React.FC<RasterTileFormProps> = ({setResponse}) => {
const {value} = event.target;
setMetadataUrl(value);
+ if (isCOGUrl(value) && !rasterTileServerUrls.trim()) {
+ setRasterTileServerUrls(TITILER_BASE_URL);
+ }
+
if (!tileNameWasModified) {
setTileName(value.split('/').filter(Boolean).pop() || '');
}
},
- [tileNameWasModified]
+ [tileNameWasModified, rasterTileServerUrls]
);
const onRasterTileServerUrlsChange = useCallback(
@@ -147,7 +253,7 @@ const RasterTileForm: React.FC<RasterTileFormProps> = ({setResponse}) => {
loading,
error: metaError
} = useFetchJson({
- url: clearedMetadataUrl,
+ url: effectiveMetadataUrl,
rasterTileType: isPMTilesUrl(clearedMetadataUrl) ? RasterTileType.PMTILES : RasterTileType.STAC,
process: parseMetadataAllowCollections
});
@@ -173,7 +279,7 @@ const RasterTileForm: React.FC<RasterTileFormProps> = ({setResponse}) => {
!error
// We still need raster tile servers for PMTiles when we plan to use elevation
) {
- rasterTileServers = rasterTileServerUrls
+ rasterTileServers = effectiveRasterTileServerUrls
.split(',')
.map(server => server.trim())
.filter(server => server);
@@ -195,7 +301,7 @@ const RasterTileForm: React.FC<RasterTileFormProps> = ({setResponse}) => {
const dataset = getDatasetAttributesFromRasterTile({
name: tileName,
- metadataUrl: clearedMetadataUrl,
+ metadataUrl: effectiveMetadataUrl,
rasterTileServerUrls: rasterTileServers
});
@@ -219,7 +325,8 @@ const RasterTileForm: React.FC<RasterTileFormProps> = ({setResponse}) => {
metaError,
tileName,
clearedMetadataUrl,
- rasterTileServerUrls,
+ effectiveMetadataUrl,
+ effectiveRasterTileServerUrls,
setResponse
]);
@@ -255,7 +362,7 @@ const RasterTileForm: React.FC<RasterTileFormProps> = ({setResponse}) => {
onChange={onMetadataUrlChange}
/>
<TilesetInputDescription>
- Supports raster .pmtiles. Limited support for STAC Items and Collections.
+ Supports raster .pmtiles, COG (.tif) URLs, STAC Items and Collections.
</TilesetInputDescription>
</div>
{showServerInput && (
@@ -282,6 +389,35 @@ const RasterTileForm: React.FC<RasterTileFormProps> = ({setResponse}) => {
</TilesetInputDescription>
</div>
)}
+ <div>
+ <TilesetInputDescription>For example, try a public raster tileset:</TilesetInputDescription>
+ <ExampleUrlsContainer>
+ <ExampleTabs>
+ {RASTER_TILE_EXAMPLES.map((ex, i) => (
+ <ExampleTab
+ key={`${ex.label}-${ex.name}`}
+ active={exampleTab === i}
+ onClick={() => {
+ setExampleTab(i);
+ onExampleClick(ex.url, ex.name);
+ }}
+ >
+ {ex.name}
+ </ExampleTab>
+ ))}
+ </ExampleTabs>
+ <ExampleUrl
+ onClick={() =>
+ onExampleClick(
+ RASTER_TILE_EXAMPLES[exampleTab].url,
+ RASTER_TILE_EXAMPLES[exampleTab].name
+ )
+ }
+ >
+ {RASTER_TILE_EXAMPLES[exampleTab].url}
+ </ExampleUrl>
+ </ExampleUrlsContainer>
+ </div>
</TilesetInputContainer>
);
};
diff --git a/src/components/src/side-panel/layer-panel/raster-tile-layer-configurator.tsx b/src/components/src/side-panel/layer-panel/raster-tile-layer-configurator.tsx
index 873859b5c..f28b50926 100644
--- a/src/components/src/side-panel/layer-panel/raster-tile-layer-configurator.tsx
+++ b/src/components/src/side-panel/layer-panel/raster-tile-layer-configurator.tsx
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: MIT
// Copyright contributors to the kepler.gl project
-import React, {useEffect, useMemo} from 'react';
+import React, {useCallback, useEffect, useMemo} from 'react';
import styled from 'styled-components';
import {PMTilesType} from '@kepler.gl/constants';
@@ -135,6 +135,90 @@ function getBandSelectorOptions(stac: CompleteSTACObject): {id?: string; label?:
}));
}
+const COMMON_NAME_LABELS: Record<string, string> = {
+ red: 'Red Channel',
+ green: 'Green Channel',
+ blue: 'Blue Channel',
+ nir: 'NIR Band',
+ swir16: 'SWIR 1.6 Band',
+ swir22: 'SWIR 2.2 Band'
+};
+
+function getSlotLabel(commonName: string): string {
+ return COMMON_NAME_LABELS[commonName] || `${commonName} Band`;
+}
+
+const BandAssignmentRow = styled.div`
+ margin-bottom: 4px;
+`;
+
+/**
+ * Resolve the default band option for a preset slot from auto-detected eo:bands
+ */
+function getDefaultBandForSlot(
+ stac: CompleteSTACObject,
+ commonName: string,
+ bandOptions: {id?: string; label?: string}[]
+): {id?: string; label?: string} | undefined {
+ const eoBands = getEOBands(stac) || [];
+ const match = eoBands.find(b => b.common_name === commonName);
+ if (match) {
+ const bandId = match.name || match.common_name;
+ return bandOptions.find(o => o.id === bandId);
+ }
+ return undefined;
+}
+
+type BandAssignmentProps = {
+ stac: CompleteSTACObject;
+ commonNames: string[];
+ bandOptions: {id?: string; label?: string}[];
+ bandOverrides: Record<string, string> | null;
+ onChange: (value: any) => void;
+};
+
+const BandAssignment: React.FC<BandAssignmentProps> = ({
+ stac,
+ commonNames,
+ bandOptions,
+ bandOverrides,
+ onChange
+}) => {
+ const handleSlotChange = useCallback(
+ (slotName: string, bandId: string) => {
+ const current = bandOverrides || {};
+ const updated = {...current, [slotName]: bandId};
+ onChange({bandOverrides: JSON.stringify(updated)});
+ },
+ [bandOverrides, onChange]
+ );
+
+ return (
+ <>
+ {commonNames.map(commonName => {
+ const overrideId = bandOverrides?.[commonName];
+ const selectedItem = overrideId
+ ? bandOptions.find(o => o.id === overrideId)
+ : getDefaultBandForSlot(stac, commonName, bandOptions);
+ return (
+ <BandAssignmentRow key={commonName}>
+ <PanelLabel>{getSlotLabel(commonName)}</PanelLabel>
+ <ItemSelector
+ selectedItems={selectedItem}
+ options={bandOptions}
+ multiSelect={false}
+ searchable={false}
+ displayOption="label"
+ getOptionValue="id"
+ onChange={val => handleSlotChange(commonName, val as string)}
+ />
+ </BandAssignmentRow>
+ );
+ })}
+ </>
+ );
+};
+
function getCategoricalColormapListItem(categoricalColorMap) {
let categoricalItem: {label: string; id: string} | undefined;
if (categoricalColorMap) {
@@ -258,11 +342,24 @@ function RasterTileLayerConfiguratorFactory(
useSTACSearching,
colorRange: {colorMap: categoricalColorMap},
dynamicColor,
- singleBandName
+ singleBandName,
+ bandOverrides: rawBandOverrides
} = layer.config.visConfig;
const stac = dataset?.metadata as GetTileDataCustomProps['stac'];
+ const bandOverrides: Record<string, string> | null = useMemo(() => {
+ if (!rawBandOverrides) return null;
+ if (typeof rawBandOverrides === 'string') {
+ try {
+ return JSON.parse(rawBandOverrides);
+ } catch {
+ return null;
+ }
+ }
+ return rawBandOverrides as unknown as Record<string, string>;
+ }, [rawBandOverrides]);
+
const availablePresets = useMemo(() => filterAvailablePresets(stac, PRESET_OPTIONS), [stac]);
const presetOptions = useMemo(
@@ -291,6 +388,7 @@ function RasterTileLayerConfiguratorFactory(
}, [layer.visConfigSettings.colormapId.options, categoricalColorMap]);
const {bandCombination} = PRESET_OPTIONS[preset] || {};
+ const currentPresetCommonNames = PRESET_OPTIONS[preset]?.commonNames;
const colormapAllowed = isColormapAllowed(bandCombination);
const rescalingAllowed = !categoricalColorMap && isRescalingAllowed(bandCombination);
const filterAllowed = isFilterAllowed(bandCombination);
@@ -328,11 +426,18 @@ function RasterTileLayerConfiguratorFactory(
// Default of `dynamicColor` is false. Set it true if it is not possible to get data source
// wide color range
+ const onVisConfigChange = visConfiguratorProps.onChange;
useEffect(() => {
if (isDynamicColorsOnly && !dynamicColor) {
- visConfiguratorProps.onChange({dynamicColor: true});
+ onVisConfigChange({dynamicColor: true});
}
- }, [visConfiguratorProps, dynamicColor, isDynamicColorsOnly]);
+ }, [onVisConfigChange, dynamicColor, isDynamicColorsOnly]);
+
+ useEffect(() => {
+ if (preset === 'singleBand' && !singleBandName && singleBandOptions.length > 0) {
+ onVisConfigChange({singleBandName: singleBandOptions[0].id});
+ }
+ }, [onVisConfigChange, preset, singleBandName, singleBandOptions]);
const elevationUI = (
<>
@@ -363,6 +468,15 @@ function RasterTileLayerConfiguratorFactory(
<VisConfigSlider {...layer.visConfigSettings.opacity} {...visConfiguratorProps} />
</LayerConfigGroup>
{elevationUI}
+ <LayerConfigGroup {...visConfiguratorProps} label="Debug" collapsible>
+ <ConfigGroupCollapsibleContent>
+ <VisConfigSwitch
+ {...visConfiguratorProps}
+ {...layer.visConfigSettings.showTileBorders}
+ />
+ <VisConfigSlider {...visConfiguratorProps} {...layer.visConfigSettings.zoomOffset} />
+ </ConfigGroupCollapsibleContent>
+ </LayerConfigGroup>
</StyledLayerConfigurator>
);
}
@@ -387,12 +501,17 @@ function RasterTileLayerConfiguratorFactory(
displayOption="label"
getOptionValue="id"
onChange={newPreset => {
- const overrides = updateColorParamsOnPresetChange(
- stac,
- visConfiguratorProps.layer.config.visConfig.preset,
- newPreset as string
- );
- visConfiguratorProps.onChange({...overrides, preset: newPreset});
+ const overrides =
+ updateColorParamsOnPresetChange(
+ stac,
+ visConfiguratorProps.layer.config.visConfig.preset,
+ newPreset as string
+ ) || {};
+ visConfiguratorProps.onChange({
+ ...overrides,
+ preset: newPreset,
+ bandOverrides: null
+ });
}}
/>
{selectedPreset?.description ? (
@@ -485,6 +604,27 @@ function RasterTileLayerConfiguratorFactory(
</LayerConfigGroup>
)}
+ {selectedPreset?.id !== 'singleBand' &&
+ currentPresetCommonNames &&
+ singleBandOptions.length > 0 && (
+ <LayerConfigGroup
+ {...visConfiguratorProps}
+ label="Band Assignment"
+ description="Override which physical band fills each channel. Useful when band metadata is incorrect or missing."
+ collapsible
+ >
+ <ConfigGroupCollapsibleContent>
+ <BandAssignment
+ stac={stac}
+ commonNames={currentPresetCommonNames}
+ bandOptions={singleBandOptions}
+ bandOverrides={bandOverrides}
+ onChange={visConfiguratorProps.onChange}
+ />
+ </ConfigGroupCollapsibleContent>
+ </LayerConfigGroup>
+ )}
+
<LayerConfigGroup {...visConfiguratorProps} label="Visual Settings" collapsible={false}>
<VisConfigSlider {...layer.visConfigSettings.opacity} {...visConfiguratorProps} />
{colormapAllowed && (
@@ -562,6 +702,16 @@ function RasterTileLayerConfiguratorFactory(
)}
{elevationUI}
+
+ <LayerConfigGroup {...visConfiguratorProps} label="Debug" collapsible>
+ <ConfigGroupCollapsibleContent>
+ <VisConfigSwitch
+ {...visConfiguratorProps}
+ {...layer.visConfigSettings.showTileBorders}
+ />
+ <VisConfigSlider {...visConfiguratorProps} {...layer.visConfigSettings.zoomOffset} />
+ </ConfigGroupCollapsibleContent>
+ </LayerConfigGroup>
</StyledLayerConfigurator>
);
};
diff --git a/src/deckgl-layers/src/raster/raster-layer/raster-layer.ts b/src/deckgl-layers/src/raster/raster-layer/raster-layer.ts
index f8eb1f29f..1e2602980 100644
--- a/src/deckgl-layers/src/raster/raster-layer/raster-layer.ts
+++ b/src/deckgl-layers/src/raster/raster-layer/raster-layer.ts
@@ -13,7 +13,7 @@ import {
} from './raster-layer-shaders';
import {loadImages} from '../images';
import type {RasterLayerAddedProps, ImageState} from '../types';
-import {modulesEqual} from '../util';
+import {modulesEqual, applyModuleUniforms} from '../util';
import {patchPipelineValidation} from '../pipeline-validation-patch';
const defaultProps = {
@@ -63,21 +63,13 @@ export default class RasterLayer extends BitmapLayer<RasterLayerAddedProps> {
}
});
- // Set props for each custom module through shaderInputs.
- // We call getUniforms ourselves to skip modules that return null (inactive).
- // Passing allModuleProps directly to setProps would cause the null-fallback
- // in ShaderInputs to treat the entire props bag as uniforms/bindings,
- // triggering expensive texture rebinding every frame.
+ // Apply each custom module's uniforms/bindings to shaderInputs directly.
+ // We call getUniforms once per module and write the results into
+ // shaderInputs.moduleUniforms/moduleBindings, bypassing setProps() which
+ // would call getUniforms a second time on already-transformed values.
const allModuleProps = {...moduleProps, ...images};
const modules = this.props.modules || [];
- for (const mod of modules) {
- if (mod.getUniforms) {
- const result = mod.getUniforms(allModuleProps);
- if (result) {
- model.shaderInputs.setProps({[mod.name]: result});
- }
- }
- }
+ applyModuleUniforms(model.shaderInputs, modules, allModuleProps);
const drawSuccess = model.draw(this.context.renderPass);
if (!drawSuccess) {
diff --git a/src/deckgl-layers/src/raster/raster-mesh-layer/raster-mesh-layer.ts b/src/deckgl-layers/src/raster/raster-mesh-layer/raster-mesh-layer.ts
index a3cd66cd2..9284ca640 100644
--- a/src/deckgl-layers/src/raster/raster-mesh-layer/raster-mesh-layer.ts
+++ b/src/deckgl-layers/src/raster/raster-mesh-layer/raster-mesh-layer.ts
@@ -17,7 +17,7 @@ import {
} from '../raster-layer/raster-layer-shaders';
import {loadImages} from '../images';
import type {RasterLayerAddedProps, ImageState} from '../types';
-import {modulesEqual} from '../util';
+import {modulesEqual, applyModuleUniforms} from '../util';
import {patchPipelineValidation} from '../pipeline-validation-patch';
import {TOPOLOGY} from '@kepler.gl/constants';
@@ -179,20 +179,13 @@ export default class RasterMeshLayer extends SimpleMeshLayer<any, RasterLayerAdd
}
});
- // Set props for each custom module through shaderInputs.
- // Call getUniforms ourselves to skip inactive modules (null return),
- // avoiding the ShaderInputs null-fallback that would dump all textures
- // into bindings every frame.
+ // Apply each custom module's uniforms/bindings to shaderInputs directly.
+ // We call getUniforms once per module and write the results into
+ // shaderInputs.moduleUniforms/moduleBindings, bypassing setProps() which
+ // would call getUniforms a second time on already-transformed values.
const allModuleProps = {...moduleProps, ...images};
const modules = this.props.modules || [];
- for (const mod of modules) {
- if (mod.getUniforms) {
- const result = mod.getUniforms(allModuleProps);
- if (result) {
- model.shaderInputs.setProps({[mod.name]: result});
- }
- }
- }
+ applyModuleUniforms(model.shaderInputs, modules, allModuleProps);
const drawSuccess = model.draw(this.context.renderPass);
if (!drawSuccess) {
diff --git a/src/deckgl-layers/src/raster/util.ts b/src/deckgl-layers/src/raster/util.ts
index 9eac44aaa..e0b669a04 100644
--- a/src/deckgl-layers/src/raster/util.ts
+++ b/src/deckgl-layers/src/raster/util.ts
@@ -24,3 +24,58 @@ export function modulesEqual(modules: ShaderModule[], oldModules: ShaderModule[]
return true;
}
+
+function isUniformValue(value: unknown): boolean {
+ return (
+ typeof value === 'number' ||
+ typeof value === 'boolean' ||
+ ArrayBuffer.isView(value) ||
+ Array.isArray(value)
+ );
+}
+
+/**
+ * Apply module uniforms/bindings to shaderInputs, calling each module's
+ * getUniforms exactly once and writing the result directly — avoiding the
+ * double-getUniforms bug where shaderInputs.setProps() would re-invoke
+ * getUniforms on already-transformed values.
+ */
+export function applyModuleUniforms(
+ shaderInputs: {
+ moduleUniforms: Record<string, Record<string, unknown>>;
+ moduleBindings: Record<string, Record<string, unknown>>;
+ setProps?: (props: any) => void;
+ },
+ modules: ShaderModule[],
+ allModuleProps: Record<string, unknown>
+): void {
+ for (const mod of modules) {
+ if (mod.getUniforms) {
+ const result = mod.getUniforms(allModuleProps as object);
+ if (result) {
+ const uniforms: Record<string, unknown> = {};
+ const bindings: Record<string, unknown> = {};
+ for (const [key, value] of Object.entries(result)) {
+ if (isUniformValue(value)) {
+ uniforms[key] = value;
+ } else {
+ bindings[key] = value;
+ }
+ }
+ try {
+ if (!shaderInputs.moduleUniforms[mod.name]) {
+ shaderInputs.moduleUniforms[mod.name] = {};
+ }
+ if (!shaderInputs.moduleBindings[mod.name]) {
+ shaderInputs.moduleBindings[mod.name] = {};
+ }
+ Object.assign(shaderInputs.moduleUniforms[mod.name], uniforms);
+ Object.assign(shaderInputs.moduleBindings[mod.name], bindings);
+ } catch {
+ // Fallback: use the public setProps API if direct mutation is blocked
+ shaderInputs.setProps?.({[mod.name]: result});
+ }
+ }
+ }
+ }
+}
diff --git a/src/layers/src/raster-tile/config.ts b/src/layers/src/raster-tile/config.ts
index 2fd180aee..aaea25882 100644
--- a/src/layers/src/raster-tile/config.ts
+++ b/src/layers/src/raster-tile/config.ts
@@ -131,6 +131,17 @@ export const DATA_SOURCE_COLOR_DEFAULTS: Record<DATA_SOURCE_IDS, ColorRescaling>
[DATA_SOURCE_IDS.MOIDS_09Q1_061]: DEFAULT_MODIS_COLOR_DEFAULTS
};
+/**
+ * Fallback color rescaling for unknown STAC items with high-bit (>8bit) integer data.
+ * Without contrast enhancement, uint16 imagery appears nearly black.
+ */
+export const HIGH_BIT_COLOR_DEFAULTS: ColorRescaling = {
+ gammaContrastFactor: 1.5,
+ sigmoidalContrastFactor: 10,
+ sigmoidalBiasFactor: 0.2,
+ saturationValue: 1.2
+};
+
/**
* Available "presets"
*
@@ -754,5 +765,30 @@ export const rasterVisConfigs = {
label: 'Enable in Top view',
group: '',
property: 'enableTerrainTopView'
- } as VisConfigBoolean
+ } as VisConfigBoolean,
+ showTileBorders: {
+ type: 'boolean',
+ defaultValue: false,
+ label: 'Show Tile Borders',
+ group: '',
+ property: 'showTileBorders',
+ description: 'Debug: render wireframe boundaries of raster tiles'
+ } as VisConfigBoolean,
+ zoomOffset: {
+ type: 'number',
+ defaultValue: 0,
+ label: 'Zoom Offset',
+ isRanged: false,
+ range: [-5, 3],
+ step: 1,
+ group: '',
+ property: 'zoomOffset',
+ description: 'Force loading higher (+) or lower (-) zoom level tiles'
+ } as VisConfigNumber,
+ bandOverrides: {
+ type: 'input',
+ defaultValue: null,
+ label: 'Band Overrides',
+ property: 'bandOverrides'
+ } as VisConfigInput
};
diff --git a/src/layers/src/raster-tile/raster-tile-layer.ts b/src/layers/src/raster-tile/raster-tile-layer.ts
index 135681fd3..642f5156c 100644
--- a/src/layers/src/raster-tile/raster-tile-layer.ts
+++ b/src/layers/src/raster-tile/raster-tile-layer.ts
@@ -29,13 +29,20 @@ import {notNullorUndefined} from '@kepler.gl/common-utils';
import {Datasets, KeplerTable as KeplerDataset, VectorTileMetadata} from '@kepler.gl/table';
import {getApplicationConfig} from '@kepler.gl/utils';
-import {rasterVisConfigs, PRESET_OPTIONS, DATA_SOURCE_COLOR_DEFAULTS} from './config';
+import {
+ rasterVisConfigs,
+ PRESET_OPTIONS,
+ DATA_SOURCE_COLOR_DEFAULTS,
+ HIGH_BIT_COLOR_DEFAULTS
+} from './config';
import {getModules} from './gpu-utils';
import {getSTACImageRequests, loadImages, loadTerrain} from './image';
import RasterIcon from './raster-tile-icon';
import {
getDataSourceParams,
+ getDataType,
getMaxRequests,
+ getUsableAssets,
bboxIntersects,
computeZRange,
getSTACBounds,
@@ -93,6 +100,8 @@ export type RasterTileLayerVisConfigCommonSettings = {
opacity: VisConfigNumber;
enableTerrain: VisConfigBoolean;
enableTerrainTopView: VisConfigBoolean;
+ showTileBorders: VisConfigBoolean;
+ zoomOffset: VisConfigNumber;
};
export type RasterTileLayerVisConfigSettings = RasterTileLayerVisConfigCommonSettings & {
@@ -114,6 +123,7 @@ export type RasterTileLayerVisConfigSettings = RasterTileLayerVisConfigCommonSet
filterRange: VisConfigRange;
_stacQuery: VisConfigInput;
singleBandName: VisConfigSelection;
+ bandOverrides: VisConfigInput;
};
type RasterTileLayerMeta = {
@@ -153,7 +163,9 @@ export default class RasterTileLayer extends KeplerLayer {
// objects don't have a `collection` key; STAC Item objects have a `collection` key (which
// matches the collection's `id`).
const resolver = (stac: CompleteSTACObject, preset: string, presetOptions: PresetOption) =>
- `${stac.id}-${stac.collection}-${preset}-${presetOptions.singleBand?.assetId}-${presetOptions.singleBand?.bandIndex}`;
+ `${stac.id}-${stac.collection}-${preset}-${presetOptions.singleBand?.assetId}-${
+ presetOptions.singleBand?.bandIndex
+ }-${JSON.stringify(presetOptions.bandOverrides || null)}`;
this.getDataSourceParams = memoize(
(stac, preset, presetOptions) => getDataSourceParams(stac, preset, presetOptions),
resolver
@@ -327,8 +339,16 @@ export default class RasterTileLayer extends KeplerLayer {
// Apply improved image processing props only for non single band modes
const preset = this.config.visConfig.preset;
const colorDefaults = DATA_SOURCE_COLOR_DEFAULTS[stac.id];
- if (colorDefaults && preset !== 'singleBand') {
- this.updateLayerVisConfig(colorDefaults);
+ if (preset !== 'singleBand') {
+ if (colorDefaults) {
+ this.updateLayerVisConfig(colorDefaults);
+ } else {
+ const usableAssets = getUsableAssets(stac);
+ const dtype = getDataType(usableAssets);
+ if (dtype && dtype !== 'uint8' && dtype !== 'float32' && dtype !== 'float64') {
+ this.updateLayerVisConfig(HIGH_BIT_COLOR_DEFAULTS);
+ }
+ }
}
/*
@@ -456,7 +476,8 @@ export default class RasterTileLayer extends KeplerLayer {
_stacQuery,
singleBandName,
colorRange: {colorMap: categoricalColorMap},
- dynamicColor
+ dynamicColor,
+ bandOverrides
} = visConfig;
const shouldLoadTerrain = getShouldLoadTerrain(stac, mapState, visConfig);
@@ -468,8 +489,19 @@ export default class RasterTileLayer extends KeplerLayer {
const {bandCombination} = PRESET_OPTIONS[preset];
const singleBand = getSingleBandPresetOptions(stac, singleBandName);
+ let parsedOverrides: Record<string, string> | null = null;
+ if (bandOverrides && typeof bandOverrides === 'string') {
+ try {
+ parsedOverrides = JSON.parse(bandOverrides);
+ } catch {
+ parsedOverrides = null;
+ }
+ } else if (bandOverrides) {
+ parsedOverrides = bandOverrides as unknown as Record<string, string>;
+ }
const dataSourceParams: DataSourceParams | null = this.getDataSourceParams(stac, preset, {
- singleBand
+ singleBand,
+ bandOverrides: parsedOverrides
});
if (!dataSourceParams) {
@@ -521,6 +553,7 @@ export default class RasterTileLayer extends KeplerLayer {
minZoom,
maxZoom,
tileSize: 512 / devicePixelRatio,
+ zoomOffset: visConfig.zoomOffset || 0,
getTileData: (args: any) => this.getTileData({...args, ...getTileDataCustomProps}),
onViewportLoad: this.onViewportLoad.bind(this),
// @ts-expect-error - TS doesn't know we'll pass appropriate props here
@@ -573,7 +606,8 @@ export default class RasterTileLayer extends KeplerLayer {
maxCategoricalBandValue,
hasCategoricalColorMap: Boolean(categoricalColorMap),
hasShadowEffect,
- onRedrawNeeded: layerCallbacks?.onRedrawNeeded
+ onRedrawNeeded: layerCallbacks?.onRedrawNeeded,
+ showTileBorders: visConfig.showTileBorders
});
return [tileLayer];
@@ -587,7 +621,7 @@ export default class RasterTileLayer extends KeplerLayer {
const {visConfig} = this.config;
const tileSource = data.tileSource;
- const showTileBorders = false;
+ const showTileBorders = visConfig.showTileBorders;
const minZoom = metadata.minZoom || 0;
const maxZoom = metadata.maxZoom || 30;
@@ -610,7 +644,7 @@ export default class RasterTileLayer extends KeplerLayer {
minZoom,
maxZoom,
tileSize: 512 / devicePixelRatio,
- zoomOffset: devicePixelRatio === 1 ? -1 : 0,
+ zoomOffset: (devicePixelRatio === 1 ? -1 : 0) + (visConfig.zoomOffset || 0),
// @ts-expect-error - TS doesn't know we'll pass appropriate props here
renderSubLayers: renderSubLayersPMTiles,
@@ -828,10 +862,9 @@ function renderSubLayersStac(props: RenderSubLayersProps): DeckLayer<any> | Deck
const idSuffix = props.hasShadowEffect ? 'shadow' : '';
- return terrain
+ const rasterLayer = terrain
? new RasterMeshLayer(props, {
id: `raster-3d-layer-${props.id}-${idSuffix}`,
- // Dummy data
data: [1],
mesh: terrain,
images,
@@ -840,9 +873,7 @@ function renderSubLayersStac(props: RenderSubLayersProps): DeckLayer<any> | Deck
getPolygonOffset: null,
coordinateSystem: COORDINATE_SYSTEM.LNGLAT,
- // Color to use if surfaceImage is unavailable
getColor: [255, 255, 255]
- // material: false
})
: new RasterLayer(props, {
id: `raster-2d-layer-${props.id}-${idSuffix}`,
@@ -852,15 +883,39 @@ function renderSubLayersStac(props: RenderSubLayersProps): DeckLayer<any> | Deck
bounds: [west, south, east, north],
_imageCoordinateSystem: COORDINATE_SYSTEM.CARTESIAN
});
+
+ if (props.showTileBorders) {
+ const borderColor: [number, number, number, number] = [0, 255, 0, 200];
+ return [
+ rasterLayer,
+ new PathLayer({
+ id: `${props.id}-border`,
+ data: [
+ [
+ [west, north],
+ [west, south],
+ [east, south],
+ [east, north],
+ [west, north]
+ ]
+ ],
+ getPath: d => d,
+ getColor: borderColor,
+ widthMinPixels: 2
+ })
+ ];
+ }
+
+ return rasterLayer;
}
function renderSubLayersPMTiles(props: {
id: string;
data: any;
tileSource: any;
- showTileBorders: any;
- minZoom: any;
- maxZoom: any;
+ showTileBorders: boolean;
+ minZoom: number;
+ maxZoom: number;
tile: any;
}) {
const {
@@ -890,8 +945,8 @@ function renderSubLayersPMTiles(props: {
}
}
- // Debug tile borders
- const borderColor = zoom <= minZoom || zoom >= maxZoom ? [255, 0, 0, 255] : [0, 0, 255, 255];
+ const borderColor: [number, number, number, number] =
+ zoom <= minZoom || zoom >= maxZoom ? [255, 0, 0, 255] : [0, 0, 255, 255];
if (showTileBorders) {
layers.push(
new PathLayer({
@@ -906,7 +961,7 @@ function renderSubLayersPMTiles(props: {
]
],
getPath: d => d,
- getColor: borderColor as any,
+ getColor: borderColor,
widthMinPixels: 4
})
);
diff --git a/src/layers/src/raster-tile/raster-tile-utils.ts b/src/layers/src/raster-tile/raster-tile-utils.ts
index ee667b1df..867a6f42f 100644
--- a/src/layers/src/raster-tile/raster-tile-utils.ts
+++ b/src/layers/src/raster-tile/raster-tile-utils.ts
@@ -30,7 +30,9 @@ import {
type Item = StacTypes.STACItem;
type Collection = StacTypes.STACCollection;
type EOBand = StacTypes.Band;
+type CoreBand = StacTypes.CoreBand;
type DataTypeOfTheBand = StacTypes.DataTypeOfTheBand;
+type CommonNameOfTheBand = StacTypes.CommonNameOfTheBand;
export const CATEGORICAL_TEXTURE_WIDTH = 256;
@@ -103,7 +105,7 @@ function getZoomRange(stac: CompleteSTACObject): [number, number] {
* @param stac stac object
* @return Data type of the band
*/
-function getDataType(
+export function getDataType(
usableAssets: CompleteSTACAssetLinks,
typesToCheck?: string[]
): DataTypeOfTheBand | null {
@@ -117,7 +119,14 @@ function getDataType(
continue;
}
+ // Legacy: raster:bands
asset['raster:bands']?.forEach(band => band.data_type && dataTypes.add(band.data_type));
+
+ // Fallback: STAC 1.1.0+ core bands (only if no raster:bands on this asset)
+ if (!asset['raster:bands']?.length) {
+ const coreBands: CoreBand[] = asset.bands || [];
+ coreBands.forEach(band => band.data_type && dataTypes.add(band.data_type));
+ }
}
// TODO: support multiple data types across assets
@@ -194,7 +203,8 @@ export function getImageMinMax(imageData: TypedArray): [number | null, number |
export function getBandIdsForCommonNames(
stac: CompleteSTACObject,
usableAssets: CompleteSTACAssetLinks,
- commonNames: string[]
+ commonNames: string[],
+ bandOverrides?: Record<string, string> | null
): AssetRequestInfo | null {
// An array of strings describing asset identifiers, e.g. the "key" in the assets object
const assetIds: AssetIds = [];
@@ -203,8 +213,20 @@ export function getBandIdsForCommonNames(
const bandIndexes: BandIndexes = [];
for (const commonName of commonNames) {
- // Find asset that includes a band with this common name
- const result = findAssetWithName(usableAssets, commonName, 'common_name');
+ const overrideName = bandOverrides?.[commonName];
+ let result: [string, number] | null = null;
+
+ if (overrideName) {
+ result = findAssetWithName(usableAssets, overrideName, 'name');
+ if (!result) {
+ result = findAssetWithName(usableAssets, overrideName, 'common_name');
+ }
+ }
+
+ if (!result) {
+ result = findAssetWithName(usableAssets, commonName, 'common_name');
+ }
+
if (result) {
const [assetName, bandIndex] = result;
assetIds.push(assetName);
@@ -253,8 +275,11 @@ function consolidateBandIndexes(
// (because of larger download sizes). In the future may want separate loading paths if we
// encounter single asset objects with > 4 bands.
- // TODO: eo:bands can be _either_ on each asset _or_ on the STAC's properties, which is not currently handled
- loadBandIndexes = (asset['eo:bands'] as EOBand[])?.map((_, idx) => idx);
+ const eoBands = asset['eo:bands'] as EOBand[] | undefined;
+ const assetBands: EOBand[] | CoreBand[] | undefined = eoBands?.length
+ ? eoBands
+ : (asset?.bands as CoreBand[] | undefined);
+ loadBandIndexes = assetBands?.map((_: unknown, idx: number) => idx) ?? [];
renderBandIndexes = bandIndexes;
} else {
loadAssetIds = assetIds;
@@ -280,12 +305,33 @@ export function findAssetWithName(
for (const [assetName, assetData] of Object.entries(assets)) {
const eoBands = assetData['eo:bands'] || [];
- // Search bands array of this asset
+ // Search eo:bands array of this asset
for (let i = 0; i < eoBands.length; i++) {
const eoBand = eoBands[i];
if (name === eoBand[property]) {
return [assetName, i];
}
+ if (property === 'common_name' && !eoBand.common_name) {
+ if (name === inferCommonNameFromDescription(eoBand.description)) {
+ return [assetName, i];
+ }
+ }
+ }
+
+ // Fall back to STAC 1.1.0+ core bands
+ if (eoBands.length === 0) {
+ const coreBands: CoreBand[] = assetData?.bands || [];
+ const coreProp = property === 'common_name' ? 'eo:common_name' : 'name';
+ for (let i = 0; i < coreBands.length; i++) {
+ if (name === coreBands[i][coreProp]) {
+ return [assetName, i];
+ }
+ if (property === 'common_name' && !coreBands[i]['eo:common_name']) {
+ if (name === inferCommonNameFromDescription(coreBands[i].description)) {
+ return [assetName, i];
+ }
+ }
+ }
}
}
@@ -337,8 +383,12 @@ export function getRasterStatisticsMinMax(
}
if (bandMetadata) {
- minCategoricalBandValue = bandMetadata['raster:bands']?.[0].statistics?.minimum;
- maxCategoricalBandValue = bandMetadata['raster:bands']?.[0].statistics?.maximum;
+ const bandIdx = singleBandInfo?.bandIndex ?? 0;
+ const coreBands = bandMetadata.bands as CoreBand[] | undefined;
+ const statistics =
+ bandMetadata['raster:bands']?.[bandIdx]?.statistics ?? coreBands?.[bandIdx]?.statistics;
+ minCategoricalBandValue = statistics?.minimum;
+ maxCategoricalBandValue = statistics?.maximum;
}
return [minCategoricalBandValue, maxCategoricalBandValue];
@@ -409,7 +459,12 @@ export function getDataSourceParams(
if (bandCombination === 'single') {
bandInfo = getSingleBandInfo(usableAssets, presetOptions?.singleBand);
} else if (commonNames) {
- bandInfo = getBandIdsForCommonNames(stac, usableAssets, commonNames);
+ bandInfo = getBandIdsForCommonNames(
+ stac,
+ usableAssets,
+ commonNames,
+ presetOptions?.bandOverrides
+ );
} else {
return null;
}
@@ -466,12 +521,13 @@ export function getSTACBounds(stac: Item | Collection): number[] | null {
/**
* Get all eo:band objects from STAC object
+ * Falls back to STAC 1.1.0+ core `bands`, normalizing them to the legacy EOBand shape.
* @param stac STAC object
* @return array of eo:band objects or null
*/
export function getEOBands(stac: CompleteSTACObject): EOBand[] | null {
- const assets = getAssets(stac);
- if (!assets) {
+ const assets = getUsableAssets(stac);
+ if (!assets || Object.keys(assets).length === 0) {
return null;
}
@@ -479,13 +535,64 @@ export function getEOBands(stac: CompleteSTACObject): EOBand[] | null {
for (const data of Object.values(assets)) {
const assetBands = data['eo:bands'];
if (Array.isArray(assetBands) && assetBands.length > 0) {
- eoBands.push(...assetBands);
+ eoBands.push(
+ ...assetBands.map(band => ({
+ ...band,
+ common_name: band.common_name || inferCommonNameFromDescription(band.description)
+ }))
+ );
+ } else {
+ const coreBands: CoreBand[] | undefined = data?.bands as CoreBand[] | undefined;
+ if (Array.isArray(coreBands) && coreBands.length > 0) {
+ eoBands.push(...coreBands.map(coreBandToEOBand));
+ }
}
}
return eoBands;
}
+function coreBandToEOBand(band: CoreBand): EOBand {
+ return {
+ name: band.name,
+ common_name: band['eo:common_name'] || inferCommonNameFromDescription(band.description),
+ center_wavelength: band['eo:center_wavelength'],
+ full_width_half_max: band['eo:full_width_half_max']
+ };
+}
+
+const KNOWN_COMMON_NAMES: ReadonlySet<string> = new Set([
+ 'coastal',
+ 'blue',
+ 'green',
+ 'red',
+ 'rededge',
+ 'yellow',
+ 'pan',
+ 'nir',
+ 'nir08',
+ 'nir09',
+ 'cirrus',
+ 'swir16',
+ 'swir22',
+ 'lwir',
+ 'lwir11',
+ 'lwir12'
+]);
+
+/**
+ * If `description` matches a known eo common_name value, return it.
+ * This covers STAC items (e.g. from TiTiler) that store the common name
+ * in `description` instead of `common_name` / `eo:common_name`.
+ */
+function inferCommonNameFromDescription(
+ description: string | undefined
+): CommonNameOfTheBand | undefined {
+ if (!description) return undefined;
+ const normalized = description.trim().toLowerCase();
+ return KNOWN_COMMON_NAMES.has(normalized) ? (normalized as CommonNameOfTheBand) : undefined;
+}
+
/**
* Filter presets by those that can be used with the given stac item
* Each preset has a commonNames key, which is a list of eo `common_name` values. Some STAC items
@@ -542,9 +649,9 @@ export function getAssets(stac: CompleteSTACObject): CompleteSTACAssetLinks {
/**
* Find usable assets in main assets object
* The `assets` object can point to many different objects, including original XML or JSON metadata,
- * thumbnails, etc. These aren't usable as image data in Studio.
+ * thumbnails, etc. These aren't usable as image data in Raster Tile Layer.
* @param stac STAC object
- * @return asset mapping including only assets usable in Studio
+ * @return asset mapping including only assets usable in Raster Tile Layer
*/
export function getUsableAssets(stac: CompleteSTACObject): CompleteSTACAssetLinks {
const allAssets = getAssets(stac);
@@ -564,9 +671,14 @@ export function getUsableAssets(stac: CompleteSTACObject): CompleteSTACAssetLink
continue;
}
- // raster:bands array exists
+ // raster:bands array exists (legacy STAC 1.0.x)
if (assetData['raster:bands']) {
usableAssets[assetName] = assetData;
+ } else if (hasCoreBandsWithDataType(assetData)) {
+ // STAC 1.1.0+ core bands with data_type
+ usableAssets[assetName] = assetData;
+ } else if (Array.isArray(assetData['eo:bands']) && assetData['eo:bands'].length > 0) {
+ usableAssets[assetName] = assetData;
}
// TODO: Could also mark the asset as unusable if the asset has a non-GeoTIFF or COG Media Type
@@ -575,6 +687,11 @@ export function getUsableAssets(stac: CompleteSTACObject): CompleteSTACAssetLink
return usableAssets;
}
+function hasCoreBandsWithDataType(assetData: Record<string, unknown>): boolean {
+ const bands = assetData?.bands;
+ return Array.isArray(bands) && bands.some((band: CoreBand) => band.data_type);
+}
+
/**
* Get the max number of requests the TileLayer should be able to send at once
* With HTTP 1 under Chrome, you can make a max of 6 concurrent requests per domain, so this number
diff --git a/src/layers/src/raster-tile/types.ts b/src/layers/src/raster-tile/types.ts
index 4666ba51a..0be5cecc5 100644
--- a/src/layers/src/raster-tile/types.ts
+++ b/src/layers/src/raster-tile/types.ts
@@ -86,6 +86,7 @@ export type PresetOption = {
assetId: string;
bandIndex?: number;
};
+ bandOverrides?: Record<string, string> | null;
};
export type DataSourceParams = AssetRequestInfo & {
@@ -174,6 +175,7 @@ export type RenderSubLayersCustomProps = ColorRescaling &
maxCategoricalBandValue?: number;
hasCategoricalColorMap: boolean;
hasShadowEffect?: boolean;
+ showTileBorders?: boolean;
};
export interface RenderSubLayersDefaultProps {
diff --git a/src/table/src/tileset/raster-tile-utils.ts b/src/table/src/tileset/raster-tile-utils.ts
index 67db45aad..bdb1b72bd 100644
--- a/src/table/src/tileset/raster-tile-utils.ts
+++ b/src/table/src/tileset/raster-tile-utils.ts
@@ -54,37 +54,42 @@ function validateSTAC(stac: JsonObjectOrArray, options: {allowCollections: boole
const isCollection = stac?.type === 'Collection';
- const required_extensions = [EO_EXT_ID, RASTER_EXT_ID];
- if (isCollection) {
- required_extensions.push(ITEM_ASSETS_EXT_ID);
+ const assets = isCollection ? stac?.item_assets : stac?.assets;
+ if (!assets || typeof assets !== 'object') {
+ return Error('STAC object is missing asset information.');
}
- if (
- !Array.isArray(stac.stac_extensions) ||
- !stac.stac_extensions.some(ext => typeof ext === 'string' && EO_EXT_ID.exec(ext)) ||
- !stac.stac_extensions.some(ext => typeof ext === 'string' && RASTER_EXT_ID.exec(ext))
- ) {
- return Error('EO and Raster STAC extensions are required.');
+ const hasCoreBands = Object.values(assets).some(asset => {
+ const bands = (asset as Record<string, unknown>)?.bands;
+ return Array.isArray(bands) && bands.length > 0;
+ });
+
+ const hasLegacyExtensions =
+ Array.isArray(stac.stac_extensions) &&
+ stac.stac_extensions.some(ext => typeof ext === 'string' && EO_EXT_ID.exec(ext)) &&
+ stac.stac_extensions.some(ext => typeof ext === 'string' && RASTER_EXT_ID.exec(ext));
+
+ if (!hasCoreBands && !hasLegacyExtensions) {
+ return Error('EO and Raster STAC extensions are required (or STAC 1.1.0+ core bands).');
}
if (
isCollection &&
- !stac.stac_extensions.some(ext => typeof ext === 'string' && EO_EXT_ID.exec(ext))
+ !hasCoreBands &&
+ (!Array.isArray(stac.stac_extensions) ||
+ !stac.stac_extensions.some(ext => typeof ext === 'string' && ITEM_ASSETS_EXT_ID.exec(ext)))
) {
return Error('item-assets STAC extension is required.');
}
- const assets = isCollection ? stac?.item_assets : stac?.assets;
- if (!assets || typeof assets !== 'object') {
- return Error('STAC object is missing asset information.');
- }
+ const hasLegacyBandAssets = Object.values(assets).some(
+ asset => Array.isArray(asset?.['eo:bands']) && Array.isArray(asset?.['raster:bands'])
+ );
- if (
- !Object.values(assets).some(
- asset => Array.isArray(asset?.['eo:bands']) && Array.isArray(asset?.['raster:bands'])
- )
- ) {
- return Error('At least one STAC asset must have both eo:bands and raster:bands data.');
+ if (!hasLegacyBandAssets && !hasCoreBands) {
+ return Error(
+ 'At least one STAC asset must have both eo:bands and raster:bands data, or core bands.'
+ );
}
return null;
diff --git a/src/types/stac.d.ts b/src/types/stac.d.ts
index fda45bb45..ef4075fef 100644
--- a/src/types/stac.d.ts
+++ b/src/types/stac.d.ts
@@ -49,6 +49,7 @@ export type FullWidthHalfMaxFWHM = number;
export interface Fields {
'eo:cloud_cover'?: CloudCover;
'eo:bands'?: Bands;
+ bands?: CoreBand[];
/**
* This interface was referenced by `Fields`'s JSON-Schema definition
* via the `patternProperty` "^(?!eo:)".
@@ -57,6 +58,7 @@ export interface Fields {
}
export interface Band {
name?: NameOfTheBand;
+ description?: string;
common_name?: CommonNameOfTheBand;
center_wavelength?: CenterWavelength;
full_width_half_max?: FullWidthHalfMaxFWHM;
@@ -111,7 +113,7 @@ export type GeoJSONGeometry =
| GeoJSONMultiPoint2
| GeoJSONMultiLineString2
| GeoJSONMultiPolygon2;
-export type STACVersion = '1.0.0';
+export type STACVersion = '1.0.0' | '1.1.0' | string;
export type ReferenceToAJSONSchema = string;
export type STACExtensions = ReferenceToAJSONSchema[];
/**
@@ -429,7 +431,7 @@ export interface ProviderFields {
* This object represents Collections in a SpatioTemporal Asset Catalog.
*/
export type STACCollectionSpecification = STACCollection;
-export type STACVersion = '1.0.0';
+export type STACVersion = '1.0.0' | '1.1.0' | string;
export type ReferenceToAJSONSchema = string;
export type STACExtensions = ReferenceToAJSONSchema[];
export type TypeOfSTACEntity = 'Collection';
@@ -770,6 +772,7 @@ export type NumberOfPixelsInTheBucket = number;
export interface Assetfields {
'raster:bands'?: Bands;
+ bands?: CoreBand[];
/**
* This interface was referenced by `Assetfields`'s JSON-Schema definition
* via the `patternProperty` "^(?!raster:)".
@@ -809,18 +812,42 @@ export interface StacExtensions {
[k: string]: unknown;
}
+/**
+ * STAC 1.1.0 Core Band Object.
+ * Merges spectral (formerly eo:bands) and data-value (formerly raster:bands) fields
+ * into a single band object in common metadata.
+ */
+export interface CoreBand {
+ name?: string;
+ description?: string;
+ 'eo:common_name'?: CommonNameOfTheBand;
+ 'eo:center_wavelength'?: number;
+ 'eo:full_width_half_max'?: number;
+ data_type?: DataTypeOfTheBand;
+ nodata?: NoDataPixelValue;
+ unit?: string;
+ bits_per_sample?: number;
+ sampling?: PixelSamplingInTheBand;
+ scale?: number;
+ offset?: number;
+ spatial_resolution?: number;
+ statistics?: Statistics;
+ histogram?: Histogram;
+ [k: string]: unknown;
+}
+
/**
* STAC Item or Collection
*/
export type STACObject = STACItem | STACCollection;
/**
- * STAC Item including our required extensions: EO and Raster
+ * STAC Item including required extensions: EO and Raster (1.0.x) or core bands (1.1.0+)
*/
export type CompleteSTACItem = STACItem & EOExtension & RasterExtension;
/**
- * STAC Collection including our required extensions: Item Assets, EO, and Raster
+ * STAC Collection including required extensions (1.0.x) or core bands (1.1.0+)
*/
export type CompleteSTACCollection = STACCollection &
ItemAssetsDefinitionExtension &
diff --git a/test/browser/layer-tests/raster-tile-layer-specs.js b/test/browser/layer-tests/raster-tile-layer-specs.js
index 5a83f65d8..89638edd3 100644
--- a/test/browser/layer-tests/raster-tile-layer-specs.js
+++ b/test/browser/layer-tests/raster-tile-layer-specs.js
@@ -3,6 +3,14 @@
import test from 'tape';
import {KeplerGlLayers} from '@kepler.gl/layers';
+import {
+ getEOBands,
+ findAssetWithName,
+ getUsableAssets,
+ getRasterStatisticsMinMax,
+ filterAvailablePresets
+} from '@kepler.gl/layers';
+import {parseRasterMetadata} from '@kepler.gl/table';
import {testCreateCases} from 'test/helpers/layer-utils';
const {RasterTileLayer} = KeplerGlLayers;
@@ -324,3 +332,410 @@ test('#RasterTileLayer -> layer serialization', t => {
t.end();
});
+
+// ---- STAC 1.1.0 Core Bands Support Tests ----
+
+const MOCK_STAC_110_METADATA = {
+ type: 'Feature',
+ stac_version: '1.1.0',
+ stac_extensions: ['https://stac-extensions.github.io/projection/v1.1.0/schema.json'],
+ id: 'test-cog',
+ geometry: {type: 'Point', coordinates: [0, 0]},
+ bbox: [-122.5, 37.5, -122.0, 38.0],
+ links: [],
+ properties: {datetime: '2023-01-01T00:00:00Z'},
+ assets: {
+ data: {
+ href: 'https://example.com/cog.tif',
+ type: 'image/tiff; application=geotiff',
+ bands: [
+ {
+ name: 'b1',
+ 'eo:common_name': 'red',
+ data_type: 'uint8',
+ statistics: {minimum: 0, maximum: 255, mean: 128}
+ },
+ {
+ name: 'b2',
+ 'eo:common_name': 'green',
+ data_type: 'uint8',
+ statistics: {minimum: 0, maximum: 255, mean: 120}
+ },
+ {
+ name: 'b3',
+ 'eo:common_name': 'blue',
+ data_type: 'uint8',
+ statistics: {minimum: 0, maximum: 255, mean: 110}
+ }
+ ]
+ }
+ }
+};
+
+const MOCK_STAC_110_LEGACY_MIX = {
+ type: 'Feature',
+ stac_version: '1.1.0',
+ stac_extensions: [
+ 'https://stac-extensions.github.io/eo/v1.0.0/schema.json',
+ 'https://stac-extensions.github.io/raster/v1.0.0/schema.json'
+ ],
+ id: 'test-mix',
+ geometry: {type: 'Point', coordinates: [0, 0]},
+ bbox: [-122.5, 37.5, -122.0, 38.0],
+ links: [],
+ properties: {datetime: '2023-01-01T00:00:00Z'},
+ assets: {
+ visual: {
+ href: 'https://example.com/visual.tif',
+ type: 'image/tiff; application=geotiff',
+ 'eo:bands': [
+ {name: 'red', common_name: 'red'},
+ {name: 'green', common_name: 'green'},
+ {name: 'blue', common_name: 'blue'}
+ ],
+ 'raster:bands': [
+ {data_type: 'uint8', statistics: {minimum: 0, maximum: 255}},
+ {data_type: 'uint8', statistics: {minimum: 0, maximum: 255}},
+ {data_type: 'uint8', statistics: {minimum: 0, maximum: 255}}
+ ]
+ },
+ nir_core: {
+ href: 'https://example.com/nir.tif',
+ type: 'image/tiff; application=geotiff',
+ bands: [
+ {
+ name: 'nir',
+ 'eo:common_name': 'nir',
+ data_type: 'uint16',
+ statistics: {minimum: 0, maximum: 10000}
+ }
+ ]
+ }
+ }
+};
+
+test('#STAC 1.1.0 -> parseRasterMetadata accepts core bands', t => {
+ const result = parseRasterMetadata(MOCK_STAC_110_METADATA, {allowCollections: false});
+ t.ok(result, 'should return a result');
+ t.notOk(result instanceof Error, 'should not return an error for STAC 1.1.0 with core bands');
+ t.equal(result.stac_version, '1.1.0', 'should preserve stac_version');
+ t.end();
+});
+
+test('#STAC 1.1.0 -> parseRasterMetadata rejects items without bands', t => {
+ const noBands = {
+ type: 'Feature',
+ stac_version: '1.1.0',
+ stac_extensions: [],
+ id: 'no-bands',
+ geometry: {type: 'Point', coordinates: [0, 0]},
+ bbox: [-1, -1, 1, 1],
+ links: [],
+ properties: {datetime: '2023-01-01T00:00:00Z'},
+ assets: {
+ data: {
+ href: 'https://example.com/cog.tif',
+ type: 'image/tiff'
+ }
+ }
+ };
+ const result = parseRasterMetadata(noBands, {allowCollections: false});
+ t.ok(
+ result instanceof Error,
+ 'should return an error for STAC 1.1.0 without core bands or extensions'
+ );
+ t.end();
+});
+
+test('#STAC 1.1.0 -> parseRasterMetadata still accepts legacy 1.0.0', t => {
+ const legacy = {
+ type: 'Feature',
+ stac_version: '1.0.0',
+ stac_extensions: [
+ 'https://stac-extensions.github.io/eo/v1.0.0/schema.json',
+ 'https://stac-extensions.github.io/raster/v1.0.0/schema.json'
+ ],
+ id: 'legacy',
+ geometry: {type: 'Point', coordinates: [0, 0]},
+ bbox: [-1, -1, 1, 1],
+ links: [],
+ properties: {datetime: '2023-01-01T00:00:00Z'},
+ assets: {
+ red: {
+ href: 'https://example.com/red.tif',
+ 'eo:bands': [{name: 'red', common_name: 'red'}],
+ 'raster:bands': [{data_type: 'uint8'}]
+ }
+ }
+ };
+ const result = parseRasterMetadata(legacy, {allowCollections: false});
+ t.ok(result, 'should return a result');
+ t.notOk(result instanceof Error, 'should not return an error for legacy STAC 1.0.0');
+ t.end();
+});
+
+test('#STAC 1.1.0 -> getUsableAssets with core bands', t => {
+ const usable = getUsableAssets(MOCK_STAC_110_METADATA);
+ t.ok(usable.data, 'should include asset with core bands containing data_type');
+ t.equal(Object.keys(usable).length, 1, 'should return one usable asset');
+ t.end();
+});
+
+test('#STAC 1.1.0 -> getUsableAssets mixed legacy + core', t => {
+ const usable = getUsableAssets(MOCK_STAC_110_LEGACY_MIX);
+ t.ok(usable.visual, 'should include legacy asset with raster:bands');
+ t.ok(usable.nir_core, 'should include core bands asset');
+ t.equal(Object.keys(usable).length, 2, 'should return two usable assets');
+ t.end();
+});
+
+test('#STAC 1.1.0 -> getEOBands normalizes core bands', t => {
+ const bands = getEOBands(MOCK_STAC_110_METADATA);
+ t.ok(bands, 'should return bands');
+ t.equal(bands.length, 3, 'should return 3 bands');
+ t.equal(bands[0].common_name, 'red', 'should map eo:common_name to common_name for red');
+ t.equal(bands[1].common_name, 'green', 'should map eo:common_name to common_name for green');
+ t.equal(bands[2].common_name, 'blue', 'should map eo:common_name to common_name for blue');
+ t.equal(bands[0].name, 'b1', 'should preserve name');
+ t.end();
+});
+
+test('#STAC 1.1.0 -> getEOBands mixed legacy + core', t => {
+ const bands = getEOBands(MOCK_STAC_110_LEGACY_MIX);
+ t.ok(bands, 'should return bands');
+ t.equal(bands.length, 4, 'should return 4 bands (3 legacy + 1 core)');
+ const nir = bands.find(b => b.common_name === 'nir');
+ t.ok(nir, 'should include the NIR band from core bands');
+ t.end();
+});
+
+test('#STAC 1.1.0 -> findAssetWithName with core bands', t => {
+ const usable = getUsableAssets(MOCK_STAC_110_METADATA);
+ const result = findAssetWithName(usable, 'red', 'common_name');
+ t.ok(result, 'should find asset with common_name=red');
+ t.equal(result[0], 'data', 'should return asset name "data"');
+ t.equal(result[1], 0, 'should return band index 0');
+
+ const greenResult = findAssetWithName(usable, 'green', 'common_name');
+ t.ok(greenResult, 'should find asset with common_name=green');
+ t.equal(greenResult[1], 1, 'should return band index 1');
+
+ const nameResult = findAssetWithName(usable, 'b1', 'name');
+ t.ok(nameResult, 'should find asset by name=b1');
+ t.equal(nameResult[0], 'data', 'should return asset name "data"');
+ t.equal(nameResult[1], 0, 'should return band index 0');
+
+ const noResult = findAssetWithName(usable, 'nir', 'common_name');
+ t.notOk(noResult, 'should return null for missing band');
+ t.end();
+});
+
+test('#STAC 1.1.0 -> getRasterStatisticsMinMax with core bands', t => {
+ const [min, max] = getRasterStatisticsMinMax(MOCK_STAC_110_METADATA, 'singleBand', {
+ assetId: 'data'
+ });
+ t.equal(min, 0, 'should get minimum from core bands statistics');
+ t.equal(max, 255, 'should get maximum from core bands statistics');
+ t.end();
+});
+
+test('#STAC 1.1.0 -> filterAvailablePresets with core bands', t => {
+ const presetData = {
+ trueColor: {
+ id: 'trueColor',
+ commonNames: ['red', 'green', 'blue'],
+ bandCombination: 'rgb'
+ },
+ ndvi: {
+ id: 'ndvi',
+ commonNames: ['red', 'nir'],
+ bandCombination: 'normalizedDifference'
+ },
+ singleBand: {
+ id: 'singleBand',
+ commonNames: null,
+ bandCombination: 'single'
+ }
+ };
+
+ const available = filterAvailablePresets(MOCK_STAC_110_METADATA, presetData);
+ t.ok(available, 'should return available presets');
+ t.ok(available.includes('trueColor'), 'should include trueColor preset');
+ t.ok(available.includes('singleBand'), 'should include singleBand preset');
+ t.notOk(available.includes('ndvi'), 'should not include ndvi (missing nir)');
+ t.end();
+});
+
+test('#STAC 1.1.0 -> RasterTileLayer with core bands metadata handling', t => {
+ const layer = new RasterTileLayer({id: 'test-110', dataId: 'stac-110'});
+
+ const dataset = {
+ type: 'raster-tile',
+ metadata: MOCK_STAC_110_METADATA,
+ label: 'STAC 1.1.0 COG'
+ };
+
+ t.doesNotThrow(() => {
+ layer.updateLayerMeta(dataset);
+ }, 'should handle STAC 1.1.0 metadata without throwing');
+
+ const layerData = layer.formatLayerData({'stac-110': dataset});
+ t.ok(layerData, 'should return layer data for STAC 1.1.0');
+ t.equal(layerData.dataset, dataset, 'should have correct dataset');
+
+ t.end();
+});
+
+// ---- Description fallback tests ----
+
+const MOCK_STAC_DESCRIPTION_FALLBACK = {
+ type: 'Feature',
+ stac_version: '1.0.0',
+ stac_extensions: [
+ 'https://stac-extensions.github.io/eo/v1.0.0/schema.json',
+ 'https://stac-extensions.github.io/raster/v1.0.0/schema.json'
+ ],
+ id: 'description-fallback-test',
+ geometry: {type: 'Point', coordinates: [0, 0]},
+ bbox: [-1, -1, 1, 1],
+ links: [],
+ properties: {datetime: '2023-01-01T00:00:00Z'},
+ assets: {
+ data: {
+ href: 'https://example.com/cog.tif',
+ type: 'image/tiff; application=geotiff',
+ 'eo:bands': [
+ {name: 'b1', description: 'red'},
+ {name: 'b2', description: 'green'},
+ {name: 'b3', description: 'blue'}
+ ],
+ 'raster:bands': [
+ {data_type: 'uint8', statistics: {minimum: 0, maximum: 255}},
+ {data_type: 'uint8', statistics: {minimum: 0, maximum: 255}},
+ {data_type: 'uint8', statistics: {minimum: 0, maximum: 255}}
+ ]
+ }
+ }
+};
+
+const MOCK_STAC_110_DESCRIPTION_FALLBACK = {
+ type: 'Feature',
+ stac_version: '1.1.0',
+ stac_extensions: [],
+ id: 'description-fallback-110',
+ geometry: {type: 'Point', coordinates: [0, 0]},
+ bbox: [-1, -1, 1, 1],
+ links: [],
+ properties: {datetime: '2023-01-01T00:00:00Z'},
+ assets: {
+ data: {
+ href: 'https://example.com/cog.tif',
+ type: 'image/tiff; application=geotiff',
+ bands: [
+ {name: 'b1', description: 'red', data_type: 'uint8'},
+ {name: 'b2', description: 'green', data_type: 'uint8'},
+ {name: 'b3', description: 'blue', data_type: 'uint8'}
+ ]
+ }
+ }
+};
+
+test('#Description fallback -> getEOBands infers common_name from description (legacy eo:bands)', t => {
+ const bands = getEOBands(MOCK_STAC_DESCRIPTION_FALLBACK);
+ t.ok(bands, 'should return bands');
+ t.equal(bands.length, 3, 'should return 3 bands');
+ t.equal(bands[0].common_name, 'red', 'should infer red from description');
+ t.equal(bands[1].common_name, 'green', 'should infer green from description');
+ t.equal(bands[2].common_name, 'blue', 'should infer blue from description');
+ t.end();
+});
+
+test('#Description fallback -> getEOBands infers common_name from description (core bands)', t => {
+ const bands = getEOBands(MOCK_STAC_110_DESCRIPTION_FALLBACK);
+ t.ok(bands, 'should return bands');
+ t.equal(bands.length, 3, 'should return 3 bands');
+ t.equal(bands[0].common_name, 'red', 'should infer red from core band description');
+ t.equal(bands[1].common_name, 'green', 'should infer green from core band description');
+ t.equal(bands[2].common_name, 'blue', 'should infer blue from core band description');
+ t.end();
+});
+
+test('#Description fallback -> findAssetWithName uses description fallback', t => {
+ const usable = getUsableAssets(MOCK_STAC_DESCRIPTION_FALLBACK);
+ const result = findAssetWithName(usable, 'red', 'common_name');
+ t.ok(result, 'should find asset with common_name=red via description');
+ t.equal(result[0], 'data', 'should return correct asset name');
+ t.equal(result[1], 0, 'should return correct band index');
+
+ const blueResult = findAssetWithName(usable, 'blue', 'common_name');
+ t.ok(blueResult, 'should find asset with common_name=blue via description');
+ t.equal(blueResult[1], 2, 'should return band index 2 for blue');
+ t.end();
+});
+
+test('#Description fallback -> filterAvailablePresets works with description fallback', t => {
+ const presetData = {
+ trueColor: {
+ id: 'trueColor',
+ commonNames: ['red', 'green', 'blue'],
+ bandCombination: 'rgb'
+ },
+ singleBand: {
+ id: 'singleBand',
+ commonNames: null,
+ bandCombination: 'single'
+ }
+ };
+
+ const available = filterAvailablePresets(MOCK_STAC_DESCRIPTION_FALLBACK, presetData);
+ t.ok(available, 'should return available presets');
+ t.ok(available.includes('trueColor'), 'should include trueColor via description fallback');
+ t.ok(available.includes('singleBand'), 'should include singleBand');
+ t.end();
+});
+
+test('#Description fallback -> ignores non-matching descriptions', t => {
+ const stac = {
+ type: 'Feature',
+ stac_version: '1.0.0',
+ stac_extensions: [
+ 'https://stac-extensions.github.io/eo/v1.0.0/schema.json',
+ 'https://stac-extensions.github.io/raster/v1.0.0/schema.json'
+ ],
+ id: 'unknown-desc-test',
+ geometry: {type: 'Point', coordinates: [0, 0]},
+ bbox: [-1, -1, 1, 1],
+ links: [],
+ properties: {datetime: '2023-01-01T00:00:00Z'},
+ assets: {
+ data: {
+ href: 'https://example.com/cog.tif',
+ 'eo:bands': [
+ {name: 'b1', description: 'custom band'},
+ {name: 'b2', description: 'another band'}
+ ],
+ 'raster:bands': [{data_type: 'uint8'}, {data_type: 'uint8'}]
+ }
+ }
+ };
+ const bands = getEOBands(stac);
+ t.ok(bands, 'should return bands');
+ t.notOk(bands[0].common_name, 'should not infer common_name from non-standard description');
+ t.notOk(bands[1].common_name, 'should not infer common_name from non-standard description');
+ t.end();
+});
+
+// ---- Debug mode tests ----
+
+test('#RasterTileLayer -> showTileBorders default config', t => {
+ const layer = new RasterTileLayer({id: 'test-debug', dataId: 'test'});
+ t.equal(layer.config.visConfig.showTileBorders, false, 'showTileBorders should default to false');
+
+ layer.updateLayerVisConfig({showTileBorders: true});
+ t.equal(
+ layer.config.visConfig.showTileBorders,
+ true,
+ 'showTileBorders should be updatable to true'
+ );
+ t.end();
+});