Skip to content

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

fix: bitmap layer fixes (#3474)

Igor Dykhta3c0fe3f507d9
diff --git a/src/components/src/map-container.tsx b/src/components/src/map-container.tsx
index 30ce56071..22de5399e 100644
--- a/src/components/src/map-container.tsx
+++ b/src/components/src/map-container.tsx
@@ -1145,6 +1145,20 @@ export default function MapContainerFactory(
onClick={(data, event) => {
// @ts-ignore
normalizeEvent(event.srcEvent, viewport);
+
+ // Handle bitmap layer alignment mode: if a bitmap layer is waiting
+ // for a map click, route the click coordinate to it
+ if (data.coordinate) {
+ const aligningLayer = visState.layers.find(
+ (l: any) => l.type === 'bitmap' && l.alignWaitingForMap && l.config.isVisible
+ );
+ if (aligningLayer) {
+ (aligningLayer as any).onAlignMapClick(data.coordinate as [number, number]);
+ this._onRedrawNeeded(0);
+ return;
+ }
+ }
+
const res = EditorLayerUtils.onClick(data, event, {
editorMenuActive,
editor,
diff --git a/src/components/src/side-panel/layer-panel/layer-configurator.tsx b/src/components/src/side-panel/layer-panel/layer-configurator.tsx
index 45f0526f6..93d1dc4e4 100644
--- a/src/components/src/side-panel/layer-panel/layer-configurator.tsx
+++ b/src/components/src/side-panel/layer-panel/layer-configurator.tsx
@@ -171,7 +171,7 @@ const BitmapImageSourceSection: React.FC<BitmapImageSourceProps> = ({dataset, on
(dataset.metadata as BitmapDatasetMetadata).imageUrl = imageUrl;
(dataset.metadata as BitmapDatasetMetadata).isDataUri = isDataUri;
}
- // Force a layer re-render by bumping a timestamp in visConfig
+ // Force a layer re-render by bumping a no-op visConfig change
onChange({_imageTs: Date.now()});
},
[dataset, onChange]
@@ -292,6 +292,75 @@ const BitmapImageSourceSection: React.FC<BitmapImageSourceProps> = ({dataset, on
);
};
+const AlignModeContainer = styled.div`
+ padding: 8px 0;
+ font-size: 11px;
+ color: ${props => props.theme.textColor};
+`;
+
+const AlignModeStatus = styled.div<{$highlight?: boolean}>`
+ padding: 6px 8px;
+ border-radius: 4px;
+ background: ${props => props.$highlight ? props.theme.panelBackgroundHover : 'transparent'};
+ margin-bottom: 6px;
+ line-height: 1.4;
+`;
+
+const AlignModeResetButton = styled.button`
+ background: ${props => props.theme.secondaryBtnBgd};
+ color: ${props => props.theme.secondaryBtnColor};
+ border: 1px solid ${props => props.theme.secondaryBtnBgd};
+ border-radius: 4px;
+ padding: 4px 10px;
+ font-size: 11px;
+ cursor: pointer;
+ margin-top: 4px;
+ &:hover {
+ background: ${props => props.theme.secondaryBtnBgdHover};
+ }
+`;
+
+const AlignPointCount = styled.span`
+ font-weight: 600;
+ color: ${props => props.theme.activeColor};
+`;
+
+type BitmapAlignModeUIProps = {
+ layer: any;
+ onChange: (v: Record<string, any>) => void;
+};
+
+const BitmapAlignModeUI: React.FC<BitmapAlignModeUIProps> = ({layer, onChange}) => {
+ const pointCount = layer.alignControlPoints?.length || 0;
+ const waitingForMap = layer.alignWaitingForMap;
+
+ const onReset = useCallback(() => {
+ layer.resetAlignControlPoints();
+ onChange({_alignTs: Date.now()});
+ }, [layer, onChange]);
+
+ return (
+ <AlignModeContainer>
+ {waitingForMap ? (
+ <AlignModeStatus $highlight>
+ Now click the <strong>same point on the map</strong> (where it should be).
+ </AlignModeStatus>
+ ) : (
+ <AlignModeStatus $highlight>
+ Click a <strong>recognizable point on the image</strong>.
+ </AlignModeStatus>
+ )}
+ <div style={{marginTop: '4px'}}>
+ <AlignPointCount>{pointCount}</AlignPointCount> point pair{pointCount !== 1 ? 's' : ''} set
+ {pointCount >= 2 && ' — bounds auto-updated'}
+ </div>
+ {pointCount > 0 && (
+ <AlignModeResetButton onClick={onReset}>Reset Points</AlignModeResetButton>
+ )}
+ </AlignModeContainer>
+ );
+};
+
export const getLayerFields = (datasets: Datasets, layer: Layer) =>
datasets[layer.config?.dataId || ''] ? datasets[layer.config.dataId].fields : [];
@@ -1452,6 +1521,12 @@ export default function LayerConfiguratorFactory(
</div>
<VisConfigSwitch {...layer.visConfigSettings.showBounds} {...visConfiguratorProps} />
</LayerConfigGroup>
+ <LayerConfigGroup label={'layer.alignment'} collapsible>
+ <VisConfigSwitch {...layer.visConfigSettings.alignMode} {...visConfiguratorProps} />
+ {layer.config.visConfig.alignMode && (
+ <BitmapAlignModeUI layer={layer} onChange={visConfiguratorProps.onChange} />
+ )}
+ </LayerConfigGroup>
</StyledLayerVisualConfigurator>
);
}
diff --git a/src/layers/src/bitmap-layer/bitmap-layer.ts b/src/layers/src/bitmap-layer/bitmap-layer.ts
index 126f413ec..3aff1025d 100644
--- a/src/layers/src/bitmap-layer/bitmap-layer.ts
+++ b/src/layers/src/bitmap-layer/bitmap-layer.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: MIT
// Copyright contributors to the kepler.gl project
-import {BitmapLayer as DeckBitmapLayer, PathLayer} from '@deck.gl/layers';
+import {BitmapLayer as DeckBitmapLayer, PathLayer, ScatterplotLayer} from '@deck.gl/layers';
import {
EditableGeoJsonLayer,
ModifyMode,
@@ -32,6 +32,7 @@ export type BitmapLayerVisConfigSettings = {
opacity: VisConfigNumber;
showBounds: VisConfigBoolean;
editBounds: VisConfigBoolean;
+ alignMode: VisConfigBoolean;
boundsWest: VisConfigNumber;
boundsSouth: VisConfigNumber;
boundsEast: VisConfigNumber;
@@ -58,6 +59,13 @@ export const bitmapVisConfigs = {
group: 'display',
property: 'editBounds'
} as VisConfigBoolean,
+ alignMode: {
+ type: 'boolean',
+ defaultValue: false,
+ label: 'layerVisConfigs.alignMode',
+ group: 'display',
+ property: 'alignMode'
+ } as VisConfigBoolean,
boundsWest: {
type: 'number',
defaultValue: 0,
@@ -100,6 +108,11 @@ export const bitmapVisConfigs = {
} as VisConfigNumber
};
+export type AlignControlPoint = {
+ uv: [number, number]; // normalized image coordinates (0-1)
+ geo: [number, number]; // [lng, lat]
+};
+
export default class BitmapOverlayLayer extends Layer {
declare visConfigSettings: BitmapLayerVisConfigSettings;
private _editFeatureCollection: any = null;
@@ -107,16 +120,114 @@ export default class BitmapOverlayLayer extends Layer {
private _onRedrawNeeded: (() => void) | undefined;
private _rafId: number | undefined;
+ // Alignment mode state
+ alignControlPoints: AlignControlPoint[] = [];
+ alignWaitingForMap: boolean = false;
+ private _pendingUV: [number, number] | null = null;
+
constructor(props: {dataId: string; visConfig?: Record<string, any>} & Record<string, any>) {
super(props);
this.registerVisConfig(bitmapVisConfigs);
- // Apply visConfig from findDefaultLayerProps (e.g. bounds seeded from metadata)
if (props.visConfig) {
- this.updateLayerVisConfig(props.visConfig);
+ const {alignMode: _, editBounds: __, ...persistedVisConfig} = props.visConfig;
+ super.updateLayerVisConfig(persistedVisConfig);
}
this.meta = {};
}
+ validateVisConfig(_dataset: KeplerDataset, visConfig: Record<string, any>): Record<string, any> {
+ const {alignMode: _, editBounds: __, ...rest} = visConfig;
+ return rest;
+ }
+
+ // --- Alignment mode methods ---
+
+ onAlignImageClick(uv: [number, number]): void {
+ this._pendingUV = uv;
+ this.alignWaitingForMap = true;
+ }
+
+ onAlignMapClick(lngLat: [number, number]): void {
+ if (!this._pendingUV) return;
+ this.alignControlPoints = [
+ ...this.alignControlPoints,
+ {uv: this._pendingUV, geo: lngLat}
+ ];
+ this._pendingUV = null;
+ this.alignWaitingForMap = false;
+
+ if (this.alignControlPoints.length >= 2) {
+ this._computeBoundsFromControlPoints();
+ }
+ }
+
+ resetAlignControlPoints(): void {
+ this.alignControlPoints = [];
+ this.alignWaitingForMap = false;
+ this._pendingUV = null;
+ }
+
+ private _computeBoundsFromControlPoints(): void {
+ const pts = this.alignControlPoints;
+ if (pts.length < 2) return;
+
+ // Solve affine: lng = a * u + b, lat = c * v + d
+ // From 2+ points, use least squares (for 2 points, exact solution)
+ const n = pts.length;
+ let sumU = 0, sumLng = 0, sumUU = 0, sumULng = 0;
+ let sumV = 0, sumLat = 0, sumVV = 0, sumVLat = 0;
+ for (const p of pts) {
+ const [u, v] = p.uv;
+ const [lng, lat] = p.geo;
+ sumU += u; sumLng += lng; sumUU += u * u; sumULng += u * lng;
+ sumV += v; sumLat += lat; sumVV += v * v; sumVLat += v * lat;
+ }
+
+ // lng = a*u + b (solve for a, b)
+ const detU = n * sumUU - sumU * sumU;
+ if (Math.abs(detU) < 1e-12) return;
+ const a = (n * sumULng - sumU * sumLng) / detU;
+ const b = (sumLng - a * sumU) / n;
+
+ // lat = c*v + d (solve for c, d)
+ const detV = n * sumVV - sumV * sumV;
+ if (Math.abs(detV) < 1e-12) return;
+ const c = (n * sumVLat - sumV * sumLat) / detV;
+ const d = (sumLat - c * sumV) / n;
+
+ // Bounds: image corners are (0,0), (1,0), (1,1), (0,1)
+ // UV origin (0,0) = top-left of image, (1,1) = bottom-right
+ const west = b; // u=0
+ const east = a + b; // u=1
+ const north = d; // v=0 (top of image)
+ const south = c + d; // v=1 (bottom of image)
+
+ this.updateLayerVisConfig({
+ boundsWest: Math.min(west, east),
+ boundsEast: Math.max(west, east),
+ boundsSouth: Math.min(south, north),
+ boundsNorth: Math.max(south, north)
+ });
+
+ this._onRedrawNeeded?.();
+ }
+
+ updateLayerVisConfig(newVisConfig: Record<string, any>): this {
+ if ('alignMode' in newVisConfig && !newVisConfig.alignMode) {
+ this.resetAlignControlPoints();
+ }
+ // Make alignMode and editBounds mutually exclusive
+ if (newVisConfig.alignMode && this.config.visConfig.editBounds) {
+ newVisConfig.editBounds = false;
+ }
+ if (newVisConfig.editBounds && this.config.visConfig.alignMode) {
+ newVisConfig.alignMode = false;
+ this.resetAlignControlPoints();
+ }
+ super.updateLayerVisConfig(newVisConfig);
+ return this;
+ }
+
static findDefaultLayerProps(dataset: KeplerDataset): FindDefaultLayerPropsReturnValue {
if (dataset.type !== DatasetType.BITMAP) {
return {props: []};
@@ -237,7 +348,12 @@ export default class BitmapOverlayLayer extends Layer {
const {visible} = this.getDefaultDeckLayerProps(opts);
- const [west, south, east, north] = bounds as [number, number, number, number];
+ // Use live visConfig bounds (handles direct mutations from alignment mode)
+ // rather than the potentially stale cached data.bounds from formatLayerData
+ const west = visConfig.boundsWest ?? bounds[0];
+ const south = visConfig.boundsSouth ?? bounds[1];
+ const east = visConfig.boundsEast ?? bounds[2];
+ const north = visConfig.boundsNorth ?? bounds[3];
const dataBoundsKey = `${west},${south},${east},${north}`;
// Rebuild the editable feature collection only when data.bounds changes
@@ -287,24 +403,71 @@ export default class BitmapOverlayLayer extends Layer {
activeBounds = [west, south, east, north];
}
+ const isAligning = visConfig.alignMode;
+
const layers: any[] = [
new DeckBitmapLayer({
id: this.id,
image: imageUrl,
bounds: activeBounds,
opacity: visConfig.opacity ?? 1,
- pickable: false,
+ pickable: isAligning,
visible,
- parameters: {
- blend: true,
- blendColorSrcFactor: 'one',
- blendColorDstFactor: 'one-minus-src-alpha',
- blendAlphaSrcFactor: 'one',
- blendAlphaDstFactor: 'one-minus-src-alpha'
- }
+ onClick: isAligning
+ ? (info: any): boolean | undefined => {
+ if (!this.alignWaitingForMap && info.bitmap?.uv) {
+ this.onAlignImageClick(info.bitmap.uv as [number, number]);
+ this._onRedrawNeeded?.();
+ return true;
+ }
+ return undefined;
+ }
+ : undefined
})
];
+ // Visualize alignment control points
+ if (visConfig.alignMode && this.alignControlPoints.length > 0) {
+ layers.push(
+ new ScatterplotLayer({
+ id: `${this.id}-align-pts`,
+ data: this.alignControlPoints,
+ getPosition: (d: AlignControlPoint) => d.geo,
+ getFillColor: [255, 100, 100, 220],
+ getRadius: 6,
+ radiusUnits: 'pixels',
+ pickable: false,
+ visible,
+ updateTriggers: {
+ getPosition: this.alignControlPoints.length
+ }
+ })
+ );
+ }
+
+ // Visualize pending point (waiting for map click)
+ if (visConfig.alignMode && this._pendingUV) {
+ const [u, v] = this._pendingUV;
+ const [aW, aS, aE, aN] = activeBounds;
+ const pendingLng = aW + u * (aE - aW);
+ const pendingLat = aN + v * (aS - aN);
+ layers.push(
+ new ScatterplotLayer({
+ id: `${this.id}-align-pending`,
+ data: [{position: [pendingLng, pendingLat]}],
+ getPosition: (d: any) => d.position,
+ getFillColor: [100, 200, 255, 220],
+ getLineColor: [255, 255, 255, 255],
+ getRadius: 8,
+ radiusUnits: 'pixels',
+ stroked: true,
+ lineWidthMinPixels: 2,
+ pickable: false,
+ visible
+ })
+ );
+ }
+
if (visConfig.showBounds && !visConfig.editBounds) {
// Static boundary outline (no interaction)
const [aW, aS, aE, aN] = activeBounds;
diff --git a/src/localization/src/translations/en.ts b/src/localization/src/translations/en.ts
index 9e6807792..01fa4493c 100644
--- a/src/localization/src/translations/en.ts
+++ b/src/localization/src/translations/en.ts
@@ -105,6 +105,7 @@ export default {
appearance: 'Appearance',
bounds: 'Bounds',
imageSource: 'Image Source',
+ alignment: 'Alignment',
uniqueIdField: 'Unique ID Field',
type: {
point: 'point',
@@ -155,6 +156,7 @@ export default {
imageUrl: 'Image URL',
showBounds: 'Show Bounds',
editBounds: 'Drag corners to resize',
+ alignMode: 'Align to map',
boundsWest: 'West',
boundsSouth: 'South',
boundsEast: 'East',