Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.
feat: optional background stars in globe mode (#3542)
Igor Dykhta2d3a003f9381
diff --git a/src/components/src/map-container.tsx b/src/components/src/map-container.tsxindex c0c3d850a..b79595e3a 100644--- a/src/components/src/map-container.tsx+++ b/src/components/src/map-container.tsx@@ -89,6 +89,7 @@ import {getGlobeClearColor,getGlobeBasemapAttributions,resolveGlobeBasemapProvider,+ getStarsBackgroundImage,KeplerGlobeView} from '@kepler.gl/deckgl-layers';import type {GlobeAttribution} from '@kepler.gl/deckgl-layers';@@ -626,12 +627,14 @@ export default function MapContainerFactory(mapStyleBackgroundColorSelector = props => props.mapStyle.backgroundColor;globeModeSelector = props => Boolean(props.mapState?.globe?.enabled);globeBackgroundColorSelector = props => props.mapState?.globe?.config?.backgroundColor;+ globeStarsSelector = props => Boolean(props.mapState?.globe?.config?.stars);styleSelector = createSelector(this.mapStyleTypeSelector,this.mapStyleBackgroundColorSelector,this.globeModeSelector,this.globeBackgroundColorSelector,- (styleType, backgroundColor, isGlobeMode, globeBackgroundColor) => ({+ this.globeStarsSelector,+ (styleType, backgroundColor, isGlobeMode, globeBackgroundColor, globeStars) => ({...MAP_STYLE.container,...(styleType === NO_MAP_ID ? {backgroundColor: rgbToHex(backgroundColor)} : {}),// In globe mode the deck.gl canvas is transparent (the globe View uses@@ -643,7 +646,14 @@ export default function MapContainerFactory(backgroundColor: rgbToHex((globeBackgroundColor as [number, number, number]) ||(getGlobeClearColor().slice(0, 3) as [number, number, number])- )+ ),+ // Optionally overlay a tileable star-field pattern on the background.+ ...(globeStars+ ? {+ backgroundImage: `url('${getStarsBackgroundImage()}')`,+ backgroundRepeat: 'repeat'+ }+ : {})}: {})})diff --git a/src/components/src/side-panel/map-style-panel/globe-config-panel.tsx b/src/components/src/side-panel/map-style-panel/globe-config-panel.tsxindex 3c0c21183..a1e7ae194 100644--- a/src/components/src/side-panel/map-style-panel/globe-config-panel.tsx+++ b/src/components/src/side-panel/map-style-panel/globe-config-panel.tsx@@ -342,6 +342,24 @@ function GlobeConfigPanelFactory(disabled={false}/></StyledConfigRow>++ {/* Stars (rendered behind the globe in 3D space) */}+ <StyledConfigRow>+ <PanelLabelWrapper>+ <PanelHeaderAction+ className="layer-group__visibility-toggle"+ id="globe-stars-toggle"+ tooltip={globeConfig.stars ? 'tooltip.hide' : 'tooltip.show'}+ onClick={() => onToggle('stars')}+ IconComponent={globeConfig.stars ? EyeSeen : EyeUnseen}+ active={globeConfig.stars}+ flush+ />+ <LayerLabel $active={globeConfig.stars}>+ <FormattedMessage id="mapLayers.stars" />+ </LayerLabel>+ </PanelLabelWrapper>+ </StyledConfigRow></PanelContent></StyledGlobeConfigPanel>);diff --git a/src/constants/src/default-settings.ts b/src/constants/src/default-settings.tsindex c799518b4..d8debc976 100644--- a/src/constants/src/default-settings.ts+++ b/src/constants/src/default-settings.ts@@ -1392,6 +1392,7 @@ export type GlobeConfig = {surfaceColor: [number, number, number];surface: boolean;backgroundColor: [number, number, number];+ stars: boolean;};export type Globe = {@@ -1416,7 +1417,8 @@ export const DEFAULT_GLOBE_CONFIG: GlobeConfig = {surfaceColor: [9, 16, 29],// Color of the empty space rendered around the globe (deck.gl clear color).// Matches the previous hardcoded clear color [0.015, 0.035, 0.065] in 0-1 space.- backgroundColor: [4, 9, 17]+ backgroundColor: [4, 9, 17],+ stars: false};export const GLOBE_SUPPORTED_LAYERS: Record<string, boolean> = {diff --git a/src/deckgl-layers/src/globe/globe-stars-layer.ts b/src/deckgl-layers/src/globe/globe-stars-layer.tsnew file mode 100644index 000000000..29087654d--- /dev/null+++ b/src/deckgl-layers/src/globe/globe-stars-layer.ts@@ -0,0 +1,70 @@+// SPDX-License-Identifier: MIT+// Copyright contributors to the kepler.gl project++/**+ * Generates a CSS-compatible star-field background image as a data URL.+ * The stars are rendered onto an offscreen canvas, tiled seamlessly via CSS+ * `background-repeat`. The result is deterministic (seeded PRNG) and cached+ * so it's only generated once.+ */++const STAR_CANVAS_SIZE = 512;+const STAR_COUNT = 600;++// Seeded pseudo-random number generator (Park-Miller) for determinism.+function seededRandom(seed: number): () => number {+ let s = seed;+ return () => {+ s = (s * 16807) % 2147483647;+ return (s - 1) / 2147483646;+ };+}++// Transparent 1x1 PNG used as a fallback when a canvas context is unavailable+// (SSR or unsupported browser), so that `url(...)` never resolves to an empty+// value that could trigger a request for the current document.+const TRANSPARENT_PIXEL =+ 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=';++let cachedDataUrl: string | null = null;++/**+ * Returns a data URL of a tileable star-field image (512×512 PNG).+ * Generates the image once and caches it for subsequent calls.+ */+export function getStarsBackgroundImage(): string {+ if (cachedDataUrl) return cachedDataUrl;++ if (typeof document === 'undefined') {+ // SSR fallback: return a transparent 1x1 pixel to avoid url() triggering a page request+ return TRANSPARENT_PIXEL;+ }++ const canvas = document.createElement('canvas');+ canvas.width = STAR_CANVAS_SIZE;+ canvas.height = STAR_CANVAS_SIZE;+ const ctx = canvas.getContext('2d');+ if (!ctx) return (cachedDataUrl = TRANSPARENT_PIXEL);++ // Transparent background so CSS backgroundColor shows through+ ctx.clearRect(0, 0, STAR_CANVAS_SIZE, STAR_CANVAS_SIZE);++ const random = seededRandom(42);++ for (let i = 0; i < STAR_COUNT; i++) {+ const x = random() * STAR_CANVAS_SIZE;+ const y = random() * STAR_CANVAS_SIZE;+ const brightness = 140 + Math.floor(random() * 115); // 140–255+ const alpha = 0.4 + random() * 0.6; // 0.4–1.0+ const radius = 0.3 + random() * 1.0; // 0.3–1.3 px++ ctx.beginPath();+ ctx.arc(x, y, radius, 0, Math.PI * 2);+ ctx.fillStyle = `rgba(${brightness}, ${brightness}, ${brightness}, ${alpha})`;+ ctx.fill();+ }++ cachedDataUrl = canvas.toDataURL('image/png');+ return cachedDataUrl;+}+diff --git a/src/deckgl-layers/src/globe/index.ts b/src/deckgl-layers/src/globe/index.tsindex 28ea74251..57ca604fd 100644--- a/src/deckgl-layers/src/globe/index.ts+++ b/src/deckgl-layers/src/globe/index.ts@@ -50,3 +50,4 @@ export type {GlobeBasemapProvider, GlobeAttribution} from './globe-layers';export {MVTLabelLayer} from './mvt-label-layer';export {default as EnhancedMultiIconLayer} from './enhanced-multi-icon-layer';export {KeplerGlobeView} from './globe-view';+export {getStarsBackgroundImage} from './globe-stars-layer';diff --git a/src/localization/src/translations/en.ts b/src/localization/src/translations/en.tsindex 06ec9fa95..84aefb01c 100644--- a/src/localization/src/translations/en.ts+++ b/src/localization/src/translations/en.ts@@ -52,7 +52,8 @@ export default {adminBorders: 'Admin Borders',terminator: 'Day/Night',sunAzimuth: 'Sun Azimuth',- surface: 'Globe Surface'+ surface: 'Globe Surface',+ stars: 'Stars'},panel: {text: {diff --git a/src/schemas/src/schema-manager.ts b/src/schemas/src/schema-manager.tsindex 2c9d8bd60..b3da61171 100644--- a/src/schemas/src/schema-manager.ts+++ b/src/schemas/src/schema-manager.ts@@ -46,6 +46,7 @@ export type SavedMapState = {surface: boolean;surfaceColor: [number, number, number];backgroundColor: [number, number, number];+ stars?: boolean;};};};diff --git a/src/types/reducers.d.ts b/src/types/reducers.d.tsindex 4782e5aa2..9f6877d72 100644--- a/src/types/reducers.d.ts+++ b/src/types/reducers.d.ts@@ -58,6 +58,7 @@ export type MapState = {surfaceColor: [number, number, number];surface: boolean;backgroundColor: [number, number, number];+ stars: boolean;};};/** The current split map mode (single, dual, swipe) */