Skip to content

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

feat: optional end time for time filter animation (#3699)

Igor Dykhta150246a0ca53
diff --git a/docs/user-guides/e-filters.md b/docs/user-guides/e-filters.md
index 87a1d3e49..eb28e0587 100644
--- a/docs/user-guides/e-filters.md
+++ b/docs/user-guides/e-filters.md
@@ -15,7 +15,8 @@ To add a column filter:
![choose a dataset](https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/image29.png "choose a dataset")
4. Your filter is applied to your map as soon as you specify the field and value.
-5. Delete a filter anytime by clicking the __trashcan__ to the right of the filter you wish to delete.
+5. For timestamp fields, you can optionally choose an **End time** field so features stay visible for the whole `[start, end]` span during playback. End time is hidden while the filter is synced across datasets. See [Playback](./h-playback.md).
+6. Delete a filter anytime by clicking the __trashcan__ to the right of the filter you wish to delete.
__Note__: column filters apply to all layers in the same dataset on your map.
diff --git a/docs/user-guides/h-playback.md b/docs/user-guides/h-playback.md
index a6cc5ebfb..7694d7aac 100644
--- a/docs/user-guides/h-playback.md
+++ b/docs/user-guides/h-playback.md
@@ -15,6 +15,14 @@ Follow these steps to create a playback video of an event:
![custom y axis](https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/h-playback-3.png "select filters")
+## Start and end time (duration)
+
+By default, playback uses a single timestamp field: a feature is visible only while that instant falls inside the moving window.
+
+To keep features visible for a whole time span (service coverage, deployments, availability windows), add a time filter on the **start** timestamp, then optionally choose an **End time** field in the filter panel. A feature stays on the map while the playback window overlaps `[start, end]`. Rows with a missing end time are treated as still active. Rows whose end time is before the start time are ignored. The timeline histogram counts a feature in every bin that falls inside its start–end range.
+
+**End time** is available only on a time filter that is not synced across datasets. If you use Time Filter Sync, clear the extra datasets first, then set End time.
+
## Zoom & precision controls
The enlarged timeline now lets you stay focused on the portion that matters:
diff --git a/src/components/src/filters/filter-panels/time-range-filter-panel.tsx b/src/components/src/filters/filter-panels/time-range-filter-panel.tsx
index 73f9e645c..f33616ff3 100644
--- a/src/components/src/filters/filter-panels/time-range-filter-panel.tsx
+++ b/src/components/src/filters/filter-panels/time-range-filter-panel.tsx
@@ -2,6 +2,7 @@
// Copyright contributors to the kepler.gl project
import React, {useCallback, useMemo} from 'react';
+import styled from 'styled-components';
import TimeRangeFilterFactory from '../time-range-filter';
import {Clock} from '../../common/icons';
import {TimeRangeFilterPanelComponent} from './types';
@@ -9,14 +10,22 @@ import {isSideFilter, getTimelineFromFilter} from '@kepler.gl/utils';
import FilterPanelHeaderFactory from '../../side-panel/filter-panel/filter-panel-header';
import PanelHeaderActionFactory from '../../side-panel/panel-header-action';
import FieldSelectorFactory from '../../common/field-selector';
-import {StyledFilterContent} from '../../common/styled-components';
+import {PanelLabel, SidePanelSection, StyledFilterContent} from '../../common/styled-components';
import {getSupportedFilterFields} from './new-filter-panel';
-import {FILTER_TYPES} from '@kepler.gl/constants';
+import {ALL_FIELD_TYPES, FILTER_TYPES} from '@kepler.gl/constants';
import TimeSyncedFieldSelectorFactory from './time-synced-field-selector';
import FilterSyncedDatasetPanelFactory from './filter-synced-dataset-panel';
+import {FormattedMessage} from '@kepler.gl/localization';
const SYNC_FILTER_ID_LENGTH = 2;
+const EndFieldHint = styled.div`
+ color: ${props => props.theme.subtextColor};
+ font-size: 11px;
+ line-height: 1.4;
+ margin-top: 6px;
+`;
+
TimeRangeFilterPanelFactory.deps = [
TimeRangeFilterFactory,
FilterPanelHeaderFactory,
@@ -78,6 +87,11 @@ function TimeRangeFilterPanelFactory(
[setFilter, idx]
);
+ const onEndFieldSelector = useCallback(
+ (field, valueIndex = 0) => setFilter(idx, 'endName', field ? field.name : null, valueIndex),
+ [setFilter, idx]
+ );
+
const onSourceDataSelector = useCallback(
value => setFilter(idx, 'dataId', value, 0),
[idx, setFilter]
@@ -89,6 +103,13 @@ function TimeRangeFilterPanelFactory(
[dataset.supportedFilterTypes, allAvailableFields]
);
+ const endTimeFields = useMemo(() => {
+ const startName = Array.isArray(filter.name) ? filter.name[0] : filter.name;
+ return supportedFields.filter(
+ field => field.type === ALL_FIELD_TYPES.timestamp && field.name !== startName
+ );
+ }, [supportedFields, filter.name]);
+
const isSynced = useMemo(() => {
return (
filter.dataId.length >= SYNC_FILTER_ID_LENGTH && filter.type === FILTER_TYPES.timeRange
@@ -145,6 +166,24 @@ function TimeRangeFilterPanelFactory(
supportedFields={supportedFields}
syncTimeFilterWithLayerTimeline={syncTimeFilterWithLayerTimeline}
/>
+ {!isSynced && endTimeFields.length ? (
+ <SidePanelSection>
+ <PanelLabel htmlFor={`filter-${filter.id}-end-time`}>
+ <FormattedMessage id="filterManager.timeIntervalEndField" />
+ </PanelLabel>
+ <FieldSelector
+ inputTheme="secondary"
+ fields={endTimeFields}
+ value={Array.isArray(filter.endName) ? filter.endName[0] : filter.endName}
+ placeholder="placeholder.endTimeField"
+ erasable
+ onSelect={field => onEndFieldSelector(field, 0)}
+ />
+ <EndFieldHint>
+ <FormattedMessage id="filterManager.timeIntervalEndFieldHint" />
+ </EndFieldHint>
+ </SidePanelSection>
+ ) : null}
{isHistogramVisible && (
<div className="filter-panel__filter">
<TimeRangeFilter
diff --git a/src/components/src/filters/time-widget-settings.tsx b/src/components/src/filters/time-widget-settings.tsx
index c9a54451c..23eb5a1d5 100644
--- a/src/components/src/filters/time-widget-settings.tsx
+++ b/src/components/src/filters/time-widget-settings.tsx
@@ -345,7 +345,10 @@ function TimeWidgetSettingsFactory(FieldSelector: ReturnType<typeof FieldSelecto
<AxisRow>
<FieldBlock>
<FieldLabel>Select Field</FieldLabel>
- <FieldValue>{filter.name}</FieldValue>
+ <FieldValue>
+ {Array.isArray(filter.name) ? filter.name[0] : filter.name}
+ {filter.endName?.[0] ? ` → ${filter.endName[0]}` : ''}
+ </FieldValue>
</FieldBlock>
<FieldBlock>
<FieldLabel>Interval</FieldLabel>
diff --git a/src/localization/src/translations/ca.ts b/src/localization/src/translations/ca.ts
index 47ab90bdc..cbf2d2444 100644
--- a/src/localization/src/translations/ca.ts
+++ b/src/localization/src/translations/ca.ts
@@ -27,7 +27,8 @@ export default {
selectValue: 'Selecciona un Valor',
enterValue: 'Entra un valor',
empty: 'buit',
- selectLayer: 'Selecciona una capa'
+ selectLayer: 'Selecciona una capa',
+ endTimeField: 'Selecciona hora de fi'
},
misc: {
by: '',
@@ -290,7 +291,10 @@ export default {
timeFilterSync: 'Conjunts sincronitzats',
timeLayerSync: 'Vincula amb la línia de temps de la capa',
timeLayerUnsync: 'Desvincula de la línia de temps de la capa',
- column: 'Columna'
+ column: 'Columna',
+ timeIntervalEndField: 'Hora de fi',
+ timeIntervalEndFieldHint:
+ 'Opcional. Les entitats romanen visibles mentre la finestra de reproducció se superposa a aquest interval.'
},
datasetTitle: {
showDataTable: 'Mostra taula de dades',
diff --git a/src/localization/src/translations/cn.ts b/src/localization/src/translations/cn.ts
index f19374bd7..50d90e3b1 100644
--- a/src/localization/src/translations/cn.ts
+++ b/src/localization/src/translations/cn.ts
@@ -27,7 +27,8 @@ export default {
selectValue: '选择值',
enterValue: '输入值',
empty: '未选择',
- selectLayer: '选择图层'
+ selectLayer: '选择图层',
+ endTimeField: '选择结束时间'
},
misc: {
by: '',
@@ -276,7 +277,9 @@ export default {
timeFilterSync: '同步数据集',
timeLayerSync: '与图层时间线联动',
timeLayerUnsync: '取消与图层时间线联动',
- column: '列'
+ column: '列',
+ timeIntervalEndField: '结束时间',
+ timeIntervalEndFieldHint: '可选。当播放窗口与该时间范围重叠时,要素保持可见。'
},
datasetTitle: {
showDataTable: '显示数据表',
diff --git a/src/localization/src/translations/en.ts b/src/localization/src/translations/en.ts
index a55327ffb..0c5b4c9e4 100644
--- a/src/localization/src/translations/en.ts
+++ b/src/localization/src/translations/en.ts
@@ -27,7 +27,8 @@ export default {
selectValue: 'Select A Value',
enterValue: 'Enter a value',
empty: 'empty',
- selectLayer: 'Select a layer'
+ selectLayer: 'Select a layer',
+ endTimeField: 'Select end time'
},
misc: {
by: '',
@@ -334,7 +335,10 @@ export default {
timeFilterSync: 'Synced datasets',
timeLayerSync: 'Link with the layer timeline',
timeLayerUnsync: 'Unlink with the layer timeline',
- column: 'Column'
+ column: 'Column',
+ timeIntervalEndField: 'End time',
+ timeIntervalEndFieldHint:
+ 'Optional. Features stay visible while the playback window overlaps this time span.'
},
datasetTitle: {
showDataTable: 'Show data table',
diff --git a/src/localization/src/translations/es.ts b/src/localization/src/translations/es.ts
index b6ef98c95..a60d6de36 100644
--- a/src/localization/src/translations/es.ts
+++ b/src/localization/src/translations/es.ts
@@ -27,7 +27,8 @@ export default {
selectValue: 'Selecciona un Valor',
enterValue: 'Entra un valor',
empty: 'vacio',
- selectLayer: 'Selecciona una capa'
+ selectLayer: 'Selecciona una capa',
+ endTimeField: 'Selecciona hora de fin'
},
misc: {
by: '',
@@ -291,7 +292,10 @@ export default {
timeFilterSync: 'Conjuntos sincronizados',
timeLayerSync: 'Vincular con la línea de tiempo de la capa',
timeLayerUnsync: 'Desvincular de la línea de tiempo de la capa',
- column: 'Columna'
+ column: 'Columna',
+ timeIntervalEndField: 'Hora de fin',
+ timeIntervalEndFieldHint:
+ 'Opcional. Las entidades permanecen visibles mientras la ventana de reproducción se superpone a este intervalo.'
},
datasetTitle: {
showDataTable: 'Mostar la tabla de datos',
diff --git a/src/localization/src/translations/fi.ts b/src/localization/src/translations/fi.ts
index b22236b77..3291af9bc 100644
--- a/src/localization/src/translations/fi.ts
+++ b/src/localization/src/translations/fi.ts
@@ -26,7 +26,8 @@ export default {
selectValue: 'Valitse arvo',
enterValue: 'Anna arvo',
empty: 'tyhjä',
- selectLayer: 'Valitse taso'
+ selectLayer: 'Valitse taso',
+ endTimeField: 'Valitse päättymisaika'
},
misc: {
by: '',
@@ -289,7 +290,10 @@ export default {
timeFilterSync: 'Synkronoidut aineistot',
timeLayerSync: 'Linkitä tason aikajanaan',
timeLayerUnsync: 'Poista linkitys tason aikajanasta',
- column: 'Sarake'
+ column: 'Sarake',
+ timeIntervalEndField: 'Päättymisaika',
+ timeIntervalEndFieldHint:
+ 'Valinnainen. Kohteet pysyvät näkyvissä, kun toistoikkuna osuu tälle aikavälille.'
},
datasetTitle: {
showDataTable: 'Näytä attribuuttitaulu',
diff --git a/src/localization/src/translations/ja.ts b/src/localization/src/translations/ja.ts
index 675d8bec9..f7de39abd 100644
--- a/src/localization/src/translations/ja.ts
+++ b/src/localization/src/translations/ja.ts
@@ -27,7 +27,8 @@ export default {
selectValue: '値を選択',
enterValue: '値を入力',
empty: '未選択',
- selectLayer: 'レイヤを選択'
+ selectLayer: 'レイヤを選択',
+ endTimeField: '終了時刻を選択'
},
misc: {
by: '',
@@ -288,7 +289,10 @@ export default {
timeFilterSync: '同期データセット',
timeLayerSync: 'レイヤタイムラインにリンク',
timeLayerUnsync: 'レイヤタイムラインのリンクを解除',
- column: '列'
+ column: '列',
+ timeIntervalEndField: '終了時刻',
+ timeIntervalEndFieldHint:
+ '任意。再生ウィンドウがこの期間と重なっている間、フィーチャは表示されたままになります。'
},
datasetTitle: {
showDataTable: 'データ表を表示',
diff --git a/src/localization/src/translations/pt.ts b/src/localization/src/translations/pt.ts
index 3783cc5f9..da2ef93a3 100644
--- a/src/localization/src/translations/pt.ts
+++ b/src/localization/src/translations/pt.ts
@@ -27,7 +27,8 @@ export default {
selectValue: 'Selecione um valor',
enterValue: 'Insira um valor',
empty: 'Vazio',
- selectLayer: 'Selecione uma camada'
+ selectLayer: 'Selecione uma camada',
+ endTimeField: 'Selecione a hora de término'
},
misc: {
by: '',
@@ -291,7 +292,10 @@ export default {
timeFilterSync: 'Conjuntos sincronizados',
timeLayerSync: 'Vincular à linha do tempo da camada',
timeLayerUnsync: 'Desvincular da linha do tempo da camada',
- column: 'Coluna'
+ column: 'Coluna',
+ timeIntervalEndField: 'Hora de término',
+ timeIntervalEndFieldHint:
+ 'Opcional. As entidades permanecem visíveis enquanto a janela de reprodução se sobrepõe a este intervalo.'
},
datasetTitle: {
showDataTable: 'Mostrar tabela de dados',
diff --git a/src/localization/src/translations/ru.ts b/src/localization/src/translations/ru.ts
index fa38e0c16..c630b681f 100644
--- a/src/localization/src/translations/ru.ts
+++ b/src/localization/src/translations/ru.ts
@@ -27,7 +27,8 @@ export default {
selectValue: 'Выберите A значение',
enterValue: 'Введите значение',
empty: 'пустой',
- selectLayer: 'Выберите слой'
+ selectLayer: 'Выберите слой',
+ endTimeField: 'Выберите время окончания'
},
misc: {
by: '',
@@ -290,7 +291,10 @@ export default {
timeFilterSync: 'Синхронизированные наборы данных',
timeLayerSync: 'Привязать к временной шкале слоя',
timeLayerUnsync: 'Отвязать от временной шкалы слоя',
- column: 'Столбец'
+ column: 'Столбец',
+ timeIntervalEndField: 'Время окончания',
+ timeIntervalEndFieldHint:
+ 'Необязательно. Объекты остаются видимыми, пока окно воспроизведения пересекается с этим интервалом.'
},
datasetTitle: {
showDataTable: 'Показать таблицу данных ',
diff --git a/src/reducers/src/vis-state-updaters.ts b/src/reducers/src/vis-state-updaters.ts
index 97e5ff087..333761155 100644
--- a/src/reducers/src/vis-state-updaters.ts
+++ b/src/reducers/src/vis-state-updaters.ts
@@ -60,6 +60,7 @@ import {
addNewLayersToSplitMap,
snapToMarks,
applyFilterFieldName,
+ applyTimeFilterEndFieldName,
applyFiltersToDatasets,
arrayInsert,
computeSplitMapLayers,
@@ -1388,7 +1389,16 @@ function _removeFilterDataIdAtValueIndex(filter, valueIndex, datasets) {
filter = removeFilterPlot(filter, dataId);
}
- for (const prop of ['dataId', 'name', 'fieldIdx', 'gpuChannel']) {
+ for (const prop of [
+ 'dataId',
+ 'name',
+ 'fieldIdx',
+ 'gpuChannel',
+ 'endName',
+ 'endFieldIdx',
+ 'endMappedValue',
+ 'gpuEndChannel'
+ ]) {
if (Array.isArray(filter[prop])) {
const nextVal = filter[prop].slice();
nextVal.splice(valueIndex, 1);
@@ -1456,6 +1466,28 @@ function _updateFilterProp(state, filter, prop, value, valueIndex, datasetIds?)
break;
}
+ case FILTER_UPDATER_PROPS.endName: {
+ const datasetId = filter.dataId[valueIndex];
+ const {filter: updatedFilter, dataset: newDataset} = applyTimeFilterEndFieldName(
+ filter,
+ state.datasets,
+ datasetId,
+ value,
+ valueIndex
+ );
+ if (updatedFilter) {
+ filter = updatedFilter;
+ filter = setFilterGpuMode(filter, state.filters);
+ filter = filter.gpu
+ ? assignGpuChannel(filter, state.filters)
+ : {...filter, gpuChannel: undefined, gpuEndChannel: undefined};
+ state = set(['datasets', datasetId], newDataset, state);
+ filter = removeFilterPlot(filter, datasetId);
+ datasetIdsToFilter = updatedFilter.dataId;
+ }
+ break;
+ }
+
case FILTER_UPDATER_PROPS.layerId: {
// We need to update only datasetId/s if we have added/removed layers
// - check for layerId changes (XOR works because of string values)
diff --git a/src/schemas/src/vis-state-schema.ts b/src/schemas/src/vis-state-schema.ts
index 765802895..3975754d8 100644
--- a/src/schemas/src/vis-state-schema.ts
+++ b/src/schemas/src/vis-state-schema.ts
@@ -925,7 +925,10 @@ export const filterPropsV1 = {
enabled: null,
invertTrendColor: null,
- timezone: null
+ timezone: null,
+
+ // Optional end timestamp for duration-based time animation (#3198)
+ endName: null
};
export const propertiesV0 = {
diff --git a/src/table/src/gpu-filter-utils.ts b/src/table/src/gpu-filter-utils.ts
index 77e00b6a9..e93fc24f2 100644
--- a/src/table/src/gpu-filter-utils.ts
+++ b/src/table/src/gpu-filter-utils.ts
@@ -3,12 +3,30 @@
import moment from 'moment';
import {MAX_GPU_FILTERS, FILTER_TYPES} from '@kepler.gl/constants';
-import {Field, Filter} from '@kepler.gl/types';
-import {set, DataContainerInterface} from '@kepler.gl/utils';
+import {Field, Filter, TimeRangeFilter} from '@kepler.gl/types';
+import {set, DataContainerInterface, isTimeIntervalFilter} from '@kepler.gl/utils';
import {toArray, notNullorUndefined} from '@kepler.gl/common-utils';
import {GpuFilter} from './kepler-table';
+/**
+ * Interval time filters occupy two GPU channels (start <= windowEnd AND end >= windowStart).
+ * All other GPU filters still occupy one.
+ */
+function getFilterGpuChannelCount(filter: Filter, datasetIdx = 0): number {
+ return isTimeIntervalFilter(filter, datasetIdx) ? 2 : 1;
+}
+
+function channelOccupiedByFilter(f: Filter, dataId: string, channel: number): boolean {
+ const dataIdx = toArray(f.dataId).indexOf(dataId);
+ if (dataIdx < 0 || !f.gpu) {
+ return false;
+ }
+ return (
+ toArray(f.gpuChannel)[dataIdx] === channel || toArray(f.gpuEndChannel)[dataIdx] === channel
+ );
+}
+
/**
* Set gpu mode based on current number of gpu filters exists
*/
@@ -57,12 +75,8 @@ export function assignGpuChannel(filter: Filter, filters: Filter[]) {
const gpuChannel = filter.gpuChannel || [];
filter.dataId.forEach((dataId, datasetIdx) => {
- const findGpuChannel = channel => f => {
- const dataIdx = toArray(f.dataId).indexOf(dataId);
- return (
- f.id !== filter.id && dataIdx > -1 && f.gpu && toArray(f.gpuChannel)[dataIdx] === channel
- );
- };
+ const findGpuChannel = channel => f =>
+ f.id !== filter.id && channelOccupiedByFilter(f, dataId, channel);
if (
Number.isFinite(gpuChannel[datasetIdx]) &&
@@ -92,11 +106,78 @@ export function assignGpuChannel(filter: Filter, filters: Filter[]) {
};
}
- return {
+ const next: Filter = {
...filter,
gpuChannel
};
+
+ if (!filter.dataId.some((_, idx) => isTimeIntervalFilter(filter, idx))) {
+ delete next.gpuEndChannel;
+ return next;
+ }
+
+ const withEnd = assignGpuEndChannel(next, filters);
+ if (!withEnd.gpu) {
+ return {
+ ...filter,
+ gpu: false
+ };
+ }
+ return withEnd;
+}
+
+/**
+ * Reserve a second GPU channel for the end timestamp of an interval time filter.
+ */
+function assignGpuEndChannel(filter: Filter, filters: Filter[]): Filter {
+ const gpuEndChannel = [...(filter.gpuEndChannel || [])];
+
+ filter.dataId.forEach((dataId, datasetIdx) => {
+ if (!isTimeIntervalFilter(filter, datasetIdx)) {
+ return;
+ }
+
+ const startChannel = toArray(filter.gpuChannel)[datasetIdx];
+ const findGpuChannel = channel => f =>
+ f.id !== filter.id && channelOccupiedByFilter(f, dataId, channel);
+
+ if (
+ Number.isFinite(gpuEndChannel[datasetIdx]) &&
+ gpuEndChannel[datasetIdx] !== startChannel &&
+ !filters.find(findGpuChannel(gpuEndChannel[datasetIdx]))
+ ) {
+ return;
+ }
+
+ let i = 0;
+ while (i < MAX_GPU_FILTERS) {
+ if (i !== startChannel && !filters.find(findGpuChannel(i))) {
+ gpuEndChannel[datasetIdx] = i;
+ return;
+ }
+ i++;
+ }
+
+ gpuEndChannel[datasetIdx] = undefined as unknown as number;
+ });
+
+ const assignedAll = filter.dataId.every(
+ (_, idx) => !isTimeIntervalFilter(filter, idx) || Number.isFinite(gpuEndChannel[idx])
+ );
+
+ if (!assignedAll) {
+ return {
+ ...filter,
+ gpu: false
+ };
+ }
+
+ return {
+ ...filter,
+ gpuEndChannel
+ };
}
+
/**
* Edit filter.gpu to ensure that only
* X number of gpu filers can coexist.
@@ -107,13 +188,14 @@ export function resetFilterGpuMode(filters: Filter[]): Filter[] {
return filters.map(f => {
if (f.gpu) {
let gpu = true;
- toArray(f.dataId).forEach(dataId => {
+ toArray(f.dataId).forEach((dataId, datasetIdx) => {
const count = gpuPerDataset[dataId];
+ const needed = getFilterGpuChannelCount(f, datasetIdx);
- if (count === MAX_GPU_FILTERS) {
+ if ((count || 0) + needed > MAX_GPU_FILTERS) {
gpu = false;
} else {
- gpuPerDataset[dataId] = count ? count + 1 : 1;
+ gpuPerDataset[dataId] = (count || 0) + needed;
}
});
@@ -140,6 +222,11 @@ function getEmptyFilterRange() {
*/
const defaultGetIndex = d => d.index;
+function isEndGpuChannel(filter: Filter, dataId: string, channelIndex: number): boolean {
+ const datasetIdx = toArray(filter.dataId).indexOf(dataId);
+ return datasetIdx > -1 && toArray(filter.gpuEndChannel)[datasetIdx] === channelIndex;
+}
+
const getFilterValueAccessor =
(channels: (Filter | undefined)[], dataId: string, fields: any[]) =>
(dc: DataContainerInterface) =>
@@ -149,11 +236,14 @@ const getFilterValueAccessor =
) =>
(d, objectInfo?: {index: number}) => {
// for empty channel, value is 0 and min max would be [0, 0]
- const channelValues = channels.map(filter => {
+ const channelValues = channels.map((filter, channelIndex) => {
if (!filter) {
return 0;
}
- const fieldIndex = getDatasetFieldIndexForFilter(dataId, filter);
+ const useEndField = isEndGpuChannel(filter, dataId, channelIndex);
+ const fieldIndex = useEndField
+ ? getDatasetEndFieldIndexForFilter(dataId, filter)
+ : getDatasetFieldIndexForFilter(dataId, filter);
const field = fields[fieldIndex];
let value;
@@ -173,11 +263,17 @@ const getFilterValueAccessor =
: data;
}
- return notNullorUndefined(value)
- ? Array.isArray(value)
- ? value.map(v => v - filter.domain?.[0])
- : value - filter.domain?.[0]
- : Number.MIN_SAFE_INTEGER;
+ if (!notNullorUndefined(value)) {
+ // Null end timestamps mean "still active": map to domain max so end >= windowStart always holds.
+ if (useEndField) {
+ return (filter.domain?.[1] ?? 0) - (filter.domain?.[0] ?? 0);
+ }
+ return Number.MIN_SAFE_INTEGER;
+ }
+
+ return Array.isArray(value)
+ ? value.map(v => v - filter.domain?.[0])
+ : value - filter.domain?.[0];
});
// TODO: can we refactor the above to avoid the transformation below?
@@ -199,6 +295,34 @@ function isFilterTriggerEqual(a, b) {
return a === b || (a?.name === b?.name && a?.domain0 === b?.domain0);
}
+function findFilterOnGpuChannel(
+ filters: Filter[],
+ dataId: string,
+ channel: number
+): Filter | undefined {
+ return filters.find(
+ f =>
+ f.gpu &&
+ f.dataId.includes(dataId) &&
+ f.gpuChannel &&
+ f.gpuChannel[f.dataId.indexOf(dataId)] === channel
+ );
+}
+
+function findFilterOnGpuEndChannel(
+ filters: Filter[],
+ dataId: string,
+ channel: number
+): Filter | undefined {
+ return filters.find(
+ f =>
+ f.gpu &&
+ f.dataId.includes(dataId) &&
+ f.gpuEndChannel &&
+ f.gpuEndChannel[f.dataId.indexOf(dataId)] === channel
+ );
+}
+
/**
* Get filter properties for gpu filtering
*/
@@ -215,29 +339,42 @@ export function getGpuFilterProps(
const channels: (Filter | undefined)[] = [];
for (let i = 0; i < MAX_GPU_FILTERS; i++) {
- const filter = filters.find(
- f =>
- f.gpu &&
- f.dataId.includes(dataId) &&
- f.gpuChannel &&
- f.gpuChannel[f.dataId.indexOf(dataId)] === i
+ const filter = findFilterOnGpuChannel(filters, dataId, i);
+ const endFilter = filter ? undefined : findFilterOnGpuEndChannel(filters, dataId, i);
+ const assigned = filter || endFilter;
+ const datasetIdx = assigned ? assigned.dataId.indexOf(dataId) : -1;
+ const isIntervalStart = Boolean(
+ filter && datasetIdx > -1 && isTimeIntervalFilter(filter, datasetIdx)
);
- filterRange[i][0] = filter ? filter.value[0] - filter.domain?.[0] : 0;
- filterRange[i][1] = filter ? filter.value[1] - filter.domain?.[0] : 0;
+ if (endFilter) {
+ filterRange[i][0] = endFilter.value[0] - endFilter.domain?.[0];
+ filterRange[i][1] = endFilter.domain?.[1] - endFilter.domain?.[0];
+ } else if (isIntervalStart && filter) {
+ // start <= windowEnd
+ filterRange[i][0] = 0;
+ filterRange[i][1] = filter.value[1] - filter.domain?.[0];
+ } else {
+ filterRange[i][0] = filter ? filter.value[0] - filter.domain?.[0] : 0;
+ filterRange[i][1] = filter ? filter.value[1] - filter.domain?.[0] : 0;
+ }
+
const oldFilterTrigger = oldGpuFilter?.filterValueUpdateTriggers?.[`gpuFilter_${i}`] || null;
- const trigger = filter
+ const triggerName = endFilter
+ ? toArray((endFilter as TimeRangeFilter).endName)[datasetIdx]
+ : assigned?.name[datasetIdx];
+ const trigger = assigned
? {
- name: filter.name[filter.dataId.indexOf(dataId)],
- domain0: filter.domain?.[0]
+ name: triggerName || assigned.name[datasetIdx],
+ domain0: assigned.domain?.[0]
}
: null;
// don't create a new object, cause deck.gl use shallow compare
triggers[`gpuFilter_${i}`] = isFilterTriggerEqual(trigger, oldFilterTrigger)
? oldFilterTrigger
: trigger;
- channels.push(filter);
+ channels.push(assigned);
}
const filterValueAccessor = getFilterValueAccessor(channels, dataId, fields);
@@ -263,3 +400,17 @@ export function getDatasetFieldIndexForFilter(dataId: string, filter: Filter): n
return notNullorUndefined(fieldIndex) ? fieldIndex : -1;
}
+
+/**
+ * Return dataset field index from filter.endFieldIdx for interval time filters.
+ */
+export function getDatasetEndFieldIndexForFilter(dataId: string, filter: Filter): number {
+ const datasetIndex = toArray(filter.dataId).indexOf(dataId);
+ if (datasetIndex < 0) {
+ return -1;
+ }
+
+ const fieldIndex = toArray((filter as TimeRangeFilter).endFieldIdx)[datasetIndex];
+
+ return notNullorUndefined(fieldIndex) ? fieldIndex : -1;
+}
diff --git a/src/types/reducers.d.ts b/src/types/reducers.d.ts
index b35bb6217..b4a44ba1d 100644
--- a/src/types/reducers.d.ts
+++ b/src/types/reducers.d.ts
@@ -168,8 +168,14 @@ export type FilterBase<L extends LineChart> = {
// gpu filter
gpu: boolean;
gpuChannel?: number[];
+ gpuEndChannel?: number[];
fieldType?: string;
+ // Optional end timestamp for duration-based time filters (parallel to name/fieldIdx)
+ endName?: (string | null | undefined)[];
+ endFieldIdx?: (number | null | undefined)[];
+ endMappedValue?: ((number | null)[] | null | undefined)[];
+
// polygon
layerId?: string[];
};
@@ -215,6 +221,14 @@ export type TimeRangeFilter = FilterBase<LineChart> &
syncTimelineMode: SyncTimelineMode;
animationWindow: string;
invertTrendColor: boolean;
+ /**
+ * When set, a feature is visible while the playback window overlaps
+ * [startField, endField] rather than requiring a single timestamp in range.
+ */
+ endName?: (string | null | undefined)[];
+ endFieldIdx?: (number | null | undefined)[];
+ endMappedValue?: ((number | null)[] | null | undefined)[];
+ gpuEndChannel?: number[];
};
export type PolygonFilter = FilterBase<LineChart> & {
diff --git a/src/types/schemas.d.ts b/src/types/schemas.d.ts
index 11c92cb96..eaad4540b 100644
--- a/src/types/schemas.d.ts
+++ b/src/types/schemas.d.ts
@@ -11,6 +11,7 @@ export type SavedFilter = {
dataId: Filter['dataId'];
id: Filter['id'];
name: Filter['name'];
+ endName?: Filter['endName'];
type: Filter['type'];
value: Filter['value'];
// deprecated
diff --git a/src/utils/src/filter-utils.ts b/src/utils/src/filter-utils.ts
index a3ab46ede..5373a1237 100644
--- a/src/utils/src/filter-utils.ts
+++ b/src/utils/src/filter-utils.ts
@@ -85,7 +85,8 @@ export const TimestampStepMap = [
export const FILTER_UPDATER_PROPS = keyMirror({
dataId: null,
name: null,
- layerId: null
+ layerId: null,
+ endName: null
});
export const FILTER_COMPONENTS = {
@@ -129,6 +130,90 @@ export const FILTER_ID_LENGTH = 4;
export const LAYER_FILTERS = [FILTER_TYPES.polygon];
+/**
+ * True when a timeRange filter has an end timestamp field for the given dataset.
+ * Features stay visible while the playback window overlaps [start, end].
+ */
+export function isTimeIntervalFilter(filter: Filter, datasetIdx = 0): boolean {
+ return Boolean(
+ filter?.type === FILTER_TYPES.timeRange &&
+ toArray((filter as TimeRangeFilter).endName)[datasetIdx]
+ );
+}
+
+function isFullTimeDomainValue(filter: TimeRangeFilter): boolean {
+ return (
+ Array.isArray(filter.value) &&
+ Array.isArray(filter.domain) &&
+ filter.value[0] === filter.domain[0] &&
+ filter.value[1] === filter.domain[1]
+ );
+}
+
+/**
+ * Interval overlap: feature [start, end] intersects window [w0, w1].
+ * A null/undefined end means the feature is still active (open-ended).
+ * Inverted intervals (end < start) are treated as invalid and hidden.
+ */
+export function timeWindowOverlapsInterval(
+ start: number | null | undefined,
+ end: number | null | undefined,
+ window: [number, number]
+): boolean {
+ if (!notNullorUndefined(start) || Number.isNaN(start)) {
+ return false;
+ }
+ const featureEnd = notNullorUndefined(end) && !Number.isNaN(end) ? end : Number.POSITIVE_INFINITY;
+ if (featureEnd < start) {
+ return false;
+ }
+ return start <= window[1] && featureEnd >= window[0];
+}
+
+function omitTimeIntervalFields<T extends Filter>(filter: T): T {
+ const {
+ endName: _endName,
+ endFieldIdx: _endFieldIdx,
+ endMappedValue: _endMappedValue,
+ gpuEndChannel: _gpuEndChannel,
+ ...rest
+ } = filter as T & {
+ endName?: unknown;
+ endFieldIdx?: unknown;
+ endMappedValue?: unknown;
+ gpuEndChannel?: unknown;
+ };
+ return rest as T;
+}
+
+function clearTimeFilterEndFieldAtIndex(
+ filter: TimeRangeFilter,
+ filterDatasetIndex: number
+): TimeRangeFilter {
+ const endName = [...toArray(filter.endName)];
+ const endFieldIdx = [...toArray(filter.endFieldIdx)];
+ const endMappedValue = [...toArray(filter.endMappedValue)];
+ const gpuEndChannel: number[] = [...(filter.gpuEndChannel || [])];
+
+ endName[filterDatasetIndex] = null;
+ endFieldIdx[filterDatasetIndex] = null;
+ endMappedValue[filterDatasetIndex] = null;
+ gpuEndChannel[filterDatasetIndex] = undefined as unknown as number;
+
+ const hasAnyEnd = endName.some(Boolean);
+ if (!hasAnyEnd) {
+ return omitTimeIntervalFields(filter);
+ }
+
+ return {
+ ...filter,
+ endName,
+ endFieldIdx,
+ endMappedValue,
+ gpuEndChannel
+ };
+}
+
/**
* Generates a filter with a dataset id as dataId
*/
@@ -236,7 +321,7 @@ export function validateFilter<K extends KeplerTableModel<K, L>, L>(
};
const fieldName = initializeFilter.name[filterDatasetIndex];
- const {filter: updatedFilter, dataset: updatedDataset} = applyFilterFieldName(
+ let {filter: updatedFilter, dataset: updatedDataset} = applyFilterFieldName(
initializeFilter,
datasets,
datasetId,
@@ -249,6 +334,29 @@ export function validateFilter<K extends KeplerTableModel<K, L>, L>(
return failed;
}
+ const endName = toArray((filter as TimeRangeFilter).endName)[filterDatasetIndex];
+ if (updatedFilter.type === FILTER_TYPES.timeRange && endName) {
+ const appliedEnd = applyTimeFilterEndFieldName(
+ updatedFilter,
+ {
+ ...datasets,
+ [datasetId]: updatedDataset
+ },
+ datasetId,
+ endName,
+ filterDatasetIndex
+ );
+ if (appliedEnd.filter) {
+ updatedFilter = appliedEnd.filter;
+ updatedDataset = appliedEnd.dataset;
+ } else {
+ updatedFilter = clearTimeFilterEndFieldAtIndex(
+ updatedFilter as TimeRangeFilter,
+ filterDatasetIndex
+ );
+ }
+ }
+
// don't adjust value yet before all datasets are loaded
updatedFilter.view = filter.view ?? updatedFilter.view;
@@ -530,6 +638,14 @@ export function getFilterFunction<L extends {config: {dataId: string | null}; id
const accessor = Array.isArray(mappedValue)
? data => mappedValue[data.index]
: data => timeToUnixMilli(valueAccessor(data), field.format);
+
+ const datasetIdx = toArray(filter.dataId).indexOf(dataId);
+ const endMapped = (filter as TimeRangeFilter).endMappedValue?.[datasetIdx];
+ if (isTimeIntervalFilter(filter, datasetIdx) && Array.isArray(endMapped)) {
+ return data =>
+ timeWindowOverlapsInterval(accessor(data), endMapped[data.index], filter.value);
+ }
+
return data => isInRange(accessor(data), filter.value);
}
case FILTER_TYPES.polygon: {
@@ -648,7 +764,7 @@ export function diffFilters(
filterChanged = set([record, filter.id], 'added', filterChanged);
} else {
// check what has changed
- ['name', 'value', 'dataId'].forEach(prop => {
+ ['name', 'endName', 'value', 'dataId'].forEach(prop => {
if (filter[prop] !== oldFilter[prop]) {
filterChanged = set([record, filter.id], `${prop}_changed`, filterChanged);
}
@@ -1027,9 +1143,17 @@ export function applyFilterFieldName<K extends KeplerTableModel<K, L>, L>(
...(filter.plotType ? {plotType: filter.plotType} : {})
};
- if (mergeDomain) {
- const domainSteps: (Filter & {step?: number}) | null =
- mergeFilterDomain(newFilter, datasets) ?? ({} as Filter);
+ if (newFilter.type !== FILTER_TYPES.timeRange) {
+ newFilter = omitTimeIntervalFields(newFilter);
+ } else if (toArray(newFilter.endName)[filterDatasetIndex] === fieldName) {
+ newFilter = clearTimeFilterEndFieldAtIndex(newFilter as TimeRangeFilter, filterDatasetIndex);
+ }
+
+ if (mergeDomain || isTimeIntervalFilter(newFilter, filterDatasetIndex)) {
+ const domainSteps: (Filter & {step?: number}) | null = mergeFilterDomain(newFilter, {
+ ...datasets,
+ [datasetId]: dataset
+ });
if (domainSteps) {
const {domain, step} = domainSteps;
newFilter.domain = domain;
@@ -1046,6 +1170,16 @@ export function applyFilterFieldName<K extends KeplerTableModel<K, L>, L>(
...newFilter,
value: filter.value
};
+ } else if (
+ newFilter.type === FILTER_TYPES.timeRange &&
+ toArray(newFilter.endName).some(Boolean) &&
+ newFilter.domain
+ ) {
+ // Selecting a new start field resets the window to the merged start/end domain
+ newFilter = {
+ ...newFilter,
+ value: newFilter.domain
+ };
}
return {
@@ -1054,6 +1188,104 @@ export function applyFilterFieldName<K extends KeplerTableModel<K, L>, L>(
};
}
+/**
+ * Set or clear the optional end timestamp field on a timeRange filter.
+ * When set, animation uses interval overlap instead of a single timestamp.
+ */
+export function applyTimeFilterEndFieldName<K extends KeplerTableModel<K, L>, L>(
+ filter: Filter,
+ datasets: Record<string, K>,
+ datasetId: string,
+ fieldName: string | null | undefined,
+ filterDatasetIndex = 0
+): {
+ filter: Filter | null;
+ dataset: K;
+} {
+ const dataset = datasets[datasetId];
+ if (!dataset || filter.type !== FILTER_TYPES.timeRange) {
+ return {filter: null, dataset};
+ }
+
+ const timeFilter = filter as TimeRangeFilter;
+
+ if (!fieldName) {
+ const cleared = clearTimeFilterEndFieldAtIndex(timeFilter, filterDatasetIndex);
+ const merged = mergeFilterDomain(cleared, datasets);
+ if (merged?.domain) {
+ const wasFullDomain = isFullTimeDomainValue(timeFilter);
+ return {
+ filter: {
+ ...cleared,
+ domain: merged.domain,
+ step: merged.step ?? cleared.step,
+ value: wasFullDomain
+ ? merged.domain
+ : adjustValueToFilterDomain(timeFilter.value, {
+ ...cleared,
+ domain: merged.domain
+ })
+ },
+ dataset
+ };
+ }
+ return {filter: cleared, dataset};
+ }
+
+ const fieldIndex = dataset.getColumnFieldIdx(fieldName);
+ if (fieldIndex === -1) {
+ return {filter: null, dataset};
+ }
+
+ const field = dataset.fields[fieldIndex];
+ if (field?.type !== ALL_FIELD_TYPES.timestamp) {
+ return {filter: null, dataset};
+ }
+
+ if (toArray(timeFilter.name)[filterDatasetIndex] === fieldName) {
+ return {filter: null, dataset};
+ }
+
+ const filterProps = dataset.getColumnFilterProps(fieldName);
+ if (!filterProps || !('mappedValue' in filterProps)) {
+ return {filter: null, dataset};
+ }
+
+ const wasFullDomain = isFullTimeDomainValue(timeFilter);
+ let newFilter: TimeRangeFilter = {
+ ...timeFilter,
+ endName: Object.assign([...toArray(timeFilter.endName)], {
+ [filterDatasetIndex]: fieldName
+ }),
+ endFieldIdx: Object.assign([...toArray(timeFilter.endFieldIdx)], {
+ [filterDatasetIndex]: fieldIndex
+ }),
+ endMappedValue: Object.assign([...toArray(timeFilter.endMappedValue)], {
+ [filterDatasetIndex]: (filterProps as TimeRangeFieldDomain).mappedValue
+ })
+ };
+
+ const merged = mergeFilterDomain(newFilter, {
+ ...datasets,
+ [datasetId]: dataset
+ });
+ if (merged?.domain) {
+ newFilter = {
+ ...newFilter,
+ domain: merged.domain as [number, number],
+ step: merged.step ?? newFilter.step,
+ value: (wasFullDomain
+ ? merged.domain
+ : adjustValueToFilterDomain(timeFilter.value, {
+ ...newFilter,
+ domain: merged.domain
+ })) as [number, number]
+ };
+ }
+
+ return {filter: newFilter, dataset};
+}
+
/**
* Merge the domains of a filter in case it applies to multiple datasets
*/
@@ -1069,6 +1301,11 @@ export function mergeFilterDomain(
const dataset = datasets[filterDataId];
const filterProps = dataset.getColumnFilterProps(filter.name[idx]);
domainSteps = mergeFilterDomainStep(domainSteps ?? ({} as Filter), filterProps);
+ const endName = toArray((filter as TimeRangeFilter).endName)[idx];
+ if (endName) {
+ const endProps = dataset.getColumnFilterProps(endName);
+ domainSteps = mergeFilterDomainStep(domainSteps ?? ({} as Filter), endProps);
+ }
});
return domainSteps;
}
diff --git a/src/utils/src/index.ts b/src/utils/src/index.ts
index ff6cc91b1..331695bce 100644
--- a/src/utils/src/index.ts
+++ b/src/utils/src/index.ts
@@ -54,6 +54,7 @@ export {
histogramFromValues,
histogramFromDomain,
histogramFromOrdinal,
+ histogramFromTimeIntervals,
mergePolygonLayerIndexes,
runGpuFilterForPlot,
updateTimeFilterPlotType
diff --git a/src/utils/src/plot.ts b/src/utils/src/plot.ts
index c1ff3b2e2..475769d32 100644
--- a/src/utils/src/plot.ts
+++ b/src/utils/src/plot.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: MIT
// Copyright contributors to the kepler.gl project
-import {bisectLeft, extent, histogram as d3Histogram, ticks} from 'd3-array';
+import {bisectLeft, bisectRight, extent, histogram as d3Histogram, ticks} from 'd3-array';
import isEqual from 'es-toolkit/compat/isEqual';
import {getFilterMappedValue, getInitialInterval, intervalToFunction} from './time';
import moment from 'moment';
@@ -18,7 +18,7 @@ import {
ValueOf,
LineDatum
} from '@kepler.gl/types';
-import {notNullorUndefined} from '@kepler.gl/common-utils';
+import {notNullorUndefined, toArray} from '@kepler.gl/common-utils';
import {
ANIMATION_WINDOW,
BINS,
@@ -159,7 +159,78 @@ export function histogramFromOrdinal(
}
/**
- *
+ * Bin rows by time interval overlap: a feature [start, end] is counted in every
+ * bin whose range intersects that span. Null/undefined end is treated as still
+ * active through the last threshold (open-ended).
+ */
+export function histogramFromTimeIntervals(
+ thresholds: number[],
+ indexes: number[],
+ startAccessor: (idx: number) => number | null | undefined,
+ endAccessor: (idx: number) => number | null | undefined
+): Bin[] {
+ if (!thresholds || thresholds.length < 2) {
+ return [];
+ }
+
+ const nBins = thresholds.length - 1;
+ const bins: Bin[] = [];
+ for (let i = 0; i < nBins; i++) {
+ bins.push({
+ count: 0,
+ indexes: [],
+ x0: thresholds[i],
+ x1: thresholds[i + 1]
+ });
+ }
+
+ const lastThreshold = thresholds[nBins];
+
+ for (const idx of indexes) {
+ const start = startAccessor(idx);
+ if (!notNullorUndefined(start) || Number.isNaN(start)) {
+ continue;
+ }
+ const rawEnd = endAccessor(idx);
+ if (notNullorUndefined(rawEnd) && !Number.isNaN(rawEnd) && rawEnd < start) {
+ continue;
+ }
+ const end = notNullorUndefined(rawEnd) && !Number.isNaN(rawEnd) ? rawEnd : lastThreshold;
+
+ let startBin = bisectRight(thresholds, start) - 1;
+ let endBin = bisectRight(thresholds, end) - 1;
+
+ if (startBin < 0) startBin = 0;
+ if (startBin >= nBins && start === lastThreshold) startBin = nBins - 1;
+ if (endBin >= nBins) endBin = nBins - 1;
+ if (endBin < 0 || startBin >= nBins || endBin < startBin) {
+ continue;
+ }
+
+ for (let i = startBin; i <= endBin; i++) {
+ bins[i].indexes.push(idx);
+ bins[i].count += 1;
+ }
+ }
+
+ return bins.filter(b => b.count > 0);
+}
+
+function getEndMappedValue(dataset, filter: TimeRangeFilter): (number | null)[] | null {
+ const datasetIdx = toArray(filter.dataId).indexOf(dataset.id);
+ const fromFilter = filter.endMappedValue?.[datasetIdx];
+ if (Array.isArray(fromFilter)) {
+ return fromFilter;
+ }
+ const endName = toArray(filter.endName)[datasetIdx];
+ if (!endName || typeof dataset.getColumnField !== 'function') {
+ return null;
+ }
+ const field = dataset.getColumnField(endName);
+ return field?.filterProps?.mappedValue || null;
+}
+
+/**
* @param domain
* @param values
* @param numBins
@@ -226,6 +297,15 @@ export function binByTime(indexes, dataset, interval, filter) {
return null;
}
const intervalBins = getBinThresholds(interval, filter.domain);
+ const endMapped = getEndMappedValue(dataset, filter);
+ if (Array.isArray(endMapped)) {
+ return histogramFromTimeIntervals(
+ intervalBins,
+ indexes,
+ idx => mappedValue[idx],
+ idx => endMapped[idx]
+ );
+ }
const valueAccessor = idx => mappedValue[idx];
const bins = histogramFromThreshold(intervalBins, indexes, valueAccessor);
diff --git a/test/node/utils/filter-utils-test.js b/test/node/utils/filter-utils-test.js
index 4feef3557..9bb08534b 100644
--- a/test/node/utils/filter-utils-test.js
+++ b/test/node/utils/filter-utils-test.js
@@ -19,7 +19,10 @@ import {
getTimestampFieldDomain,
scaleSourceDomainToDestination,
mergeFilterWithTimeline,
- createDataContainer
+ createDataContainer,
+ isTimeIntervalFilter,
+ timeWindowOverlapsInterval,
+ applyTimeFilterEndFieldName
} from '@kepler.gl/utils';
import {FILTER_TYPES} from '@kepler.gl/constants';
@@ -910,3 +913,150 @@ test('filterUtils -> getPolygonFilterFunctor -> arc layer validates both endpoin
t.end();
});
+
+test('filterUtils -> timeWindowOverlapsInterval', t => {
+ t.equal(timeWindowOverlapsInterval(0, 10, [2, 8]), true, 'window inside feature interval');
+ t.equal(timeWindowOverlapsInterval(0, 10, [-5, 0]), true, 'window touches start');
+ t.equal(timeWindowOverlapsInterval(0, 10, [10, 15]), true, 'window touches end');
+ t.equal(timeWindowOverlapsInterval(0, 10, [11, 20]), false, 'window after feature');
+ t.equal(timeWindowOverlapsInterval(20, 30, [0, 10]), false, 'window before feature');
+ t.equal(
+ timeWindowOverlapsInterval(5, null, [0, 10]),
+ true,
+ 'null end is still active once started'
+ );
+ t.equal(timeWindowOverlapsInterval(20, null, [0, 10]), false, 'null end is hidden before start');
+ t.equal(timeWindowOverlapsInterval(null, 10, [0, 10]), false, 'null start is hidden');
+ t.equal(
+ timeWindowOverlapsInterval(10, 0, [0, 20]),
+ false,
+ 'inverted interval (end < start) is hidden'
+ );
+ t.equal(
+ timeWindowOverlapsInterval(5, 5, [0, 10]),
+ true,
+ 'zero-length interval at a point overlaps'
+ );
+ t.end();
+});
+
+test('filterUtils -> getFilterFunction time interval overlap', t => {
+ const startMapped = [0, 10, 20, 30];
+ const endMapped = [15, 15, 40, null];
+ const field = {
+ filterProps: {mappedValue: startMapped},
+ valueAccessor: () => null,
+ format: ''
+ };
+ const filter = {
+ type: FILTER_TYPES.timeRange,
+ dataId: ['ds'],
+ value: [12, 18],
+ endName: ['end'],
+ endMappedValue: [endMapped]
+ };
+
+ t.ok(isTimeIntervalFilter(filter, 0), 'should detect interval mode from endName');
+
+ const filterFunction = getFilterFunction(field, 'ds', filter, [], null);
+
+ t.equal(filterFunction({index: 0}), true, '[0, 15] overlaps window [12, 18]');
+ t.equal(filterFunction({index: 1}), true, '[10, 15] overlaps window [12, 18]');
+ t.equal(filterFunction({index: 2}), false, '[20, 40] starts after the window');
+ t.equal(filterFunction({index: 3}), false, '[30, inf] has not started yet');
+
+ const instantFn = getFilterFunction(
+ field,
+ 'ds',
+ {
+ type: FILTER_TYPES.timeRange,
+ dataId: ['ds'],
+ value: [12, 18]
+ },
+ [],
+ null
+ );
+ t.equal(instantFn({index: 0}), false, 'instant mode still requires the timestamp in range');
+ t.equal(instantFn({index: 1}), false, 'timestamp 10 is outside [12, 18]');
+ t.end();
+});
+
+test('filterUtils -> applyTimeFilterEndFieldName', t => {
+ const dataset = {
+ id: 'ds',
+ fields: [
+ {
+ name: 'start',
+ type: 'timestamp',
+ filterProps: {
+ fieldType: 'timestamp',
+ mappedValue: [0, 10],
+ domain: [0, 10],
+ step: 1
+ }
+ },
+ {
+ name: 'end',
+ type: 'timestamp',
+ filterProps: {
+ fieldType: 'timestamp',
+ mappedValue: [20, 50],
+ domain: [20, 50],
+ step: 1
+ }
+ },
+ {
+ name: 'other',
+ type: 'real',
+ filterProps: {fieldType: 'real', domain: [0, 1], step: 0.1}
+ }
+ ],
+ getColumnFieldIdx(name) {
+ return this.fields.findIndex(f => f.name === name);
+ },
+ getColumnFilterProps(name) {
+ return this.fields.find(f => f.name === name)?.filterProps || null;
+ }
+ };
+
+ const filter = {
+ type: FILTER_TYPES.timeRange,
+ dataId: ['ds'],
+ name: ['start'],
+ fieldIdx: [0],
+ domain: [0, 10],
+ value: [0, 10],
+ step: 1
+ };
+
+ const {filter: withEnd} = applyTimeFilterEndFieldName(filter, {ds: dataset}, 'ds', 'end', 0);
+ t.ok(withEnd, 'should apply a timestamp end field');
+ t.deepEqual(withEnd.endName, ['end'], 'should store endName');
+ t.deepEqual(withEnd.endFieldIdx, [1], 'should store endFieldIdx');
+ t.deepEqual(withEnd.domain, [0, 50], 'domain should span start min to end max');
+ t.deepEqual(withEnd.value, [0, 50], 'full-range window should expand with domain');
+
+ const {filter: sameAsStart} = applyTimeFilterEndFieldName(
+ filter,
+ {ds: dataset},
+ 'ds',
+ 'start',
+ 0
+ );
+ t.equal(sameAsStart, null, 'should reject using the start field as end');
+
+ const {filter: nonTimestamp} = applyTimeFilterEndFieldName(
+ filter,
+ {ds: dataset},
+ 'ds',
+ 'other',
+ 0
+ );
+ t.equal(nonTimestamp, null, 'should reject a non-timestamp end field');
+
+ const {filter: cleared} = applyTimeFilterEndFieldName(withEnd, {ds: dataset}, 'ds', null, 0);
+ t.notOk(cleared.endName, 'clearing end field should remove endName');
+ t.deepEqual(cleared.domain, [0, 10], 'domain should shrink back to the start field');
+
+ t.end();
+});
diff --git a/test/node/utils/gpu-filter-utils-test.js b/test/node/utils/gpu-filter-utils-test.js
index 6e766b34e..102acd687 100644
--- a/test/node/utils/gpu-filter-utils-test.js
+++ b/test/node/utils/gpu-filter-utils-test.js
@@ -6,8 +6,10 @@ import {
resetFilterGpuMode,
assignGpuChannel,
assignGpuChannels,
- getDatasetFieldIndexForFilter
+ getDatasetFieldIndexForFilter,
+ getGpuFilterProps
} from '@kepler.gl/table';
+import {FILTER_TYPES} from '@kepler.gl/constants';
test('gpuFilterUtils -> resetFilterGpuMode', t => {
const testFilters = [
@@ -199,3 +201,142 @@ test('gpuFilterUtils -> getDatasetFieldIndexForFilter', t => {
t.end();
});
+
+test('gpuFilterUtils -> assignGpuChannel interval time filter', t => {
+ const assigned = assignGpuChannel(
+ {
+ id: '3',
+ dataId: ['a'],
+ gpu: true,
+ type: FILTER_TYPES.timeRange,
+ endName: ['end']
+ },
+ [{id: '2', dataId: ['a'], gpu: true, gpuChannel: [0]}]
+ );
+
+ t.deepEqual(
+ assigned,
+ {
+ id: '3',
+ dataId: ['a'],
+ gpu: true,
+ type: FILTER_TYPES.timeRange,
+ endName: ['end'],
+ gpuChannel: [1],
+ gpuEndChannel: [2]
+ },
+ 'should reserve two channels for start and end timestamps'
+ );
+
+ const noRoom = assignGpuChannel(
+ {
+ id: '6',
+ dataId: ['a'],
+ gpu: true,
+ type: FILTER_TYPES.timeRange,
+ endName: ['end']
+ },
+ [
+ {id: '2', dataId: ['a'], gpu: true, gpuChannel: [0]},
+ {id: '3', dataId: ['a'], gpu: true, gpuChannel: [1]},
+ {id: '4', dataId: ['a'], gpu: true, gpuChannel: [2]}
+ ]
+ );
+
+ t.deepEqual(
+ noRoom,
+ {
+ id: '6',
+ dataId: ['a'],
+ gpu: false,
+ type: FILTER_TYPES.timeRange,
+ endName: ['end']
+ },
+ 'should fall back to CPU when two channels are not available'
+ );
+
+ t.end();
+});
+
+test('gpuFilterUtils -> getGpuFilterProps unchanged for single-channel filters', t => {
+ const filters = [
+ {
+ id: 'f1',
+ gpu: true,
+ type: FILTER_TYPES.timeRange,
+ dataId: ['ds'],
+ name: ['timestamp'],
+ fieldIdx: [0],
+ gpuChannel: [0],
+ domain: [1000, 5000],
+ value: [2000, 3000]
+ },
+ {
+ id: 'f2',
+ gpu: true,
+ type: FILTER_TYPES.range,
+ dataId: ['ds'],
+ name: ['value'],
+ fieldIdx: [1],
+ gpuChannel: [2],
+ domain: [0, 10],
+ value: [2, 8]
+ }
+ ];
+ const fields = [
+ {name: 'timestamp', filterProps: {mappedValue: [1000, 2000]}, valueAccessor: d => d.timestamp},
+ {name: 'value', valueAccessor: d => d.value}
+ ];
+
+ const gpu = getGpuFilterProps(filters, 'ds', fields);
+
+ t.deepEqual(gpu.filterRange[0], [1000, 2000], 'timeRange channel stays [v0-domain0, v1-domain0]');
+ t.deepEqual(gpu.filterRange[1], [0, 0], 'unused channel stays [0, 0]');
+ t.deepEqual(gpu.filterRange[2], [2, 8], 'range channel stays [v0-domain0, v1-domain0]');
+ t.equal(gpu.filterValueUpdateTriggers.gpuFilter_0.name, 'timestamp');
+ t.equal(gpu.filterValueUpdateTriggers.gpuFilter_2.name, 'value');
+ t.equal(gpu.filterValueUpdateTriggers.gpuFilter_1, null);
+ t.equal(Object.prototype.hasOwnProperty.call(filters[0], 'gpuEndChannel'), false);
+
+ t.end();
+});
+
+test('gpuFilterUtils -> getGpuFilterProps interval overlap ranges', t => {
+ const filters = [
+ {
+ id: 'f1',
+ gpu: true,
+ type: FILTER_TYPES.timeRange,
+ dataId: ['ds'],
+ name: ['start'],
+ endName: ['end'],
+ fieldIdx: [0],
+ endFieldIdx: [1],
+ gpuChannel: [0],
+ gpuEndChannel: [1],
+ domain: [1000, 5000],
+ value: [2000, 3000]
+ }
+ ];
+ const fields = [
+ {name: 'start', filterProps: {mappedValue: [1000, 2000]}, valueAccessor: d => d.start},
+ {name: 'end', filterProps: {mappedValue: [3000, 4000]}, valueAccessor: d => d.end}
+ ];
+
+ const gpu = getGpuFilterProps(filters, 'ds', fields);
+
+ t.deepEqual(gpu.filterRange[0], [0, 2000], 'start channel should be [0, windowEnd - domain0]');
+ t.deepEqual(
+ gpu.filterRange[1],
+ [1000, 4000],
+ 'end channel should be [windowStart - domain0, domain1 - domain0]'
+ );
+ t.equal(
+ gpu.filterValueUpdateTriggers.gpuFilter_0.name,
+ 'start',
+ 'start trigger uses start field'
+ );
+ t.equal(gpu.filterValueUpdateTriggers.gpuFilter_1.name, 'end', 'end trigger uses end field');
+
+ t.end();
+});
diff --git a/test/node/utils/plot-test.js b/test/node/utils/plot-test.js
index 526145dd3..31eeab2e8 100644
--- a/test/node/utils/plot-test.js
+++ b/test/node/utils/plot-test.js
@@ -5,6 +5,7 @@ import test from 'tape';
import {
histogramFromThreshold,
histogramFromValues,
+ histogramFromTimeIntervals,
mergePolygonLayerIndexes,
runGpuFilterForPlot
} from '@kepler.gl/utils';
@@ -180,3 +181,72 @@ test('Utils -> histogramFromValues', t => {
t.end();
});
+
+test('Utils -> histogramFromTimeIntervals', t => {
+ const thresholds = [0, 10, 20, 30];
+ const starts = [5, 15, 0, 25];
+ const ends = [15, 15, 30, null];
+
+ const bins = histogramFromTimeIntervals(
+ thresholds,
+ [0, 1, 2, 3],
+ idx => starts[idx],
+ idx => ends[idx]
+ );
+
+ t.deepEqual(
+ bins.map(b => ({count: b.count, indexes: b.indexes, x0: b.x0, x1: b.x1})),
+ [
+ {count: 2, indexes: [0, 2], x0: 0, x1: 10},
+ {count: 3, indexes: [0, 1, 2], x0: 10, x1: 20},
+ {count: 2, indexes: [2, 3], x0: 20, x1: 30}
+ ],
+ 'should count a feature in every bin that overlaps [start, end]'
+ );
+
+ t.deepEqual(
+ histogramFromTimeIntervals(
+ thresholds,
+ [0],
+ idx => 10,
+ idx => 10
+ ),
+ [{count: 1, indexes: [0], x0: 10, x1: 20}],
+ 'an instant at a bin boundary should land in the following bin'
+ );
+
+ t.deepEqual(
+ histogramFromTimeIntervals(
+ thresholds,
+ [0],
+ () => null,
+ () => 20
+ ),
+ [],
+ 'should skip rows with no start time'
+ );
+
+ t.deepEqual(
+ histogramFromTimeIntervals(
+ [],
+ [0],
+ () => 5,
+ () => 15
+ ),
+ [],
+ 'should return no bins without thresholds'
+ );
+
+ t.deepEqual(
+ histogramFromTimeIntervals(
+ thresholds,
+ [0],
+ () => 15,
+ () => 5
+ ),
+ [],
+ 'should skip inverted intervals (end < start)'
+ );
+
+ t.end();
+});