feat(scatter): jittering for category data

[Ovilia]

Brief Information

This pull request is in the type of:

• bug fixing
• new feature
• others

What does this PR do?

This PR proposes a jittering effect for category axes and single axes, solving #18432 as well as providing a foundation to support the violin series.

It also provide an option jitterOverlap to support a beeswarm-like effect where scatters try not to overlap each other.

Fixed issues

#18432

API Changes

A new axis.jitter option in number type, which is the jitter max range in pixels

axis
    jitter: number, max range in pixels that scatters can range from
    jitterOverlap: boolean, whether scatters can overlap each other
    jitterMargin: if jitterOverlap is false, the margin of scatters from each other

Details

Jittering is useful in scatter plots for:

• Overlapping Data Points: Prevents points with the same or similar values from overlapping.
• Categorical Axes: Distinguishes points within the same category.
• Small Sample Sizes: Separates closely clustered data points.
• Discrete Data: Helps with data naturally falling into specific values (e.g., counts).

Document Info

One of the following should be checked.

• This PR doesn't relate to document changes
• The document should be updated later
• The document changes have been made in apache/echarts-doc@5b6f4ec

Misc

ZRender Changes

• This PR depends on ZRender changes (ecomfe/zrender#xxx).

Related test cases or examples to use the new APIs

N.A.

Others

Merging options

• Please squash the commits into a single one when merging.

Other information

[echarts-bot]

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.

The pull request is marked to be PR: author is committer because you are a committer of this project.

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.

[github-actions]

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

[Ovilia]

Demo: https://echarts.apache.org/examples/zh/editor.html?version=PR-19941%40ecfe583&code=MYewdgzgLgBAJgQygmBeGBtAugbgFABmIATjABQA2AprAJZowAMOM9APDAEyPMwDUfWgEoYAbzwx4SBADoADgFcIACzIYA5AnX9yAWSTKZBCiBJl9UQ8QRg4IALZkRAKhgAWEXxgBGIQBoYCysbO0cXHx4sIXwAXzw8EDkoWnAGcUkADwBBDNoIAC4xCUkYKABPOSpC9WAkKgBzEjL1P2LJRGRCjQRvFphNTj7NAGYhhDd1LFaSmAArWigoKmJC7mKY6ZgynLzC0Q3iiGXaKgKimfLK6ohaxeWWtqlkdbwYnCA

[xyy7260]

@Ovilia 这个还有多久可以发布呢

[Ovilia]

@xyy7260 This feature is planned for ECharts 6.0, which is expected to be release in the first season of 2025. If you are interested in using it before then, you may fork it after being merged and use it locally.

[xyy7260]

@Ovilia 没尝试过如何提前合并。 如果我要提前合并，在哪里查看你这个 fork

[Ovilia]

@Ovilia 没尝试过如何提前合并。 如果我要提前合并，在哪里查看你这个 fork

Step 1: Clone the repository or update your local repository with the latest changes.

git pull origin next
Step 2: Switch to the base branch of the pull request.

git checkout next
Step 3: Merge the head branch into the base branch.

git merge feat-scatter

[xyy7260]

@Ovilia OK

[100pah]

Considering the size issue, should we consider that introduce this kind of features on demand rather than including it by default?
That is, support to import it by users manually.
I'm not sure yet 🤔.

[Ovilia]

I've run the release script and checked the increased package size of this PR is 5KB (0.15% to the package size) before minifying. So I think it's easier to be imported by default.

[100pah]

I think also need to clamp with the coordinate system boundary, otherwise the invalid outcome coords will cause that some points can not be draw and hard to be discovered by developers. The same goes for the overlap processing.

[100pah]

I think if the items is ordered by floatCoord, the backtracking (i = 0) here is not necessary. With this backtracking, the entire algorithm could degraded to O(n^3) in the worst case. But without it, it can keep O(n^2).

Just have a try, to modify it (with a linked list and sort in ascending order by floatCoord):

export type JitterData = {
    fixedCoord: number;
    floatCoord: number;
    r: number;
    next: JitterData | null;
    prev: JitterData | null;
};

// Items is a circular linked list, in the ascending order by floatCoord.
const inner = makeInner<{ items: JitterData }, Axis2D | SingleAxis>();

function fixJitterAvoidOverlaps(
    fixedAxis: Axis2D | SingleAxis,
    fixedCoord: number,
    floatCoord: number,
    radius: number,
    jitter: number,
    margin: number
): number {
    const store = inner(fixedAxis);
    if (!store.items) {
        store.items = {
            fixedCoord: -1,
            floatCoord: -1,
            r: -1,
            next: null, // head of a link list
            prev: null, // tail of a link list
        };
        store.items.next = store.items;
        store.items.prev = store.items;
    }
    const items = store.items;

    const overlapA = placeJitterOnDirection(items, fixedCoord, floatCoord, radius, jitter, margin, 1);
    const overlapB = placeJitterOnDirection(items, fixedCoord, floatCoord, radius, jitter, margin, -1);
    const overlapResult = Math.abs(overlapA.resultCoord - floatCoord) < Math.abs(overlapB.resultCoord - floatCoord)
        ? overlapA : overlapB;
    let minFloat = overlapResult.resultCoord;
    if (Math.abs(minFloat - floatCoord) > jitter / 2) {
        // If the new item is moved too far, then give up.
        // Fall back to random jitter.
        minFloat = fixJitterIgnoreOverlaps(floatCoord, jitter);
    }

    // Insert to store
    const insertBy = overlapResult.insertBy;
    const resultDirection = overlapResult.direction;
    const pointer1 = resultDirection > 0 ? 'next' : 'prev';
    const pointer2 = resultDirection > 0 ? 'prev' : 'next';
    const newItem: JitterData = {
        fixedCoord: fixedCoord,
        floatCoord: overlapResult.resultCoord,
        r: radius,
        next: null,
        prev: null,
    };
    newItem[pointer1] = insertBy[pointer1];
    newItem[pointer2] = insertBy;
    insertBy[pointer1][pointer2] = newItem;
    insertBy[pointer1] = newItem;

    return minFloat;
}

function placeJitterOnDirection(
    items: JitterData,
    fixedCoord: number,
    floatCoord: number,
    radius: number,
    jitter: number,
    margin: number,
    direction: 1 | -1
): {
    resultCoord: number;
    insertBy: JitterData;
    direction: 1 | -1;
} {
    // Check for overlap with previous items.
    let y = floatCoord;
    const pointer1 = direction > 0 ? 'next' : 'prev';
    let insertBy = items;
    let item = items[pointer1];

    while (item !== items) {
        const dx = fixedCoord - item.fixedCoord;
        const dy = y - item.floatCoord;
        const d2 = dx * dx + dy * dy;
        const r = radius + item.r + margin;
        if (d2 < r * r) {
            // Overlap. Try to move the new item along otherCoord direction.
            y = item.floatCoord + Math.sqrt(r * r - dx * dx) * direction;
            insertBy = item;

            if (Math.abs(y - floatCoord) > jitter / 2) {
                // If the new item is moved too far, then give up.
                // Fall back to random jitter.
                return {resultCoord: Number.MAX_VALUE, insertBy, direction};
            }
        }

        item = item[pointer1];
    }

    return {resultCoord: y, insertBy, direction};
}