Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.
feat: add experimental Flow Field layer (#3722)
Igor Dykhta5ae1530229bd
diff --git a/package.json b/package.jsonindex 29e2eefb6..3e03e0436 100644--- a/package.json+++ b/package.json@@ -73,6 +73,7 @@"start:replace-component": "yarn install-and-start examples/replace-component start:local","start:custom-theme": "yarn install-and-start examples/custom-theme start-local","start:custom-map-style": "yarn install-and-start examples/custom-map-style start-local",+ "start:custom-layer": "yarn install-and-start examples/custom-layer start","start:live-data": "node examples/live-data/esbuild.config.mjs --start","start:node-app": "yarn install-and-start examples/node-app start-local","start:web": "yarn install-and-start website start",diff --git a/src/components/src/side-panel/layer-manager.tsx b/src/components/src/side-panel/layer-manager.tsxindex 38fedc9b4..13872a623 100644--- a/src/components/src/side-panel/layer-manager.tsx+++ b/src/components/src/side-panel/layer-manager.tsx@@ -208,6 +208,7 @@ function LayerManagerFactory(const enableFlowLayer = getApplicationConfig().enableFlowLayer;const enableA5Layer = getApplicationConfig().enableA5Layer;const enableGeohashLayer = getApplicationConfig().enableGeohashLayer;+ const enableFlowFieldLayer = getApplicationConfig().enableFlowFieldLayer;const enableLayerGroups = getApplicationConfig().enableLayerGroups;const filteredLayerClasses = useMemo(() => {@@ -232,6 +233,10 @@ function LayerManagerFactory(const {geohash: _geohash, ...rest} = filteredClasses;filteredClasses = rest as LayerClassesType;}+ if (!enableFlowFieldLayer) {+ const {flowField: _flowField, ...rest} = filteredClasses;+ filteredClasses = rest as LayerClassesType;+ }return filteredClasses as LayerClassesType;}, [enableRasterTileLayer,@@ -239,6 +244,7 @@ function LayerManagerFactory(enableFlowLayer,enableA5Layer,enableGeohashLayer,+ enableFlowFieldLayer,layerClasses]);diff --git a/src/components/src/side-panel/layer-panel/dataset-layer-section.tsx b/src/components/src/side-panel/layer-panel/dataset-layer-section.tsxindex a0754c56e..1ff14ee51 100644--- a/src/components/src/side-panel/layer-panel/dataset-layer-section.tsx+++ b/src/components/src/side-panel/layer-panel/dataset-layer-section.tsx@@ -68,6 +68,7 @@ function DatasetLayerSectionFactory(const enableBitmapLayer = getApplicationConfig().enableBitmapLayer;const enableA5Layer = getApplicationConfig().enableA5Layer;const enableGeohashLayer = getApplicationConfig().enableGeohashLayer;+ const enableFlowFieldLayer = getApplicationConfig().enableFlowFieldLayer;const filteredLayerClasses = useMemo(() => {let filteredClasses = layerClasses;@@ -95,6 +96,10 @@ function DatasetLayerSectionFactory(const {geohash: _geohash, ...rest} = filteredClasses;filteredClasses = rest as LayerClassesType;}+ if (!enableFlowFieldLayer) {+ const {flowField: _flowField, ...rest} = filteredClasses;+ filteredClasses = rest as LayerClassesType;+ }return filteredClasses as LayerClassesType;}, [enableRasterTileLayer,@@ -103,6 +108,7 @@ function DatasetLayerSectionFactory(enableBitmapLayer,enableA5Layer,enableGeohashLayer,+ enableFlowFieldLayer,layerClasses]);diff --git a/src/components/src/side-panel/layer-panel/layer-column-config.tsx b/src/components/src/side-panel/layer-panel/layer-column-config.tsxindex c992f5364..e87fb5121 100644--- a/src/components/src/side-panel/layer-panel/layer-column-config.tsx+++ b/src/components/src/side-panel/layer-panel/layer-column-config.tsx@@ -1,7 +1,9 @@// SPDX-License-Identifier: MIT// Copyright contributors to the kepler.gl project-import React, {useCallback, useMemo} from 'react';+import React, {useCallback, useEffect, useMemo, useState} from 'react';+import styled from 'styled-components';+import classnames from 'classnames';import {LayerBaseConfig} from '@kepler.gl/layers';import {@@ -9,7 +11,8 @@ import {ColumnPairs,LayerColumns,ColumnLabels,- EnhancedFieldPair+ EnhancedFieldPair,+ ColumnGroup} from '@kepler.gl/types';import {toArray} from '@kepler.gl/common-utils';@@ -27,6 +30,7 @@ export type LayerColumnConfigProps<FieldOption extends MinimalField> = {columnPairs?: ColumnPairs | null;fieldPairs?: FieldPair[];columnLabels: ColumnLabels | null;+ columnGroups?: ColumnGroup[] | null;isActive: boolean;};@@ -51,6 +55,70 @@ function getValidFieldPairsSuggestionsForColumn(return null;}+function columnHasValue(column?: {value?: unknown; fieldIdx?: number}): boolean {+ return Boolean(+ column && column.value != null && typeof column.fieldIdx === 'number' && column.fieldIdx > -1+ );+}++function inferActiveColumnGroup(+ columnGroups: ColumnGroup[] | null | undefined,+ columns: LayerColumns+): string | null {+ if (!columnGroups?.length) {+ return null;+ }+ // Only infer from filled columns — never fall back to the first tab, or an+ // intentional switch to an empty group (e.g. GeoJSON) gets immediately undone.+ const withValues = columnGroups.find(group =>+ group.columns.some(key => columnHasValue(columns[key]))+ );+ return withValues?.key ?? null;+}++function clearColumnKeys(columns: LayerColumns, keys: string[]): LayerColumns {+ return keys.reduce(+ (acc, key) => ({+ ...acc,+ [key]: {+ ...acc[key],+ value: null,+ fieldIdx: -1+ }+ }),+ {...columns}+ );+}++const ColumnGroupTabs = styled.div`+ display: flex;+ border-bottom: 1px solid ${({theme}) => theme.panelBorderColor || theme.dropdownListBorderTop};+ margin-bottom: 8px;+ .column-group-tab {+ appearance: none;+ background: none;+ border: none;+ padding: 6px 0;+ margin: 0 10px 0 0;+ color: ${({theme}) => theme.subtextColor};+ border-bottom: 2px solid transparent;+ font: inherit;+ font-size: 11px;+ font-weight: 500;+ letter-spacing: 0.2px;+ &.active {+ color: ${({theme}) => theme.textColorHl};+ border-bottom-color: ${({theme}) => theme.panelToggleBorderColor};+ }+ &:hover,+ &:focus-visible {+ cursor: pointer;+ color: ${({theme}) => theme.textColorHl};+ outline: none;+ }+ }+`;+LayerColumnConfigFactory.deps = [ColumnSelectorFactory];function LayerColumnConfigFactory(ColumnSelector: ReturnType<typeof ColumnSelectorFactory>) {@@ -59,6 +127,7 @@ function LayerColumnConfigFactory(ColumnSelector: ReturnType<typeof ColumnSelectfieldPairs,columns,columnLabels,+ columnGroups,fields,updateLayerConfig,assignColumn,@@ -77,6 +146,38 @@ function LayerColumnConfigFactory(ColumnSelector: ReturnType<typeof ColumnSelect[columnPairs, fieldPairs]);+ const groupedColumnKeys = useMemo(() => {+ const keys = new Set<string>();+ (columnGroups || []).forEach(group => group.columns.forEach(key => keys.add(key)));+ return keys;+ }, [columnGroups]);++ const inferredGroupKey = useMemo(+ () => inferActiveColumnGroup(columnGroups, columns),+ [columnGroups, columns]+ );++ const [activeGroupKey, setActiveGroupKey] = useState<string | null>(+ () => inferredGroupKey || columnGroups?.[0]?.key || null+ );++ // Follow column values when they imply a different group (e.g. auto-config+ // fills GeoJSON). Do not snap back to Lat/Lng just because the active tab is empty.+ useEffect(() => {+ if (!inferredGroupKey || inferredGroupKey === activeGroupKey) {+ return;+ }+ const activeHasValues = Boolean(+ activeGroupKey &&+ columnGroups+ ?.find(g => g.key === activeGroupKey)+ ?.columns.some(key => columnHasValue(columns[key]))+ );+ if (!activeHasValues) {+ setActiveGroupKey(inferredGroupKey);+ }+ }, [inferredGroupKey, activeGroupKey, columnGroups, columns]);+const onUpdateColumn = useCallback((key, value) => {const assignedColumns =@@ -89,16 +190,138 @@ function LayerColumnConfigFactory(ColumnSelector: ReturnType<typeof ColumnSelect[updateLayerConfig, columnPairs, assignColumnPairs, assignColumn]);+ const onSelectColumnGroup = useCallback(+ (groupKey: string) => {+ if (groupKey === activeGroupKey) {+ return;+ }+ setActiveGroupKey(groupKey);++ const otherKeys = (columnGroups || [])+ .filter(group => group.key !== groupKey)+ .flatMap(group => group.columns);++ if (!otherKeys.length) {+ return;+ }++ // Start from full layer columns (assignColumn reads/returns complete config.columns).+ const base = assignColumn(otherKeys[0], null as any);+ const remaining = otherKeys.slice(1);+ updateLayerConfig({+ columns: remaining.length ? clearColumnKeys(base, remaining) : base+ });+ },+ [activeGroupKey, assignColumn, columnGroups, updateLayerConfig]+ );++ const onColumnGroupTabKeyDown = useCallback(+ (event: React.KeyboardEvent<HTMLButtonElement>, groupKey: string) => {+ if (!columnGroups?.length) {+ return;+ }+ const currentIndex = columnGroups.findIndex(group => group.key === groupKey);+ if (currentIndex < 0) {+ return;+ }++ let nextIndex = currentIndex;+ switch (event.key) {+ case 'ArrowRight':+ case 'ArrowDown':+ nextIndex = (currentIndex + 1) % columnGroups.length;+ break;+ case 'ArrowLeft':+ case 'ArrowUp':+ nextIndex = (currentIndex - 1 + columnGroups.length) % columnGroups.length;+ break;+ case 'Home':+ nextIndex = 0;+ break;+ case 'End':+ nextIndex = columnGroups.length - 1;+ break;+ case 'Enter':+ case ' ':+ event.preventDefault();+ onSelectColumnGroup(groupKey);+ return;+ default:+ return;+ }++ event.preventDefault();+ const nextKey = columnGroups[nextIndex].key;+ onSelectColumnGroup(nextKey);+ // Move focus to the newly selected tab after selection.+ const tablist = event.currentTarget.parentElement;+ const nextTab = tablist?.querySelector<HTMLElement>(`[data-column-group-tab="${nextKey}"]`);+ nextTab?.focus();+ },+ [columnGroups, onSelectColumnGroup]+ );++ const visibleColumnKeys = useMemo(() => {+ const allKeys = Object.keys(columns);+ if (!columnGroups?.length || !activeGroupKey) {+ return allKeys;+ }+ const activeGroup = columnGroups.find(group => group.key === activeGroupKey);+ const activeKeys = (activeGroup?.columns || []).filter(key => key in columns);+ const rest = allKeys.filter(key => !groupedColumnKeys.has(key));+ // Position group first, then attribute columns.+ return [...activeKeys, ...rest];+ }, [columns, columnGroups, activeGroupKey, groupedColumnKeys]);+if (!Object.keys(columns).length) {- // don't render if columns is emptyreturn <div />;}+ const tabPanelId = 'layer-column-group-panel';+return (<div>+ {columnGroups && columnGroups.length > 1 ? (+ <ColumnGroupTabs+ className="layer-config__column-groups"+ role="tablist"+ aria-label="Position columns"+ >+ {columnGroups.map(group => {+ const selected = group.key === activeGroupKey;+ const tabId = `layer-column-group-tab-${group.key}`;+ return (+ <button+ key={group.key}+ type="button"+ id={tabId}+ role="tab"+ data-column-group-tab={group.key}+ className={classnames('column-group-tab', {active: selected})}+ aria-selected={selected}+ aria-controls={tabPanelId}+ tabIndex={selected ? 0 : -1}+ onClick={() => onSelectColumnGroup(group.key)}+ onKeyDown={event => onColumnGroupTabKeyDown(event, group.key)}+ >+ {group.label}+ </button>+ );+ })}+ </ColumnGroupTabs>+ ) : null}<SidePanelSection>- <div className="layer-config__column">- {Object.keys(columns).map(key => (+ <div+ className="layer-config__column"+ id={tabPanelId}+ role={columnGroups && columnGroups.length > 1 ? 'tabpanel' : undefined}+ aria-labelledby={+ columnGroups && columnGroups.length > 1 && activeGroupKey+ ? `layer-column-group-tab-${activeGroupKey}`+ : undefined+ }+ >+ {visibleColumnKeys.map(key => (<ColumnSelectorcolumn={columns[key]}columns={columns}diff --git a/src/components/src/side-panel/layer-panel/layer-column-mode-config.tsx b/src/components/src/side-panel/layer-panel/layer-column-mode-config.tsxindex 9f45d2e12..81334ec74 100644--- a/src/components/src/side-panel/layer-panel/layer-column-mode-config.tsx+++ b/src/components/src/side-panel/layer-panel/layer-column-mode-config.tsx@@ -91,7 +91,7 @@ export type ColumnModeConfigProps = {id: string;columns: LayerColumns;renderColumnConfig: (- mode: {key: string; label: string; columns: any},+ mode: {key: string; label: string; columns: any; columnGroups?: any},selected: boolean) => JSX.Element;selectColumnMode: (mode: SupportedColumnModeConfig) => void;@@ -115,17 +115,32 @@ export function ColumnModeConfigFactory(const columnModes = useMemo(() =>supportedColumnModes- ? supportedColumnModes.map(({key, label, requiredColumns, optionalColumns}) => {- const allColumns = (requiredColumns || [])- .concat(optionalColumns || [])- .reduce((acc, k) => {- acc[k] = columns[k];- return acc;- }, {});- return {key, label, columns: allColumns};- })+ ? supportedColumnModes.map(+ ({key, label, requiredColumns, optionalColumns, columnGroups}) => {+ const groupColumns = (columnGroups || []).flatMap(group => group.columns || []);+ const requiredKeys = new Set(requiredColumns || []);+ const allColumns = (requiredColumns || [])+ .concat(optionalColumns || [])+ .concat(groupColumns)+ .reduce((acc, k) => {+ const col = columns[k];+ if (!col) {+ return acc;+ }+ // Show required * from this mode's requiredColumns (e.g. altitude in ELEVATION).+ if (requiredKeys.has(k)) {+ const {optional: _optional, ...requiredCol} = col;+ acc[k] = requiredCol;+ } else {+ acc[k] = {...col, optional: true};+ }+ return acc;+ }, {});+ return {key, label, columns: allColumns, columnGroups};+ }+ ): Object.keys(columns).length > 0- ? [{key: 'default', label: '', columns}]+ ? [{key: 'default', label: '', columns, columnGroups: undefined}]: [],[supportedColumnModes, columns]);@@ -239,13 +254,21 @@ function LayerColumnModeConfigFactory();const renderColumnConfig = useCallback(- ({key: columnMode, columns: cols}, isSelected) => (+ (+ {+ key: columnMode,+ columns: cols,+ columnGroups+ }: {key: string; label: string; columns: any; columnGroups?: any},+ isSelected: boolean+ ) => (<LayerColumnConfigcolumnPairs={layer.columnPairs}columns={cols}assignColumnPairs={layer.assignColumnPairs.bind(layer)}assignColumn={layer.assignColumn.bind(layer)}columnLabels={layer.columnLabels}+ columnGroups={columnGroups}fields={fields}fieldPairs={fieldPairs}updateLayerConfig={config =>diff --git a/src/components/src/side-panel/layer-panel/layer-configurator.tsx b/src/components/src/side-panel/layer-panel/layer-configurator.tsxindex ab3442b4a..bbb2e6f3a 100644--- a/src/components/src/side-panel/layer-panel/layer-configurator.tsx+++ b/src/components/src/side-panel/layer-panel/layer-configurator.tsx@@ -1716,6 +1716,56 @@ export default function LayerConfiguratorFactory();}+ _renderFlowFieldLayerConfig({layer, visConfiguratorProps, layerConfiguratorProps}) {+ const colorBySpeed = Boolean(layer.config.visConfig.colorBySpeed);+ return (+ <StyledLayerVisualConfigurator>+ <LayerConfigGroup label="layer.color">+ <VisConfigSwitch {...layer.visConfigSettings.colorBySpeed} {...visConfiguratorProps} />+ {colorBySpeed ? (+ <LayerColorRangeSelector {...visConfiguratorProps} property="colorRange" />+ ) : (+ <LayerColorSelector {...layerConfiguratorProps} />+ )}+ <VisConfigSlider {...layer.visConfigSettings.opacity} {...visConfiguratorProps} />+ </LayerConfigGroup>+ <LayerConfigGroup label="layerVisConfigs.flowField.streamlines" collapsible>+ <VisConfigSlider+ {...layer.visConfigSettings.linesPerScreen}+ {...visConfiguratorProps}+ />+ <VisConfigSlider {...layer.visConfigSettings.strokeWidth} {...visConfiguratorProps} />+ <VisConfigSlider {...layer.visConfigSettings.trailLength} {...visConfiguratorProps} />+ <ConfigGroupCollapsibleContent>+ <VisConfigSlider+ {...layer.visConfigSettings.zoomResponse}+ {...visConfiguratorProps}+ />+ </ConfigGroupCollapsibleContent>+ </LayerConfigGroup>+ <LayerConfigGroup label="layerVisConfigs.flowField.animation">+ <VisConfigSlider {...layer.visConfigSettings.cycleSeconds} {...visConfiguratorProps} />+ <VisConfigSlider {...layer.visConfigSettings.lineLifetime} {...visConfiguratorProps} />+ <VisConfigSwitch {...layer.visConfigSettings.seamlessLoop} {...visConfiguratorProps} />+ </LayerConfigGroup>+ <LayerConfigGroup label="layerVisConfigs.flowField.field" collapsible>+ <VisConfigSlider {...layer.visConfigSettings.smoothing} {...visConfiguratorProps} />+ <ConfigGroupCollapsibleContent>+ <VisConfigSlider+ {...layer.visConfigSettings.gridResolution}+ {...visConfiguratorProps}+ />+ <VisConfigSlider+ {...layer.visConfigSettings.elevationMultiplier}+ {...visConfiguratorProps}+ />+ <VisConfigSwitch {...layer.visConfigSettings.debugGrid} {...visConfiguratorProps} />+ </ConfigGroupCollapsibleContent>+ </LayerConfigGroup>+ </StyledLayerVisualConfigurator>+ );+ }+_renderFlowLayerConfig({layer, visConfiguratorProps}) {const {visConfig} = layer.config;const renderingModeOptions = (diff --git a/src/components/src/side-panel/layer-panel/vis-config-slider.tsx b/src/components/src/side-panel/layer-panel/vis-config-slider.tsxindex da52cd02d..76698d5d7 100644--- a/src/components/src/side-panel/layer-panel/vis-config-slider.tsx+++ b/src/components/src/side-panel/layer-panel/vis-config-slider.tsx@@ -6,6 +6,7 @@ import styled from 'styled-components';import {PanelLabel, SidePanelSection} from '../../common/styled-components';import RangeSliderFactory from '../../common/range-slider';+import InfoHelperFactory from '../../common/info-helper';import {FormattedMessage} from '@kepler.gl/localization';import {KeyEvent} from '@kepler.gl/constants';import {Checkbox} from '../..';@@ -29,12 +30,15 @@ type VisConfigSliderProps = {property: string;onChange: (v: Record<string, number | string | number[] | string[]>) => void;label?: string | ((c: LayerBaseConfig) => string);+ description?: string;range: [number, number];step?: number;isRanged: boolean;disabled?: boolean;inputTheme?: string;allowCustomValue?: boolean;+ /** i18n id or plain label for the custom-value checkbox. Defaults to "custom input". */+ customInputLabel?: string;focusRange?: [number, number];focusWeight?: number;};@@ -45,6 +49,11 @@ const InputWrapper = styled.div`margin-bottom: 12px;`;+const LabelRow = styled.div`+ display: flex;+ align-items: center;+`;+const CustomInputWrapper = styled.div`display: flex;`;@@ -151,17 +160,22 @@ const CustomInput: React.FC<CustomInputProps> = ({isRanged, value, onChangeCusto);};-VisConfigSliderFactory.deps = [RangeSliderFactory];+VisConfigSliderFactory.deps = [RangeSliderFactory, InfoHelperFactory];-export default function VisConfigSliderFactory(RangeSlider: ReturnType<typeof RangeSliderFactory>) {+export default function VisConfigSliderFactory(+ RangeSlider: ReturnType<typeof RangeSliderFactory>,+ InfoHelper: ReturnType<typeof InfoHelperFactory>+) {const VisConfigSlider: React.FC<VisConfigSliderProps> = ({- layer: {config},+ layer: {id, config},property,label,+ description,range,step,isRanged,allowCustomValue,+ customInputLabel,disabled,onChange,inputTheme,@@ -187,20 +201,27 @@ export default function VisConfigSliderFactory(RangeSlider: ReturnType<typeof Rareturn (<SidePanelSection disabled={Boolean(disabled)}>{label ? (- <PanelLabel>- {typeof label === 'string' ? (- <FormattedMessage id={label} />- ) : typeof label === 'function' ? (- <FormattedMessage id={label(config)} />- ) : (- <FormattedMessage id={`property.${property}`} />- )}- </PanelLabel>+ <LabelRow>+ <PanelLabel>+ {typeof label === 'string' ? (+ <FormattedMessage id={label} />+ ) : typeof label === 'function' ? (+ <FormattedMessage id={label(config)} />+ ) : (+ <FormattedMessage id={`property.${property}`} />+ )}+ </PanelLabel>+ {description ? (+ <InfoHelper description={description} id={`${id}-${property}-description`} />+ ) : null}+ </LabelRow>) : null}{allowCustomValue ? (<InputWrapper>- <CustomInputLabel>custom input</CustomInputLabel>+ <CustomInputLabel>+ {customInputLabel ? <FormattedMessage id={customInputLabel} /> : 'custom input'}+ </CustomInputLabel><Checkbox id={`property.${property}`} checked={custom} onChange={onChangeCheckbox} /></InputWrapper>) : null}diff --git a/src/constants/src/default-settings.ts b/src/constants/src/default-settings.tsindex d57c2cfb5..87d0d0f5d 100644--- a/src/constants/src/default-settings.ts+++ b/src/constants/src/default-settings.ts@@ -1475,7 +1475,9 @@ export const GLOBE_SUPPORTED_LAYERS: Record<string, boolean> = {tile3d: false,// Flow arrows are flat quads in common space (equatorial plane) and collapse when// viewed edge-on on the globe, so the flow layer is not supported in Globe mode.- flow: false+ flow: false,+ // Flow Field uses mercator ClipExtension bounds; stock clipping is wrong on globe.+ flowField: false};export enum MapSplitMode {diff --git a/src/constants/src/layers.ts b/src/constants/src/layers.tsindex f0c3917c9..564d9169c 100644--- a/src/constants/src/layers.ts+++ b/src/constants/src/layers.ts@@ -613,6 +613,7 @@ export const LAYER_TYPES = keyMirror({a5: null,geohash: null,flow: null,+ flowField: null,vectorTile: null,rasterTile: null,wms: null,diff --git a/src/layers/src/base-layer.ts b/src/layers/src/base-layer.tsindex 30e71ffef..5716ab2ee 100644--- a/src/layers/src/base-layer.ts+++ b/src/layers/src/base-layer.ts@@ -316,10 +316,14 @@ class Layer implements KeplerLayer {get optionalColumns(): string[] {const {supportedColumnModes} = this;if (supportedColumnModes) {- return supportedColumnModes.reduce<string[]>(- (acc, obj) => (obj.optionalColumns ? acc.concat(obj.optionalColumns) : acc),- []- );+ return supportedColumnModes.reduce<string[]>((acc, obj) => {+ const fromOptional = obj.optionalColumns || [];+ const fromGroups = (obj.columnGroups || []).reduce<string[]>(+ (groupAcc, group) => groupAcc.concat(group.columns || []),+ []+ );+ return acc.concat(fromOptional, fromGroups);+ }, []);}return [];}@@ -848,6 +852,13 @@ class Layer implements KeplerLayer {getLayerColumns(propsColumns = {}) {const columnValidators = this.columnValidators || {};+ // A column can be optional in one mode and required in another (e.g. Flow Field+ // altitude). Prefer the active mode's requiredColumns so optional does not win.+ const activeMode = this.config?.columnMode+ ? (this.supportedColumnModes || []).find(mode => mode.key === this.config.columnMode)+ : null;+ const activeRequired = new Set(activeMode?.requiredColumns || []);+const required = this.requiredLayerColumns.reduce((accu, key) => ({...accu,@@ -861,17 +872,19 @@ class Layer implements KeplerLayer {}),{});- const optional = this.optionalColumns.reduce(- (accu, key) => ({+ const optional = this.optionalColumns.reduce((accu, key) => {+ if (activeRequired.has(key)) {+ return accu;+ }+ return {...accu,[key]: {value: propsColumns[key]?.value ?? null,fieldIdx: propsColumns[key]?.fieldIdx ?? -1,optional: true}- }),- {}- );+ };+ }, {});const columns = {...required, ...optional};diff --git a/src/layers/src/flow-field-layer/flow-field-layer-icon.tsx b/src/layers/src/flow-field-layer/flow-field-layer-icon.tsxnew file mode 100644index 000000000..806f7b5ba--- /dev/null+++ b/src/layers/src/flow-field-layer/flow-field-layer-icon.tsx@@ -0,0 +1,37 @@+// SPDX-License-Identifier: MIT+// Copyright contributors to the kepler.gl project++import React from 'react';+import {Base, BaseProps} from '../base';++const FlowFieldLayerIcon: React.FC<Partial<BaseProps>> = ({+ height = '16px',+ predefinedClassName = 'flow-field-layer-icon',+ ...props+}) => (+ <Base height={height} predefinedClassName={predefinedClassName} viewBox="0 0 64 64" {...props}>+ <path+ d="M6 40 C14 36 18 28 26 26 C34 24 38 30 46 28 C52 26 56 20 60 18"+ fill="none"+ stroke="currentColor"+ strokeWidth="3"+ strokeLinecap="round"+ />+ <path+ d="M4 52 C16 50 20 42 30 40 C40 38 44 46 54 44 C58 43 60 40 62 36"+ fill="none"+ stroke="currentColor"+ strokeWidth="3"+ strokeLinecap="round"+ />+ <path+ d="M8 22 C16 18 22 12 32 14 C42 16 46 10 58 12"+ fill="none"+ stroke="currentColor"+ strokeWidth="3"+ strokeLinecap="round"+ />+ </Base>+);++export default FlowFieldLayerIcon;diff --git a/src/layers/src/flow-field-layer/flow-field-layer.ts b/src/layers/src/flow-field-layer/flow-field-layer.tsnew file mode 100644index 000000000..0703a5a06--- /dev/null+++ b/src/layers/src/flow-field-layer/flow-field-layer.ts@@ -0,0 +1,1796 @@+// SPDX-License-Identifier: MIT+// Copyright contributors to the kepler.gl project++// Flow Field / Streamlines kepler.gl layer.+// Ventusky-style animated streamlines over a lat/lng field from:+// - u/v components, or+// - speed + direction, or+// - altitude / elevation (downhill gradient → u/v).+// Positions can come from lat/lng columns or GeoJSON feature centroids.+// Rendered with deck.gl TripsLayer.+//+// Not the origin–destination Flow layer, and not @deck.gl-community geo-layers+// ParticleLayer / WindLayer (those take a station WindField).++import {WebMercatorViewport} from '@deck.gl/core';+import {ClipExtension} from '@deck.gl/extensions';+import {PathLayer, PolygonLayer} from '@deck.gl/layers';+import {TripsLayer} from '@deck.gl/geo-layers';+import {GEOJSON_FIELDS, GEOARROW_METADATA_KEY, LAYER_TYPES} from '@kepler.gl/constants';+import {default as KeplerTable} from '@kepler.gl/table';+import {Field} from '@kepler.gl/types';+import {DATA_TYPES} from 'type-analyzer';+import Layer, {LayerBaseConfigPartial} from '../base-layer';+import {getCentroidFromGeometry, parseGeoJsonRawFeature} from '../geojson-layer/geojson-utils';+import {FindDefaultLayerPropsReturnValue} from '../layer-utils';+import FlowFieldLayerIcon from './flow-field-layer-icon';++type FlowPoint = {lat: number; lng: number; u: number; v: number; alt?: number};+/** Point with a scalar height used to derive downhill u/v. */+type AltitudePoint = {lat: number; lng: number; alt: number};+type FlowTrip = {path: number[][]; timestamps: number[]; speed: number};+type FlowGrid = {+ cols: number;+ rows: number;+ lngs: number[];+ lats: number[];+ u: Float32Array;+ v: Float32Array;+ /** Terrain / height in meters; used as path Z when present. */+ alt: Float32Array | null;+ filled: Uint8Array | null;+ minSpeed: number;+ maxSpeed: number;+};++// Animate currentTime inside deck.gl so we never call kepler's onRedrawNeeded.+// That callback dispatches updateMap({}) every frame, which MapViewStateContext+// treats as an external viewport change and snaps pan/zoom back.+class AnimatedTripsLayer extends TripsLayer<any, {cycleSeconds?: number; seamlessLoop?: boolean}> {+ draw(params: any) {+ // Skip until the PathLayer model exists. Calling PathLayer.draw without it+ // (or with empty/invalid geometry mid-update) can throw and disable the layer.+ if (!this.state.model) {+ this.setNeedsRedraw();+ return;+ }+ const cycle = Math.max(1, this.props.cycleSeconds || 20);+ const phase = (performance.now() / 1000 / cycle) % 1;+ const currentTime = this.props.seamlessLoop ? 1 + phase : phase;+ const {fadeTrail, trailLength} = this.props;+ this.state.model.shaderInputs.setProps({trips: {fadeTrail, trailLength, currentTime}});+ PathLayer.prototype.draw.call(this, params);+ this.setNeedsRedraw();+ }+}++AnimatedTripsLayer.layerName = 'AnimatedTripsLayer';++const clipExtension = new ClipExtension();++export const FlowFieldColumnMode = {+ UV: 'UV',+ SPEED_DIR: 'SPEED_DIR',+ ELEVATION: 'ELEVATION'+} as const;++/** Legacy GeoJSON-specific modes; normalized to the three modes above. */+const LEGACY_GEOJSON_COLUMN_MODE = {+ GEOJSON_UV: FlowFieldColumnMode.UV,+ GEOJSON_SPEED_DIR: FlowFieldColumnMode.SPEED_DIR,+ GEOJSON_ELEVATION: FlowFieldColumnMode.ELEVATION+} as const;++const SUPPORTED_ANALYZER_TYPES = {+ [DATA_TYPES.GEOMETRY]: true,+ [DATA_TYPES.GEOMETRY_FROM_STRING]: true,+ [DATA_TYPES.PAIR_GEOMETRY_FROM_STRING]: true+};++// Position source is chosen via Lat/Lng ↔ GeoJSON tabs (columnGroups).+const POSITION_COLUMN_GROUPS = [+ {key: 'latlng', label: 'Lat / Lng', columns: ['lat', 'lng']},+ {key: 'geojson', label: 'GeoJSON', columns: ['geojson']}+];++const SUPPORTED_COLUMN_MODES = [+ {+ key: FlowFieldColumnMode.UV,+ label: 'U / V components',+ requiredColumns: ['u', 'v'],+ optionalColumns: ['altitude'],+ columnGroups: POSITION_COLUMN_GROUPS+ },+ {+ key: FlowFieldColumnMode.SPEED_DIR,+ label: 'Speed / direction',+ requiredColumns: ['speed', 'direction'],+ optionalColumns: ['altitude'],+ columnGroups: POSITION_COLUMN_GROUPS+ },+ {+ key: FlowFieldColumnMode.ELEVATION,+ label: 'Altitude (downhill)',+ requiredColumns: ['altitude'],+ optionalColumns: [],+ columnGroups: POSITION_COLUMN_GROUPS+ }+];++const COLUMN_LABELS = {+ lat: 'Lat',+ lng: 'Lng',+ geojson: 'GeoJSON',+ u: 'U (Eastward)',+ v: 'V (Northward)',+ speed: 'Speed',+ direction: 'Direction (From)',+ altitude: 'Altitude'+};++function normalizeColumnMode(mode: string | undefined): string {+ if (!mode) {+ return FlowFieldColumnMode.UV;+ }+ return LEGACY_GEOJSON_COLUMN_MODE[mode as keyof typeof LEGACY_GEOJSON_COLUMN_MODE] || mode;+}++function hasGeojsonPosition(columns: {geojson?: {fieldIdx?: number; value?: unknown}}): boolean {+ const geo = columns?.geojson;+ return Boolean(geo && typeof geo.fieldIdx === 'number' && geo.fieldIdx > -1 && geo.value);+}++function hasLatLngPosition(columns: {+ lat?: {fieldIdx?: number; value?: unknown};+ lng?: {fieldIdx?: number; value?: unknown};+}): boolean {+ const {lat, lng} = columns || {};+ return Boolean(+ lat &&+ typeof lat.fieldIdx === 'number' &&+ lat.fieldIdx > -1 &&+ lat.value &&+ lng &&+ typeof lng.fieldIdx === 'number' &&+ lng.fieldIdx > -1 &&+ lng.value+ );+}++function isElevationMode(mode: string | undefined): boolean {+ return normalizeColumnMode(mode) === FlowFieldColumnMode.ELEVATION;+}++function isSpeedDirMode(mode: string | undefined): boolean {+ return normalizeColumnMode(mode) === FlowFieldColumnMode.SPEED_DIR;+}++// Auto-detect requires exact `u` / `v` column names.+const DEFAULT_U_FIELD_NAMES = ['u'];+const DEFAULT_V_FIELD_NAMES = ['v'];+const LAT_FIELD_NAMES = ['lat', 'latitude'];+const LNG_FIELD_NAMES = ['lon', 'lng', 'long', 'longitude'];+const ALT_FIELD_NAMES = ['altitude', 'alt', 'elevation', 'elev', 'elv', 'height', 'z'];++function findNamedField(fields: Field[], names: string[]) {+ const wanted = names.map(name => name.toLowerCase());+ for (const name of wanted) {+ const field = fields.find(f => String(f.name).toLowerCase() === name);+ if (field) {+ return field;+ }+ }+ return null;+}++function fieldToColumn(field: Field | null | undefined, fields: Field[] = []) {+ if (!field) {+ return null;+ }+ const fieldIdx = Number.isInteger(field.fieldIdx) ? field.fieldIdx : fields.indexOf(field);+ return {+ value: field.name,+ fieldIdx: fieldIdx > -1 ? fieldIdx : -1+ };+}++function latLngColumnsFromDataset(dataset: KeplerTable) {+ const pair = dataset.fieldPairs?.[0]?.pair;+ if (pair?.lat && pair?.lng) {+ return {+ lat: pair.lat,+ lng: pair.lng,+ altitude: pair.altitude || null+ };+ }+ const fields = dataset.fields || [];+ const lat = fieldToColumn(findNamedField(fields, LAT_FIELD_NAMES), fields);+ const lng = fieldToColumn(findNamedField(fields, LNG_FIELD_NAMES), fields);+ if (!lat || !lng) {+ return null;+ }+ return {lat, lng, altitude: null};+}++function geojsonFieldNames(fields: Field[]): string[] {+ return fields+ .filter(+ f =>+ (f.type === 'geojson' || f.type === 'geoarrow') &&+ f.analyzerType &&+ SUPPORTED_ANALYZER_TYPES[f.analyzerType]+ )+ .map(f => f.name);+}++function getGeoArrowEncoding(field: Field | undefined): string | undefined {+ if (!field?.metadata) {+ return undefined;+ }+ if (typeof (field.metadata as Map<string, string>).get === 'function') {+ return (field.metadata as Map<string, string>).get(GEOARROW_METADATA_KEY) || undefined;+ }+ return (field.metadata as Record<string, string>)[GEOARROW_METADATA_KEY];+}++/** Centroid [lng, lat] from a raw GeoJSON / WKT / WKB cell value. */+function centroidFromRawFeature(+ rawFeature: unknown,+ geoArrowEncoding?: string | null+): [number, number] | null {+ const feature = parseGeoJsonRawFeature(rawFeature, geoArrowEncoding);+ if (!feature?.geometry) {+ return null;+ }+ const centroid = getCentroidFromGeometry(feature.geometry);+ if (!centroid || !Number.isFinite(centroid[0]) || !Number.isFinite(centroid[1])) {+ return null;+ }+ return [centroid[0], centroid[1]];+}++export const flowFieldVisConfigs = {+ opacity: {+ type: 'number',+ defaultValue: 0.55,+ label: 'layerVisConfigs.opacity',+ isRanged: false,+ range: [0, 1],+ step: 0.01,+ property: 'opacity',+ allowCustomValue: false+ },+ linesPerScreen: {+ type: 'number',+ defaultValue: 7500,+ label: 'layerVisConfigs.flowField.linesPerScreen',+ description: 'layerVisConfigs.flowField.linesPerScreenDescription',+ isRanged: false,+ range: [10, 20000],+ step: 10,+ property: 'linesPerScreen'+ },+ zoomResponse: {+ type: 'number',+ defaultValue: 0.25,+ label: 'layerVisConfigs.flowField.zoomResponse',+ description: 'layerVisConfigs.flowField.zoomResponseDescription',+ isRanged: false,+ range: [0, 1],+ step: 0.01,+ property: 'zoomResponse'+ },+ strokeWidth: {+ type: 'number',+ defaultValue: 3,+ label: 'layerVisConfigs.flowField.strokeWidth',+ isRanged: false,+ range: [0.2, 50],+ step: 0.1,+ property: 'strokeWidth',+ allowCustomValue: false+ },+ colorBySpeed: {+ type: 'boolean',+ defaultValue: false,+ label: 'layerVisConfigs.flowField.colorBySpeed',+ description: 'layerVisConfigs.flowField.colorBySpeedDescription',+ property: 'colorBySpeed'+ },+ colorRange: 'colorRange',+ trailLength: {+ type: 'number',+ defaultValue: 22,+ label: 'layerVisConfigs.flowField.trailLength',+ isRanged: false,+ range: [1, 100],+ step: 1,+ property: 'trailLength'+ },+ cycleSeconds: {+ type: 'number',+ defaultValue: 20,+ label: 'layerVisConfigs.flowField.cycle',+ description: 'layerVisConfigs.flowField.cycleDescription',+ isRanged: false,+ range: [2, 180],+ step: 1,+ property: 'cycleSeconds'+ },+ lineLifetime: {+ type: 'number',+ defaultValue: 0.55,+ label: 'layerVisConfigs.flowField.lineLifetime',+ description: 'layerVisConfigs.flowField.lineLifetimeDescription',+ isRanged: false,+ range: [0.05, 1],+ step: 0.01,+ property: 'lineLifetime'+ },+ seamlessLoop: {+ type: 'boolean',+ defaultValue: true,+ label: 'layerVisConfigs.flowField.seamlessLoop',+ description: 'layerVisConfigs.flowField.seamlessLoopDescription',+ property: 'seamlessLoop'+ },+ smoothing: {+ type: 'number',+ defaultValue: 4,+ label: 'layerVisConfigs.flowField.smoothing',+ description: 'layerVisConfigs.flowField.smoothingDescription',+ isRanged: false,+ range: [0, 12],+ step: 1,+ property: 'smoothing'+ },+ gridResolution: {+ type: 'number',+ defaultValue: 64,+ label: 'layerVisConfigs.flowField.gridResolution',+ description: 'layerVisConfigs.flowField.gridResolutionDescription',+ isRanged: false,+ range: [4, 256],+ step: 4,+ property: 'gridResolution'+ },+ elevationMultiplier: {+ type: 'number',+ defaultValue: 1,+ label: 'layerVisConfigs.flowField.elevationMultiplier',+ description: 'layerVisConfigs.flowField.elevationMultiplierDescription',+ isRanged: false,+ range: [0, 1000],+ step: 1,+ property: 'elevationMultiplier',+ allowCustomValue: true,+ customInputLabel: 'layerVisConfigs.flowField.customElevation'+ },+ debugGrid: {+ type: 'boolean',+ defaultValue: false,+ label: 'layerVisConfigs.flowField.debugGrid',+ description: 'layerVisConfigs.flowField.debugGridDescription',+ property: 'debugGrid'+ }+};++const METERS_PER_DEG_LAT = 111320;+const MAX_STEPS = 96;+const FINE_CELL = 1 / 4096;+// Cap axis size so smoothing (O(cells * radius^2)) stays interactive on the main thread.+const MIN_GRID_AXIS = 4;+const MAX_GRID_AXIS = 512;+const SETTLE_MS = 180;++function degToStride(targetDeg) {+ return Math.max(1, Math.round(targetDeg / FINE_CELL));+}++function logMix(a, b, t) {+ const la = Math.log(Math.max(a, 1e-12));+ const lb = Math.log(Math.max(b, 1e-12));+ return Math.exp(la + (lb - la) * t);+}++function parseHexColor(hex) {+ const h = String(hex || '').replace('#', '');+ if (h.length < 6) {+ return [186, 233, 223];+ }+ return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];+}++function paletteRgb(colorRange) {+ const colors = colorRange?.colors || [];+ return colors.map(c => (Array.isArray(c) ? c.slice(0, 3) : parseHexColor(c)));+}++function speedToColor(speed, minSpeed, maxSpeed, colorRange, opacity) {+ const palette = paletteRgb(colorRange);+ const alpha = Math.round(opacity * 255);+ if (!palette.length) {+ return [186, 233, 223, alpha];+ }+ if (palette.length === 1) {+ return [...palette[0], alpha];+ }+ // Map over the actual speed domain so the first and last palette colors+ // are used at min and max (not 0 → absolute max, which rarely hits the ends).+ const span = Math.max(maxSpeed - minSpeed, 1e-6);+ const t = Math.max(0, Math.min(1, (speed - minSpeed) / span));+ // Discrete bands: each palette stop owns an equal share, including endpoints.+ const i = Math.min(palette.length - 1, Math.max(0, Math.floor(t * palette.length - 1e-9)));+ const c = palette[i] || palette[0];+ return [c[0], c[1], c[2], alpha];+}++function isFiniteNumber(value) {+ return typeof value === 'number' && Number.isFinite(value);+}++/** TripsLayer crashes on undefined path points (reads position[0]). */+function isValidTrip(trip: FlowTrip | null | undefined): trip is FlowTrip {+ if (!trip?.path || !trip?.timestamps) {+ return false;+ }+ const {path, timestamps} = trip;+ if (!Array.isArray(path) || path.length < 2 || timestamps.length !== path.length) {+ return false;+ }+ for (let i = 0; i < path.length; i++) {+ const point = path[i];+ if (!point || point.length < 2 || !isFiniteNumber(point[0]) || !isFiniteNumber(point[1])) {+ return false;+ }+ if (!isFiniteNumber(timestamps[i])) {+ return false;+ }+ }+ return true;+}++function viewSignature(mapState) {+ return [+ Math.round(mapState.longitude * 1000),+ Math.round(mapState.latitude * 1000),+ Math.round(mapState.zoom * 40),+ Math.round(mapState.width || 0),+ Math.round(mapState.height || 0),+ Math.round(mapState.pitch || 0),+ Math.round(mapState.bearing || 0)+ ].join(':');+}++function hashString(value) {+ let hash = 2166136261;+ for (let i = 0; i < value.length; i++) {+ hash ^= value.charCodeAt(i);+ hash = Math.imul(hash, 16777619);+ }+ return hash >>> 0;+}++function mulberry32(seed) {+ let t = seed >>> 0;+ return () => {+ t += 0x6d2b79f5;+ let r = Math.imul(t ^ (t >>> 15), 1 | t);+ r ^= r + Math.imul(r ^ (r >>> 7), 61 | r);+ return ((r ^ (r >>> 14)) >>> 0) / 4294967296;+ };+}++function meteorologicalToUV(speed, directionDeg) {+ const rad = (directionDeg * Math.PI) / 180;+ return {+ u: -speed * Math.sin(rad),+ v: -speed * Math.cos(rad)+ };+}++function uniqueSorted(values: number[], epsilon: number) {+ const sorted = values.slice().sort((a, b) => a - b);+ const out: number[] = [];+ for (const value of sorted) {+ if (!out.length || Math.abs(value - out[out.length - 1]) > epsilon) {+ out.push(value);+ }+ }+ return out;+}++function medianSpacing(values: number[]) {+ if (values.length < 2) {+ return null;+ }+ const steps: number[] = [];+ for (let i = 1; i < values.length; i++) {+ const step = values[i] - values[i - 1];+ if (step > 0) {+ steps.push(step);+ }+ }+ if (!steps.length) {+ return null;+ }+ steps.sort((a, b) => a - b);+ return steps[Math.floor(steps.length / 2)];+}++function isRegularSpacing(values: number[], tol = 0.2) {+ const median = medianSpacing(values);+ if (median == null || !(median > 0) || values.length < 2) {+ return false;+ }+ for (let i = 1; i < values.length; i++) {+ const step = values[i] - values[i - 1];+ if (Math.abs(step - median) / median >= tol) {+ return false;+ }+ }+ return true;+}++// Rebuild a complete axis at the native cell size so missing rows/cols stay+// empty instead of collapsing the grid to only occupied coordinates.+function expandAxis(values: number[]) {+ const step = medianSpacing(values);+ if (step == null || !(step > 0) || values.length < 3) {+ return null;+ }+ const origin = values[0];+ const last = values[values.length - 1];+ const count = Math.round((last - origin) / step) + 1;+ if (count < 3 || count > MAX_GRID_AXIS) {+ return null;+ }+ let snapped = 0;+ for (const value of values) {+ const k = Math.round((value - origin) / step);+ if (Math.abs(value - (origin + k * step)) <= step * 0.25) {+ snapped++;+ }+ }+ if (snapped / values.length < 0.75) {+ return null;+ }+ return Array.from({length: count}, (_, i) => origin + i * step);+}++function snapToAxis(value, axis) {+ if (!axis || axis.length < 2) {+ return -1;+ }+ const step = axis[1] - axis[0];+ if (!(step > 0)) {+ return -1;+ }+ const k = Math.round((value - axis[0]) / step);+ if (k < 0 || k >= axis.length) {+ return -1;+ }+ if (Math.abs(value - axis[k]) > step * 0.35) {+ return -1;+ }+ return k;+}++function boxBlur(grid, radius) {+ if (radius <= 0) {+ return grid;+ }+ const {cols, rows, u, v, alt, filled} = grid;+ // Bound work: dense grids with large radius can freeze the UI on format.+ const cellCount = cols * rows;+ const maxRadius = cellCount > 120_000 ? 2 : cellCount > 40_000 ? 3 : 12;+ const r = Math.min(Math.max(1, Math.round(radius)), maxRadius);+ const nextU = new Float32Array(u.length);+ const nextV = new Float32Array(v.length);+ const nextAlt = alt ? new Float32Array(alt.length) : null;+ const nextFilled = filled ? new Uint8Array(filled) : null;+ for (let row = 0; row < rows; row++) {+ for (let col = 0; col < cols; col++) {+ const i = row * cols + col;+ // Smooth existing samples only. Empty cells stay empty so the field+ // cannot grow into regions with no points.+ if (filled && !filled[i]) {+ continue;+ }+ let su = 0;+ let sv = 0;+ let sa = 0;+ let n = 0;+ for (let dy = -r; dy <= r; dy++) {+ const y = row + dy;+ if (y < 0 || y >= rows) continue;+ for (let dx = -r; dx <= r; dx++) {+ const x = col + dx;+ if (x < 0 || x >= cols) continue;+ const j = y * cols + x;+ if (filled && !filled[j]) continue;+ su += u[j];+ sv += v[j];+ if (alt) sa += alt[j];+ n++;+ }+ }+ if (n) {+ nextU[i] = su / n;+ nextV[i] = sv / n;+ if (nextAlt) nextAlt[i] = sa / n;+ }+ }+ }+ let minSpeed = Infinity;+ let maxSpeed = 0;+ const mask = nextFilled || filled;+ for (let i = 0; i < nextU.length; i++) {+ if (mask && !mask[i]) continue;+ const speed = Math.hypot(nextU[i], nextV[i]);+ minSpeed = Math.min(minSpeed, speed);+ maxSpeed = Math.max(maxSpeed, speed);+ }+ return {+ ...grid,+ u: nextU,+ v: nextV,+ alt: nextAlt || alt || null,+ filled: nextFilled || filled,+ minSpeed: Number.isFinite(minSpeed) ? minSpeed : 0,+ maxSpeed: maxSpeed || 1+ };+}++/**+ * Downhill flow from a gridded elevation field (same idea as the+ * scripts/flow-field-from-elevation helper): u = -∂z/∂x, v = -∂z/∂y.+ */+function elevationFieldToUV(+ z: Float32Array,+ filled: Uint8Array,+ cols: number,+ rows: number,+ lngs: number[],+ lats: number[]+): {u: Float32Array; v: Float32Array; minSpeed: number; maxSpeed: number} {+ const u = new Float32Array(cols * rows);+ const v = new Float32Array(cols * rows);+ const outFilled = new Uint8Array(cols * rows);+ const dlat = rows > 1 ? lats[1] - lats[0] : 1;+ const dlng = cols > 1 ? lngs[1] - lngs[0] : 1;+ let minSpeed = Infinity;+ let maxSpeed = 0;++ for (let ri = 0; ri < rows; ri++) {+ const mEast = METERS_PER_DEG_LAT * Math.max(0.2, Math.cos((lats[ri] * Math.PI) / 180)) * dlng;+ const mNorth = METERS_PER_DEG_LAT * dlat;+ for (let ci = 0; ci < cols; ci++) {+ const i = ri * cols + ci;+ if (!filled[i] || !Number.isFinite(z[i])) continue;++ let dzDlng: number | null = null;+ if (ci > 0 && ci < cols - 1 && filled[i - 1] && filled[i + 1]) {+ dzDlng = (z[i + 1] - z[i - 1]) / (2 * mEast);+ } else if (ci < cols - 1 && filled[i + 1]) {+ dzDlng = (z[i + 1] - z[i]) / mEast;+ } else if (ci > 0 && filled[i - 1]) {+ dzDlng = (z[i] - z[i - 1]) / mEast;+ }++ let dzDlat: number | null = null;+ if (ri > 0 && ri < rows - 1 && filled[i - cols] && filled[i + cols]) {+ dzDlat = (z[i + cols] - z[i - cols]) / (2 * mNorth);+ } else if (ri < rows - 1 && filled[i + cols]) {+ dzDlat = (z[i + cols] - z[i]) / mNorth;+ } else if (ri > 0 && filled[i - cols]) {+ dzDlat = (z[i] - z[i - cols]) / mNorth;+ }++ if (dzDlng == null || dzDlat == null) continue;++ const uu = -dzDlng;+ const vv = -dzDlat;+ u[i] = uu;+ v[i] = vv;+ outFilled[i] = 1;+ const speed = Math.hypot(uu, vv);+ minSpeed = Math.min(minSpeed, speed);+ maxSpeed = Math.max(maxSpeed, speed);+ }+ }++ // Reuse filled mask: cells that had elevation but no gradient stay empty.+ for (let i = 0; i < filled.length; i++) {+ if (!outFilled[i]) {+ filled[i] = 0;+ }+ }++ return {+ u,+ v,+ minSpeed: Number.isFinite(minSpeed) ? minSpeed : 0,+ maxSpeed: maxSpeed || 1+ };+}++function computeBinCounts(+ minLng: number,+ maxLng: number,+ minLat: number,+ maxLat: number,+ gridResolution: number+) {+ const res = Math.max(MIN_GRID_AXIS, Math.min(MAX_GRID_AXIS, Math.round(gridResolution || 64)));+ const lngSpan = Math.max(1e-9, maxLng - minLng);+ const latSpan = Math.max(1e-9, maxLat - minLat);+ if (lngSpan >= latSpan) {+ return {+ binsX: res,+ binsY: Math.max(MIN_GRID_AXIS, Math.min(MAX_GRID_AXIS, Math.round((res * latSpan) / lngSpan)))+ };+ }+ return {+ binsX: Math.max(MIN_GRID_AXIS, Math.min(MAX_GRID_AXIS, Math.round((res * lngSpan) / latSpan))),+ binsY: res+ };+}++/** Bounds without Math.min/max spread (avoids RangeError on large grids). */+function boundsFromPoints(points: {lat: number; lng: number}[]) {+ let minLng = Infinity;+ let maxLng = -Infinity;+ let minLat = Infinity;+ let maxLat = -Infinity;+ for (const p of points) {+ if (p.lng < minLng) minLng = p.lng;+ if (p.lng > maxLng) maxLng = p.lng;+ if (p.lat < minLat) minLat = p.lat;+ if (p.lat > maxLat) maxLat = p.lat;+ }+ return {minLng, maxLng, minLat, maxLat};+}++function buildElevationScalarGrid(+ points: AltitudePoint[],+ gridResolution = 64+): {+ cols: number;+ rows: number;+ lngs: number[];+ lats: number[];+ z: Float32Array;+ filled: Uint8Array;+} | null {+ if (points.length < 4) {+ return null;+ }++ const lats = uniqueSorted(+ points.map(p => p.lat),+ 1e-6+ );+ const lngs = uniqueSorted(+ points.map(p => p.lng),+ 1e-6+ );++ const expandedLats = expandAxis(lats);+ const expandedLngs = expandAxis(lngs);+ const latAxis = expandedLats || (isRegularSpacing(lats) ? lats : null);+ const lngAxis = expandedLngs || (isRegularSpacing(lngs) ? lngs : null);+ const looksRegular = Boolean(+ latAxis &&+ lngAxis &&+ latAxis.length >= 2 &&+ lngAxis.length >= 2 &&+ (expandedLats || expandedLngs || latAxis.length * lngAxis.length <= points.length * 1.4)+ );++ // Keep the native regular grid when it is already coarser than the target.+ if (+ looksRegular &&+ latAxis &&+ lngAxis &&+ Math.max(latAxis.length, lngAxis.length) <= gridResolution+ ) {+ const rows = latAxis.length;+ const cols = lngAxis.length;+ const z = new Float32Array(cols * rows);+ const filled = new Uint8Array(cols * rows);+ for (const p of points) {+ const ri = snapToAxis(p.lat, latAxis);+ const ci = snapToAxis(p.lng, lngAxis);+ if (ri < 0 || ci < 0 || !Number.isFinite(p.alt)) continue;+ const i = ri * cols + ci;+ z[i] = p.alt;+ filled[i] = 1;+ }+ return {cols, rows, lngs: lngAxis, lats: latAxis, z, filled};+ }++ const {minLng, maxLng, minLat, maxLat} = boundsFromPoints(points);+ const {binsX, binsY} = computeBinCounts(minLng, maxLng, minLat, maxLat, gridResolution);+ const zSum = new Float32Array(binsX * binsY);+ const filled = new Uint8Array(binsX * binsY);+ const counts = new Uint32Array(binsX * binsY);+ for (const p of points) {+ if (!Number.isFinite(p.alt)) continue;+ const ci = Math.min(binsX - 1, Math.floor(((p.lng - minLng) / (maxLng - minLng || 1)) * binsX));+ const ri = Math.min(binsY - 1, Math.floor(((p.lat - minLat) / (maxLat - minLat || 1)) * binsY));+ const i = ri * binsX + ci;+ zSum[i] += p.alt;+ counts[i]++;+ }+ const z = new Float32Array(binsX * binsY);+ for (let i = 0; i < zSum.length; i++) {+ if (counts[i]) {+ z[i] = zSum[i] / counts[i];+ filled[i] = 1;+ }+ }+ const scatterLngs = Array.from(+ {length: binsX},+ (_, i) => minLng + ((maxLng - minLng) * i) / Math.max(1, binsX - 1)+ );+ const scatterLats = Array.from(+ {length: binsY},+ (_, i) => minLat + ((maxLat - minLat) * i) / Math.max(1, binsY - 1)+ );+ return {cols: binsX, rows: binsY, lngs: scatterLngs, lats: scatterLats, z, filled};+}++function buildGridFromAltitude(+ points: AltitudePoint[],+ smoothing: number,+ gridResolution = 64+): FlowGrid | null {+ const scalar = buildElevationScalarGrid(points, gridResolution);+ if (!scalar) {+ return null;+ }+ const {cols, rows, lngs, lats, z, filled} = scalar;+ const {u, v, minSpeed, maxSpeed} = elevationFieldToUV(z, filled, cols, rows, lngs, lats);+ return boxBlur(+ {+ cols,+ rows,+ lngs,+ lats,+ u,+ v,+ // Keep the height field so streamlines follow terrain in Z, not just slope in UV.+ alt: z,+ filled,+ minSpeed,+ maxSpeed+ },+ smoothing+ );+}++function buildGrid(points: FlowPoint[], smoothing: number, gridResolution = 64): FlowGrid | null {+ if (points.length < 4) {+ return null;+ }++ const lats = uniqueSorted(+ points.map(p => p.lat),+ 1e-6+ );+ const lngs = uniqueSorted(+ points.map(p => p.lng),+ 1e-6+ );++ const expandedLats = expandAxis(lats);+ const expandedLngs = expandAxis(lngs);+ const latAxis = expandedLats || (isRegularSpacing(lats) ? lats : null);+ const lngAxis = expandedLngs || (isRegularSpacing(lngs) ? lngs : null);+ const looksRegular = Boolean(+ latAxis &&+ lngAxis &&+ latAxis.length >= 2 &&+ lngAxis.length >= 2 &&+ (expandedLats || expandedLngs || latAxis.length * lngAxis.length <= points.length * 1.4)+ );++ if (+ looksRegular &&+ latAxis &&+ lngAxis &&+ Math.max(latAxis.length, lngAxis.length) <= gridResolution+ ) {+ const rows = latAxis.length;+ const cols = lngAxis.length;+ const u = new Float32Array(cols * rows);+ const v = new Float32Array(cols * rows);+ const alt = new Float32Array(cols * rows);+ const filled = new Uint8Array(cols * rows);+ let minSpeed = Infinity;+ let maxSpeed = 0;+ let hasAlt = false;+ for (const p of points) {+ const ri = snapToAxis(p.lat, latAxis);+ const ci = snapToAxis(p.lng, lngAxis);+ if (ri < 0 || ci < 0) continue;+ const i = ri * cols + ci;+ u[i] = p.u;+ v[i] = p.v;+ if (Number.isFinite(p.alt)) {+ alt[i] = p.alt as number;+ hasAlt = true;+ }+ filled[i] = 1;+ const speed = Math.hypot(p.u, p.v);+ minSpeed = Math.min(minSpeed, speed);+ maxSpeed = Math.max(maxSpeed, speed);+ }+ return boxBlur(+ {+ cols,+ rows,+ lngs: lngAxis,+ lats: latAxis,+ u,+ v,+ alt: hasAlt ? alt : null,+ filled,+ minSpeed: Number.isFinite(minSpeed) ? minSpeed : 0,+ maxSpeed: maxSpeed || 1+ },+ smoothing+ );+ }++ // Scatter / downsample into a target-resolution grid.+ const {minLng, maxLng, minLat, maxLat} = boundsFromPoints(points);+ const {binsX, binsY} = computeBinCounts(minLng, maxLng, minLat, maxLat, gridResolution);+ const su = new Float32Array(binsX * binsY);+ const sv = new Float32Array(binsX * binsY);+ const sa = new Float32Array(binsX * binsY);+ const filled = new Uint8Array(binsX * binsY);+ const counts = new Uint32Array(binsX * binsY);+ let hasAlt = false;+ for (const p of points) {+ const ci = Math.min(binsX - 1, Math.floor(((p.lng - minLng) / (maxLng - minLng || 1)) * binsX));+ const ri = Math.min(binsY - 1, Math.floor(((p.lat - minLat) / (maxLat - minLat || 1)) * binsY));+ const i = ri * binsX + ci;+ su[i] += p.u;+ sv[i] += p.v;+ if (Number.isFinite(p.alt)) {+ sa[i] += p.alt as number;+ hasAlt = true;+ }+ counts[i]++;+ }+ let minSpeed = Infinity;+ let maxSpeed = 0;+ for (let i = 0; i < su.length; i++) {+ if (counts[i]) {+ su[i] /= counts[i];+ sv[i] /= counts[i];+ sa[i] /= counts[i];+ filled[i] = 1;+ const speed = Math.hypot(su[i], sv[i]);+ minSpeed = Math.min(minSpeed, speed);+ maxSpeed = Math.max(maxSpeed, speed);+ }+ }+ const scatterLngs = Array.from(+ {length: binsX},+ (_, i) => minLng + ((maxLng - minLng) * i) / Math.max(1, binsX - 1)+ );+ const scatterLats = Array.from(+ {length: binsY},+ (_, i) => minLat + ((maxLat - minLat) * i) / Math.max(1, binsY - 1)+ );+ return boxBlur(+ {+ cols: binsX,+ rows: binsY,+ lngs: scatterLngs,+ lats: scatterLats,+ u: su,+ v: sv,+ alt: hasAlt ? sa : null,+ filled,+ minSpeed: Number.isFinite(minSpeed) ? minSpeed : 0,+ maxSpeed: maxSpeed || 1+ },+ smoothing+ );+}++function findSpan(values, x) {+ let lo = 0;+ let hi = values.length - 1;+ if (hi < 1 || x < values[0] || x > values[hi]) {+ return -1;+ }+ while (hi - lo > 1) {+ const mid = (lo + hi) >> 1;+ if (values[mid] <= x) lo = mid;+ else hi = mid;+ }+ return lo;+}++function sampleField(grid, lng, lat) {+ const {lngs, lats, cols, rows, u, v, alt, filled} = grid;+ const ci = findSpan(lngs, lng);+ const ri = findSpan(lats, lat);+ if (ci < 0 || ri < 0 || ci >= cols - 1 || ri >= rows - 1) {+ return null;+ }+ const i00 = ri * cols + ci;+ const i10 = ri * cols + ci + 1;+ const i01 = (ri + 1) * cols + ci;+ const i11 = (ri + 1) * cols + ci + 1;+ const lng0 = lngs[ci];+ const lng1 = lngs[ci + 1];+ const lat0 = lats[ri];+ const lat1 = lats[ri + 1];+ const tx = (lng - lng0) / (lng1 - lng0 || 1);+ const ty = (lat - lat0) / (lat1 - lat0 || 1);+ const corners = [+ {i: i00, w: (1 - tx) * (1 - ty)},+ {i: i10, w: tx * (1 - ty)},+ {i: i01, w: (1 - tx) * ty},+ {i: i11, w: tx * ty}+ ];+ // Prefer fully filled quads. For sparse scatter grids, fall back to the+ // filled corners of this cell (renormalized) so streamlines still appear.+ const usable = filled ? corners.filter(c => filled[c.i]) : corners;+ if (!usable.length) {+ return null;+ }+ let wSum = 0;+ let uu = 0;+ let vv = 0;+ let aa = 0;+ for (const c of usable) {+ wSum += c.w;+ uu += u[c.i] * c.w;+ vv += v[c.i] * c.w;+ if (alt) aa += alt[c.i] * c.w;+ }+ if (wSum < 1e-8) {+ const c = usable[0];+ return {u: u[c.i], v: v[c.i], alt: alt ? alt[c.i] : 0};+ }+ uu /= wSum;+ vv /= wSum;+ aa = alt ? aa / wSum : 0;+ if (!Number.isFinite(uu) || !Number.isFinite(vv)) {+ return null;+ }+ return {u: uu, v: vv, alt: Number.isFinite(aa) ? aa : 0};+}++function viewportBounds(mapState) {+ try {+ const viewport = new WebMercatorViewport({+ width: mapState.width || 800,+ height: mapState.height || 600,+ longitude: mapState.longitude,+ latitude: mapState.latitude,+ zoom: mapState.zoom,+ pitch: mapState.pitch || 0,+ bearing: mapState.bearing || 0+ });+ const [west, south, east, north] = viewport.getBounds();+ return {minLng: west, minLat: south, maxLng: east, maxLat: north};+ } catch {+ return {+ minLng: mapState.longitude - 10,+ minLat: mapState.latitude - 6,+ maxLng: mapState.longitude + 10,+ maxLat: mapState.latitude + 6+ };+ }+}++function fieldBounds(grid) {+ if (!grid?.lngs?.length || !grid?.lats?.length) {+ return null;+ }+ return {+ minLng: grid.lngs[0],+ maxLng: grid.lngs[grid.cols - 1],+ minLat: grid.lats[0],+ maxLat: grid.lats[grid.rows - 1]+ };+}++function advance(grid, lng, lat, dt, sign) {+ const s0 = sampleField(grid, lng, lat);+ if (!s0) return null;+ if (Math.hypot(s0.u, s0.v) < 1e-6) return null;+ const metersPerDegLng = METERS_PER_DEG_LAT * Math.max(0.2, Math.cos((lat * Math.PI) / 180));+ const midLng = lng + (sign * s0.u * dt * 0.5) / metersPerDegLng;+ const midLat = lat + (sign * s0.v * dt * 0.5) / METERS_PER_DEG_LAT;+ const s1 = sampleField(grid, midLng, midLat);+ if (!s1) return null;+ const metersMid = METERS_PER_DEG_LAT * Math.max(0.2, Math.cos((midLat * Math.PI) / 180));+ const nextLng = lng + (sign * s1.u * dt) / metersMid;+ const nextLat = lat + (sign * s1.v * dt) / METERS_PER_DEG_LAT;+ if (!sampleField(grid, nextLng, nextLat)) return null;+ return {lng: nextLng, lat: nextLat};+}++function integrateDir(+ grid: FlowGrid,+ startLng: number,+ startLat: number,+ dt: number,+ sign: number,+ maxTravel: number+) {+ const path: number[][] = [];+ let lng = startLng;+ let lat = startLat;+ for (let step = 0; step < MAX_STEPS; step++) {+ if (!isFiniteNumber(lng) || !isFiniteNumber(lat)) break;+ const sample = sampleField(grid, lng, lat);+ if (!sample) break;+ path.push([lng, lat, sample.alt || 0]);+ const next = advance(grid, lng, lat, dt, sign);+ if (!next) break;+ if (!isFiniteNumber(next.lng) || !isFiniteNumber(next.lat)) break;+ // Stop before antimeridian jumps; wrapLongitude + TripsLayer is unsafe.+ if (Math.abs(next.lng - lng) > 180) break;+ if (Math.abs(next.lng - startLng) + Math.abs(next.lat - startLat) > maxTravel) break;+ lng = next.lng;+ lat = next.lat;+ }+ return path;+}++function integrate(grid, startLng, startLat, lifetime, maxTravel, stepDeg) {+ if (!grid?.lngs || grid.lngs.length < 2 || !grid?.lats || grid.lats.length < 2) {+ return null;+ }+ const gridStep = Math.min(+ Math.abs(grid.lngs[1] - grid.lngs[0]) || 0.5,+ Math.abs(grid.lats[1] - grid.lats[0]) || 0.5+ );+ const useStep = Math.max(1e-6, Math.min(gridStep * 0.55, stepDeg || gridStep));+ const dt = (useStep * METERS_PER_DEG_LAT) / Math.max(grid.maxSpeed, 1e-3);+ const travel = Math.max(maxTravel || useStep * 8, useStep * 4);+ const fwd = integrateDir(grid, startLng, startLat, dt, 1, travel);+ const bwd = integrateDir(grid, startLng, startLat, dt, -1, travel);+ const path = [...bwd.slice(1).reverse(), ...fwd];+ if (path.length < 4) {+ return null;+ }+ const timestamps = path.map((_, i) => (i / (path.length - 1)) * lifetime);+ return {path, timestamps};+}++function streamlineWindow(grid, mapState, visConfig) {+ const view = viewportBounds(mapState);+ const field = fieldBounds(grid);+ if (!field || ![field.minLng, field.maxLng, field.minLat, field.maxLat].every(isFiniteNumber)) {+ return {+ minCi: 0,+ maxCi: 0,+ minRi: 0,+ maxRi: 0,+ strideLng: 1,+ strideLat: 1,+ stepDeg: 1,+ maxTravel: 1,+ clipBounds: [view.minLng, view.minLat, view.maxLng, view.maxLat],+ rangeKey: 'empty'+ };+ }+ const count = Math.max(10, Math.round(visConfig.linesPerScreen));+ const n = Math.sqrt(count);+ const t = Math.max(0, Math.min(1, visConfig.zoomResponse));+ const viewLng = Math.max(1e-6, view.maxLng - view.minLng);+ const viewLat = Math.max(1e-6, view.maxLat - view.minLat);+ const fieldLng = Math.max(1e-6, field.maxLng - field.minLng);+ const fieldLat = Math.max(1e-6, field.maxLat - field.minLat);+ let targetLng = logMix(viewLng / n, fieldLng / n, t);+ let targetLat = logMix(viewLat / n, fieldLat / n, t);+ const minAxis = Math.max(6, Math.round(n * 0.2));+ targetLng = Math.min(targetLng, viewLng / minAxis);+ targetLat = Math.min(targetLat, viewLat / minAxis);+ const strideLng = degToStride(targetLng);+ const strideLat = degToStride(targetLat);++ const padLng = viewLng * 0.08;+ const padLat = viewLat * 0.08;+ const minLng = Math.max(field.minLng, view.minLng - padLng);+ const maxLng = Math.min(field.maxLng, view.maxLng + padLng);+ const minLat = Math.max(field.minLat, view.minLat - padLat);+ const maxLat = Math.min(field.maxLat, view.maxLat + padLat);++ const minCi = Math.floor(Math.floor(minLng / FINE_CELL) / strideLng) * strideLng;+ const maxCi = Math.ceil(maxLng / FINE_CELL);+ const minRi = Math.floor(Math.floor(minLat / FINE_CELL) / strideLat) * strideLat;+ const maxRi = Math.ceil(maxLat / FINE_CELL);++ return {+ minCi,+ maxCi,+ minRi,+ maxRi,+ strideLng,+ strideLat,+ stepDeg: Math.min(viewLng, viewLat) / 40,+ maxTravel: Math.min(viewLng, viewLat) * 0.7,+ clipBounds: [view.minLng, view.minLat, view.maxLng, view.maxLat],+ rangeKey: `${minCi}:${maxCi}:${minRi}:${maxRi}:${strideLng}:${strideLat}`+ };+}++function collectStreamlines(+ grid: FlowGrid,+ visConfig: any,+ cache: Map<string, FlowTrip | null>,+ seedWindow: any+) {+ const {minCi, maxCi, minRi, maxRi, strideLng, strideLat, maxTravel, stepDeg} = seedWindow;+ const travelKey = Math.round(maxTravel * 50);++ const lines: FlowTrip[] = [];+ const needed = new Set<string>();+ for (let ri = minRi; ri < maxRi; ri += strideLat) {+ for (let ci = minCi; ci < maxCi; ci += strideLng) {+ const key = `${ci}:${ri}:${travelKey}`;+ needed.add(key);+ let line = cache.get(key);+ if (line === undefined) {+ const rand = mulberry32(hashString(`${ci}:${ri}`));+ const lng = (ci + 0.18 + rand() * 0.64) * FINE_CELL;+ const lat = (ri + 0.18 + rand() * 0.64) * FINE_CELL;+ if (!sampleField(grid, lng, lat)) {+ cache.set(key, null);+ } else {+ const pathLifetime = visConfig.seamlessLoop ? 1 : visConfig.lineLifetime;+ const built = integrate(grid, lng, lat, pathLifetime, maxTravel, stepDeg);+ if (!built) {+ cache.set(key, null);+ } else {+ const sample = sampleField(grid, lng, lat);+ const speed = sample ? Math.hypot(sample.u, sample.v) : 0;+ const phase = rand();+ const trip: FlowTrip = {+ path: built.path,+ timestamps: built.timestamps.map(ts => ts + phase),+ speed+ };+ cache.set(key, isValidTrip(trip) ? trip : null);+ }+ }+ }+ line = cache.get(key);+ if (line && isValidTrip(line)) {+ lines.push(line);+ // A second trip on the same vertices, not a concatenated polyline.+ // Joining end→start would draw a straight segment against the flow.+ if (visConfig.seamlessLoop) {+ const looped: FlowTrip = {+ path: line.path,+ timestamps: line.timestamps.map(ts => ts + 1),+ speed: line.speed+ };+ if (isValidTrip(looped)) {+ lines.push(looped);+ }+ }+ }+ }+ }++ if (cache.size > needed.size * 4) {+ for (const key of [...cache.keys()]) {+ if (!needed.has(key)) {+ cache.delete(key);+ }+ }+ }++ return lines;+}++/** Midpoint cell bounds around axis node i (half-way to neighbors). */+function axisCellEdges(values: number[], i: number): [number, number] {+ const n = values.length;+ const lo = i === 0 ? values[0] : (values[i - 1] + values[i]) / 2;+ const hi = i === n - 1 ? values[n - 1] : (values[i] + values[i + 1]) / 2;+ return [lo, hi];+}++function buildDebugGridGeometry(grid: FlowGrid, elevationMultiplier: number) {+ const {cols, rows, lngs, lats, alt, filled} = grid;+ const zAt = (ci: number, ri: number) => {+ if (!alt) return 0;+ const z = alt[ri * cols + ci];+ return Number.isFinite(z) ? z * elevationMultiplier : 0;+ };++ const gridLines: {path: number[][]}[] = [];+ for (let ci = 0; ci < cols; ci++) {+ const path: number[][] = [];+ for (let ri = 0; ri < rows; ri++) {+ path.push([lngs[ci], lats[ri], zAt(ci, ri)]);+ }+ if (path.length >= 2) {+ gridLines.push({path});+ }+ }+ for (let ri = 0; ri < rows; ri++) {+ const path: number[][] = [];+ for (let ci = 0; ci < cols; ci++) {+ path.push([lngs[ci], lats[ri], zAt(ci, ri)]);+ }+ if (path.length >= 2) {+ gridLines.push({path});+ }+ }++ const filledCells: {polygon: number[][]}[] = [];+ if (filled) {+ for (let ri = 0; ri < rows; ri++) {+ for (let ci = 0; ci < cols; ci++) {+ if (!filled[ri * cols + ci]) continue;+ const [lng0, lng1] = axisCellEdges(lngs, ci);+ const [lat0, lat1] = axisCellEdges(lats, ri);+ const z = zAt(ci, ri);+ filledCells.push({+ polygon: [+ [lng0, lat0, z],+ [lng1, lat0, z],+ [lng1, lat1, z],+ [lng0, lat1, z],+ [lng0, lat0, z]+ ]+ });+ }+ }+ }++ return {gridLines, filledCells};+}++function buildDebugGridLayers(+ grid: FlowGrid,+ layerId: string,+ elevationMultiplier: number,+ blendingParameters: Record<string, unknown>+) {+ const {gridLines, filledCells} = buildDebugGridGeometry(grid, elevationMultiplier);+ return [+ new PathLayer({+ id: `${layerId}-debug-grid`,+ data: gridLines,+ getPath: d => d.path,+ getColor: [120, 140, 160, 120],+ getWidth: 1,+ widthUnits: 'pixels',+ pickable: false,+ wrapLongitude: false,+ parameters: {depthTest: false, ...blendingParameters}+ }),+ new PolygonLayer({+ id: `${layerId}-debug-filled`,+ data: filledCells,+ getPolygon: d => d.polygon,+ getFillColor: [80, 220, 140, 90],+ getLineColor: [40, 180, 110, 200],+ lineWidthMinPixels: 1,+ stroked: true,+ filled: true,+ pickable: false,+ wrapLongitude: false,+ parameters: {depthTest: false, ...blendingParameters}+ })+ ];+}++export default class FlowFieldLayer extends Layer {+ declare _streamlines: FlowTrip[];+ declare _streamlinesKey: string;+ declare _lineCache: Map<string, FlowTrip | null>;+ declare _cacheMeta: string;+ declare _viewSig: string;+ declare _moving: boolean;+ declare _settleTimer: ReturnType<typeof setTimeout> | number;+ declare _clipBounds: number[] | null;+ declare _onRedrawNeeded: (() => void) | null | undefined;++ constructor(props: any) {+ super(props);+ this.registerVisConfig(flowFieldVisConfigs);+ this._streamlines = [];+ this._streamlinesKey = '';+ this._lineCache = new Map();+ this._cacheMeta = '';+ this._viewSig = '';+ this._moving = false;+ this._settleTimer = 0;+ this._clipBounds = null;+ this._onRedrawNeeded = null;+ }++ get type(): string {+ return LAYER_TYPES.flowField;+ }++ get name() {+ return 'Flow Field';+ }++ get layerIcon() {+ return FlowFieldLayerIcon;+ }++ get columnLabels() {+ return COLUMN_LABELS;+ }++ get columnPairs() {+ return this.defaultPointColumnPairs;+ }++ get supportedColumnModes() {+ return SUPPORTED_COLUMN_MODES;+ }++ get noneLayerDataAffectingProps() {+ return [+ ...super.noneLayerDataAffectingProps,+ 'strokeWidth',+ 'trailLength',+ 'cycleSeconds',+ 'lineLifetime',+ 'seamlessLoop',+ 'linesPerScreen',+ 'zoomResponse',+ 'colorBySpeed',+ 'colorRange',+ 'elevationMultiplier'+ ];+ }++ hasAllColumns(): boolean {+ if (!super.hasAllColumns()) {+ return false;+ }+ // Position: either lat+lng or a GeoJSON geometry column.+ return hasLatLngPosition(this.config.columns) || hasGeojsonPosition(this.config.columns);+ }++ getDefaultLayerConfig(config: LayerBaseConfigPartial = {} as LayerBaseConfigPartial) {+ const rawMode = (config as any).columnMode;+ return {+ ...super.getDefaultLayerConfig(config),+ columnMode: normalizeColumnMode(rawMode) || FlowFieldColumnMode.UV,+ color: config.color ?? [255, 255, 255]+ };+ }++ static findDefaultLayerProps(+ dataset: KeplerTable,+ foundLayers?: any[]+ ): FindDefaultLayerPropsReturnValue {+ const {fields = [], label} = dataset;+ // Auto-create only for explicit `u` / `v` (not aliases) plus lat/lng or GeoJSON.+ // Speed/direction and elevation modes stay manual.+ const uField = findNamedField(fields, DEFAULT_U_FIELD_NAMES);+ const vField = findNamedField(fields, DEFAULT_V_FIELD_NAMES);+ if (!uField || !vField) {+ return {props: [], foundLayers};+ }++ const latLng = latLngColumnsFromDataset(dataset);+ const foundGeojson = this.findDefaultColumnField(+ {geojson: [...(GEOJSON_FIELDS.geojson || []), ...geojsonFieldNames(fields)]},+ fields+ );+ const geoColumn = foundGeojson?.[0]?.geojson || null;+ const positionColumns = latLng+ ? {lat: latLng.lat, lng: latLng.lng}+ : geoColumn+ ? {geojson: geoColumn}+ : null;++ if (!positionColumns) {+ return {props: [], foundLayers};+ }++ const baseLabel = (typeof label === 'string' && label.replace(/\.[^/.]+$/, '')) || 'Flow Field';+ const altField = findNamedField(fields, ALT_FIELD_NAMES);+ const altColumn = latLng?.altitude || fieldToColumn(altField, fields);+ const defaultColor: [number, number, number] = [255, 255, 255];+ const uvColumns = {+ u: fieldToColumn(uField, fields)!,+ v: fieldToColumn(vField, fields)!,+ ...(altColumn ? {altitude: altColumn} : {})+ };++ const props: FindDefaultLayerPropsReturnValue['props'] = [+ {+ label: baseLabel,+ color: defaultColor,+ isVisible: true,+ columnMode: FlowFieldColumnMode.UV,+ columns: latLng+ ? {lat: latLng.lat, lng: latLng.lng, ...uvColumns}+ : {geojson: geoColumn!, ...uvColumns}+ }+ ];++ // When lat/lng is primary, also offer a GeoJSON-backed alt config for layer-type switches.+ const altProps: FindDefaultLayerPropsReturnValue['altProps'] =+ latLng && geoColumn+ ? [+ {+ label: baseLabel,+ color: defaultColor,+ isVisible: true,+ columnMode: FlowFieldColumnMode.UV,+ columns: {+ geojson: geoColumn,+ ...uvColumns+ }+ }+ ]+ : [];++ return {props, altProps, foundLayers};+ }++ formatLayerData(datasets: any) {+ if (this.config.dataId === null) {+ return {};+ }+ const dataset = datasets[this.config.dataId];+ if (!dataset) {+ return {};+ }+ const {dataContainer, filteredIndex, fields} = dataset;+ const {lat, lng, geojson, u, v, speed, direction, altitude} = this.config.columns;+ const mode = normalizeColumnMode(this.config.columnMode);+ // Prefer lat/lng when both are set; GeoJSON is the fallback position source.+ const useGeojson =+ hasGeojsonPosition(this.config.columns) && !hasLatLngPosition(this.config.columns);+ const altitudeMode = isElevationMode(mode);+ const speedMode = isSpeedDirMode(mode);++ if (useGeojson) {+ if (!geojson || geojson.fieldIdx < 0) {+ return {};+ }+ } else if (!lat || lat.fieldIdx < 0 || !lng || lng.fieldIdx < 0) {+ return {};+ }++ const geoEncoding = useGeojson ? getGeoArrowEncoding(fields?.[geojson.fieldIdx]) : undefined;++ const readLatLng = (idx: number): {lat: number; lng: number} | null => {+ if (useGeojson) {+ const centroid = centroidFromRawFeature(+ dataContainer.valueAt(idx, geojson.fieldIdx),+ geoEncoding+ );+ if (!centroid) {+ return null;+ }+ return {lng: centroid[0], lat: centroid[1]};+ }+ const latVal = dataContainer.valueAt(idx, lat.fieldIdx);+ const lngVal = dataContainer.valueAt(idx, lng.fieldIdx);+ if (!Number.isFinite(latVal) || !Number.isFinite(lngVal)) {+ return null;+ }+ return {lat: latVal, lng: lngVal};+ };++ if (altitudeMode) {+ if (!altitude || altitude.fieldIdx < 0) {+ return {};+ }+ const altPoints: AltitudePoint[] = [];+ for (let i = 0; i < filteredIndex.length; i++) {+ const idx = filteredIndex[i];+ const pos = readLatLng(idx);+ const altVal = dataContainer.valueAt(idx, altitude.fieldIdx);+ if (!pos || !Number.isFinite(altVal)) {+ continue;+ }+ altPoints.push({lat: pos.lat, lng: pos.lng, alt: altVal});+ }+ this._streamlinesKey = '';+ this._cacheMeta = '';+ this._lineCache = new Map();+ this._clipBounds = null;+ this._viewSig = '';+ this._moving = false;+ const grid = buildGridFromAltitude(+ altPoints,+ this.config.visConfig.smoothing,+ this.config.visConfig.gridResolution+ );+ return {data: altPoints, grid};+ }++ if (!speedMode && (u.fieldIdx < 0 || v.fieldIdx < 0)) {+ return {};+ }+ if (speedMode && (speed.fieldIdx < 0 || direction.fieldIdx < 0)) {+ return {};+ }++ const points: FlowPoint[] = [];+ for (let i = 0; i < filteredIndex.length; i++) {+ const idx = filteredIndex[i];+ const pos = readLatLng(idx);+ if (!pos) continue;+ let uu;+ let vv;+ if (speedMode) {+ const converted = meteorologicalToUV(+ dataContainer.valueAt(idx, speed.fieldIdx),+ dataContainer.valueAt(idx, direction.fieldIdx)+ );+ uu = converted.u;+ vv = converted.v;+ } else {+ uu = dataContainer.valueAt(idx, u.fieldIdx);+ vv = dataContainer.valueAt(idx, v.fieldIdx);+ }+ if (!Number.isFinite(uu) || !Number.isFinite(vv)) continue;+ const altVal =+ altitude?.fieldIdx > -1 ? dataContainer.valueAt(idx, altitude.fieldIdx) : undefined;+ points.push({+ lat: pos.lat,+ lng: pos.lng,+ u: uu,+ v: vv,+ ...(Number.isFinite(altVal) ? {alt: altVal} : {})+ });+ }++ this._streamlinesKey = '';+ this._cacheMeta = '';+ this._lineCache = new Map();+ this._clipBounds = null;+ this._viewSig = '';+ this._moving = false;+ const grid = buildGrid(+ points,+ this.config.visConfig.smoothing,+ this.config.visConfig.gridResolution+ );+ return {data: points, grid};+ }++ renderLayer(opts: any) {+ const {data, mapState, layerCallbacks, visible} = opts;+ const {visConfig, isVisible, color} = this.config;+ // Honor split-map visibility from renderDeckGlLayer (`visible`), not only config.+ if (!isVisible || visible === false || !data?.grid) {+ return [];+ }++ this._onRedrawNeeded = layerCallbacks?.onRedrawNeeded;++ const meta = [+ visConfig.linesPerScreen,+ visConfig.zoomResponse,+ visConfig.lineLifetime,+ visConfig.seamlessLoop ? 1 : 0+ ].join(':');++ if (this._cacheMeta !== meta) {+ this._lineCache = new Map();+ this._cacheMeta = meta;+ this._streamlinesKey = '';+ this._moving = false;+ }++ const viewSig = viewSignature(mapState);+ if (this._viewSig && this._viewSig !== viewSig) {+ this._moving = true;+ if (this._settleTimer) {+ clearTimeout(this._settleTimer);+ }+ this._settleTimer = setTimeout(() => {+ this._moving = false;+ this._streamlinesKey = '';+ this._onRedrawNeeded?.();+ }, SETTLE_MS);+ }+ this._viewSig = viewSig;++ if (!this._moving) {+ let seedWindow = streamlineWindow(data.grid, mapState, visConfig);+ if (this._streamlinesKey !== seedWindow.rangeKey) {+ this._streamlines = collectStreamlines(data.grid, visConfig, this._lineCache, seedWindow);+ if (!this._streamlines.length) {+ seedWindow = streamlineWindow(data.grid, mapState, {...visConfig, zoomResponse: 0});+ this._streamlines = collectStreamlines(data.grid, visConfig, this._lineCache, seedWindow);+ }+ this._streamlinesKey = seedWindow.rangeKey;+ this._clipBounds = seedWindow.clipBounds;+ }+ }++ const trips = (this._streamlines || []).filter(isValidTrip);+ const blendingParameters = mapState?.layerParameters ?? {};+ const elevationMultiplier = Math.max(0, visConfig.elevationMultiplier ?? 1);+ const debugLayers = visConfig.debugGrid+ ? buildDebugGridLayers(data.grid, this.id, elevationMultiplier, blendingParameters)+ : [];++ if (!trips.length && !debugLayers.length) {+ return [];+ }++ if (!trips.length) {+ return debugLayers;+ }++ const opacity = Math.max(0, Math.min(1, visConfig.opacity ?? 0.85));+ const [r, g, b] = color || [186, 233, 223];+ const view = viewportBounds(mapState);+ const clipBounds = this._clipBounds || [view.minLng, view.minLat, view.maxLng, view.maxLat];+ if (!clipBounds.every(isFiniteNumber)) {+ return debugLayers;+ }+ const minSpeed = data.grid.minSpeed || 0;+ const maxSpeed = data.grid.maxSpeed || 1;+ const getColor = (+ visConfig.colorBySpeed+ ? (d: FlowTrip) =>+ speedToColor(d.speed || 0, minSpeed, maxSpeed, visConfig.colorRange, opacity)+ : [r, g, b, Math.round(opacity * 255)]+ ) as any;++ const hasAltitude = Boolean(data.grid?.alt);++ return [+ ...debugLayers,+ new AnimatedTripsLayer({+ id: this.id,+ data: trips,+ getPath:+ elevationMultiplier === 1+ ? d => d.path+ : d => d.path.map(p => [p[0], p[1], (p[2] || 0) * elevationMultiplier]),+ getTimestamps: d => d.timestamps,+ getColor,+ updateTriggers: {+ getPath: elevationMultiplier,+ getColor: visConfig.colorBySpeed+ ? [true, visConfig.colorRange, opacity, minSpeed, maxSpeed]+ : [false, r, g, b, opacity]+ },+ getWidth: visConfig.strokeWidth,+ widthUnits: 'pixels',+ capRounded: true,+ jointRounded: true,+ fadeTrail: true,+ trailLength: visConfig.trailLength / 100,+ cycleSeconds: visConfig.cycleSeconds,+ seamlessLoop: visConfig.seamlessLoop,+ pickable: false,+ // wrapLongitude splits paths in PathLayer but not TripsLayer timestamps,+ // which can throw during attribute update (reading undefined[0]).+ wrapLongitude: false,+ parameters: {+ depthTest: Boolean(mapState.dragRotate) || (hasAltitude && elevationMultiplier > 0),+ ...blendingParameters+ },+ extensions: [clipExtension],+ clipByInstance: false,+ clipBounds+ } as any)+ ];+ }+}diff --git a/src/layers/src/index.ts b/src/layers/src/index.tsindex 2a5a53146..5092d7155 100644--- a/src/layers/src/index.ts+++ b/src/layers/src/index.ts@@ -46,6 +46,9 @@ export {defaultElevation as a5DefaultElevation} from './a5-layer/a5-layer';import {default as GeohashGeometryLayer} from './geohash-layer/geohash-layer';export {defaultElevation as geohashDefaultElevation} from './geohash-layer/geohash-layer';import {default as FlowLayer} from './flow-layer/flow-layer';+import {default as FlowFieldLayer} from './flow-field-layer/flow-field-layer';+export {FlowFieldColumnMode, flowFieldVisConfigs} from './flow-field-layer/flow-field-layer';+export {default as FlowFieldLayerIcon} from './flow-field-layer/flow-field-layer-icon';export {getS2Center} from './s2-geometry-layer/s2-utils';export {getA5Center} from './a5-layer/a5-utils';export {getGeohashCenter} from './geohash-layer/geohash-utils';@@ -113,6 +116,7 @@ export const KeplerGlLayers = {A5GeometryLayer,GeohashGeometryLayer,FlowLayer,+ FlowFieldLayer,VectorTileLayer,RasterTileLayer,WMSLayer,@@ -138,6 +142,7 @@ export const LayerClasses = {[LAYER_TYPES.a5]: A5GeometryLayer,[LAYER_TYPES.geohash]: GeohashGeometryLayer,[LAYER_TYPES.flow]: FlowLayer,+ [LAYER_TYPES.flowField]: FlowFieldLayer,[LAYER_TYPES['vectorTile']]: VectorTileLayer,[LAYER_TYPES['rasterTile']]: RasterTileLayer,[LAYER_TYPES.wms]: WMSLayer,diff --git a/src/layers/src/trip-layer/trip-layer.ts b/src/layers/src/trip-layer/trip-layer.tsindex 1f72b5508..f0d2e5732 100644--- a/src/layers/src/trip-layer/trip-layer.ts+++ b/src/layers/src/trip-layer/trip-layer.ts@@ -172,7 +172,6 @@ export const tripVisConfigs: {sizeScale: {...LAYER_VIS_CONFIGS.sizeScale,label: 'layerVisConfigs.adjustSize',- description: 'layerVisConfigs.adjustSizeDescription',defaultValue: 1,isRanged: false,range: [-10, 10],diff --git a/src/localization/src/translations/ca.ts b/src/localization/src/translations/ca.tsindex f1977cd49..f777ab1cb 100644--- a/src/localization/src/translations/ca.ts+++ b/src/localization/src/translations/ca.ts@@ -123,6 +123,7 @@ export default {trip: 'viatge',s2: 'S2',geohash: 'GeoHash',+ flowfield: 'Flow Field','3d': '3D',flow: 'flow',vectortile: 'mosaic vectorial',diff --git a/src/localization/src/translations/cn.ts b/src/localization/src/translations/cn.tsindex 101c32073..07ba0b962 100644--- a/src/localization/src/translations/cn.ts+++ b/src/localization/src/translations/cn.ts@@ -122,6 +122,7 @@ export default {trip: 'trip',s2: 'S2',geohash: 'GeoHash',+ flowfield: 'Flow Field','3d': '3D',flow: 'flow',vectortile: 'vector tile',diff --git a/src/localization/src/translations/en.ts b/src/localization/src/translations/en.tsindex 23b790ae7..177c0fd1d 100644--- a/src/localization/src/translations/en.ts+++ b/src/localization/src/translations/en.ts@@ -140,6 +140,7 @@ export default {geohash: 'GeoHash','3d': '3D',flow: 'flow',+ flowfield: 'Flow Field',vectortile: 'vector tile',rastertile: 'raster tile',wms: 'WMS',@@ -255,6 +256,46 @@ export default {lineCurviness: 'Curviness',locationTotalsEnabled: 'Location Totals',maxTopFlowsDisplayNum: 'Max Top Flows'+ },+ flowField: {+ streamlines: 'Streamlines',+ animation: 'Animation',+ field: 'Field',+ colorGroupDescription: 'Single layer color, or a speed palette when Color By Speed is on.',+ linesPerScreen: 'Lines Per Screen',+ linesPerScreenDescription:+ 'Target number of streamlines in the current view. Higher is denser.',+ zoomResponse: 'Zoom Response',+ zoomResponseDescription:+ '0 keeps the same number of lines on screen as you zoom. 1 keeps geographic spacing (lines thin out as you zoom in). Values in between mix the two.',+ strokeWidth: 'Stroke Width',+ strokeWidthDescription: 'Width of each streamline, in pixels.',+ colorBySpeed: 'Color By Speed',+ colorBySpeedDescription:+ 'Color streamlines by speed using the palette. Off uses a single layer color.',+ opacityDescription: 'Transparency of the streamlines.',+ trailLength: 'Trail Length',+ trailLengthDescription: 'Visible trail length as a percent of the animation cycle.',+ cycle: 'Cycle',+ cycleDescription: 'Length of one full animation loop, in seconds.',+ lineLifetime: 'Line Lifetime',+ lineLifetimeDescription:+ 'How long each trail stays visible, as a fraction of the cycle (1 = the whole cycle).',+ seamlessLoop: 'Seamless Loop',+ seamlessLoopDescription: 'Repeat trails so they do not pop off at the end of the cycle.',+ smoothing: 'Smoothing',+ smoothingDescription:+ 'Blur u/v over this many neighboring cells. 0 uses raw samples and does not fill empty cells.',+ gridResolution: 'Grid Resolution',+ gridResolutionDescription:+ 'Target number of cells along the longer geographic axis of the field. Lower is coarser and faster; higher keeps more detail.',+ elevationMultiplier: 'Elevation Multiplier',+ elevationMultiplierDescription:+ 'Scale path height from the altitude/elevation column. 1 is real meters; higher values exaggerate relief in 3D.',+ customElevation: 'custom elevation',+ debugGrid: 'Debug Grid',+ debugGridDescription:+ 'Draw the flow grid and highlight cells that have data. Useful when streamlines look sparse or empty.'}},layerManager: {diff --git a/src/localization/src/translations/es.ts b/src/localization/src/translations/es.tsindex 1f2c92f3c..592e1cad6 100644--- a/src/localization/src/translations/es.ts+++ b/src/localization/src/translations/es.ts@@ -123,6 +123,7 @@ export default {trip: 'viaje',s2: 'S2',geohash: 'GeoHash',+ flowfield: 'Flow Field','3d': '3D',flow: 'flow',vectortile: 'mosaico vectorial',diff --git a/src/localization/src/translations/fi.ts b/src/localization/src/translations/fi.tsindex 2490489cf..627c64e85 100644--- a/src/localization/src/translations/fi.ts+++ b/src/localization/src/translations/fi.ts@@ -122,6 +122,7 @@ export default {trip: 'matka',s2: 'S2',geohash: 'GeoHash',+ flowfield: 'Flow Field','3d': '3D',flow: 'virtaus',vectortile: 'vektoritiili',diff --git a/src/localization/src/translations/ja.ts b/src/localization/src/translations/ja.tsindex 76f160a7f..f45df252d 100644--- a/src/localization/src/translations/ja.ts+++ b/src/localization/src/translations/ja.ts@@ -123,6 +123,7 @@ export default {trip: 'trip',s2: 'S2',geohash: 'GeoHash',+ flowfield: 'Flow Field','3d': '3D',flow: 'flow',vectortile: 'vector tile',diff --git a/src/localization/src/translations/pt.ts b/src/localization/src/translations/pt.tsindex d6f8c05b7..bc3523ff6 100644--- a/src/localization/src/translations/pt.ts+++ b/src/localization/src/translations/pt.ts@@ -123,6 +123,7 @@ export default {trip: 'viagem',s2: 'S2',geohash: 'GeoHash',+ flowfield: 'Flow Field','3d': '3D',flow: 'flow',vectortile: 'mosaico vetorial',diff --git a/src/localization/src/translations/ru.ts b/src/localization/src/translations/ru.tsindex 4e04a0aa1..94331bb6c 100644--- a/src/localization/src/translations/ru.ts+++ b/src/localization/src/translations/ru.ts@@ -123,6 +123,7 @@ export default {trip: 'пути',s2: 'S2',geohash: 'GeoHash',+ flowfield: 'Flow Field','3d': '3D',flow: 'поток',vectortile: 'векторный тайл',diff --git a/src/reducers/src/vis-state-merger.ts b/src/reducers/src/vis-state-merger.tsindex e2befaddd..041ec32e5 100644--- a/src/reducers/src/vis-state-merger.ts+++ b/src/reducers/src/vis-state-merger.ts@@ -1106,17 +1106,26 @@ function _getColumnConfigForValidation(newLayer) {: null;if (colModeConfig) {- // only validate columns in column mode+ // only validate columns in column mode (including tabbed columnGroups)+ const groupColumns = (colModeConfig.columnGroups || []).flatMap(group => group.columns || []);+ const requiredKeys = new Set(colModeConfig.requiredColumns || []);columnConfig = [...(colModeConfig.requiredColumns || []),- ...(colModeConfig.optionalColumns || [])- ].reduce(- (accu, key) => ({- ...accu,- [key]: columnConfig[key]- }),- {}- );+ ...(colModeConfig.optionalColumns || []),+ ...groupColumns+ ].reduce((accu, key) => {+ const col = columnConfig[key];+ if (!col) {+ return accu;+ }+ // Optionality must follow the active mode: a field optional in another mode+ // (e.g. altitude in UV) is still required when this mode lists it in requiredColumns.+ if (requiredKeys.has(key)) {+ const {optional: _optional, ...requiredCol} = col;+ return {...accu, [key]: requiredCol};+ }+ return {...accu, [key]: {...col, optional: true}};+ }, {});}return columnConfig;diff --git a/src/types/layers.d.ts b/src/types/layers.d.tsindex 161bfbc52..381191e14 100644--- a/src/types/layers.d.ts+++ b/src/types/layers.d.ts@@ -62,11 +62,23 @@ export type EnhancedFieldPair = {pair: FieldPair['pair'];};+export type ColumnGroup = {+ key: string;+ label: string;+ /** Column keys shown when this group is active (mutually exclusive with other groups). */+ columns: string[];+};+export type SupportedColumnMode = {key: string;label: string;requiredColumns: string[];optionalColumns?: string[];+ /**+ * Optional mutually exclusive column sets rendered as tabs+ * (e.g. Lat/Lng vs GeoJSON position source).+ */+ columnGroups?: ColumnGroup[];hasHelp?: boolean;verifyField?: (field: Field) => boolean;};@@ -240,6 +252,8 @@ export type VisConfig = {) => boolean;allowCustomValue?: boolean;+ /** Checkbox label shown when allowCustomValue is true. Defaults to "custom input". */+ customInputLabel?: string;};export type VisConfigNumber = VisConfig & {diff --git a/src/utils/src/application-config.ts b/src/utils/src/application-config.tsindex 58cf581b6..59c82824d 100644--- a/src/utils/src/application-config.ts+++ b/src/utils/src/application-config.ts@@ -161,6 +161,9 @@ export type KeplerApplicationConfig = {// GeoHash layer is optional. Enabled by default; disable via initApplicationConfig.enableGeohashLayer?: boolean;+ // Flow Field (streamlines) layer config+ enableFlowFieldLayer?: boolean;+/** Whether to show example URLs in tileset setup forms (vector tile, raster tile, WMS, 3D tile) */showInlineTilesetExamples?: boolean;@@ -341,6 +344,9 @@ const DEFAULT_APPLICATION_CONFIG: Required<KeplerApplicationConfig> = {// GeoHash layer configenableGeohashLayer: true,+ // Flow Field layer config+ enableFlowFieldLayer: true,+showInlineTilesetExamples: true,// Image export configdiff --git a/test/browser/layer-tests/flow-field-layer-specs.js b/test/browser/layer-tests/flow-field-layer-specs.jsnew file mode 100644index 000000000..a65262e09--- /dev/null+++ b/test/browser/layer-tests/flow-field-layer-specs.js@@ -0,0 +1,418 @@+// SPDX-License-Identifier: MIT+// Copyright contributors to the kepler.gl project++import test from 'tape';++import {+ testCreateCases,+ testFormatLayerDataCases,+ testRenderLayerCases+} from 'test/helpers/layer-utils';+import {KeplerGlLayers} from '@kepler.gl/layers';+import {getGpuFilterProps, KeplerTable} from '@kepler.gl/table';+import {processCsvData, processGeojson} from '@kepler.gl/processors';+import {findPointFieldPairs} from '@kepler.gl/table';++const {FlowFieldLayer} = KeplerGlLayers;++const dataId = 'flow-field-test-data';+const flowCsv = `latitude,longitude,u,v+37.0,-122.0,1.0,0.5+37.5,-122.0,1.1,0.4+38.0,-122.0,0.9,0.6+37.0,-121.5,1.2,0.3+37.5,-121.5,1.0,0.5+38.0,-121.5,0.8,0.7+37.0,-121.0,1.3,0.2+37.5,-121.0,0.95,0.55+38.0,-121.0,0.85,0.65+`;++const elevCsv = `latitude,longitude,elevation+37.0,-122.0,10+37.5,-122.0,20+38.0,-122.0,15+37.0,-121.5,25+37.5,-121.5,30+38.0,-121.5,18+37.0,-121.0,12+37.5,-121.0,22+38.0,-121.0,16+`;++const speedDirCsv = `latitude,longitude,speed,direction+37.0,-122.0,10,0+37.5,-122.0,10,90+38.0,-122.0,10,180+37.0,-121.5,10,270+37.5,-121.5,8,45+38.0,-121.5,8,135+37.0,-121.0,12,225+37.5,-121.0,12,315+38.0,-121.0,5,0+`;++const {rows, fields} = processCsvData(flowCsv);++function createDatasetFromCsv(csv, id = dataId) {+ const parsed = processCsvData(csv);+ const dataset = new KeplerTable({+ info: {id, label: id},+ color: [255, 255, 255]+ });+ dataset.importData({+ data: {fields: parsed.fields, rows: parsed.rows}+ });+ dataset.fieldPairs = findPointFieldPairs(dataset.fields);+ dataset.gpuFilter = getGpuFilterProps([], id, dataset.fields);+ return dataset;+}++function createFlowFieldDataset() {+ return createDatasetFromCsv(flowCsv, dataId);+}++test('#FlowFieldLayer -> constructor', t => {+ const TEST_CASES = [+ {+ props: {+ dataId: 'smoothie',+ isVisible: true,+ label: 'test flow field layer'+ },+ test: layer => {+ t.ok(layer.config, 'should create a layer config');+ t.equal(layer.type, 'flowField', 'should have type flowField');+ t.equal(layer.name, 'Flow Field', 'should have name Flow Field');+ t.equal(layer.config.visConfig.linesPerScreen, 7500, 'default linesPerScreen');+ t.equal(layer.config.visConfig.cycleSeconds, 20, 'default cycleSeconds');+ t.equal(layer.config.visConfig.smoothing, 4, 'default smoothing');+ t.deepEqual(layer.config.color, [255, 255, 255], 'default color white');+ t.equal(layer.supportedColumnModes.length, 3, 'should have 3 column modes');+ t.ok(+ layer.supportedColumnModes.every(+ m =>+ Array.isArray(m.columnGroups) &&+ m.columnGroups.some(g => g.key === 'latlng') &&+ m.columnGroups.some(g => g.key === 'geojson')+ ),+ 'each mode should expose Lat/Lng and GeoJSON position tabs'+ );+ }+ }+ ];++ testCreateCases(t, FlowFieldLayer, TEST_CASES);+ t.end();+});++test('#FlowFieldLayer -> findDefaultLayerProps', t => {+ const dataset = createFlowFieldDataset();+ const {props} = FlowFieldLayer.findDefaultLayerProps(dataset);+ t.equal(props.length, 1, 'should find one default flow field layer');+ t.equal(props[0].columnMode, 'UV', 'should use UV mode');+ t.ok(props[0].columns.lat, 'should set lat');+ t.ok(props[0].columns.lng, 'should set lng');+ t.ok(props[0].columns.u, 'should set u');+ t.ok(props[0].columns.v, 'should set v');+ t.end();+});++test('#FlowFieldLayer -> formatLayerData', t => {+ const dataset = createFlowFieldDataset();+ const TEST_CASES = [+ {+ name: 'flow field uv',+ layer: {+ type: 'flowField',+ id: 'flow_field_uv',+ config: {+ dataId,+ label: 'flow field',+ columnMode: 'UV',+ columns: {+ lat: 'latitude',+ lng: 'longitude',+ u: 'u',+ v: 'v'+ },+ isVisible: true+ }+ },+ datasets: {+ [dataId]: dataset+ },+ assert: result => {+ const {layerData} = result;+ t.ok(layerData.grid, 'should build a grid');+ t.ok(layerData.data?.length >= 4, 'should keep sample points');+ t.ok(Number.isFinite(layerData.grid.maxSpeed), 'grid has maxSpeed');+ t.equal(layerData.grid.alt, null, 'should not invent a zero altitude grid');+ }+ }+ ];++ testFormatLayerDataCases(t, FlowFieldLayer, TEST_CASES);+ t.end();+});++test('#FlowFieldLayer -> findDefaultLayerProps altitude', t => {+ const dataset = createDatasetFromCsv(elevCsv, 'elev-data');+ const {props} = FlowFieldLayer.findDefaultLayerProps(dataset);+ t.equal(props.length, 0, 'should not auto-create from altitude alone');+ t.end();+});++test('#FlowFieldLayer -> formatLayerData from altitude', t => {+ const dataset = createDatasetFromCsv(elevCsv, dataId);+ const TEST_CASES = [+ {+ name: 'flow field altitude',+ layer: {+ type: 'flowField',+ id: 'flow_field_alt',+ config: {+ dataId,+ label: 'flow field altitude',+ columnMode: 'ELEVATION',+ columns: {+ lat: 'latitude',+ lng: 'longitude',+ altitude: 'elevation'+ },+ isVisible: true+ }+ },+ datasets: {+ [dataId]: dataset+ },+ assert: result => {+ const {layerData} = result;+ t.ok(layerData.grid, 'should build a grid from altitude');+ t.ok(layerData.grid.alt, 'grid should keep altitude for path Z');+ t.ok(Number.isFinite(layerData.grid.maxSpeed), 'grid has maxSpeed from slope');+ t.ok(layerData.grid.maxSpeed > 0, 'downhill gradient should be non-zero');+ }+ }+ ];++ testFormatLayerDataCases(t, FlowFieldLayer, TEST_CASES);+ t.end();+});++test('#FlowFieldLayer -> findDefaultLayerProps speed/direction', t => {+ const dataset = createDatasetFromCsv(speedDirCsv, 'speed-dir-data');+ const {props} = FlowFieldLayer.findDefaultLayerProps(dataset);+ t.equal(props.length, 0, 'should not auto-create from speed/direction alone');+ t.end();+});++test('#FlowFieldLayer -> formatLayerData from speed/direction', t => {+ const dataset = createDatasetFromCsv(speedDirCsv, dataId);+ const TEST_CASES = [+ {+ name: 'flow field speed dir',+ layer: {+ type: 'flowField',+ id: 'flow_field_speed',+ config: {+ dataId,+ label: 'flow field speed',+ columnMode: 'SPEED_DIR',+ columns: {+ lat: 'latitude',+ lng: 'longitude',+ speed: 'speed',+ direction: 'direction'+ },+ isVisible: true+ }+ },+ datasets: {+ [dataId]: dataset+ },+ assert: result => {+ const {layerData} = result;+ t.ok(layerData.grid, 'should build a grid from speed/direction');+ t.ok(layerData.data?.length >= 4, 'should keep sample points');+ // Meteorological from-direction 0° (from N) → u=0, v=-speed+ const north = layerData.data.find(d => d.lat === 37 && d.lng === -122);+ t.ok(north, 'should include first point');+ t.ok(Math.abs(north.u) < 1e-6, 'from-north wind has ~0 eastward u');+ t.ok(north.v < 0, 'from-north wind has negative northward v');+ }+ }+ ];++ testFormatLayerDataCases(t, FlowFieldLayer, TEST_CASES);+ t.end();+});++test('#FlowFieldLayer -> renderLayer', t => {+ const dataset = createFlowFieldDataset();+ const TEST_CASES = [+ {+ name: 'flow field render uv',+ layer: {+ type: 'flowField',+ id: 'flow_field_render',+ config: {+ dataId,+ label: 'flow field',+ columnMode: 'UV',+ columns: {+ lat: 'latitude',+ lng: 'longitude',+ u: 'u',+ v: 'v'+ },+ isVisible: true,+ visConfig: {+ linesPerScreen: 200,+ smoothing: 0+ }+ }+ },+ datasets: {+ [dataId]: dataset+ },+ assert: (deckLayers, layer) => {+ t.equal(layer.type, 'flowField', 'should be flowField layer');+ t.ok(Array.isArray(deckLayers), 'should return deck layers array');+ t.ok(deckLayers.length >= 1, 'should create at least one deck.gl layer');+ t.equal(deckLayers[0].id, 'flow_field_render', 'deck layer id matches');+ }+ }+ ];++ testRenderLayerCases(t, FlowFieldLayer, TEST_CASES);+ t.end();+});++const flowGeojsonFc = {+ type: 'FeatureCollection',+ features: [+ {+ type: 'Feature',+ properties: {u: 1.0, v: 0.5},+ geometry: {type: 'Point', coordinates: [-122.0, 37.0]}+ },+ {+ type: 'Feature',+ properties: {u: 1.1, v: 0.4},+ geometry: {+ type: 'LineString',+ coordinates: [+ [-122.0, 37.5],+ [-121.9, 37.6]+ ]+ }+ },+ {+ type: 'Feature',+ properties: {u: 0.9, v: 0.6},+ geometry: {+ type: 'Polygon',+ coordinates: [+ [+ [-122.0, 38.0],+ [-121.9, 38.0],+ [-121.9, 38.1],+ [-122.0, 38.1],+ [-122.0, 38.0]+ ]+ ]+ }+ },+ {+ type: 'Feature',+ properties: {u: 1.2, v: 0.3},+ geometry: {type: 'Point', coordinates: [-121.5, 37.0]}+ }+ ]+};++function createFlowFieldGeojsonDataset(id = 'flow-geojson-data') {+ const parsed = processGeojson(flowGeojsonFc);+ const dataset = new KeplerTable({+ info: {id, label: id},+ color: [255, 255, 255]+ });+ dataset.importData({+ data: {fields: parsed.fields, rows: parsed.rows}+ });+ dataset.fieldPairs = findPointFieldPairs(dataset.fields);+ dataset.gpuFilter = getGpuFilterProps([], id, dataset.fields);+ return dataset;+}++test('#FlowFieldLayer -> findDefaultLayerProps geojson', t => {+ const dataset = createFlowFieldGeojsonDataset();+ const {props, altProps} = FlowFieldLayer.findDefaultLayerProps(dataset);+ t.equal(props.length, 1, 'geojson-only dataset should create a Flow Field prop');+ t.equal(altProps?.length || 0, 0, 'should not need altProps when geojson is primary');+ t.equal(props[0].columnMode, 'UV', 'should use UV mode with geojson position');+ t.ok(props[0].columns.geojson, 'should set geojson column');+ t.ok(props[0].columns.u, 'should set u');+ t.ok(props[0].columns.v, 'should set v');+ t.end();+});++test('#FlowFieldLayer -> formatLayerData from geojson centroids', t => {+ const dataset = createFlowFieldGeojsonDataset(dataId);+ const TEST_CASES = [+ {+ name: 'flow field geojson uv',+ layer: {+ type: 'flowField',+ id: 'flow_field_geojson_uv',+ config: {+ dataId,+ label: 'flow field geojson',+ columnMode: 'UV',+ columns: {+ geojson: '_geojson',+ u: 'u',+ v: 'v'+ },+ isVisible: true+ }+ },+ datasets: {+ [dataId]: dataset+ },+ assert: result => {+ const {layerData} = result;+ t.ok(layerData.grid, 'should build a grid from geojson centroids');+ t.equal(layerData.data?.length, 4, 'should keep one sample per feature');+ const point = layerData.data.find(d => d.lng === -122 && d.lat === 37);+ t.ok(point, 'Point geometry should use its coordinates as position');+ t.equal(point.u, 1.0, 'should keep u from properties');+ t.equal(point.v, 0.5, 'should keep v from properties');++ const line = layerData.data.find(+ d => Math.abs(d.lng - -121.95) < 1e-9 && Math.abs(d.lat - 37.55) < 1e-9+ );+ t.ok(line, 'LineString should use vertex-average centroid');++ // Polygon centroid averages all ring vertices including the closing duplicate+ const polyCoords = [+ [-122.0, 38.0],+ [-121.9, 38.0],+ [-121.9, 38.1],+ [-122.0, 38.1],+ [-122.0, 38.0]+ ];+ const expectedPolyLng = polyCoords.reduce((s, c) => s + c[0], 0) / polyCoords.length;+ const expectedPolyLat = polyCoords.reduce((s, c) => s + c[1], 0) / polyCoords.length;+ const poly = layerData.data.find(+ d => Math.abs(d.lng - expectedPolyLng) < 1e-9 && Math.abs(d.lat - expectedPolyLat) < 1e-9+ );+ t.ok(poly, 'Polygon should use boundary-vertex-average centroid');+ }+ }+ ];++ testFormatLayerDataCases(t, FlowFieldLayer, TEST_CASES);+ t.end();+});diff --git a/test/browser/layer-tests/index.js b/test/browser/layer-tests/index.jsindex 81241c967..812504e14 100644--- a/test/browser/layer-tests/index.js+++ b/test/browser/layer-tests/index.js@@ -19,6 +19,7 @@ import './trip-layer-specs';import './s2-geometry-layer-specs';import './a5-layer-specs';import './geohash-layer-specs';+import './flow-field-layer-specs';import './wms-layer-specs';import './vector-tile-layer-specs';import './flow-layer-specs';