Skip to content

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.tsx
index 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.tsx
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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) */