Skip to content

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

feat(layers): add target arrows to Arc and Line layers (#3818)

Igor Dykhtacfb531d563ce
diff --git a/src/components/src/side-panel/layer-panel/layer-configurator.tsx b/src/components/src/side-panel/layer-panel/layer-configurator.tsx
index 152fd5b84..848d620ee 100644
--- a/src/components/src/side-panel/layer-panel/layer-configurator.tsx
+++ b/src/components/src/side-panel/layer-panel/layer-configurator.tsx
@@ -60,6 +60,12 @@ const FLOW_RENDERING_MODE_LABELS: Record<string, string> = {
'animated-straight': 'Animated'
};
+const TARGET_ARROW_SHAPE_LABELS: Record<string, string> = {
+ triangle: 'Triangle',
+ chevron: 'Chevron',
+ stealth: 'Stealth'
+};
+
type LayerConfiguratorProps = {
layer: Layer;
datasets: Datasets;
@@ -938,6 +944,19 @@ export default function LayerConfiguratorFactory(
layerConfiguratorProps,
layerChannelConfigProps
}) {
+ const arrowShapeSetting = layer.visConfigSettings.targetArrowShape as
+ | {options?: string[]}
+ | undefined;
+ const arrowShapeOptions = (
+ arrowShapeSetting?.options || ['chevron', 'triangle', 'stealth']
+ ).map(id => ({
+ id,
+ label: TARGET_ARROW_SHAPE_LABELS[id] || id
+ }));
+ const selectedArrowShape =
+ arrowShapeOptions.find(({id}) => id === layer.config.visConfig.targetArrowShape) ||
+ arrowShapeOptions[0];
+
return (
<StyledLayerVisualConfigurator>
{/* Color */}
@@ -985,6 +1004,32 @@ export default function LayerConfiguratorFactory(
</ConfigGroupCollapsibleContent>
</LayerConfigGroup>
+ <LayerConfigGroup
+ {...visConfiguratorProps}
+ label="layerVisConfigs.targetArrow"
+ description="layerVisConfigs.targetArrowDescription"
+ property="targetArrowEnabled"
+ >
+ <SidePanelSection>
+ <PanelLabel>
+ <FormattedMessage id="layerVisConfigs.targetArrowShape" />
+ </PanelLabel>
+ <ItemSelector
+ selectedItems={selectedArrowShape}
+ options={arrowShapeOptions}
+ displayOption="label"
+ getOptionValue="id"
+ multiSelect={false}
+ searchable={false}
+ onChange={value => visConfiguratorProps.onChange({targetArrowShape: value})}
+ />
+ </SidePanelSection>
+ <VisConfigSlider
+ {...layer.visConfigSettings.targetArrowSize}
+ {...visConfiguratorProps}
+ />
+ </LayerConfigGroup>
+
{/* elevation scale */}
{layer.visConfigSettings.elevationScale ? (
<LayerConfigGroup label="layerVisConfigs.elevationScale" collapsible>
diff --git a/src/deckgl-layers/src/arrow-head-layer/arrow-head-layer.spec.ts b/src/deckgl-layers/src/arrow-head-layer/arrow-head-layer.spec.ts
new file mode 100644
index 000000000..890dad994
--- /dev/null
+++ b/src/deckgl-layers/src/arrow-head-layer/arrow-head-layer.spec.ts
@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+import {assembleGLSLShaderPair} from '@luma.gl/shadertools';
+
+import {withArrowHeadVertexInject} from './arrow-head-layer';
+
+const platformInfo = {
+ type: 'webgl' as const,
+ shaderLanguage: 'glsl' as const,
+ shaderLanguageVersion: 300 as const,
+ gpu: 'test',
+ features: new Set<string>()
+};
+
+const vs = `#version 300 es
+#define SHADER_NAME arrow-test
+in vec3 positions;
+void main(void) {
+ vec3 size = positions;
+ DECKGL_FILTER_SIZE(size, geometry);
+ gl_Position = vec4(size, 1.0);
+}
+`;
+
+const fs = `#version 300 es
+precision highp float;
+out vec4 fragColor;
+void main(void) {
+ fragColor = vec4(1.0);
+}
+`;
+
+function assemble(inject: Record<string, string>) {
+ return assembleGLSLShaderPair({
+ platformInfo,
+ vs,
+ fs,
+ inject,
+ modules: [],
+ hookFunctions: [
+ 'vs:DECKGL_FILTER_SIZE(inout vec3 size, VertexGeometry geometry)',
+ 'vs:DECKGL_FILTER_GL_POSITION(inout vec4 position, VertexGeometry geometry)'
+ ]
+ }).vs;
+}
+
+describe('arrow head shader', () => {
+ test('declares instanceAngles before the size hook uses it', () => {
+ const assembled = assemble(withArrowHeadVertexInject());
+
+ const declaration = assembled.indexOf('in float instanceAngles');
+ const use = assembled.indexOf('radians(instanceAngles)');
+
+ expect(declaration).toBeGreaterThan(-1);
+ expect(use).toBeGreaterThan(declaration);
+ });
+
+ test('keeps an existing size injection such as the data filter', () => {
+ const assembled = assemble(
+ withArrowHeadVertexInject({
+ 'vs:DECKGL_FILTER_SIZE': 'size = size * dataFilter_value;'
+ })
+ );
+
+ const filterAt = assembled.indexOf('size * dataFilter_value');
+ const rotateAt = assembled.indexOf('radians(instanceAngles)');
+
+ expect(filterAt).toBeGreaterThan(-1);
+ expect(rotateAt).toBeGreaterThan(filterAt);
+ });
+
+ test('supplies source and target positions before brushing filters the arrow', () => {
+ const assembled = assemble(
+ withArrowHeadVertexInject({
+ 'vs:DECKGL_FILTER_GL_POSITION':
+ 'bool visible = brushing_arePointsInRange(geometry.worldPosition.xy, geometry.worldPositionAlt.xy);'
+ })
+ );
+
+ const sourceAt = assembled.indexOf('geometry.worldPosition = instanceSourcePositions');
+ const targetAt = assembled.indexOf('geometry.worldPositionAlt = instanceTargetPositions');
+ const brushAt = assembled.indexOf('brushing_arePointsInRange');
+
+ expect(sourceAt).toBeGreaterThan(-1);
+ expect(targetAt).toBeGreaterThan(sourceAt);
+ expect(brushAt).toBeGreaterThan(targetAt);
+ });
+});
diff --git a/src/deckgl-layers/src/arrow-head-layer/arrow-head-layer.ts b/src/deckgl-layers/src/arrow-head-layer/arrow-head-layer.ts
new file mode 100644
index 000000000..2d420a214
--- /dev/null
+++ b/src/deckgl-layers/src/arrow-head-layer/arrow-head-layer.ts
@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+import type {ScatterplotLayerProps} from '@deck.gl/layers';
+import {ScatterplotLayer} from '@deck.gl/layers';
+
+import type {ScatterplotIconLayerProps} from '../svg-icon-layer/scatterplot-icon-layer';
+import ScatterplotIconLayer, {iconFragmentShader} from '../svg-icon-layer/scatterplot-icon-layer';
+
+type ArrowHeadLayerProps = ScatterplotIconLayerProps & {
+ getAngle?: ScatterplotLayerProps['getRadius'];
+ getSourcePosition?: ScatterplotLayerProps<any>['getPosition'];
+ getTargetPosition?: ScatterplotLayerProps<any>['getPosition'];
+ getFilterValue?: (d: any) => number[];
+ filterRange?: unknown;
+ brushingEnabled?: boolean;
+ brushingRadius?: number;
+ brushingTarget?: string;
+ getBrushingTarget?: (d: any) => number[];
+ hidden?: boolean;
+};
+
+export const ARROW_HEAD_SHAPES = ['chevron', 'triangle', 'stealth'] as const;
+export type ArrowHeadShape = (typeof ARROW_HEAD_SHAPES)[number];
+
+// Tip at the origin, body toward -y. Angle 0 points up; positive angles turn clockwise.
+const TRIANGLE = [0, 0, 0, -0.45, -1, 0, 0.45, -1, 0];
+const CHEVRON = [0, 0, 0, -0.55, -1, 0, 0, -0.55, 0, 0, 0, 0, 0, -0.55, 0, 0.55, -1, 0];
+const STEALTH = [0, 0, 0, -0.22, -1, 0, 0, -0.7, 0, 0, 0, 0, 0, -0.7, 0, 0.22, -1, 0];
+
+const GEOMETRIES: Record<ArrowHeadShape, number[]> = {
+ triangle: TRIANGLE,
+ chevron: CHEVRON,
+ stealth: STEALTH
+};
+
+export function getArrowHeadGeometry(shape: string): number[] {
+ if (shape === 'chevron' || shape === 'stealth') {
+ return GEOMETRIES[shape];
+ }
+ return TRIANGLE;
+}
+
+type ShaderInject = Record<string, string>;
+
+/**
+ * deck.gl emits hook functions (DECKGL_FILTER_SIZE) before the main shader
+ * source. An `in` added to that source is still undeclared inside the hook.
+ * Declare the angle on `vs:#decl`, which is injected before the hooks.
+ */
+export function withArrowHeadVertexInject(inject: ShaderInject = {}): ShaderInject {
+ const decl = inject['vs:#decl'] || '';
+ const filterSize = inject['vs:DECKGL_FILTER_SIZE'] || '';
+ const filterPosition = inject['vs:DECKGL_FILTER_GL_POSITION'] || '';
+
+ return {
+ ...inject,
+ 'vs:#decl': `${decl}in float instanceAngles;
+in vec3 instanceSourcePositions;
+in vec3 instanceTargetPositions;\n`,
+ 'vs:DECKGL_FILTER_GL_POSITION': `
+ geometry.worldPosition = instanceSourcePositions;
+ geometry.worldPositionAlt = instanceTargetPositions;
+ ${filterPosition}
+ `,
+ 'vs:DECKGL_FILTER_SIZE': `${filterSize}
+ float arrowAngle = radians(instanceAngles);
+ float arrowCos = cos(arrowAngle);
+ float arrowSin = sin(arrowAngle);
+ size.xy = mat2(arrowCos, -arrowSin, arrowSin, arrowCos) * size.xy;
+ `
+ };
+}
+
+/**
+ * Screen-aligned arrowhead. ScatterplotIconLayer draws a mesh in pixel space;
+ * instanceAngles rotates that mesh around the tip.
+ */
+export default class ArrowHeadLayer extends ScatterplotIconLayer {
+ static layerName = 'ArrowHeadLayer';
+
+ constructor(props: ArrowHeadLayerProps) {
+ super(props);
+ }
+
+ initializeState() {
+ // Add the angle before the scatterplot model is built so the buffer layout
+ // includes it on the first compile.
+ this.getAttributeManager()!.addInstanced({
+ instanceAngles: {
+ size: 1,
+ transition: true,
+ accessor: 'getAngle',
+ defaultValue: 0
+ },
+ instanceSourcePositions: {
+ size: 3,
+ type: 'float64',
+ fp64: this.use64bitPositions(),
+ transition: true,
+ accessor: 'getSourcePosition'
+ },
+ instanceTargetPositions: {
+ size: 3,
+ type: 'float64',
+ fp64: this.use64bitPositions(),
+ transition: true,
+ accessor: 'getTargetPosition'
+ }
+ });
+ super.initializeState();
+ }
+
+ getShaders() {
+ // Skip ScatterplotIconLayer: its shader inject replaces extension hooks
+ // (data filter, brushing) and scales the mesh for the globe.
+ const shaders = ScatterplotLayer.prototype.getShaders.call(this);
+
+ return {
+ ...shaders,
+ fs: iconFragmentShader,
+ inject: withArrowHeadVertexInject(shaders.inject || {})
+ };
+ }
+
+ draw(opts) {
+ ScatterplotLayer.prototype.draw.call(this, opts);
+ }
+}
diff --git a/src/deckgl-layers/src/index.ts b/src/deckgl-layers/src/index.ts
index c01c060f9..9d91b6867 100644
--- a/src/deckgl-layers/src/index.ts
+++ b/src/deckgl-layers/src/index.ts
@@ -16,6 +16,7 @@ export {default as EnhancedGridLayer} from './grid-layer/enhanced-cpu-grid-layer
export {default as EnhancedHexagonLayer} from './hexagon-layer/enhanced-hexagon-layer';
export {default as EnhancedLineLayer} from './line-layer/line-layer';
export {default as SvgIconLayer} from './svg-icon-layer/svg-icon-layer';
+export {default as ArrowHeadLayer, getArrowHeadGeometry} from './arrow-head-layer/arrow-head-layer';
export {default as FilterArrowExtension} from './deckgl-extensions/filter-arrow-layer';
export {default as RasterLayer} from './raster/raster-layer/raster-layer';
diff --git a/src/deckgl-layers/src/line-layer/line-layer.spec.ts b/src/deckgl-layers/src/line-layer/line-layer.spec.ts
new file mode 100644
index 000000000..c9379e568
--- /dev/null
+++ b/src/deckgl-layers/src/line-layer/line-layer.spec.ts
@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+import {readFileSync} from 'fs';
+import {join} from 'path';
+
+import {injectLineElevationScale} from './line-layer';
+
+// The demo aliases @deck.gl to this TypeScript source, which is indented and
+// has a blank line the published bundle does not.
+const sourceShader = readFileSync(
+ join(
+ __dirname,
+ '../../../../node_modules/@deck.gl/layers/src/line-layer/line-layer-vertex.glsl.ts'
+ ),
+ 'utf8'
+);
+
+const flatShader = `void main(void) {
+geometry.worldPosition = instanceSourcePositions;
+geometry.worldPositionAlt = instanceTargetPositions;
+vec3 source_world = instanceSourcePositions;
+vec3 target_world = instanceTargetPositions;
+}`;
+
+describe('injectLineElevationScale', () => {
+ test('scales elevation in the indented deck.gl source shader', () => {
+ const injected = injectLineElevationScale(sourceShader);
+
+ expect(injected).toContain('source_world.z *= elevationScaleProps.elevationScale');
+ expect(injected).toContain('target_world.z *= elevationScaleProps.elevationScale');
+ });
+
+ test('scales elevation in the flattened published shader', () => {
+ const injected = injectLineElevationScale(flatShader);
+
+ expect(injected).toContain('source_world.z *= elevationScaleProps.elevationScale');
+ expect(injected.indexOf('source_world.z *=')).toBeLessThan(
+ injected.indexOf('geometry.worldPosition = source_world')
+ );
+ });
+});
diff --git a/src/deckgl-layers/src/line-layer/line-layer.ts b/src/deckgl-layers/src/line-layer/line-layer.ts
index 1cd696403..e83f8497b 100644
--- a/src/deckgl-layers/src/line-layer/line-layer.ts
+++ b/src/deckgl-layers/src/line-layer/line-layer.ts
@@ -3,6 +3,8 @@
import {LineLayer, LineLayerProps} from '@deck.gl/layers';
import type {Color, AttributeManager} from '@deck.gl/core';
+import {console as Console} from 'global/window';
+
import {editShader} from '../';
type RGBAColor = Color;
@@ -40,21 +42,25 @@ function addInstanceColorShader(vs) {
);
}
-function addElevationScale(vs) {
- return editShader(
- vs,
- 'line elevation scale vs - multiply by elevation scale',
- `geometry.worldPosition = instanceSourcePositions;
-geometry.worldPositionAlt = instanceTargetPositions;
-vec3 source_world = instanceSourcePositions;
-vec3 target_world = instanceTargetPositions;`,
- `vec3 source_world = instanceSourcePositions;
+// deck.gl's published shader is flat; the TypeScript source the demo bundles is indented
+// and has a blank line between the two assignments. Match either form.
+const LINE_ELEVATION_ANCHOR =
+ /geometry\.worldPosition = instanceSourcePositions;\s*geometry\.worldPositionAlt = instanceTargetPositions;\s*vec3 source_world = instanceSourcePositions;\s*vec3 target_world = instanceTargetPositions;/;
+
+const LINE_ELEVATION_REPLACEMENT = `vec3 source_world = instanceSourcePositions;
vec3 target_world = instanceTargetPositions;
source_world.z *= elevationScaleProps.elevationScale;
target_world.z *= elevationScaleProps.elevationScale;
geometry.worldPosition = source_world;
-geometry.worldPositionAlt = target_world;`
- );
+geometry.worldPositionAlt = target_world;`;
+
+export function injectLineElevationScale(vs: string): string {
+ if (!LINE_ELEVATION_ANCHOR.test(vs)) {
+ Console.error('Cannot edit line elevation scale vs - multiply by elevation scale layer shader');
+ return vs;
+ }
+
+ return vs.replace(LINE_ELEVATION_ANCHOR, LINE_ELEVATION_REPLACEMENT);
}
export default class EnhancedLineLayer extends LineLayer<
@@ -65,7 +71,7 @@ export default class EnhancedLineLayer extends LineLayer<
const shaders = super.getShaders();
let vs = addInstanceColorShader(shaders.vs);
- vs = addElevationScale(vs);
+ vs = injectLineElevationScale(vs);
return {
...shaders,
diff --git a/src/deckgl-layers/src/svg-icon-layer/scatterplot-icon-layer.ts b/src/deckgl-layers/src/svg-icon-layer/scatterplot-icon-layer.ts
index a5f9e9a3a..0c2917e6c 100644
--- a/src/deckgl-layers/src/svg-icon-layer/scatterplot-icon-layer.ts
+++ b/src/deckgl-layers/src/svg-icon-layer/scatterplot-icon-layer.ts
@@ -18,7 +18,7 @@ const globeModeUniforms = {
}
};
-const iconFragmentShader = /* glsl */ `\
+export const iconFragmentShader = /* glsl */ `\
#version 300 es
#define SHADER_NAME scatterplot-icon-layer-fragment-shader
precision highp float;
diff --git a/src/layers/src/arc-layer/arc-layer.ts b/src/layers/src/arc-layer/arc-layer.ts
index f4006d2bc..f1bdfd5a4 100644
--- a/src/layers/src/arc-layer/arc-layer.ts
+++ b/src/layers/src/arc-layer/arc-layer.ts
@@ -34,14 +34,17 @@ import {
ColorRange,
RGBColor,
Merge,
+ VisConfigBoolean,
VisConfigColorRange,
VisConfigColorSelect,
VisConfigNumber,
VisConfigRange,
+ VisConfigSelection,
LayerColumn,
Field,
AnimationConfig
} from '@kepler.gl/types';
+import {createTargetArrowLayers, targetArrowVisConfigs} from './target-arrow';
import {KeplerTable} from '@kepler.gl/table';
export type ArcLayerVisConfigSettings = {
@@ -50,6 +53,9 @@ export type ArcLayerVisConfigSettings = {
colorRange: VisConfigColorRange;
sizeRange: VisConfigRange;
targetColor: VisConfigColorSelect;
+ targetArrowEnabled: VisConfigBoolean;
+ targetArrowShape: VisConfigSelection;
+ targetArrowSize: VisConfigNumber;
};
export type ArcLayerColumnsConfig = {
@@ -75,6 +81,9 @@ export type ArcLayerVisConfig = {
sizeRange: [number, number];
targetColor: RGBColor;
thickness: number;
+ targetArrowEnabled: boolean;
+ targetArrowShape: string;
+ targetArrowSize: number;
};
export type ArcLayerVisualChannelConfig = LayerColorConfig & LayerSizeConfig;
@@ -210,7 +219,7 @@ export default class ArcLayer extends Layer {
constructor(props) {
super(props);
- this.registerVisConfig(arcVisConfigs);
+ this.registerVisConfig({...arcVisConfigs, ...targetArrowVisConfigs});
this.getPositionAccessor = (dataContainer: DataContainerInterface) =>
arcPosAccessor(this.config.columns, this.config.columnMode)(dataContainer);
}
@@ -540,6 +549,20 @@ export default class ArcLayer extends Layer {
};
}
+ const arrowLayers = createTargetArrowLayers({
+ layer: this,
+ formattedData: data,
+ defaultLayerProps,
+ mapState,
+ interactionConfig,
+ greatCircle: isGlobeMode,
+ height: 1,
+ elevationScale: 1,
+ getColor: data.getTargetColor,
+ hoveredObject,
+ highlightColor: this.config.highlightColor
+ });
+
return [
// @ts-expect-error
new ArcLayerClass({
@@ -570,7 +593,8 @@ export default class ArcLayer extends Layer {
getWidth: data.getWidth
})
]
- : [])
+ : []),
+ ...arrowLayers
];
}
diff --git a/src/layers/src/arc-layer/target-arrow.spec.ts b/src/layers/src/arc-layer/target-arrow.spec.ts
new file mode 100644
index 000000000..96c3c8bf8
--- /dev/null
+++ b/src/layers/src/arc-layer/target-arrow.spec.ts
@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+import {MapView} from '@deck.gl/core';
+import {worldToPixels} from '@math.gl/web-mercator';
+
+import {KeplerGlobeView} from '@kepler.gl/deckgl-layers';
+
+import {createTargetArrowLayer, targetArrowAngle} from './target-arrow';
+
+function mercatorViewport(overrides = {}) {
+ const viewport = new MapView({farZMultiplier: 1.2}).makeViewport({
+ width: 800,
+ height: 800,
+ viewState: {
+ latitude: 37.8,
+ longitude: -122.4,
+ zoom: 10,
+ pitch: 0,
+ bearing: 0,
+ ...overrides
+ }
+ });
+ if (!viewport) {
+ throw new Error('expected a viewport');
+ }
+ return viewport;
+}
+
+const mapState = {
+ width: 800,
+ height: 800,
+ latitude: 37.8,
+ longitude: -122.4,
+ zoom: 10,
+ pitch: 0,
+ bearing: 0,
+ globe: {enabled: false}
+};
+
+function makeArrowHost(overrides = {}): any {
+ return {
+ id: 'test-layer',
+ config: {
+ visConfig: {
+ targetArrowEnabled: true,
+ targetArrowShape: 'triangle',
+ targetArrowSize: 16,
+ opacity: 0.8
+ }
+ },
+ ...overrides
+ };
+}
+
+function createArrowLayer(layer: any, overrides = {}) {
+ return createTargetArrowLayer({
+ layer,
+ formattedData: {data: {}},
+ defaultLayerProps: {visible: true},
+ mapState,
+ interactionConfig: {brush: {enabled: true, config: {size: 2}}},
+ greatCircle: false,
+ height: 0,
+ elevationScale: 1,
+ getColor: [10, 20, 30],
+ ...overrides
+ });
+}
+
+describe('targetArrowAngle', () => {
+ const source = [-122.45, 37.75, 0];
+ const straight = {greatCircle: false, height: 0};
+
+ test('points along the screen axes on a north-up map', () => {
+ const viewport = mercatorViewport();
+ expect(targetArrowAngle(viewport, source, [-122.45, 37.85, 0], straight)).toBeCloseTo(0, 0);
+ expect(targetArrowAngle(viewport, source, [-122.35, 37.75, 0], straight)).toBeCloseTo(90, 0);
+ expect(targetArrowAngle(viewport, source, [-122.55, 37.75, 0], straight)).toBeCloseTo(-90, 0);
+ const south = targetArrowAngle(viewport, source, [-122.45, 37.65, 0], straight);
+ expect(Math.abs(Math.abs(south) - 180)).toBeLessThan(1);
+ });
+
+ test('rotates with map bearing', () => {
+ const flat = targetArrowAngle(mercatorViewport(), source, [-122.35, 37.75, 0], straight);
+ const turned = targetArrowAngle(
+ mercatorViewport({bearing: 90}),
+ source,
+ [-122.35, 37.75, 0],
+ straight
+ );
+ const delta = Math.abs(turned - flat);
+ expect(Math.min(delta, 360 - delta)).toBeCloseTo(90, 0);
+ });
+
+ test('uses the short crossing at the antimeridian', () => {
+ const viewport = mercatorViewport({longitude: 180, latitude: 0, zoom: 3});
+ expect(targetArrowAngle(viewport, [170, 0, 0], [-170, 0, 0], straight)).toBeCloseTo(90, 0);
+ });
+
+ test('a raised arc meets its target at a different angle than the chord when pitched', () => {
+ const viewport = mercatorViewport({pitch: 50, zoom: 8});
+ const from = [-122.5, 37.7, 0];
+ const to = [-122.3, 37.9, 0];
+ const chord = targetArrowAngle(viewport, from, to, straight);
+ const arc = targetArrowAngle(viewport, from, to, {greatCircle: false, height: 1});
+ expect(Math.abs(arc - chord)).toBeGreaterThan(15);
+ });
+
+ test('returns 0 when the segment has no direction', () => {
+ const viewport = mercatorViewport();
+ expect(targetArrowAngle(viewport, source, source, straight)).toBe(0);
+ expect(targetArrowAngle(viewport, [Number.NaN, 0, 0], source, straight)).toBe(0);
+ });
+
+ test('common-space projection uses the same pixel axes as viewport.project', () => {
+ const viewport = mercatorViewport();
+ const projected = viewport.project([-122.4, 37.8, 0]);
+ const common = worldToPixels(
+ viewport.projectPosition([-122.4, 37.8, 0]),
+ viewport.pixelProjectionMatrix
+ );
+ expect(common[0]).toBeCloseTo(projected[0], 3);
+ expect(common[1]).toBeCloseTo(projected[1], 3);
+ });
+
+ test('a northbound globe segment at the view center points up', () => {
+ const viewport = new KeplerGlobeView({resolution: 5}).makeViewport({
+ width: 800,
+ height: 800,
+ viewState: {latitude: 20, longitude: 0, zoom: 2, pitch: 0, bearing: 0}
+ });
+ if (!viewport) {
+ throw new Error('expected a globe viewport');
+ }
+ const angle = targetArrowAngle(viewport, [0, 20, 0], [0, 22, 0], {
+ greatCircle: true,
+ height: 0
+ });
+ expect(Math.abs(angle)).toBeLessThan(10);
+ });
+});
+
+describe('createTargetArrowLayer', () => {
+ test('invalidates GeoArrow records when the target vector changes', () => {
+ const source = {length: 1, get: () => [-122.45, 37.75, 0]};
+ const firstTarget = {length: 1, get: () => [-122.35, 37.85, 0]};
+ const secondTarget = {length: 1, get: () => [-122.25, 37.95, 0]};
+ const host = makeArrowHost({geoArrowVector0: source, geoArrowVector1: firstTarget});
+
+ const firstLayer = createArrowLayer(host);
+ host.geoArrowVector1 = secondTarget;
+ const secondLayer = createArrowLayer(host);
+ const firstData = firstLayer?.props.data as any[];
+ const secondData = secondLayer?.props.data as any[];
+
+ expect(firstData[0].targetPosition).toEqual([-122.35, 37.85, 0]);
+ expect(secondData[0].targetPosition).toEqual([-122.25, 37.95, 0]);
+ });
+
+ test('uses depth testing by default and lets map parameters override defaults', () => {
+ const host = makeArrowHost({
+ geoArrowVector0: {length: 1, get: () => [-122.45, 37.75, 0]},
+ geoArrowVector1: {length: 1, get: () => [-122.35, 37.85, 0]}
+ });
+ const defaultLayer = createArrowLayer(host);
+ const overriddenLayer = createArrowLayer(host, {
+ mapState: {
+ ...mapState,
+ layerParameters: {depthTest: false, depthMask: true, cull: true}
+ }
+ });
+
+ expect(defaultLayer?.props.parameters).toEqual({
+ depthTest: true,
+ depthMask: false,
+ cull: false
+ });
+ expect(overriddenLayer?.props.parameters).toEqual({
+ depthTest: false,
+ depthMask: true,
+ cull: true
+ });
+ });
+
+ test('brushes arrowheads against both stroke endpoints', () => {
+ const sourcePosition = [-122.45, 37.75, 0];
+ const targetPosition = [-122.35, 37.85, 0];
+ const host = makeArrowHost({
+ geoArrowVector0: {length: 1, get: () => sourcePosition},
+ geoArrowVector1: {length: 1, get: () => targetPosition}
+ });
+ const layer = createArrowLayer(host);
+ const props = layer?.props as any;
+ const record = props.data[0];
+
+ expect(props.brushingTarget).toBe('source_target');
+ expect(props.getSourcePosition(record)).toEqual(sourcePosition);
+ expect(props.getTargetPosition(record)).toEqual(targetPosition);
+ });
+});
diff --git a/src/layers/src/arc-layer/target-arrow.ts b/src/layers/src/arc-layer/target-arrow.ts
new file mode 100644
index 000000000..48432d698
--- /dev/null
+++ b/src/layers/src/arc-layer/target-arrow.ts
@@ -0,0 +1,553 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+import {COORDINATE_SYSTEM, MapView, Viewport} from '@deck.gl/core';
+import {BrushingExtension, DataFilterExtension} from '@deck.gl/extensions';
+import {worldToPixels} from '@math.gl/web-mercator';
+
+import {ArrowHeadLayer, getArrowHeadGeometry, KeplerGlobeView} from '@kepler.gl/deckgl-layers';
+import {MAX_GPU_FILTERS, PROPERTY_GROUPS} from '@kepler.gl/constants';
+import {VisConfigBoolean, VisConfigNumber, VisConfigSelection} from '@kepler.gl/types';
+
+export const TARGET_ARROW_SHAPES = ['chevron', 'triangle', 'stealth'] as const;
+
+const ARC_NUM_SEGMENTS = 50;
+const EARTH_RADIUS_METERS = 6370972;
+
+const brushingExtension = new BrushingExtension();
+const dataFilterExtension = new DataFilterExtension({
+ filterSize: MAX_GPU_FILTERS,
+ // The stroke layer already reports filtered counts.
+ countItems: false
+});
+
+export const targetArrowVisConfigs: {
+ targetArrowEnabled: VisConfigBoolean;
+ targetArrowShape: VisConfigSelection;
+ targetArrowSize: VisConfigNumber;
+} = {
+ targetArrowEnabled: {
+ defaultValue: false,
+ type: 'boolean',
+ label: 'layerVisConfigs.targetArrow',
+ description: 'layerVisConfigs.targetArrowDescription',
+ group: PROPERTY_GROUPS.stroke,
+ property: 'targetArrowEnabled'
+ },
+ targetArrowShape: {
+ defaultValue: 'chevron',
+ type: 'select',
+ label: 'layerVisConfigs.targetArrowShape',
+ group: PROPERTY_GROUPS.stroke,
+ property: 'targetArrowShape',
+ options: [...TARGET_ARROW_SHAPES]
+ },
+ targetArrowSize: {
+ defaultValue: 16,
+ type: 'number',
+ label: 'layerVisConfigs.targetArrowSize',
+ group: PROPERTY_GROUPS.stroke,
+ property: 'targetArrowSize',
+ isRanged: false,
+ range: [4, 64],
+ step: 1,
+ allowCustomValue: false
+ }
+};
+
+type LngLatZ = [number, number, number];
+
+type StrokeRecord = {
+ index: number;
+ sourcePosition: number[];
+ targetPosition: number[];
+};
+
+type ArrowHost = {
+ id: string;
+ config: {
+ visConfig: {
+ targetArrowEnabled?: boolean;
+ targetArrowShape?: string;
+ targetArrowSize?: number;
+ opacity?: number;
+ };
+ };
+ filteredIndex?: ArrayLike<number> | null;
+ filteredIndexTrigger?: unknown;
+ geoArrowVector0?: {length: number; get: (index: number) => unknown} | null;
+ geoArrowVector1?: {length: number; get: (index: number) => unknown} | null;
+};
+
+export type TargetArrowOptions = {
+ /** Great-circle stroke, used on the globe. */
+ greatCircle: boolean;
+ /** deck.gl ArcLayer getHeight. Straight lines use 0. */
+ height: number;
+ /** Multiplies endpoint altitude before the head is placed. */
+ elevationScale: number;
+};
+
+const recordCache = new WeakMap<
+ object,
+ {source: unknown; target: unknown; filtered: unknown; records: StrokeRecord[]}
+>();
+
+function glslMod(x: number, y: number): number {
+ return x - y * Math.floor(x / y);
+}
+
+/** Same longitude wrap as deck.gl ArcLayer's useShortestPath branch. */
+function shortestPathEndpoints(source: LngLatZ, target: LngLatZ): [LngLatZ, LngLatZ] {
+ let sourceLng = glslMod(source[0] + 180, 360) - 180;
+ let targetLng = glslMod(target[0] + 180, 360) - 180;
+ const deltaLng = targetLng - sourceLng;
+ if (deltaLng > 180) targetLng -= 360;
+ if (deltaLng < -180) sourceLng -= 360;
+ return [
+ [sourceLng, source[1], source[2]],
+ [targetLng, target[1], target[2]]
+ ];
+}
+
+function smoothstep(t: number): number {
+ const x = Math.min(1, Math.max(0, t));
+ return x * x * (3 - 2 * x);
+}
+
+function segmentRatio(index: number): number {
+ return smoothstep(index / (ARC_NUM_SEGMENTS - 1));
+}
+
+/** deck.gl arc-layer paraboloid. `height` is ArcLayer getHeight. */
+function paraboloid(
+ distance: number,
+ sourceZ: number,
+ targetZ: number,
+ ratio: number,
+ height: number
+): number {
+ const deltaZ = targetZ - sourceZ;
+ const dh = distance * height;
+ if (dh === 0) {
+ return sourceZ + deltaZ * ratio;
+ }
+ const unitZ = deltaZ / dh;
+ const p2 = unitZ * unitZ + 1;
+ // step(deltaZ, 0) is 1 when deltaZ <= 0.
+ const descending = deltaZ <= 0;
+ const z0 = descending ? targetZ : sourceZ;
+ const r = descending ? 1 - ratio : ratio;
+ const inside = r * (p2 - r);
+ if (inside <= 0) {
+ return z0;
+ }
+ return Math.sqrt(inside) * dh + z0;
+}
+
+function interpolateFlat(source: LngLatZ, target: LngLatZ, ratio: number, height: number): LngLatZ {
+ const distance = Math.hypot(source[0] - target[0], source[1] - target[1]);
+ const z = paraboloid(distance, source[2], target[2], ratio, height);
+ return [
+ source[0] + (target[0] - source[0]) * ratio,
+ source[1] + (target[1] - source[1]) * ratio,
+ z
+ ];
+}
+
+function angularDistance(source: LngLatZ, target: LngLatZ): number {
+ const sourceLng = (source[0] * Math.PI) / 180;
+ const sourceLat = (source[1] * Math.PI) / 180;
+ const targetLng = (target[0] * Math.PI) / 180;
+ const targetLat = (target[1] * Math.PI) / 180;
+ const dLng = Math.sin((sourceLng - targetLng) / 2);
+ const dLat = Math.sin((sourceLat - targetLat) / 2);
+ const a = dLat * dLat + Math.cos(sourceLat) * Math.cos(targetLat) * dLng * dLng;
+ return 2 * Math.asin(Math.min(1, Math.sqrt(Math.max(0, a))));
+}
+
+/** project_globe_ (z = 0) swizzled to .yxz, matching the arc shader. */
+function globeDirectionYxz(lng: number, lat: number): LngLatZ {
+ const lambda = (lng * Math.PI) / 180;
+ const phi = (lat * Math.PI) / 180;
+ const cosPhi = Math.cos(phi);
+ const x = Math.sin(lambda) * cosPhi;
+ const y = -Math.cos(lambda) * cosPhi;
+ const z = Math.sin(phi);
+ return [y, x, z];
+}
+
+function greatCirclePoint(
+ source: LngLatZ,
+ target: LngLatZ,
+ ratio: number,
+ height: number
+): LngLatZ {
+ const distance = angularDistance(source, target);
+ let lng = target[0];
+ let lat = target[1];
+ if (distance >= 1e-8 && Math.abs(distance - Math.PI) < 0.001) {
+ lng = (1 - ratio) * source[0] + ratio * target[0];
+ lat = (1 - ratio) * source[1] + ratio * target[1];
+ } else if (distance >= 1e-8) {
+ const a = Math.sin((1 - ratio) * distance);
+ const b = Math.sin(ratio * distance);
+ const sourceDir = globeDirectionYxz(source[0], source[1]);
+ const targetDir = globeDirectionYxz(target[0], target[1]);
+ const mixed: LngLatZ = [
+ sourceDir[0] * a + targetDir[0] * b,
+ sourceDir[1] * a + targetDir[1] * b,
+ sourceDir[2] * a + targetDir[2] * b
+ ];
+ lng = (Math.atan2(mixed[1], -mixed[0]) * 180) / Math.PI;
+ lat = (Math.atan2(mixed[2], Math.hypot(mixed[0], mixed[1])) * 180) / Math.PI;
+ }
+ const z = paraboloid(distance * EARTH_RADIUS_METERS, source[2], target[2], ratio, height);
+ return [lng, lat, z];
+}
+
+function asLngLatZ(position: number[]): LngLatZ {
+ return [position[0], position[1], position[2] || 0];
+}
+
+function scaleAltitude(position: number[], elevationScale: number): LngLatZ {
+ const [lng, lat, alt] = asLngLatZ(position);
+ return [lng, lat, alt * elevationScale];
+}
+
+/**
+ * Icon/mesh angle in degrees. 0 points up, positive turns clockwise on screen,
+ * which matches a y-down pixel delta of (dx, dy) via atan2(dx, -dy).
+ */
+function screenAngle(from: number[], to: number[]): number | null {
+ const dx = to[0] - from[0];
+ const dy = to[1] - from[1];
+ if (!Number.isFinite(dx) || !Number.isFinite(dy) || dx * dx + dy * dy < 1e-6) {
+ return null;
+ }
+ return (Math.atan2(dx, -dy) * 180) / Math.PI;
+}
+
+function projectCommon(viewport: Viewport, position: LngLatZ): [number, number] {
+ const pixels = worldToPixels(position, viewport.pixelProjectionMatrix);
+ return [pixels[0], pixels[1]];
+}
+
+function flatCurvePixel(
+ viewport: Viewport,
+ source: LngLatZ,
+ target: LngLatZ,
+ ratio: number,
+ height: number
+): [number, number] {
+ const [sourceLngLat, targetLngLat] = shortestPathEndpoints(source, target);
+ const common = interpolateFlat(
+ viewport.projectPosition(sourceLngLat),
+ viewport.projectPosition(targetLngLat),
+ ratio,
+ height
+ );
+ return projectCommon(viewport, common);
+}
+
+/**
+ * Screen direction of the last segment of an arc or line, in ArrowHeadLayer degrees.
+ * Flat arcs follow deck.gl's paraboloid in common space. Globe strokes follow the
+ * great-circle branch. Straight lines (height 0, not a great circle) use the
+ * projected endpoints.
+ */
+export function targetArrowAngle(
+ viewport: Viewport,
+ sourceIn: number[],
+ targetIn: number[],
+ {greatCircle, height}: {greatCircle: boolean; height: number}
+): number {
+ const source = asLngLatZ(sourceIn);
+ const target = asLngLatZ(targetIn);
+ if (![...source, ...target].every(Number.isFinite)) {
+ return 0;
+ }
+
+ if (!greatCircle && height === 0) {
+ const [sourceLngLat, targetLngLat] = shortestPathEndpoints(source, target);
+ return screenAngle(viewport.project(sourceLngLat), viewport.project(targetLngLat)) ?? 0;
+ }
+
+ const prevRatio = segmentRatio(ARC_NUM_SEGMENTS - 2);
+ const endRatio = segmentRatio(ARC_NUM_SEGMENTS - 1);
+ const from = greatCircle
+ ? viewport.project(greatCirclePoint(source, target, prevRatio, height))
+ : flatCurvePixel(viewport, source, target, prevRatio, height);
+ const to = greatCircle
+ ? viewport.project(greatCirclePoint(source, target, endRatio, height))
+ : flatCurvePixel(viewport, source, target, endRatio, height);
+ return screenAngle(from, to) ?? 0;
+}
+
+function readArrowPoint(value: unknown): LngLatZ | null {
+ if (!value) {
+ return null;
+ }
+ const point = value as {
+ get?: (index: number) => number;
+ length?: number;
+ [index: number]: number;
+ };
+ const lng = typeof point.get === 'function' ? point.get(0) : point[0];
+ const lat = typeof point.get === 'function' ? point.get(1) : point[1];
+ const rawAlt =
+ typeof point.get === 'function'
+ ? point.length && point.length > 2
+ ? point.get(2)
+ : 0
+ : point[2];
+ if (!Number.isFinite(lng) || !Number.isFinite(lat)) {
+ return null;
+ }
+ return [lng, lat, Number.isFinite(rawAlt) ? rawAlt : 0];
+}
+
+function strokeRecords(layer: ArrowHost, formattedData: {data?: unknown}): StrokeRecord[] {
+ const rows = formattedData?.data;
+ if (Array.isArray(rows)) {
+ return rows as StrokeRecord[];
+ }
+
+ const source = layer.geoArrowVector0;
+ const target = layer.geoArrowVector1;
+ if (!source || !target) {
+ return [];
+ }
+ const filtered = layer.filteredIndexTrigger;
+ const cached = recordCache.get(layer);
+ if (
+ cached &&
+ cached.source === source &&
+ cached.target === target &&
+ cached.filtered === filtered
+ ) {
+ return cached.records;
+ }
+
+ const records: StrokeRecord[] = [];
+ const count = Math.min(source.length, target.length);
+ for (let index = 0; index < count; index++) {
+ if (layer.filteredIndex && !layer.filteredIndex[index]) {
+ continue;
+ }
+ const sourcePosition = readArrowPoint(source.get(index));
+ const targetPosition = readArrowPoint(target.get(index));
+ if (!sourcePosition || !targetPosition) {
+ continue;
+ }
+ records.push({index, sourcePosition, targetPosition});
+ }
+ recordCache.set(layer, {source, target, filtered, records});
+ return records;
+}
+
+function hoverRecord(
+ layer: ArrowHost,
+ formattedData: {data?: unknown},
+ hoveredObject?: {
+ index?: number;
+ sourcePosition?: number[];
+ targetPosition?: number[];
+ } | null
+): StrokeRecord | null {
+ if (!hoveredObject) {
+ return null;
+ }
+ // Neighbor arcs share a row index, so the picked object identifies the stroke.
+ if (Array.isArray(hoveredObject.sourcePosition) && Array.isArray(hoveredObject.targetPosition)) {
+ return {
+ index: hoveredObject.index ?? 0,
+ sourcePosition: hoveredObject.sourcePosition,
+ targetPosition: hoveredObject.targetPosition
+ };
+ }
+ if (!Number.isFinite(hoveredObject.index)) {
+ return null;
+ }
+ return (
+ strokeRecords(layer, formattedData).find(record => record.index === hoveredObject.index) ?? null
+ );
+}
+
+function viewportFromMapState(mapState): Viewport | null {
+ if (!mapState?.width || !mapState?.height) {
+ return null;
+ }
+ const view = mapState.globe?.enabled
+ ? new KeplerGlobeView({resolution: 5})
+ : new MapView({farZMultiplier: 1.2});
+ return view.makeViewport({
+ width: mapState.width,
+ height: mapState.height,
+ viewState: mapState
+ });
+}
+
+export function createTargetArrowLayer({
+ layer,
+ formattedData,
+ defaultLayerProps,
+ mapState,
+ interactionConfig,
+ greatCircle,
+ height,
+ elevationScale,
+ getColor,
+ hoveredObject,
+ highlightColor,
+ highlight = false
+}: {
+ layer: ArrowHost;
+ formattedData: {data?: unknown; getFilterValue?: (d: StrokeRecord) => number[]};
+ defaultLayerProps: {visible?: boolean; filterRange?: unknown; hidden?: boolean};
+ mapState: {
+ width?: number;
+ height?: number;
+ latitude?: number;
+ longitude?: number;
+ zoom?: number;
+ pitch?: number;
+ bearing?: number;
+ globe?: {enabled?: boolean};
+ layerParameters?: object;
+ };
+ interactionConfig?: {brush?: {enabled?: boolean; config?: {size?: number}}};
+ greatCircle: boolean;
+ height: number;
+ elevationScale: number;
+ getColor: any;
+ hoveredObject?: {
+ index?: number;
+ sourcePosition?: number[];
+ targetPosition?: number[];
+ } | null;
+ highlightColor?: number[];
+ /** One head, painted in highlightColor over the hovered stroke. */
+ highlight?: boolean;
+}): ArrowHeadLayer | null {
+ const {visConfig} = layer.config;
+ if (!visConfig.targetArrowEnabled) {
+ return null;
+ }
+ const records = highlight
+ ? hoverRecord(layer, formattedData, hoveredObject)
+ : strokeRecords(layer, formattedData);
+ const data = Array.isArray(records) ? records : records ? [records] : [];
+ if (!data.length) {
+ return null;
+ }
+ const viewport = viewportFromMapState(mapState);
+ if (!viewport) {
+ return null;
+ }
+
+ const shape = visConfig.targetArrowShape || 'chevron';
+ const size = Number.isFinite(visConfig.targetArrowSize) ? visConfig.targetArrowSize : 16;
+ const scale = Number.isFinite(elevationScale) ? elevationScale : 1;
+ const brush = interactionConfig?.brush;
+ const color = highlight ? highlightColor || getColor : getColor;
+
+ return new ArrowHeadLayer({
+ id: `${layer.id}-arrow-head-${shape}${highlight ? '-hovered' : ''}`,
+ data,
+ coordinateSystem: COORDINATE_SYSTEM.LNGLAT,
+ pickable: false,
+ wrapLongitude: true,
+ visible: defaultLayerProps.visible,
+ hidden: defaultLayerProps.hidden,
+ opacity: highlight ? 1 : visConfig.opacity,
+ parameters: {
+ depthTest: true,
+ depthMask: false,
+ cull: false,
+ ...(mapState.layerParameters || {})
+ },
+ billboard: true,
+ stroked: false,
+ filled: true,
+ antialiasing: false,
+ radiusUnits: 'pixels',
+ radiusScale: 1,
+ radiusMinPixels: 0,
+ radiusMaxPixels: 256,
+ getPosition: (d: StrokeRecord) => [
+ d.targetPosition[0],
+ d.targetPosition[1],
+ (d.targetPosition[2] || 0) * scale
+ ],
+ getSourcePosition: (d: StrokeRecord): LngLatZ => [
+ d.sourcePosition[0],
+ d.sourcePosition[1],
+ d.sourcePosition[2] || 0
+ ],
+ getTargetPosition: (d: StrokeRecord): LngLatZ => [
+ d.targetPosition[0],
+ d.targetPosition[1],
+ d.targetPosition[2] || 0
+ ],
+ getRadius: size,
+ getAngle: (d: any) =>
+ targetArrowAngle(
+ viewport,
+ scaleAltitude(d.sourcePosition, scale),
+ scaleAltitude(d.targetPosition, scale),
+ {greatCircle, height}
+ ),
+ getFillColor: color,
+ iconGeometry: getArrowHeadGeometry(shape),
+ ...(highlight
+ ? {}
+ : {
+ extensions: [dataFilterExtension, brushingExtension],
+ filterRange: defaultLayerProps.filterRange,
+ getFilterValue: formattedData.getFilterValue,
+ brushingEnabled: Boolean(brush?.enabled),
+ brushingRadius: (brush?.config?.size || 0) * 1000,
+ brushingTarget: 'source_target'
+ }),
+ updateTriggers: {
+ getAngle: [
+ mapState.longitude,
+ mapState.latitude,
+ mapState.zoom,
+ mapState.pitch,
+ mapState.bearing,
+ mapState.width,
+ mapState.height,
+ greatCircle,
+ height,
+ scale
+ ],
+ getFillColor: color,
+ getRadius: size,
+ getFilterValue: formattedData.getFilterValue,
+ getPosition: scale,
+ getSourcePosition: scale,
+ getTargetPosition: scale
+ }
+ });
+}
+
+/** The stroke heads, plus a highlight head when a row of this layer is hovered. */
+export function createTargetArrowLayers(
+ args: Parameters<typeof createTargetArrowLayer>[0]
+): ArrowHeadLayer[] {
+ const arrowLayer = createTargetArrowLayer(args);
+ if (!arrowLayer) {
+ return [];
+ }
+ if (!args.hoveredObject) {
+ return [arrowLayer];
+ }
+ const hoveredArrowLayer = createTargetArrowLayer({
+ ...args,
+ highlight: true,
+ getColor: args.highlightColor || args.getColor
+ });
+ return hoveredArrowLayer ? [arrowLayer, hoveredArrowLayer] : [arrowLayer];
+}
diff --git a/src/layers/src/line-layer/line-layer.ts b/src/layers/src/line-layer/line-layer.ts
index a4e73ac5b..33b0914ea 100644
--- a/src/layers/src/line-layer/line-layer.ts
+++ b/src/layers/src/line-layer/line-layer.ts
@@ -17,12 +17,15 @@ import {
ColorRange,
Merge,
RGBColor,
+ VisConfigBoolean,
VisConfigColorRange,
VisConfigColorSelect,
VisConfigNumber,
VisConfigRange,
+ VisConfigSelection,
LayerColumn
} from '@kepler.gl/types';
+import {createTargetArrowLayers} from '../arc-layer/target-arrow';
import {default as KeplerTable} from '@kepler.gl/table';
import {DataContainerInterface, maybeHexToGeo} from '@kepler.gl/utils';
@@ -33,6 +36,9 @@ export type LineLayerVisConfigSettings = {
sizeRange: VisConfigRange;
targetColor: VisConfigColorSelect;
elevationScale: VisConfigNumber;
+ targetArrowEnabled: VisConfigBoolean;
+ targetArrowShape: VisConfigSelection;
+ targetArrowSize: VisConfigNumber;
};
export type LineLayerColumnsConfig = {
@@ -62,6 +68,9 @@ export type LineLayerVisConfig = {
targetColor: RGBColor;
thickness: number;
elevationScale: number;
+ targetArrowEnabled: boolean;
+ targetArrowShape: string;
+ targetArrowSize: number;
};
export type LineLayerConfig = Merge<
@@ -232,6 +241,17 @@ export default class LineLayer extends ArcLayer {
};
}
+ isLayerHovered(objectInfo): boolean {
+ return (
+ super.isLayerHovered(objectInfo) ||
+ Boolean(
+ this.config.visConfig.targetArrowEnabled &&
+ objectInfo?.picked &&
+ objectInfo?.layer?.props?.id === `${this.id}-globe`
+ )
+ );
+ }
+
static findDefaultLayerProps({fieldPairs = []}: KeplerTable): {
props: {color?: RGBColor; columns: LineLayerColumnsConfig; label: string}[];
} {
@@ -286,6 +306,21 @@ export default class LineLayer extends ArcLayer {
const globeMode = mapState?.globe?.enabled;
const blendingParameters = mapState?.layerParameters ?? {};
+ const arrowLayers = createTargetArrowLayers({
+ layer: this,
+ formattedData: data,
+ defaultLayerProps,
+ mapState,
+ interactionConfig,
+ // On a globe the line is a flat great-circle arc. On a map it is a straight
+ // segment, so the head follows the projected endpoints rather than a paraboloid.
+ greatCircle: Boolean(globeMode),
+ height: 0,
+ elevationScale: globeMode ? 1 : this.config.visConfig.elevationScale,
+ getColor: data.getTargetColor,
+ hoveredObject,
+ highlightColor: this.config.highlightColor
+ });
if (globeMode) {
const id = `${defaultLayerProps.id}-globe`;
@@ -307,11 +342,11 @@ export default class LineLayer extends ArcLayer {
// depth disk occludes segments on the far side of the globe).
getHeight: 0,
parameters: {cull: false, ...blendingParameters},
- // A Kepler line has a single color channel; an ArcLayer interpolates
- // between source and target colors, so feed the same color to both
- // ends (otherwise the target end falls back to deck.gl's default).
+ // The target end, including the arrowhead, uses the target color.
getSourceColor: data.getColor,
- getTargetColor: data.getColor,
+ getTargetColor: this.config.visConfig.targetArrowEnabled
+ ? data.getTargetColor
+ : data.getColor,
widthUnits: 'pixels' as const
}),
...(hoveredObject
@@ -329,7 +364,8 @@ export default class LineLayer extends ArcLayer {
widthUnits: 'pixels' as const
})
]
- : [])
+ : []),
+ ...arrowLayers
];
}
@@ -383,7 +419,8 @@ export default class LineLayer extends ArcLayer {
getWidth: data.getWidth
})
]
- : [])
+ : []),
+ ...arrowLayers
];
}
diff --git a/src/localization/src/translations/en.ts b/src/localization/src/translations/en.ts
index 3e8c5b05d..7e7ed1573 100644
--- a/src/localization/src/translations/en.ts
+++ b/src/localization/src/translations/en.ts
@@ -203,6 +203,10 @@ export default {
strokeColor: 'Stroke Color',
strokeColorRange: 'Stroke Color range',
targetColor: 'Target Color',
+ targetArrow: 'Target Arrow',
+ targetArrowDescription: 'Draw an arrowhead at the end of each arc or line',
+ targetArrowShape: 'Arrow Shape',
+ targetArrowSize: 'Arrow Size',
colorAggregation: 'Color Aggregation',
heightAggregation: 'Height Aggregation',
weightAggregation: 'Weight Aggregation',
diff --git a/test/browser/layer-tests/arc-layer-specs.js b/test/browser/layer-tests/arc-layer-specs.js
index f6215f3a4..576b8b516 100644
--- a/test/browser/layer-tests/arc-layer-specs.js
+++ b/test/browser/layer-tests/arc-layer-specs.js
@@ -44,6 +44,14 @@ test('#ArcLayer -> constructor', t => {
t.ok(layer.isAggregated === false, 'ArcLayer is not aggregated');
t.ok(layer.config.label === 'test arc layer', 'label should be correct');
t.ok(Object.keys(layer.columnPairs).length, 'should have columnPairs');
+ t.equal(layer.config.visConfig.targetArrowEnabled, false, 'target arrow is off');
+ t.equal(layer.config.visConfig.targetArrowShape, 'chevron', 'default arrow shape');
+ t.equal(layer.config.visConfig.targetArrowSize, 16, 'default arrow size');
+ t.equal(
+ layer.visConfigSettings.targetArrowSize.allowCustomValue,
+ false,
+ 'arrow size has no custom input'
+ );
}
}
]
@@ -458,6 +466,98 @@ test('#ArcLayer -> renderLayer', t => {
t.equal(props[key], expectedProps[key], `should have correct props.${key}`);
});
}
+ },
+ {
+ name: 'Arc render layer.3 target arrow',
+ layer: {
+ config: {
+ dataId,
+ label: 'trip arcs',
+ columns,
+ color: [10, 10, 10],
+ visConfig: {
+ targetArrowEnabled: true,
+ targetArrowShape: 'chevron',
+ targetArrowSize: 24,
+ targetColor: [200, 30, 30]
+ }
+ },
+ type: 'arc',
+ id: 'test_layer_0'
+ },
+ datasets: {
+ [dataId]: {
+ ...preparedDataset,
+ filteredIndex
+ }
+ },
+ assert: deckLayers => {
+ t.equal(deckLayers.length, 2, 'Should create the arc and an arrow head');
+ const arrowLayer = deckLayers[deckLayers.length - 1];
+ t.equal(arrowLayer.id, 'test_layer_0-arrow-head-chevron', 'arrow layer id');
+ t.equal(arrowLayer.props.pickable, false, 'arrow head does not take the line hover');
+ const radius =
+ typeof arrowLayer.props.getRadius === 'function'
+ ? arrowLayer.props.getRadius(arrowLayer.props.data[0])
+ : arrowLayer.props.getRadius;
+ t.equal(radius, 24, 'arrow size is the vis config value in pixels');
+ t.equal(arrowLayer.props.iconGeometry.length, 18, 'chevron is two triangles');
+ const angle = arrowLayer.props.getAngle(arrowLayer.props.data[0]);
+ t.equal(typeof angle, 'number', 'arrow angle is computed');
+ t.ok(Number.isFinite(angle), 'arrow angle is finite');
+ const fill =
+ typeof arrowLayer.props.getFillColor === 'function'
+ ? arrowLayer.props.getFillColor(arrowLayer.props.data[0])
+ : arrowLayer.props.getFillColor;
+ t.deepEqual(fill, [200, 30, 30], 'arrow uses the target color');
+ }
+ },
+ {
+ name: 'Arc render layer.4 target arrow hover',
+ layer: {
+ config: {
+ dataId,
+ label: 'trip arcs',
+ columns,
+ color: [10, 10, 10],
+ visConfig: {
+ targetArrowEnabled: true,
+ targetArrowShape: 'triangle',
+ targetArrowSize: 24
+ }
+ },
+ type: 'arc',
+ id: 'test_layer_0'
+ },
+ datasets: {
+ [dataId]: {
+ ...preparedDataset,
+ filteredIndex
+ }
+ },
+ renderArgs: {
+ objectHovered: {
+ picked: true,
+ object: {
+ index: 0,
+ sourcePosition: [-122.4, 37.8, 0],
+ targetPosition: [-122.3, 37.9, 0]
+ },
+ layer: {props: {id: 'test_layer_0'}}
+ }
+ },
+ assert: deckLayers => {
+ t.equal(deckLayers.length, 4, 'Should add a highlight stroke and a highlight arrow');
+ const arrowLayer = deckLayers[deckLayers.length - 1];
+ t.equal(arrowLayer.id, 'test_layer_0-arrow-head-triangle-hovered', 'highlight arrow id');
+ t.equal(arrowLayer.props.data.length, 1, 'highlight arrow is only the hovered stroke');
+ t.equal(arrowLayer.props.opacity, 1, 'highlight arrow is fully opaque');
+ const color =
+ typeof arrowLayer.props.getFillColor === 'function'
+ ? arrowLayer.props.getFillColor(arrowLayer.props.data[0])
+ : arrowLayer.props.getFillColor;
+ t.deepEqual(color, [252, 242, 26, 255], 'highlight arrow uses the layer highlight color');
+ }
}
];
diff --git a/test/browser/layer-tests/line-layer-specs.js b/test/browser/layer-tests/line-layer-specs.js
index 36dbac71a..4d4cfc9af 100644
--- a/test/browser/layer-tests/line-layer-specs.js
+++ b/test/browser/layer-tests/line-layer-specs.js
@@ -16,6 +16,7 @@ import {
import {PROJECTED_PIXEL_SIZE_MULTIPLIER} from '@kepler.gl/constants';
import {KeplerGlLayers} from '@kepler.gl/layers';
+import {INITIAL_MAP_STATE} from '@kepler.gl/reducers';
import {copyTable, copyTableAndUpdate} from '@kepler.gl/table';
const {LineLayer} = KeplerGlLayers;
@@ -41,6 +42,12 @@ test('#LineLayer -> constructor', t => {
t.ok(layer.isAggregated === false, 'LineLayer is not aggregated');
t.ok(layer.config.label === 'test line layer', 'label should be correct');
t.ok(Object.keys(layer.columnPairs).length, 'should have columnPairs');
+ t.equal(layer.config.visConfig.targetArrowEnabled, false, 'target arrow is off');
+ t.equal(
+ layer.visConfigSettings.targetArrowSize.allowCustomValue,
+ false,
+ 'arrow size has no custom input'
+ );
}
}
]
@@ -355,6 +362,186 @@ test('#LineLayer -> renderLayer', t => {
t.equal(props.brushingEnabled, true, 'should have brushingEnabled: true');
t.equal(props.brushingTarget, 'source_target', 'brushingTarget: should be source');
}
+ },
+ {
+ name: 'Line render layer.3 target arrow',
+ layer: {
+ config: {
+ dataId,
+ label: 'trip lines',
+ columns,
+ color: [10, 10, 10],
+ visConfig: {
+ targetArrowEnabled: true,
+ targetArrowShape: 'triangle',
+ targetArrowSize: 20,
+ targetColor: [200, 30, 30]
+ }
+ },
+ type: 'line',
+ id: 'test_layer_0'
+ },
+ datasets: {
+ [dataId]: {
+ ...preparedDataset,
+ filteredIndex
+ }
+ },
+ assert: deckLayers => {
+ t.equal(deckLayers.length, 2, 'Should create the line and an arrow head');
+ const arrowLayer = deckLayers[deckLayers.length - 1];
+ t.equal(arrowLayer.id, 'test_layer_0-arrow-head-triangle', 'arrow layer id');
+ t.equal(arrowLayer.props.pickable, false, 'arrow head does not take the line hover');
+ const radius =
+ typeof arrowLayer.props.getRadius === 'function'
+ ? arrowLayer.props.getRadius(arrowLayer.props.data[0])
+ : arrowLayer.props.getRadius;
+ t.equal(radius, 20, 'arrow size is the vis config value in pixels');
+ t.equal(arrowLayer.props.iconGeometry.length, 9, 'triangle is one triangle');
+ t.ok(
+ Number.isFinite(arrowLayer.props.getAngle(arrowLayer.props.data[0])),
+ 'arrow angle is finite'
+ );
+ const fill =
+ typeof arrowLayer.props.getFillColor === 'function'
+ ? arrowLayer.props.getFillColor(arrowLayer.props.data[0])
+ : arrowLayer.props.getFillColor;
+ t.deepEqual(fill, [200, 30, 30], 'arrow uses the target color');
+ }
+ },
+ {
+ name: 'Line render layer.4 target arrow hover',
+ layer: {
+ config: {
+ dataId,
+ label: 'trip lines',
+ columns,
+ color: [10, 10, 10],
+ visConfig: {
+ targetArrowEnabled: true,
+ targetArrowShape: 'triangle',
+ targetArrowSize: 20
+ }
+ },
+ type: 'line',
+ id: 'test_layer_0'
+ },
+ datasets: {
+ [dataId]: {
+ ...preparedDataset,
+ filteredIndex
+ }
+ },
+ renderArgs: {
+ objectHovered: {
+ picked: true,
+ object: {
+ index: 0,
+ sourcePosition: [-122.4, 37.8, 0],
+ targetPosition: [-122.3, 37.9, 0]
+ },
+ layer: {props: {id: 'test_layer_0'}}
+ }
+ },
+ assert: deckLayers => {
+ t.equal(deckLayers.length, 4, 'Should add a highlight stroke and a highlight arrow');
+ const arrowLayer = deckLayers[deckLayers.length - 1];
+ t.equal(arrowLayer.id, 'test_layer_0-arrow-head-triangle-hovered', 'highlight arrow id');
+ t.equal(arrowLayer.props.data.length, 1, 'highlight arrow is only the hovered stroke');
+ const color =
+ typeof arrowLayer.props.getFillColor === 'function'
+ ? arrowLayer.props.getFillColor(arrowLayer.props.data[0])
+ : arrowLayer.props.getFillColor;
+ t.deepEqual(color, [252, 242, 26, 255], 'highlight arrow uses the layer highlight color');
+ }
+ },
+ {
+ name: 'Line render layer.5 target arrow hover on globe',
+ layer: {
+ config: {
+ dataId,
+ label: 'trip lines',
+ columns,
+ color: [10, 10, 10],
+ visConfig: {
+ targetArrowEnabled: true,
+ targetArrowShape: 'triangle',
+ targetArrowSize: 20
+ }
+ },
+ type: 'line',
+ id: 'test_layer_0'
+ },
+ datasets: {
+ [dataId]: {
+ ...preparedDataset,
+ filteredIndex
+ }
+ },
+ renderArgs: {
+ mapState: {...INITIAL_MAP_STATE, globe: {enabled: true}},
+ objectHovered: {
+ picked: true,
+ object: {
+ index: 0,
+ sourcePosition: [-122.4, 37.8, 0],
+ targetPosition: [-122.3, 37.9, 0]
+ },
+ layer: {props: {id: 'test_layer_0-globe'}}
+ }
+ },
+ assert: deckLayers => {
+ t.equal(deckLayers.length, 4, 'Should add globe highlight stroke and arrow');
+ t.equal(deckLayers[1].id, 'test_layer_0-globe-hovered', 'globe highlight stroke id');
+ t.equal(
+ deckLayers[3].id,
+ 'test_layer_0-arrow-head-triangle-hovered',
+ 'globe highlight arrow id'
+ );
+ }
+ },
+ {
+ name: 'Line render layer.6 preserves globe behavior with target arrow disabled',
+ layer: {
+ config: {
+ dataId,
+ label: 'trip lines',
+ columns,
+ color: [10, 10, 10],
+ visConfig: {
+ targetArrowEnabled: false,
+ targetColor: [200, 30, 30]
+ }
+ },
+ type: 'line',
+ id: 'test_layer_0'
+ },
+ datasets: {
+ [dataId]: {
+ ...preparedDataset,
+ filteredIndex
+ }
+ },
+ renderArgs: {
+ mapState: {...INITIAL_MAP_STATE, globe: {enabled: true}},
+ objectHovered: {
+ picked: true,
+ object: {
+ index: 0,
+ sourcePosition: [-122.4, 37.8, 0],
+ targetPosition: [-122.3, 37.9, 0]
+ },
+ layer: {props: {id: 'test_layer_0-globe'}}
+ }
+ },
+ assert: deckLayers => {
+ t.equal(deckLayers.length, 1, 'Should keep the original globe stroke only');
+ t.deepEqual(
+ deckLayers[0].props.getTargetColor,
+ [10, 10, 10],
+ 'disabled arrow keeps the original solid line color'
+ );
+ }
}
];
diff --git a/test/fixtures/state-saved-v0.js b/test/fixtures/state-saved-v0.js
index 85a263c15..637bf4547 100644
--- a/test/fixtures/state-saved-v0.js
+++ b/test/fixtures/state-saved-v0.js
@@ -1130,7 +1130,10 @@ mergedLayer1.config = {
category: 'Uber',
colors: ['#5A1846', '#900C3F', '#C70039', '#E3611C', '#F1920E', '#FFC300']
},
- sizeRange: [0, 10]
+ sizeRange: [0, 10],
+ targetArrowEnabled: false,
+ targetArrowShape: 'chevron',
+ targetArrowSize: 16
}
};