feat(label): support labels auto-rotation #19348

agurtovoy · 2023-11-30T17:04:00Z

Brief Information

This pull request is in the type of:

bug fixing
new feature
others

What does this PR do?

Adds an option to auto-rotate category labels based on available space, specified category interval, and the list of provided rotations.

Fixed issues

#14996
#9265 (partially)

Details

Before: What was the problem?

The axis label rotation option enhances usability of charts with a large number of categories and/or long category names by sparing the user the effort of hovering over specific value just to see its corresponding category; the usability enhancement is even greater for non-interactive, statically rendered charts. The rotation option currently has to be chosen beforehand, though, which is suboptimal when a chart is populated with dynamic data -- depending on the data, the labels might or might need to be rotated, and the optimal rotation angle might vary.

After: How does it behave after the fixing?

This PR introduces a new axisLabel.autoRotate: boolean | number[] option, which works in concert with the axisLabel.interval: 'auto' and grid.containLabel: true options to automatically manage (category) label rotation, interval, and layout:

Kapture.2023-11-30.at.10.55.37.mp4

Kapture.2023-11-30.at.10.58.31.mp4

Kapture.2023-11-30.at.11.00.44.mp4

Document Info

This PR doesn't relate to document changes
The document should be updated later
The document changes have been made in apache/echarts-doc#xxx

I'll update the documentation once the API is settled.

Misc

Related test cases or examples to use the new APIs

See the new axis-labelAutoRotate.html test cases.

Others

Merging options

Please squash the commits into a single one when merging.

echarts-bot · 2023-11-30T17:04:06Z

Thanks for your contribution!
The community will review it ASAP. In the meanwhile, please checkout the coding standard and Wiki about How to make a pull request.

Document changes are required in this PR. Please also make a PR to apache/echarts-doc for document changes and update the issue id in the PR description. When the doc PR is merged, the maintainers will remove the PR: awaiting doc label.

agurtovoy · 2023-11-30T17:09:35Z

src/component/axis/AxisBuilder.ts

@@ -599,11 +599,6 @@ function isTwoLabelOverlapped(
    return firstRect.intersect(nextRect);
 }

-function isNameLocationCenter(nameLocation: string) {
-    return nameLocation === 'middle' || nameLocation === 'center';
-}


Moved to coord/axisHelper so it can be reused elsewhere.

agurtovoy · 2023-11-30T17:10:07Z

src/component/axis/AxisBuilder.ts

@@ -740,13 +735,10 @@ function buildAxisLabel(

    const labelModel = axisModel.getModel('axisLabel');
    const labelMargin = labelModel.get('margin');
-    const labels = axis.getViewLabels();
+    const { labels, rotation } = axis.getViewLabelsAndRotation();


Labels + calculated rotation.

agurtovoy · 2023-11-30T17:17:32Z

src/coord/Axis.ts

+    }
+
+    getNameGap(): ReturnType<typeof getAxisNameGap> {
+        return getAxisNameGap(this);


As correctly pointed out in #14996 (comment), the utility of the auto-rotate feature would be severely diminished unless we also gave users a way to automatically manage the location of the centered axis names. This is accomplished through the introduction of the nameLayout: 'auto' option -- please see below.

agurtovoy · 2023-11-30T17:20:00Z

src/coord/axisCommonTypes.ts

    nameGap?: number;
+    nameLayout?: 'auto';


An alternative was adding 'auto' as one of the nameGap's allowed values, but that would take away the ability to control the automatically managed distance between the name and the labels.

agurtovoy · 2023-11-30T17:29:13Z

src/coord/axisCommonTypes.ts

@@ -219,6 +220,8 @@ interface AxisLabelBaseOption extends Omit<TextCommonOption, 'color'> {
    // Whether axisLabel is inside the grid or outside the grid.
    inside?: boolean,
    rotate?: number,
+    autoRotate?: boolean | [number, ...number[]],


An attempted alternative was allowing the auto and number[] options for axisLabel.rotate, but that created too many rippling changes through the codebase. The implemented behavior is that specifying "hard-coded" label rotation option through rotate disables autorotation.

agurtovoy · 2023-11-30T17:29:38Z

src/coord/axisCommonTypes.ts

@@ -219,6 +220,8 @@ interface AxisLabelBaseOption extends Omit<TextCommonOption, 'color'> {
    // Whether axisLabel is inside the grid or outside the grid.
    inside?: boolean,
    rotate?: number,
+    autoRotate?: boolean | [number, ...number[]],
+    minDistance?: number,


minDistance is the minimal-allowed distance between the labels before they are rotated/collapsed.

agurtovoy · 2023-11-30T17:31:21Z

src/coord/axisCommonTypes.ts

@@ -232,7 +235,11 @@ interface AxisLabelBaseOption extends Omit<TextCommonOption, 'color'> {
    // Color can be callback
    color?: ColorString | ((value?: string | number, index?: number) => ColorString)
    overflow?: TextStyleProps['overflow']
+    // approximate auto-layout computations (autoRotate, hideOverlap) if the total number of axis labels is over
+    // the trheshold; defaults to 40
+    layoutApproximationThreshold?: number


This was previously hard-coded in the code. Elevated it into an option so that users can choose when/whether they want to trigger this optimization, since it could lead to less-than-precise layout.

agurtovoy · 2023-11-30T18:06:17Z

src/coord/axisDefault.ts

@@ -83,6 +83,7 @@ const defaultOption: AxisBaseOption = {
        // Whether axisLabel is inside the grid or outside the grid.
        inside: false,
        rotate: 0,
+        minDistance: 10,


Default labels' minDistance to 10px to match the current observable auto-interval behavior.

agurtovoy · 2023-11-30T18:07:28Z

src/coord/axisHelper.ts

- * @param axis
- * @return Be null/undefined if no labels.
- */
-export function estimateLabelUnionRect(axis: Axis) {


Moved to axisTickLabelBuilder.ts (the only place this was called from) so we can reuse label size computations we do there.

agurtovoy · 2023-11-30T18:08:45Z

src/coord/axisHelper.ts

@@ -399,3 +335,7 @@ export function unionAxisExtentFromData(dataExtent: number[], data: SeriesData,
        });
    }
 }
+
+export function isNameLocationCenter(nameLocation: string) {


Moved here from AxisBuilder.ts for cleaner reuse.

agurtovoy · 2023-11-30T19:31:19Z

src/coord/axisTickLabelBuilder.ts

+    if (axesModel.get('nameLayout') === 'auto'
+        && isNameLocationCenter(axis.model.get('nameLocation'))
+    ) {
+        const labelUnionRect = estimateLabelUnionRect(axis);


For centered labels with nameLayout: 'auto', calculate the name gap dynamically to "stack" the axis name together with the labels:

agurtovoy · 2023-11-30T19:34:48Z

src/coord/axisTickLabelBuilder.ts

+        y: bboxOffset * cos
+    };
+
+    return { axesIntersection, bounds, offset };


See https://codepen.io/agurtovoy/pen/WNPyqWx for the visualization of the math here.

agurtovoy · 2023-11-30T19:42:04Z

src/coord/axisTickLabelBuilder.ts

-        );
-        // Magic number
-        width = rect.width * 1.3;
-        height = rect.height * 1.3;


The magic 1.3 coefficient here was effectively a workaround for a subtle bug that caused an incorrect axis pixel extent to be used when calculating the category axis' unit dimensions. Please see below for the bug fix.

agurtovoy · 2023-11-30T19:45:07Z

src/coord/cartesian/Grid.ts

-        adjustAxes();
+        // sort axes to make sure we estimate ordinal axes' label dimensions after we adjusted
+        // the available grid space based on the value axes' label dimensions
+        const axesList = [...this._axesList].sort((a, b) => axisOrder(a) - axisOrder(b));


Part 1 of the "magic coefficient" bug fix referenced earlier...

agurtovoy · 2023-11-30T19:45:22Z

src/coord/cartesian/Grid.ts

+
+                // adjust axes after each potential change to grid dimensions
+                // so that the next (ordinal) axis' label estimations are more precise
+                adjustAxes();


... part 2 of the "magic coefficient" bug fix.

agurtovoy · 2023-11-30T19:46:03Z

test/axis-labelAutoRotate.html

Tests for the new functionality.

github-actions · 2023-12-01T04:52:25Z

The changes brought by this PR can be previewed at: https://echarts.apache.org/examples/editor?version=PR-19348@fcd1590

agurtovoy · 2024-01-16T21:57:05Z

@Ovilia @plainheart What can I do to help you to review this? Would love to get this in soon.

dobropeeriq · 2024-01-23T21:14:24Z

I'd love to begin using this feature. Please review.

Splinteer · 2024-01-24T18:00:34Z

Thank you for your work @agurtovoy.
I was waiting this feature for so long, it was one of the most negative points of echarts

echarts-bot bot added PR: awaiting doc Document changes is required for this PR. PR: awaiting review PR: first-time contributor labels Nov 30, 2023

pull-request-size bot added the size/XL label Nov 30, 2023

agurtovoy mentioned this pull request Nov 30, 2023

New Feature: axisLabel.autoRotate #14996

Open

agurtovoy commented Nov 30, 2023

View reviewed changes

agurtovoy force-pushed the fix-14996-feat-axis-label-auto-rotate branch from e35cb75 to a75ed79 Compare November 30, 2023 17:24

agurtovoy commented Nov 30, 2023

View reviewed changes

agurtovoy force-pushed the fix-14996-feat-axis-label-auto-rotate branch from a75ed79 to eb35c0b Compare November 30, 2023 19:18

agurtovoy commented Nov 30, 2023

View reviewed changes

test/axis-labelAutoRotate.html Outdated

Copy link

Author

agurtovoy Nov 30, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tests for the new functionality.

hexiaokang approved these changes Dec 7, 2023

View reviewed changes

agurtovoy force-pushed the fix-14996-feat-axis-label-auto-rotate branch 2 times, most recently from 627ad46 to a2a6008 Compare December 14, 2023 19:48

feat(label): support labels auto-rotation

fcd1590

agurtovoy force-pushed the fix-14996-feat-axis-label-auto-rotate branch from a2a6008 to fcd1590 Compare January 16, 2024 21:52

Ovilia added this to the 6.0.0 milestone Mar 4, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(label): support labels auto-rotation #19348

feat(label): support labels auto-rotation #19348

agurtovoy commented Nov 30, 2023 •

edited

echarts-bot bot commented Nov 30, 2023

agurtovoy Nov 30, 2023

agurtovoy Nov 30, 2023

agurtovoy Nov 30, 2023

agurtovoy Nov 30, 2023

agurtovoy Nov 30, 2023

agurtovoy Nov 30, 2023

agurtovoy Nov 30, 2023

agurtovoy Nov 30, 2023

agurtovoy Nov 30, 2023 •

edited

agurtovoy Nov 30, 2023

agurtovoy Nov 30, 2023 •

edited

agurtovoy Nov 30, 2023 •

edited

agurtovoy Nov 30, 2023

agurtovoy Nov 30, 2023

agurtovoy Nov 30, 2023

agurtovoy Nov 30, 2023

github-actions bot commented Dec 1, 2023 •

edited

agurtovoy commented Jan 16, 2024

dobropeeriq commented Jan 23, 2024

Splinteer commented Jan 24, 2024

feat(label): support labels auto-rotation #19348

Are you sure you want to change the base?

feat(label): support labels auto-rotation #19348

Conversation

agurtovoy commented Nov 30, 2023 • edited

Brief Information

What does this PR do?

Fixed issues

Details

Before: What was the problem?

After: How does it behave after the fixing?

Document Info

Misc

Related test cases or examples to use the new APIs

Others

Merging options

echarts-bot bot commented Nov 30, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agurtovoy Nov 30, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agurtovoy Nov 30, 2023 • edited

Choose a reason for hiding this comment

agurtovoy Nov 30, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Dec 1, 2023 • edited

agurtovoy commented Jan 16, 2024

dobropeeriq commented Jan 23, 2024

Splinteer commented Jan 24, 2024

agurtovoy commented Nov 30, 2023 •

edited

agurtovoy Nov 30, 2023 •

edited

agurtovoy Nov 30, 2023 •

edited

agurtovoy Nov 30, 2023 •

edited

github-actions bot commented Dec 1, 2023 •

edited