Add auto text positioning for scatter traces

[chriddyp]

Fixed #4674

Overview written in my own words

I was making the graph below and running into the classic text overlap issues. This PR adds textposition: 'auto' to avoid text overlap.

Before:

After:

Intuitively, we try to find text position that:

1. Is one of the 8 possible directions (top, top-right, right, etc).
2. Prefers a direction that is "away" from points that are nearby (to give space for those points' text positions). This is the "repulsion vector".
3. If there aren't any nearby points, then defaults to top
4. If there isn't any room because of overlap, then it'll try to find a spot on the next "ring" outwards (ring is equal to "1 1 x fontSize")
5. It'll go in a circle around that ring, using same position algorithm as 2-4. If it's on a further ring, it'll draw a line connecting the text with the point (a "leader line")
6. Continue through 6 rings
7. If it can't find a spot, then it'll be hidden

For avoidance, it will avoid:

• Other marker text

It won't:

• Take into consideration other annotation text or other shapes. (This can overlap)
• Expand the axes ranges to "make room" for the annotation

This works very well for the example above.

It doesn't work as well for dense time series. In these cases, I can imagine that we should update the algorithm to focus on showing text for local minima and maxima first, rather than going in the order of the traces. I think we could do so in the future.

In that example, performance is about 1s slower than not displaying the text.

The positioning is also done on zooming and panning. Here's a video.
textposition-auto-zoom-pan.webm

---

Below is written with the use of AI

This PR adds support for textposition: 'auto' on scatter traces, enabling automatic placement of text labels without overlaps. When set to 'auto', labels are positioned around their points in a priority order, with leader lines drawn when labels are moved away from their markers due to space constraints.

• New module src/traces/scatter/auto_text_position.js: Implements the auto-positioning algorithm using a spatial index to detect overlaps and place labels efficiently. The algorithm:
  • Tries 8 candidate positions around each point in order of preference
  • Adds leader lines when labels must be moved farther out due to nearby markers or other labels
  • Hides labels that have no available space
  • Respects fixed-position labels and per-point textposition arrays

API Updates

• Updated src/traces/scatter/attributes.js to add 'auto' as a valid textposition value
• Updated src/traces/scatter3d/attributes.js, src/traces/quiver/attributes.js, src/traces/scattergeo/attributes.js, and src/traces/scattergl/attributes.js to exclude 'auto' from non-2D scatter variants (with comments explaining why)

Drawing & Positioning

• Modified src/components/drawing/index.js:
  • Added textPointBoxOffset() to compute label geometry from measured bounding boxes
  • Refactored textPointPosition() to support both fixed and auto-positioned labels
  • Added getTextPosition() helper to resolve 'auto' to computed positions
  • Added support for leader lines with configurable gap and clearance

Integration

• Updated src/traces/scatter/plot.js to call the auto-positioning algorithm after rendering all traces on a subplot
• Updated src/plot_api/helpers.js to preserve 'auto' in cleanTextPosition()

Tests & Examples

• Test suite in test/jasmine/tests/scatter_test.js covering:
  • Basic auto positioning with stacked markers
  • Isolated labels taking first candidate position
  • Leader lines in clusters
  • Text-only labels on points
  • Mixed fixed and auto positions
  • Repositioning after zoom/relayout
• Added test mock test/image/mocks/text_chart_autoposition.json with diverse label scenarios
• Added real-world example test/image/mocks/text_chart_autoposition_real.json (NIH funding data)

Technical Details

Setup, once per subplot, before any label moves:

Index every marker from every visible scatter trace on the subplot as an obstacle, plus every label that has a fixed (non-auto) position. Collect the auto labels in trace draw order, then data order within a trace.

Then, for each auto label in that order:

1. Bail if the point is off-plot. If the point's pixel coords fall outside the plot area, hide the label and stop. No candidates are tried.

2. Build the repulsion vector. Sum (dx/d², dy/d²) over every other point's marker within mrc + 3 × fontSize of this point, where d is the distance and the vector points away from each marker. Nearer markers contribute more. Only markers count, not other labels.

3. Score and sort all 8 positions once. Each position is a unit direction (top right = (1,-1)/√2, and so on). Score is the dot product with the repulsion vector. Sort descending, ties broken by the default preference order. If the repulsion vector came out zero, skip the sort and use the default order as-is, which starts at top center. This ordering is computed once and reused at every ring.

4. Ring 0: try each position touching the point, in that order. A candidate wins if its box stays inside the plot area, overlaps no marker, no already-placed label, and no already-placed leader line, and no foreign marker sits within one font size of the box. That last check is the one people miss: a spot can be geometrically free and still get rejected as too ambiguous to read.

5. No winner at ring 0, step out one font size and run the same list again. Now the label gets a leader line back to the marker edge, and the leader itself has to be clear of obstacles too. Keep stepping out one font size at a time, up to ring 6, re-running the full ordered list at each distance.

6. Nothing free at any ring: hide the label (display: none).

7. On a win, insert the box and its leader into the index, so this label becomes an obstacle for every label placed after it.

It's greedy and single-pass. No backtracking, no relaxation, no global optimization.

A point early in the data can permanently push a later point's label into hiding, and reordering your traces changes the output.

Labels are processed in trace and data order, so earlier points win contested positions.

Test Plan

Existing test suite passes. New tests verify:

• Labels don't overlap with markers or other labels
• Leader lines are added when labels move away from points
• Text-only labels can sit on their points
• Mixed fixed/auto positions work correctly
• Repositioning works after zoom/relayout operations

[camdecoster]

This is a great new feature! I have a few comments:

• I'd like to separate the placement engine from the trace so that it can be reused throughout the library. geometry2d.js seems like a good place to move things. Ideally, the API would be set up such that the algorithm could change under the hood and the traces wouldn't have to be updated.
• What do you think of allowing for pixel positioning rather than a set of predetermined positions? That could make the fit more flexible/compact.
• I'd argue that we should include a label importance/priority sort from the beginning. If you use a helper function to do this, we can tweak the logic as needed.
• What do you think of the label "popping" that occurs when you pan? It looks a little odd, but I don't have a good suggestion at the moment. It's probably fine to start from this point and iterate if necessary.

This should fix issue #4674. Could you add that in the description?

[chriddyp]

TYSM for the review! Addressed some of the concerns.

---

Zoom & Pan: Feeling pretty good to me now:

---

geometry2d.js

✅ Done

---

What do you think of allowing for pixel positioning rather than a set of predetermined positions? That could make the fit more flexible/compact.

One thing I'm keeping in mind in this design is trying to make the "visual interpretation" of the text feel consistent and easy to navigate.

I think that limiting the available directions to be 1/8 possible ones rather than an arbitrary angle, it can help a bit with this: if a text label is near two points, then users can get a hint that the text that is associated with the point is the one that has a "clean" angle (top, top-left, right, etc) rather than a "random" angle. It's sort of like how graphic design software will provide the "snap-to" mechanism.

So I think I'd like to keep the angle restricted. The distance of the vector could be more arbitrary, but I think there's enough granularity right now.

All to say, I'm pretty happy with the results so far, so I'm not too inclined to change the algorithm. I think doing arbitrary positioning instead of iteratively trying a series of positions would require a pretty different algorithm.

---

On another note, I found another case of non-ideal placement: The leader lines can cross the actual line chart

Fixing this one feels more complex, so I'm OK with punting on it and fixing in the future.

---

Speaking of fixing in the future, I'm thinking about adding a note to the attribute description that says something like "Auto placement uses an algorithm to find the correct placement. This algorithm is subject to change in future minor and patch versions."

Just so that we feel like we can improve the algorithm in the future without issuing a major version release.

---

I'd argue that we should include a label importance/priority sort from the beginning.

Done! textpriority.

Here's an example without it, notice the point I'm hovering over and it's neighbor doesn't have text:

And here it is with those points:

Another example without it (notice that not all peaks have labels):

And then with textpriority and the peaks have labels:

[chriddyp]

Quick explanation of this part: In my reference scatter plot, I noticed that the text was closer to the squares than the circles, because the circles' corners are folded in. In dense scatter plots with text, I find myself comparing the text to different points to try to understand which text is associated with which point, and this discrepancy of distance was throwing me off.

Circles are the default case, so that's handled. And then squares are the largest symbol from the corner, so that's the default otherwise for the rest of the symbols.

I recognize this is getting kind of hardcore, and would also be OK removing this logic as well.