apache / apache/echarts

[Feature] AxisPointer snapping

Open
#16,675 14 comments 10 reactions 0 assignees View on GitHub
en new-feature
Dominant language
TypeScript
Stars
67.3k
Forks
19.8k
Avg merge
15h 17m
Merged PRs (30d)
5

Description

### What problem does this feature solve?

# The Problem

In the current implementation, axisPointer snaps to the nearest data for different axis separately. This may cause the snapped data to be far away from the mouse position and lack the flexibility to configure which value to snap to for series like candlestick.

#11684 was trying to fix this but there were still some consensus required and was closed because too much conflicts. And this issue is going to discuss more details about it.

# Case Studies

## Case 1: two `snap: true` axes

For coordinates having two axes like rectangular coordinates and polar coordinates, the Cartesian distance should be compared to calculate the nearest data. If coordinates have two `snap: true` axes, it should snap to the data with the smallest Cartesian distance.

For example, in current implementation, [this scatter chart](https://echarts.apache.org/examples/en/view.html?c=scatter-nutrients-matrix&edit=1&reset=1&version=5.3.0), the snapped points are those of the same x and y value with the mouse position, but they are in fact quite far away from the mouse position.

![axisPointer-snapping](https://user-images.githubusercontent.com/779050/158100075-a7666dec-09e6-4be8-8e21-b43176d85d20.png)

A better snapping policy would be to snap the nearest point to the mouse position because the user's attention is more focus on the position near the mouse point (especially for this case because the mouse position is also the center of the cross of the axisPointer).

Line series with both `'value'` axes can be considered the same as this case.

Axes with `type: 'cagetory'` should be treated as if they have been set `snap: true` implicitly.

### Proposed API

```js
xAxis: {
axisPointer: {
snap: true
}
},
yAxis: {
axisPointer: {
snap: true
}
}
```

## Case 2: one `snap: true` axis but fix to data

![image](https://user-images.githubusercontent.com/779050/158126119-d4d3fe13-1b72-4d8d-b4d4-430951eb7df4.png)

Developers should be given the ability to snap the xAxis and use the corresponding y value to snap yAxis to. In this case, it means the axisPointer cross should be displayed at `['Tue', 230]` instead of `['Tue', 135]`.

### Proposed API

```js
xAxis: {
axisPointer: {
snap: true
}
},
yAxis: {
axisPointer: {
snap: 'data'
}
}
```

## Case 3: series with multiple dimension data

There are cases where there are **multiple dimensions** in one piece of data, e.g., candlestick series, boxplot series, custom series and so on. The series should have the ability to define which dimension to be used to snap. We might also provide the ability for developers to override the default policy of the series.

### Proposed API

```js
xAxis: {
axisPointer: {
snap: true
}
},
yAxis: {
axisPointer: {
snap: 'data.close' // 'close' is a dimension name in the dataset
}
}
```

## Case 4: multiple series

For **multiple series** situations, e.g., two line series sharing the same `xAxis`, developers should be provided the ability to choose between *snapping to a certain series* (similar to the case of candlestick series) or *snapping to the nearest series* (like [this highcharts demo](https://jsfiddle.net/gh/get/library/pure/highcharts/highcharts/tree/master/samples/highcharts/tooltip/bordercolor-default/).

### Proposed API

To snap to a certain series:

```js
xAxis: {
axisPointer: {
snap: true
}
},
yAxis: {
axisPointer: {
snap: 'firstSeries' // or, 'firstSeries.data.close'. 'firstSeries' is a series name
}
}
```

To snap to the nearest series:

```js
xAxis: {
axisPointer: {
snap: true
}
},
yAxis: {
axisPointer: {
snap: 'data'
}
}
```

## Misc

`axisPointer` of coordinates other than cartesian may require more test cases. For example, polar axes don't support snapping and the axisPointer always look like this no matter where the mouse position is.

b4efcd87bcd33a40020f46cb0

### What does the proposed API look like?

```js
xAxis: {
axisPointer: {
snap: true // or 'data', 'data.close', 'firstSeries.data.close'
}
}
```

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the existing axisPointer snapping behavior and the discussion in closed issue #11684. Compare the proposed API against the four case studies, including multi-dimensional and multiple-series data and non-Cartesian coordinates. Done means the snapping policy and API are agreed and the documented cases are covered.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
data-visualization
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.