Skip to content

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

feat: detect extensionless COG URLs in raster tile add-data (#3723)

Igor Dykhta3c28dfd3e7ae
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 a2f40e7bc..34925fab7 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,7 +6,7 @@ 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.
- - 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.
+ - COG: provide a direct HTTPS URL to a Cloud Optimized GeoTIFF (`.tif` / `.tiff`, or an extensionless endpoint such as NextGIS Web `/cog`). 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.
@@ -19,14 +19,20 @@ Important notes for COGs via STAC:
- 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
+# Loading standalone COG 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.
+You can load a Cloud Optimized GeoTIFF directly by pasting its URL into the "Tileset metadata URL" field. kepler.gl detects COGs from:
+
+- a `.tif`, `.tiff`, or related GeoTIFF file extension
+- a path that ends with `/cog` (for example NextGIS Web COG resources)
+- the response `Content-Type` (or TIFF magic bytes) when the URL has no recognizable extension, via a HEAD request and a small ranged GET fallback
+
+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`.
+- The COG file must be publicly accessible over HTTPS. Extensionless URLs that are not a `/cog` path also need CORS so kepler.gl can read `Content-Type`.
+- If the "Raster tile servers" field is empty when you paste a COG URL, it will be auto-filled with `https://titiler.xyz`.
# Elevation
diff --git a/src/common-utils/src/url.spec.ts b/src/common-utils/src/url.spec.ts
new file mode 100644
index 000000000..3a6e5563c
--- /dev/null
+++ b/src/common-utils/src/url.spec.ts
@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+import {
+ isCOGUrl,
+ isGeoTiffContentType,
+ isTiffMagicBytes,
+ probeUrlIsCOG,
+ shouldProbeForCOG
+} from './url';
+
+const NEXTGIS_COG = 'https://nextgis-web.prod.heritagewatch.ai/api/resource/2564/cog';
+const TIF_URL = 'https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/TCI.tif';
+const TITILER_STAC = `https://titiler.xyz/cog/stac?url=${encodeURIComponent(NEXTGIS_COG)}`;
+const STAC_COLLECTION = 'https://earth-search.aws.element84.com/v1/collections/sentinel-2-l1c';
+const JSON_STAC = 'https://example.com/sdk/examples/sample-data/raster/planet-skysat-opendata.json';
+const EXTENSIONLESS = 'https://example.com/api/resource/2564/download';
+
+function mockResponse({
+ ok = true,
+ status = 200,
+ contentType,
+ body
+}: {
+ ok?: boolean;
+ status?: number;
+ contentType?: string;
+ body?: Uint8Array;
+} = {}): Response {
+ const headers = {
+ get: (name: string) => (name.toLowerCase() === 'content-type' ? contentType || null : null)
+ };
+ return {
+ ok,
+ status,
+ headers,
+ body: body
+ ? {
+ cancel: jest.fn().mockResolvedValue(undefined),
+ getReader: () => {
+ let delivered = false;
+ return {
+ read: async () => {
+ if (delivered) return {done: true, value: undefined};
+ delivered = true;
+ return {done: false, value: body};
+ },
+ cancel: async () => undefined
+ };
+ }
+ }
+ : {cancel: jest.fn().mockResolvedValue(undefined), getReader: undefined},
+ arrayBuffer: async () => (body ? body.buffer : new ArrayBuffer(0))
+ } as unknown as Response;
+}
+
+describe('isCOGUrl', () => {
+ test('matches GeoTIFF extensions', () => {
+ expect(isCOGUrl(TIF_URL)).toBe(true);
+ expect(isCOGUrl('https://example.com/file.tiff')).toBe(true);
+ expect(isCOGUrl('https://example.com/file.TIF')).toBe(true);
+ expect(isCOGUrl('https://example.com/file.geotiff')).toBe(true);
+ expect(isCOGUrl('https://example.com/file.tif?token=abc')).toBe(true);
+ expect(isCOGUrl('https://example.com/file.tif/')).toBe(true);
+ });
+
+ test('matches extensionless NextGIS-style /cog paths', () => {
+ expect(isCOGUrl(NEXTGIS_COG)).toBe(true);
+ expect(isCOGUrl(`${NEXTGIS_COG}/`)).toBe(true);
+ expect(isCOGUrl(`${NEXTGIS_COG}?download=1`)).toBe(true);
+ });
+
+ test('does not match STAC, PMTiles, or TiTiler wrappers', () => {
+ expect(isCOGUrl(STAC_COLLECTION)).toBe(false);
+ expect(isCOGUrl(JSON_STAC)).toBe(false);
+ expect(isCOGUrl(TITILER_STAC)).toBe(false);
+ expect(isCOGUrl('https://example.com/historic.pmtiles')).toBe(false);
+ expect(isCOGUrl('')).toBe(false);
+ expect(isCOGUrl(undefined)).toBe(false);
+ });
+});
+
+describe('isGeoTiffContentType', () => {
+ test('matches GeoTIFF and COG content types', () => {
+ expect(isGeoTiffContentType('image/tiff')).toBe(true);
+ expect(isGeoTiffContentType('image/tiff; application=geotiff; profile=cloud-optimized')).toBe(
+ true
+ );
+ expect(isGeoTiffContentType('image/geotiff')).toBe(true);
+ expect(isGeoTiffContentType('application/json')).toBe(false);
+ expect(isGeoTiffContentType(null)).toBe(false);
+ });
+});
+
+describe('isTiffMagicBytes', () => {
+ test('detects little-endian and big-endian classic TIFF headers', () => {
+ expect(isTiffMagicBytes(new Uint8Array([0x49, 0x49, 0x2a, 0x00]))).toBe(true);
+ expect(isTiffMagicBytes(new Uint8Array([0x4d, 0x4d, 0x00, 0x2a]))).toBe(true);
+ expect(isTiffMagicBytes(new Uint8Array([0x7b, 0x22, 0x74, 0x79]))).toBe(false);
+ expect(isTiffMagicBytes(new Uint8Array([0x49, 0x49]))).toBe(false);
+ });
+
+ test('detects little-endian and big-endian BigTIFF headers', () => {
+ // BigTIFF uses version 43 (0x2b) instead of classic TIFF's 42 (0x2a).
+ expect(isTiffMagicBytes(new Uint8Array([0x49, 0x49, 0x2b, 0x00]))).toBe(true);
+ expect(isTiffMagicBytes(new Uint8Array([0x4d, 0x4d, 0x00, 0x2b]))).toBe(true);
+ });
+});
+
+describe('shouldProbeForCOG', () => {
+ test('probes ambiguous extensionless URLs', () => {
+ expect(shouldProbeForCOG(EXTENSIONLESS)).toBe(true);
+ });
+
+ test('skips known types so STAC examples do not pay an extra HEAD', () => {
+ expect(shouldProbeForCOG(TIF_URL)).toBe(false);
+ expect(shouldProbeForCOG(NEXTGIS_COG)).toBe(false);
+ expect(shouldProbeForCOG(JSON_STAC)).toBe(false);
+ expect(shouldProbeForCOG(STAC_COLLECTION)).toBe(false);
+ expect(shouldProbeForCOG('https://example.com/file.pmtiles')).toBe(false);
+ expect(shouldProbeForCOG('not a url')).toBe(false);
+ });
+});
+
+describe('probeUrlIsCOG', () => {
+ const originalFetch = global.fetch;
+
+ afterEach(() => {
+ global.fetch = originalFetch;
+ });
+
+ test('returns true when HEAD reports a GeoTIFF Content-Type', async () => {
+ global.fetch = jest.fn(async (input, init) => {
+ expect(input).toBe(EXTENSIONLESS);
+ expect((init as RequestInit).method).toBe('HEAD');
+ return mockResponse({
+ contentType: 'image/tiff; application=geotiff; profile=cloud-optimized'
+ });
+ }) as unknown as typeof fetch;
+
+ await expect(probeUrlIsCOG(EXTENSIONLESS)).resolves.toBe(true);
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ });
+
+ test('returns false when HEAD reports JSON', async () => {
+ global.fetch = jest.fn(async () =>
+ mockResponse({contentType: 'application/json'})
+ ) as unknown as typeof fetch;
+
+ await expect(probeUrlIsCOG(EXTENSIONLESS)).resolves.toBe(false);
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ });
+
+ test('falls back to ranged GET magic bytes when HEAD fails', async () => {
+ global.fetch = jest.fn(async (_input, init) => {
+ if ((init as RequestInit).method === 'HEAD') {
+ throw new TypeError('Failed to fetch');
+ }
+ expect((init as RequestInit).headers).toEqual({Range: 'bytes=0-15'});
+ return mockResponse({
+ contentType: 'application/octet-stream',
+ body: new Uint8Array([0x49, 0x49, 0x2a, 0x00, 0x08, 0x00])
+ });
+ }) as unknown as typeof fetch;
+
+ await expect(probeUrlIsCOG(EXTENSIONLESS)).resolves.toBe(true);
+ expect(global.fetch).toHaveBeenCalledTimes(2);
+ });
+
+ test('returns false when both HEAD and GET fail', async () => {
+ global.fetch = jest.fn(async () => {
+ throw new TypeError('Failed to fetch');
+ }) as unknown as typeof fetch;
+
+ await expect(probeUrlIsCOG(EXTENSIONLESS)).resolves.toBe(false);
+ });
+
+ test('returns false when aborted', async () => {
+ const controller = new AbortController();
+ controller.abort();
+ global.fetch = jest.fn() as unknown as typeof fetch;
+ await expect(probeUrlIsCOG(EXTENSIONLESS, controller.signal)).resolves.toBe(false);
+ expect(global.fetch).not.toHaveBeenCalled();
+ });
+
+ test('returns false when the probe times out', async () => {
+ jest.useFakeTimers();
+ global.fetch = jest.fn((_input, init) => {
+ return new Promise((_resolve, reject) => {
+ const signal = (init as RequestInit | undefined)?.signal;
+ const abort = () => {
+ const err = new Error('Aborted');
+ err.name = 'AbortError';
+ reject(err);
+ };
+ if (signal?.aborted) {
+ abort();
+ return;
+ }
+ signal?.addEventListener('abort', abort);
+ });
+ }) as unknown as typeof fetch;
+
+ const promise = probeUrlIsCOG(EXTENSIONLESS, undefined, 50);
+ await jest.advanceTimersByTimeAsync(50);
+ await expect(promise).resolves.toBe(false);
+ jest.useRealTimers();
+ });
+});
diff --git a/src/common-utils/src/url.ts b/src/common-utils/src/url.ts
index 968d9164e..8ba5f2a5e 100644
--- a/src/common-utils/src/url.ts
+++ b/src/common-utils/src/url.ts
@@ -72,3 +72,198 @@ export function validateUrl(str) {
* @returns True if the URL includes '.pmtiles', otherwise false.
*/
export const isPMTilesUrl = (url?: string | null) => url?.includes('.pmtiles');
+
+const COG_EXTENSIONS = ['.tif', '.tiff', '.geotiff', '.geotif', '.gtiff', '.cog'];
+
+function getUrlPathname(url: string): string {
+ try {
+ return new URL(url).pathname.toLowerCase().replace(/\/+$/, '');
+ } catch {
+ return url.trim().toLowerCase().split(/[?#]/)[0].replace(/\/+$/, '');
+ }
+}
+
+function isAbortError(error: unknown): boolean {
+ return Boolean(
+ error &&
+ typeof error === 'object' &&
+ 'name' in error &&
+ (error as {name?: string}).name === 'AbortError'
+ );
+}
+
+/**
+ * TIFF / BigTIFF magic numbers.
+ * Classic: little-endian II*\0 or big-endian MM\0*
+ * BigTIFF: little-endian II+\0 or big-endian MM\0+
+ */
+export function isTiffMagicBytes(bytes?: ArrayBuffer | Uint8Array | null): boolean {
+ if (!bytes) return false;
+ const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+ if (view.length < 4) return false;
+ const littleEndianClassic =
+ view[0] === 0x49 && view[1] === 0x49 && view[2] === 0x2a && view[3] === 0x00;
+ const bigEndianClassic =
+ view[0] === 0x4d && view[1] === 0x4d && view[2] === 0x00 && view[3] === 0x2a;
+ const littleEndianBigTiff =
+ view[0] === 0x49 && view[1] === 0x49 && view[2] === 0x2b && view[3] === 0x00;
+ const bigEndianBigTiff =
+ view[0] === 0x4d && view[1] === 0x4d && view[2] === 0x00 && view[3] === 0x2b;
+ return littleEndianClassic || bigEndianClassic || littleEndianBigTiff || bigEndianBigTiff;
+}
+
+/**
+ * True when a Content-Type header describes GeoTIFF / Cloud Optimized GeoTIFF.
+ * Matches values such as `image/tiff; application=geotiff; profile=cloud-optimized`.
+ */
+export function isGeoTiffContentType(contentType?: string | null): boolean {
+ if (!contentType) return false;
+ const ct = contentType.toLowerCase();
+ return (
+ ct.includes('image/tiff') || ct.includes('image/geotiff') || ct.includes('application=geotiff')
+ );
+}
+
+function isJsonContentType(contentType?: string | null): boolean {
+ if (!contentType) return false;
+ const ct = contentType.toLowerCase();
+ return ct.includes('json');
+}
+
+/**
+ * Synchronous COG URL detection from the path alone.
+ * Matches GeoTIFF extensions and APIs that expose the file as a `/cog` suffix
+ * (for example NextGIS Web: `/api/resource/{id}/cog`).
+ */
+export function isCOGUrl(url?: string | null): boolean {
+ if (!url) return false;
+ const pathname = getUrlPathname(url);
+ // Already a TiTiler STAC wrapper, not a raw COG.
+ if (pathname.includes('/cog/stac')) return false;
+ if (COG_EXTENSIONS.some(ext => pathname.endsWith(ext))) return true;
+ const lastSegment = pathname.split('/').pop() || '';
+ return lastSegment === 'cog';
+}
+
+/**
+ * True when the URL is not obviously STAC/PMTiles/COG and a HEAD/range probe
+ * should be used to read Content-Type (or TIFF magic bytes).
+ */
+export function shouldProbeForCOG(url?: string | null): boolean {
+ if (!url || !validateUrl(url) || isPMTilesUrl(url) || isCOGUrl(url)) {
+ return false;
+ }
+ const pathname = getUrlPathname(url);
+ if (pathname.endsWith('.json') || pathname.endsWith('.geojson') || pathname.endsWith('.jsonl')) {
+ return false;
+ }
+ // Documented STAC collection examples; skip extra CORS-sensitive probes.
+ if (pathname.includes('/collections/') || pathname.includes('/cog/stac')) {
+ return false;
+ }
+ return true;
+}
+
+async function readResponsePrefix(response: Response, maxBytes = 16): Promise<Uint8Array | null> {
+ const reader = response.body?.getReader?.();
+ if (!reader) {
+ const buf = await response.arrayBuffer();
+ return new Uint8Array(buf.slice(0, maxBytes));
+ }
+
+ const chunks: Uint8Array[] = [];
+ let received = 0;
+ while (received < maxBytes) {
+ const {done, value} = await reader.read();
+ if (done || !value) break;
+ chunks.push(value);
+ received += value.byteLength;
+ }
+ try {
+ await reader.cancel();
+ } catch {
+ // ignore cancel errors
+ }
+ if (!chunks.length) return null;
+
+ const out = new Uint8Array(Math.min(received, maxBytes));
+ let offset = 0;
+ for (const chunk of chunks) {
+ const n = Math.min(chunk.byteLength, maxBytes - offset);
+ out.set(chunk.subarray(0, n), offset);
+ offset += n;
+ if (offset >= maxBytes) break;
+ }
+ return out;
+}
+
+function contentTypeFrom(response: Response): string | null {
+ return response.headers.get('content-type');
+}
+
+/** Default bound so a hanging HEAD/GET cannot leave Add Data probing forever. */
+export const COG_PROBE_TIMEOUT_MS = 4000;
+
+/**
+ * Probe a remote URL to decide whether it is a Cloud Optimized GeoTIFF.
+ * Tries HEAD (Content-Type) first, then a small ranged GET for magic bytes.
+ * HEAD often fails due to storage CORS settings; that is treated as a miss,
+ * not an error, and the GET fallback is attempted.
+ * The whole probe is aborted after `timeoutMs` and treated as a miss.
+ */
+export async function probeUrlIsCOG(
+ url: string,
+ signal?: AbortSignal,
+ timeoutMs: number = COG_PROBE_TIMEOUT_MS
+): Promise<boolean> {
+ if (signal?.aborted) return false;
+
+ const timeoutController = new AbortController();
+ const timeoutId = setTimeout(() => timeoutController.abort(), timeoutMs);
+ const onExternalAbort = () => timeoutController.abort();
+ signal?.addEventListener('abort', onExternalAbort);
+
+ const probeSignal = timeoutController.signal;
+
+ try {
+ try {
+ const head = await fetch(url, {method: 'HEAD', signal: probeSignal});
+ if (head.ok) {
+ const contentType = contentTypeFrom(head);
+ if (isGeoTiffContentType(contentType)) return true;
+ if (isJsonContentType(contentType)) return false;
+ }
+ } catch (error) {
+ if (isAbortError(error)) return false;
+ // Continue to ranged GET. Vector-tile form notes HEAD often fails on storage CORS.
+ }
+
+ try {
+ const response = await fetch(url, {
+ method: 'GET',
+ headers: {Range: 'bytes=0-15'},
+ signal: probeSignal
+ });
+ if (!response.ok) return false;
+
+ const contentType = contentTypeFrom(response);
+ if (isGeoTiffContentType(contentType)) {
+ response.body?.cancel?.().catch(() => undefined);
+ return true;
+ }
+ if (isJsonContentType(contentType)) {
+ response.body?.cancel?.().catch(() => undefined);
+ return false;
+ }
+
+ const prefix = await readResponsePrefix(response);
+ return isTiffMagicBytes(prefix);
+ } catch (error) {
+ if (isAbortError(error)) return false;
+ return false;
+ }
+ } finally {
+ clearTimeout(timeoutId);
+ signal?.removeEventListener('abort', onExternalAbort);
+ }
+}
diff --git a/src/common-utils/tsconfig.production.json b/src/common-utils/tsconfig.production.json
index f8ee4aa48..aa2403d41 100644
--- a/src/common-utils/tsconfig.production.json
+++ b/src/common-utils/tsconfig.production.json
@@ -24,5 +24,6 @@
"isolatedModules": true,
"baseUrl": "./src"
},
- "include": ["src"]
+ "include": ["src"],
+ "exclude": ["**/*.spec.*"]
}
diff --git a/src/components/src/hooks/use-detect-cog-url.spec.ts b/src/components/src/hooks/use-detect-cog-url.spec.ts
new file mode 100644
index 000000000..4a7d00435
--- /dev/null
+++ b/src/components/src/hooks/use-detect-cog-url.spec.ts
@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+import {act, renderHook, waitFor} from '@testing-library/react';
+
+import useDetectCOGUrl from './use-detect-cog-url';
+
+const TIF_URL = 'https://example.com/scene.tif';
+const NEXTGIS_COG = 'https://nextgis-web.prod.heritagewatch.ai/api/resource/2564/cog';
+const STAC_COLLECTION = 'https://earth-search.aws.element84.com/v1/collections/sentinel-2-l1c';
+const EXTENSIONLESS = 'https://example.com/api/resource/2564/download';
+
+describe('useDetectCOGUrl', () => {
+ const originalFetch = global.fetch;
+
+ afterEach(() => {
+ global.fetch = originalFetch;
+ jest.useRealTimers();
+ });
+
+ test('synchronously detects .tif URLs', () => {
+ const {result} = renderHook(() => useDetectCOGUrl(TIF_URL));
+ expect(result.current).toEqual({isCOG: true, probing: false});
+ });
+
+ test('synchronously detects extensionless /cog paths', () => {
+ const {result} = renderHook(() => useDetectCOGUrl(NEXTGIS_COG));
+ expect(result.current).toEqual({isCOG: true, probing: false});
+ });
+
+ test('does not probe documented STAC collection URLs', () => {
+ global.fetch = jest.fn() as unknown as typeof fetch;
+ const {result} = renderHook(() => useDetectCOGUrl(STAC_COLLECTION));
+ expect(result.current).toEqual({isCOG: false, probing: false});
+ expect(global.fetch).not.toHaveBeenCalled();
+ });
+
+ test('probes ambiguous URLs after debounce and treats GeoTIFF Content-Type as COG', async () => {
+ jest.useFakeTimers();
+ global.fetch = jest.fn(async () => {
+ return {
+ ok: true,
+ status: 200,
+ headers: {
+ get: (name: string) =>
+ name.toLowerCase() === 'content-type'
+ ? 'image/tiff; application=geotiff; profile=cloud-optimized'
+ : null
+ },
+ body: {cancel: jest.fn()}
+ } as unknown as Response;
+ }) as unknown as typeof fetch;
+
+ const {result} = renderHook(() => useDetectCOGUrl(EXTENSIONLESS, 300));
+ expect(result.current).toEqual({isCOG: false, probing: true});
+
+ await act(async () => {
+ jest.advanceTimersByTime(300);
+ });
+
+ await waitFor(() => {
+ expect(result.current).toEqual({isCOG: true, probing: false});
+ });
+ expect(global.fetch).toHaveBeenCalled();
+ });
+
+ test('does not start a probe until debounce elapses', () => {
+ jest.useFakeTimers();
+ global.fetch = jest.fn() as unknown as typeof fetch;
+
+ const {result} = renderHook(() => useDetectCOGUrl(EXTENSIONLESS, 300));
+ expect(result.current.probing).toBe(true);
+
+ act(() => {
+ jest.advanceTimersByTime(299);
+ });
+ expect(global.fetch).not.toHaveBeenCalled();
+ });
+});
diff --git a/src/components/src/hooks/use-detect-cog-url.ts b/src/components/src/hooks/use-detect-cog-url.ts
new file mode 100644
index 000000000..3f9351950
--- /dev/null
+++ b/src/components/src/hooks/use-detect-cog-url.ts
@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+import {useEffect, useState} from 'react';
+
+import {isCOGUrl, probeUrlIsCOG, shouldProbeForCOG} from '@kepler.gl/common-utils';
+
+export const COG_PROBE_DEBOUNCE_MS = 300;
+
+export type DetectCOGUrlResult = {
+ isCOG: boolean;
+ probing: boolean;
+};
+
+/**
+ * Detect whether a tileset metadata URL is a Cloud Optimized GeoTIFF.
+ * Extension and `/cog` path matches are synchronous. Ambiguous URLs are
+ * probed via HEAD / ranged GET after a short debounce so typing does not
+ * fire a request on every keystroke.
+ */
+export default function useDetectCOGUrl(
+ url: string,
+ debounceMs: number = COG_PROBE_DEBOUNCE_MS
+): DetectCOGUrlResult {
+ const syncCOG = isCOGUrl(url);
+ const needsProbe = shouldProbeForCOG(url);
+ const [probed, setProbed] = useState<{url: string; isCOG: boolean} | null>(null);
+
+ useEffect(() => {
+ if (!needsProbe || syncCOG) {
+ return;
+ }
+
+ const controller = new AbortController();
+ const timer = setTimeout(async () => {
+ const isCOG = await probeUrlIsCOG(url, controller.signal);
+ if (!controller.signal.aborted) {
+ setProbed({url, isCOG});
+ }
+ }, debounceMs);
+
+ return () => {
+ controller.abort();
+ clearTimeout(timer);
+ };
+ }, [url, needsProbe, syncCOG, debounceMs]);
+
+ if (syncCOG) {
+ return {isCOG: true, probing: false};
+ }
+ if (!needsProbe) {
+ return {isCOG: false, probing: false};
+ }
+ if (probed?.url === url) {
+ return {isCOG: probed.isCOG, probing: false};
+ }
+ return {isCOG: false, probing: true};
+}
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 1e35c9272..cca8a87bc 100644
--- a/src/components/src/modals/tilesets-modals/tileset-raster-form.tsx
+++ b/src/components/src/modals/tilesets-modals/tileset-raster-form.tsx
@@ -6,12 +6,13 @@ import styled from 'styled-components';
import {PMTilesMetadata} from '@loaders.gl/pmtiles';
-import {isPMTilesUrl, validateUrl} from '@kepler.gl/common-utils';
+import {isCOGUrl, isPMTilesUrl, validateUrl} from '@kepler.gl/common-utils';
import {DatasetType, RasterTileType, PMTilesType} from '@kepler.gl/constants';
import {JsonObjectOrArray} from '@kepler.gl/types';
import {parseRasterMetadata, parseVectorMetadata} from '@kepler.gl/table';
import {getApplicationConfig} from '@kepler.gl/utils';
+import {default as useDetectCOGUrl} from '../../hooks/use-detect-cog-url';
import {default as useFetchJson} from '../../hooks/use-fetch-raster-tile-metadata';
import {DatasetCreationAttributes, MetaResponse} from './common';
import {InputLight} from '../../common';
@@ -132,21 +133,25 @@ const RASTER_TILE_DOCUMENTATION_URL =
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)}`;
}
+function getEffectiveRasterMetadataUrl({
+ probing,
+ url,
+ isCOG
+}: {
+ probing: boolean;
+ url: string;
+ isCOG: boolean;
+}): string {
+ if (probing || !url) {
+ return '';
+ }
+ return isCOG ? getCOGMetadataUrl(url) : url;
+}
+
const RASTER_TILE_EXAMPLES = [
{
label: 'COG',
@@ -188,8 +193,12 @@ const RasterTileForm: React.FC<RasterTileFormProps> = ({setResponse}) => {
// 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 {isCOG, probing} = useDetectCOGUrl(clearedMetadataUrl);
+ const effectiveMetadataUrl = getEffectiveRasterMetadataUrl({
+ probing,
+ url: clearedMetadataUrl,
+ isCOG
+ });
const effectiveRasterTileServerUrls = isCOG ? TITILER_BASE_URL : rasterTileServerUrls;
const defaultServerUrls = (getApplicationConfig().rasterServerUrls || []).join(',');
@@ -243,9 +252,15 @@ const RasterTileForm: React.FC<RasterTileFormProps> = ({setResponse}) => {
[setRasterTileServerUrls]
);
+ useEffect(() => {
+ if (isCOG && !rasterTileServerUrls.trim()) {
+ setRasterTileServerUrls(TITILER_BASE_URL);
+ }
+ }, [isCOG, rasterTileServerUrls]);
+
const {
data: metadata,
- loading,
+ loading: metadataLoading,
error: metaError
} = useFetchJson({
url: effectiveMetadataUrl,
@@ -253,9 +268,23 @@ const RasterTileForm: React.FC<RasterTileFormProps> = ({setResponse}) => {
process: parseMetadataAllowCollections
});
+ const loading = probing || metadataLoading;
+
useEffect(() => {
+ if (probing) {
+ setResponse({
+ metadata: null,
+ dataset: null,
+ loading: true,
+ error: null
+ });
+ return;
+ }
+
if (tileName && clearedMetadataUrl) {
const pmtilesType = metadata?.pmtilesType;
+ // Known from URL before metadata loads; avoids a STAC server error flash on paste.
+ const isPMTiles = Boolean(pmtilesType) || isPMTilesUrl(clearedMetadataUrl);
if (pmtilesType === PMTilesType.MVT) {
return setResponse({
@@ -282,11 +311,12 @@ const RasterTileForm: React.FC<RasterTileFormProps> = ({setResponse}) => {
rasterTileServers.length < 1 ||
!rasterTileServers.every(server => validateUrl(server))
) {
- if (pmtilesType) {
+ if (isPMTiles) {
// For raster tiles elevation support is optional
// TODO display a warning, but not a blocking error
rasterTileServers = [];
- } else {
+ } else if (!loading) {
+ // Only show after metadata has settled; avoids a flash while STAC/COG loads.
error = new Error(
'Provide valid raster tile server urls to support STAC and elevations.'
);
@@ -318,6 +348,7 @@ const RasterTileForm: React.FC<RasterTileFormProps> = ({setResponse}) => {
metadata,
loading,
metaError,
+ probing,
tileName,
clearedMetadataUrl,
effectiveMetadataUrl,
@@ -357,7 +388,8 @@ const RasterTileForm: React.FC<RasterTileFormProps> = ({setResponse}) => {
onChange={onMetadataUrlChange}
/>
<TilesetInputDescription>
- Supports raster .pmtiles, COG (.tif) URLs, STAC Items and Collections.
+ Supports raster .pmtiles, COG URLs (including extensionless endpoints), STAC Items and
+ Collections.
</TilesetInputDescription>
</div>
{showServerInput && (
diff --git a/src/components/tsconfig.production.json b/src/components/tsconfig.production.json
index 23045f0bc..bd1a7a016 100644
--- a/src/components/tsconfig.production.json
+++ b/src/components/tsconfig.production.json
@@ -24,5 +24,6 @@
"isolatedModules": true,
"baseUrl": "./src"
},
- "include": ["src", "../deckgl-types.d.ts", "../styles/src/styled.d.ts"]
+ "include": ["src", "../deckgl-types.d.ts", "../styles/src/styled.d.ts"],
+ "exclude": ["**/*.spec.*"]
}