[Feature] AxisPointer snapping

[Ovilia]

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, 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.

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

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

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

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

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

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.

Proposed API

To snap to a certain series:

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

To snap to the nearest series:

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.

What does the proposed API look like?

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

[pissang]

Some ideas:

1. tooltip.snap should also be provided. When axisPointer is not used like in the case https://echarts.apache.org/examples/zh/editor.html?c=scatter-clustering. We can still snap the tooltip to the data.
2. When tooltip.snap is enabled. The axisPointer will also be snapped automatically.
3. When tooltip is not used. axisPointer.snap will be used to determine how to snap the axisPointer.

And for the configurations in the proposal. I'd suggest to avoid using access syntax xxx.xxx because it's not type friendly and complex to parse. We usually use separate configs.

For example:

To specify the dimension:

snap: true,
snapDimension: 'close'

To specify the series:

snap: true,
snapSeriesName: 'firstSeries'
snapSeriesIndex: 0

[Ovilia]

@pissang That's great. Thanks for the suggestion! I think I can get on with it and see if more details need to be discussed.

[xinlong-chen865]

Has the function of line chart been realized?

[Ovilia]

@xinlong-chen865 Not yet.

[steve2507]

Just chiming in to say that I am personally very interested in "Case 2: one snap: true axis but fix to data"

[rahulRajUserfacet]

By when would this feature be available?

[francisashley]

Hello, any progress with this?

[Mayerkel]

Anything on this?