Skip to content

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

23.7 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright contributors to the kepler.gl project

/* eslint-disable max-statements */
import test from 'tape';
import cloneDeep from 'es-toolkit/compat/cloneDeep';

import {
  tripDefaultLineWidth as defaultLineWidth,
  parseTripGeoJsonTimestamp,
  getAnimationDomainFromTimestamps,
  KeplerGlLayers
} from '@kepler.gl/layers';

import {copyTableAndUpdate} from '@kepler.gl/table';
import {processCsvData} from '@kepler.gl/processors';
import {INITIAL_MAP_STATE, INITIAL_VIS_STATE, visStateReducer} from '@kepler.gl/reducers';
import {VisStateActions} from '@kepler.gl/actions';
import {applyActions} from 'test/helpers/mock-state';
const {TripLayer} = KeplerGlLayers;

import {
  dataId,
  testCreateCases,
  testFormatLayerDataCases,
  testRenderLayerCases,
  prepareTripGeoDataset,
  prepareTripTableDataset,
  speedFilterDomain0,
  valueFilterDomain0,
  animationConfig
} from 'test/helpers/layer-utils';
import {TripLayerMeta, dataToFeature, dataToTimeStamp} from 'test/fixtures/trip-geojson';

test('#TripLayer -> constructor', t => {
  const TEST_CASES = {
    CREATE: [
      {
        props: {
          dataId: 'smoothie',
          isVisible: true,
          label: 'test trip layer'
        },
        test: layer => {
          t.ok(layer.config.dataId === 'smoothie', 'tripnLayer dataId should be correct');
          t.ok(layer.type === 'trip', 'type should be trip');
          t.ok(layer.isAggregated === false, 'tripLayer is not aggregated');
        }
      }
    ]
  };

  testCreateCases(t, TripLayer, TEST_CASES.CREATE);
  t.end();
});

test('#TripLayer -> formatLayerData', t => {
  const filteredIndex = [0, 2, 4];

  const TEST_CASES = [
    {
      name: 'Trip Geojson.1',
      layer: {
        type: 'trip',
        id: 'test_trip_layer_1',
        config: {
          color: [1, 2, 3],
          dataId,
          label: 'some trips',
          columns: {
            geojson: '_geojson'
          }
        }
      },
      datasets: {
        [dataId]: copyTableAndUpdate(prepareTripGeoDataset, {filteredIndex})
      },
      assert: result => {
        const {layerData, layer} = result;
        const expectedLayerData = {
          data: [dataToFeature[0], dataToFeature[2], dataToFeature[4]]
        };
        const expectedDataKeys = [
          'data',
          'getPath',
          'getTimestamps',
          'getFilterValue',
          'getColor',
          'getWidth',
          'getAdjustRoll',
          'getAdjustPitch',
          'getAdjustYaw',
          'textLabels'
        ];

        t.deepEqual(
          Object.keys(layerData).sort(),
          expectedDataKeys.sort(),
          'layerData should have 7 keys'
        );
        // data
        t.deepEqual(
          layerData.data,
          expectedLayerData.data,
          'should format correct geojson layerData'
        );
        t.deepEqual(
          layerData.data.map(layerData.getColor),
          [
            [1, 2, 3],
            [1, 2, 3],
            [1, 2, 3]
          ],
          'getColor should return correct value'
        );
        t.deepEqual(
          layerData.data.map(layerData.getFilterValue),
          [
            [Number.MIN_SAFE_INTEGER, 0, 0, 0],
            [7 - valueFilterDomain0, 0, 0, 0],
            [6 - valueFilterDomain0, 0, 0, 0]
          ],
          'getFilterValue should return correct value'
        );
        t.deepEqual(
          layerData.data.map(layerData.getWidth),
          [defaultLineWidth, defaultLineWidth, defaultLineWidth],
          'getWidth should return correct value'
        );
        t.deepEqual(
          layerData.getPath(layerData.data[0]),
          dataToFeature[0].geometry.coordinates,
          'getPath should return correct coordinates'
        );
        t.deepEqual(
          layerData.getTimestamps(layerData.data[0]),
          dataToTimeStamp[0],
          'getWidth should return getTimestamps'
        );
        // meta
        t.deepEqual(
          Object.keys(layer.meta).sort(),
          ['bounds', 'featureTypes', 'getFeature'],
          'should format correct geojson layer meta keys'
        );
        t.deepEqual(
          layer.meta.bounds,
          TripLayerMeta.bounds,
          'should format correct geojson layer meta bounds'
        );
        t.deepEqual(
          layer.meta.featureTypes,
          TripLayerMeta.featureTypes,
          'should format correct geojson layer meta featureTypes'
        );
        // dataToFeature
        t.deepEqual(
          layer.dataToTimeStamp,
          dataToTimeStamp,
          'should format correct geojson dataToFeature'
        );

        t.deepEqual(
          layer.dataToFeature,
          dataToFeature,
          'should format correct geojson dataToFeature'
        );
      }
    },
    {
      name: 'Trip Geojson.2',
      layer: {
        type: 'trip',
        id: 'test_trip_layer_2',
        config: {
          color: [1, 2, 3],
          dataId,
          label: 'some trips',
          columns: {
            geojson: '_geojson'
          },
          // color by types(string)
          colorField: {
            type: 'string',
            name: 'types'
          },
          // size by trip_distance(real)
          sizeField: {
            type: 'real',
            name: 'trip_distance'
          },
          visConfig: {
            colorRange: {
              colors: ['#010101', '#020202', '#030303']
            },
            sizeRange: [10, 20]
          }
        }
      },
      datasets: {
        [dataId]: copyTableAndUpdate(prepareTripGeoDataset, {filteredIndex})
      },
      assert: result => {
        const {layerData, layer} = result;

        const expectedLayerData = {
          data: [dataToFeature[0], dataToFeature[2], dataToFeature[4]]
        };
        // data
        t.deepEqual(
          layerData.data,
          expectedLayerData.data,
          'should format correct geojson layerData'
        );
        // getColor
        // domain: ['driver_analytics', 'driver_analytics_0', 'driver_gps']
        // range ['#010101', '#020202', '#030303']
        t.deepEqual(
          layerData.data.map(layerData.getColor),
          [
            [2, 2, 2],
            [1, 1, 1],
            [1, 1, 1]
          ],
          'getColor should return correct value'
        );
        // getWidth
        // domain: [2.37, 8.33]
        // range: [10, 20]
        // value [1.59, 2.83, 2.37]
        t.deepEqual(
          layerData.data.map(layerData.getWidth),
          [8.691275167785234, 10.771812080536913, 10],
          'getWidth should return correct value'
        );

        // dataToFeature
        t.deepEqual(
          layer.dataToTimeStamp,
          dataToTimeStamp,
          'should format correct geojson dataToFeature'
        );

        t.deepEqual(
          layer.dataToFeature,
          dataToFeature,
          'should format correct geojson dataToFeature'
        );
      }
    }
  ];

  testFormatLayerDataCases(t, TripLayer, TEST_CASES);
  t.end();
});

test('#TripLayer -> formatLayerData -> table column mode with gpu filter', t => {
  // The GPU filter reads a layer's values through the accessor the layer hands
  // it, called as getData(dataContainer, feature, fieldIndex). Table column mode
  // groups rows into trips, so the value of each channel is an array, one entry
  // per vertex of the trip.
  const TEST_CASES = [
    {
      name: 'Trip Table.1',
      layer: {
        type: 'trip',
        id: 'test_trip_table_layer',
        config: {
          dataId,
          label: 'gps trips',
          columnMode: 'table',
          columns: {
            id: 'name',
            lat: 'location-lat',
            lng: 'location-lng',
            timestamp: 'timestamp',
            altitude: 'location-alt'
          }
        }
      },
      datasets: {
        [dataId]: prepareTripTableDataset
      },
      assert: result => {
        const {layerData} = result;

        let filterValues;
        t.doesNotThrow(() => {
          filterValues = layerData.data.map(layerData.getFilterValue);
        }, 'getFilterValue should not throw in table column mode');

        // The first trip groups the 8 rows named Thuub that carry a coordinate
        // and a timestamp; the row with an empty location is dropped.
        const round = v => Math.round(v * 100) / 100;
        const groundSpeeds = [0.22, 0.27, 0.32, 0.46, 0.51, 0.3, 0.33, 0.43];

        t.deepEqual(
          (filterValues?.[0] ?? []).map(vertex => round(vertex[0])),
          groundSpeeds.map(speed => round(speed - speedFilterDomain0)),
          'getFilterValue should return one filter value per vertex of the trip'
        );
      }
    }
  ];

  testFormatLayerDataCases(t, TripLayer, TEST_CASES);
  t.end();
});

test('#TripLayer -> table vertex filters keep coordinates, times, values and colors aligned', t => {
  const start = Date.UTC(2024, 0, 1);
  const csv = `id,lat,lng,timestamp,status,speed
dropped,9,19,2024-01-01 00:00:00,skip,0
retained,13,23,2024-01-01 00:00:30,last,30
retained,10,20,2024-01-01 00:00:00,skip,0
retained,11,21,2024-01-01 00:00:10,keep,10
retained,12,22,2024-01-01 00:00:20,skip,20
retained,,,2024-01-01 00:00:40,keep,40
retained,14,24,,keep,50`;
  let state = applyActions(visStateReducer, INITIAL_VIS_STATE, [
    {
      action: VisStateActions.updateVisData,
      payload: [{info: {id: dataId}, data: processCsvData(csv)}]
    },
    {action: VisStateActions.addFilter, payload: [dataId]},
    {action: VisStateActions.setFilter, payload: [0, 'name', 'timestamp']},
    {action: VisStateActions.addFilter, payload: [dataId]},
    {action: VisStateActions.setFilter, payload: [1, 'name', 'speed']},
    {action: VisStateActions.setFilter, payload: [1, 'value', [5, 35]]}
  ]);

  testFormatLayerDataCases(t, TripLayer, [
    {
      name: 'filtered trip timestamps',
      layer: {
        type: 'trip',
        config: {
          dataId,
          columnMode: 'table',
          columns: {id: 'id', lat: 'lat', lng: 'lng', timestamp: 'timestamp'},
          colorField: {name: 'status', type: 'string'},
          colorScale: 'customOrdinal',
          visConfig: {
            colorRange: {
              colors: ['#ff0000', '#00ff00', '#0000ff'],
              colorMap: [
                ['skip', '#ff0000'],
                ['keep', '#00ff00'],
                ['last', '#0000ff']
              ]
            }
          }
        }
      },
      datasets: state.datasets,
      assert: ({layer, layerData}) => {
        t.deepEqual(
          layerData.getTimestamps(layerData.data[1]),
          [start, start + 10000, start + 20000, start + 30000],
          'unfiltered timestamps are sorted and omit rows missing coordinates or time'
        );
        state = visStateReducer(state, VisStateActions.addFilter(dataId));
        state = visStateReducer(state, VisStateActions.setFilter(2, 'name', 'status'));

        [
          {
            value: ['keep', 'last'],
            coordinates: [
              [21, 11],
              [23, 13]
            ],
            times: [10000, 30000]
          },
          {value: ['last'], coordinates: [[23, 13]], times: [30000]},
          {value: ['absent'], coordinates: [], times: []},
          {
            value: ['keep', 'last', 'skip'],
            coordinates: [
              [20, 10],
              [21, 11],
              [22, 12],
              [23, 13]
            ],
            times: [0, 10000, 20000, 30000]
          }
        ].forEach(({value, coordinates, times}) => {
          state = visStateReducer(state, VisStateActions.setFilter(2, 'value', value));
          layerData = layer.formatLayerData(state.datasets, layerData);
          const feature = layerData.data.find(d => d.properties.index === 1);
          t.deepEqual(
            feature ? layerData.getPath(feature).map(c => c.slice(0, 2)) : [],
            coordinates,
            `categorical filter ${value} retains the expected sorted coordinates`
          );
          if (!feature) {
            t.equal(layerData.data.length, 0, 'filtering every vertex leaves no trips');
            return;
          }
          t.deepEqual(
            layerData.getTimestamps(feature),
            times.map(time => start + time),
            `categorical filter ${value} retains the matching normalized timestamps`
          );
          t.deepEqual(
            layerData.getFilterValue(feature).map(vertex => vertex[0]),
            times,
            'GPU timestamp values stay aligned with retained vertices'
          );
          t.deepEqual(
            feature.properties.values,
            feature.geometry.coordinates.map(c =>
              state.datasets[dataId].dataContainer.rowAsArray(c.datumIndex)
            ),
            'retained row values match the original row indices of retained vertices'
          );
          t.deepEqual(
            layerData.getFilterValue(feature).map(vertex => vertex[1]),
            times.map(time => time / 1000),
            'numeric GPU values stay aligned alongside timestamp and category filters'
          );
          const expectedColors = {skip: [255, 0, 0], keep: [0, 255, 0], last: [0, 0, 255]};
          t.deepEqual(
            layerData.getColor(feature),
            expectedColors[feature.geometry.coordinates[0].datum[4]],
            'trip color comes from the first retained vertex'
          );
          const [trails] = layer.renderLayer({
            data: layerData,
            gpuFilter: state.datasets[dataId].gpuFilter,
            mapState: INITIAL_MAP_STATE,
            animationConfig: {domain: [start, start + 40000], currentTime: start + 15000}
          });
          t.deepEqual(
            trails.props.getTimestamps(feature),
            times,
            'rendered timestamps retain the same coordinate order after domain subtraction'
          );
        });
      }
    }
  ]);
  t.end();
});

test('#TripLayer -> renderLayer', t => {
  const filteredIndex = [0, 2, 4];

  const TEST_CASES = [
    {
      name: 'Trip Geojson.1',
      layer: {
        type: 'trip',
        id: 'test_trip_layer_1',
        config: {
          color: [1, 2, 3],
          dataId,
          label: 'some trips',
          columns: {
            geojson: '_geojson'
          },
          visConfig: {
            colorRange: {
              colors: ['#080808', '#090909', '#070707']
            },
            trailLength: 2
          }
        }
      },
      datasets: {
        [dataId]: copyTableAndUpdate(prepareTripGeoDataset, {filteredIndex})
      },
      renderArgs: {
        animationConfig
      },
      assert: deckLayers => {
        const ids = ['test_trip_layer_1'];
        t.deepEqual(
          deckLayers.map(l => l.id),
          ids,
          'Should render 1 deck layers'
        );

        const deckTripLayer = deckLayers[0];
        const expectedProps = {
          trailLength: 2000,
          capRounded: true,
          jointRounded: true,
          widthScale: 128,
          currentTime: 0,
          parameters: {depthTest: false, depthMask: false},
          filterRange: [
            [3, 11],
            [0, 0],
            [0, 0],
            [0, 0]
          ],
          opacity: 0.8
        };

        Object.keys(expectedProps).forEach(key => {
          t.deepEqual(
            deckTripLayer.props[key],
            expectedProps[key],
            `should have correct props.${key}`
          );
        });

        t.deepEqual(
          deckTripLayer.props.extensions.map(cl => cl.constructor.name),
          ['DataFilterExtension'],
          'Should provide DataFilterExtension'
        );
        // test attributes
        const {attributes} = deckTripLayer.state.attributeManager;

        t.ok(attributes.filterValues, 'Should have filterValues attribute');
        t.ok(
          attributes.filterValues.value instanceof Float32Array,
          'filterValues should be Float32Array'
        );
        t.ok(attributes.instanceColors, 'Should have instanceColors attribute');
        t.ok(attributes.instanceStrokeWidths, 'Should have instanceStrokeWidths attribute');

        // Trip features 0, 2, 4 have 10, 8, 7 coordinates respectively
        const expectedVerticesPerPath = [10, 8, 7];
        const expectedNumInstances = expectedVerticesPerPath.reduce((a, b) => a + b, 0); // 25
        const numInstances = deckTripLayer.state.numInstances ?? 0;
        t.equal(
          numInstances,
          expectedNumInstances,
          `should have exactly ${expectedNumInstances} instances`
        );

        // Verify startIndices from PathLayer tesselator
        const startIndices = deckTripLayer.state.startIndices;
        t.ok(startIndices, 'should have startIndices');
        const expectedStartIndices = [0, 10, 18, 25];
        t.deepEqual(
          Array.from(startIndices),
          expectedStartIndices,
          'startIndices should be [0, 10, 18, 25]'
        );

        // Build expected instanceColors: all vertices should be [1, 2, 3, 255]
        const expectedColors = new Uint8ClampedArray(numInstances * 4);
        for (let v = 0; v < numInstances; v++) {
          expectedColors[v * 4] = 1;
          expectedColors[v * 4 + 1] = 2;
          expectedColors[v * 4 + 2] = 3;
          expectedColors[v * 4 + 3] = 255;
        }
        t.deepEqual(
          attributes.instanceColors.value.slice(0, numInstances * 4),
          expectedColors,
          'Should have correct instanceColors for all instances'
        );

        // Build expected instanceStrokeWidths: all should be 1 (defaultLineWidth)
        const expectedStroke = new Float32Array(numInstances).fill(1);
        t.deepEqual(
          attributes.instanceStrokeWidths.value.slice(0, numInstances),
          expectedStroke,
          'Should have correct instanceStrokeWidths for all instances'
        );

        // Build expected filterValues using startIndices for per-path grouping
        // Feature 0: MIN_SAFE_INTEGER, Feature 2: 7 - valueFilterDomain0, Feature 4: 6 - valueFilterDomain0
        const perPathFilterValue = [
          Number.MIN_SAFE_INTEGER,
          7 - valueFilterDomain0,
          6 - valueFilterDomain0
        ];
        const expectedFilterValues = new Float32Array(numInstances * 4);
        for (let pathIdx = 0; pathIdx < expectedVerticesPerPath.length; pathIdx++) {
          const start = expectedStartIndices[pathIdx];
          const end = expectedStartIndices[pathIdx + 1];
          for (let v = start; v < end; v++) {
            expectedFilterValues[v * 4] = perPathFilterValue[pathIdx];
            expectedFilterValues[v * 4 + 1] = 0;
            expectedFilterValues[v * 4 + 2] = 0;
            expectedFilterValues[v * 4 + 3] = 0;
          }
        }

        // Verify per-path filter values using startIndices
        const fv = attributes.filterValues.value;
        for (let pathIdx = 0; pathIdx < expectedVerticesPerPath.length; pathIdx++) {
          const start = expectedStartIndices[pathIdx];
          const end = expectedStartIndices[pathIdx + 1];
          for (let v = start; v < end; v++) {
            const base = v * 4;
            t.ok(
              Math.abs(fv[base] - perPathFilterValue[pathIdx]) < 2,
              `filterValues[${v}][0] should be ~${perPathFilterValue[pathIdx]} for path ${pathIdx}`
            );
            t.equal(fv[base + 1], 0, `filterValues[${v}][1] should be 0`);
            t.equal(fv[base + 2], 0, `filterValues[${v}][2] should be 0`);
            t.equal(fv[base + 3], 0, `filterValues[${v}][3] should be 0`);
          }
        }
        // TODO: test UpdateTriggers
      }
    }
  ];

  testRenderLayerCases(t, TripLayer, TEST_CASES);
  t.end();
});

test('#TripLayer -> renderLayer model colors preserve trail color shape', t => {
  const TEST_CASES = [
    {
      columnMode: 'table',
      dataset: prepareTripTableDataset,
      columns: {
        id: 'name',
        lat: 'location-lat',
        lng: 'location-lng',
        timestamp: 'timestamp',
        altitude: 'location-alt'
      },
      colorField: {name: 'name', type: 'string'}
    },
    {
      columnMode: 'geojson',
      dataset: prepareTripGeoDataset,
      columns: {geojson: '_geojson'},
      colorField: {name: 'types', type: 'string'}
    }
  ].map(({columnMode, dataset, columns, colorField}) => ({
    name: `Trip model colors: ${columnMode}`,
    layer: {
      type: 'trip',
      id: `trip-model-colors-${columnMode}`,
      config: {
        dataId,
        columnMode,
        columns,
        colorField,
        color: [40, 50, 60],
        visConfig: {
          colorRange: {colors: ['#0a141e']},
          scenegraphEnabled: true,
          scenegraph: 'custom',
          scenegraphCustomModelUrl: 'https://example.com/model.glb',
          scenegraphColorEnabled: true,
          scenegraphUseTrailColor: true
        }
      }
    },
    datasets: {[dataId]: dataset},
    assert: ({layerData, layer}) => {
      const feature = layerData.data[0];
      const timestamps = layerData.getTimestamps(feature);
      const time = (timestamps[0] + timestamps[1]) / 2;
      // Inspect the public render output without fetching a model or starting WebGL.
      const renderModel = (data = layerData, currentTime = time) =>
        layer.renderLayer({
          data,
          gpuFilter: dataset.gpuFilter,
          mapState: {zoom: 10},
          animationConfig: {domain: layer.animationDomain, currentTime}
        })[1];

      t.deepEqual(layerData.getColor(feature), [10, 20, 30], 'field encodes one RGB per trip');
      t.deepEqual(
        renderModel().props.getColor(feature),
        [10, 20, 30],
        `${columnMode} model receives the full field-encoded trail color`
      );

      if (columnMode === 'table') {
        const vertexColors = timestamps.map((_, i) => [i, i + 10, i + 20]);
        const vertexData = {...layerData, getColor: () => vertexColors};
        t.deepEqual(
          renderModel(vertexData).props.getColor(feature),
          vertexColors[1],
          'per-vertex colors still select the active vertex'
        );
        t.deepEqual(
          renderModel(vertexData, timestamps[0] - 1).props.getColor(feature),
          [255, 255, 255],
          'per-vertex colors use the default outside the trip time range'
        );
      }

      layer.updateLayerConfig({colorField: null});
      const fixedData = layer.formatLayerData({[dataId]: dataset}, layerData);
      t.deepEqual(
        renderModel(fixedData).props.getColor(feature),
        [40, 50, 60],
        'uniform trail color without a field stays unchanged'
      );

      layer.updateLayerVisConfig({scenegraphUseTrailColor: false, scenegraphColor: [70, 80, 90]});
      t.deepEqual(renderModel().props.getColor, [70, 80, 90], 'explicit model color is preserved');
      layer.updateLayerVisConfig({scenegraphColorEnabled: false});
      t.deepEqual(renderModel().props.getColor, [255, 255, 255], 'disabled model tint uses white');
    }
  }));

  testFormatLayerDataCases(t, TripLayer, TEST_CASES);
  t.end();
});

test('#TripLayer -> parseTripGeoJsonTimestamp', t => {
  // mix with illegal character
  const dataToFeature1 = cloneDeep(dataToFeature);
  dataToFeature1[0].geometry.coordinates[0][3] = 0;
  dataToFeature1[1].geometry.coordinates[0][3] = NaN;
  dataToFeature1[2].geometry.coordinates[0][3] = null;
  dataToFeature1[3].geometry.coordinates[0][3] = undefined;
  dataToFeature1[4].geometry.coordinates[0][3] = 'a';

  dataToFeature1[0].geometry.coordinates[dataToFeature1[0].geometry.coordinates.length - 1][3] =
    NaN;

  const result = parseTripGeoJsonTimestamp(dataToFeature1);

  t.deepEqual(result.animationDomain, [1565577261, 1565578836], 'should filter out illugal value');
  t.end();
});

test('#TripLayer -> getAnimationDomainFromTimestamps includes single-timestamp trips', t => {
  t.deepEqual(
    getAnimationDomainFromTimestamps([[1000], [2000, 3000]]),
    [1000, 3000],
    'a one-point trip should contribute both min and max to the animation domain'
  );
  t.deepEqual(
    getAnimationDomainFromTimestamps([[1000, 2000], null, [3000]]),
    [1000, 3000],
    'a trip without geometry should be skipped'
  );
  t.end();
});