Add new style property / update text-offset to better support variable anchor placement?

[drwestco]

text-offset and text-radial-offset both seem tailored to placement of labels around a center-anchored icon. For pushpins, teardrops, or other asymmetrical icons, I don't see style syntax to distribute labels evenly around the icon's perimeter.

e.g., if the desired label placements for all eight variable-anchor positions are as follows, what's the best way to indicate this through the symbol layer style? The stop sign icon is anchored at the bottom, so the desired text-offset for 'left' vs 'bottom-left' would have a different y value.

Assuming I'm correct the current style schema doesn't support this, what would a new or modified style property look like? We could be completely explicit and have something like an offset per text anchor, but maybe there's a more elegant solution?

'text-anchor-offset': {
  'top': [x1, y1],       // [x1, y1] is used when the 'top' value is picked from 'text-variable-anchor'
  'top-left': [x2, y2],  // [x2, y2] is used when the 'top-left' value is picked from 'text-variable-anchor'
 ...
} 

[HarelM]

I'm not sure I'm following. Can you give an example of something that you currently can't do? Something very specific.
The above description is a bit too vague for me...

[HarelM]

Is this the same as here mapbox/mapbox-gl-js#8598?

[drwestco]

That issue touches on it, but doesn't completely address it. The discussion + solution (text-radial-offset and two-element text-offset) still assumes a symmetric icon, centered over its anchor. It fails to address teardrop-style icons with the icon anchor at the tip.

[HarelM]

I can't say I fully understand all the bit and bytes here unfortunately.
I'm not sure what was merged in the PR linked in the issue above as it talks about a rectangle you can provide instead of radial offset (?), along with adding a text-offset to move the rectangle upwards so that it wraps the icon in a symetrical way, this should solve your issue, wouldn't it?
I'm just not sure what was merged and how to use it.

[drwestco]

From what I can tell with the discussion, they're describing how text-variable-anchor, text-radial-offset and text-offset work together. This is the same in MapBox and MapLibre. You don't get to specify a rectangle - there's an implicit rectangle defined by the x/y values from text-offset. The rectangle is still centered on the point geometry. There's currently no syntax (that I know of) to shift that rectangle to account for an asymmetric icon.

[HarelM]

Can you draw the rectangle made by the 3 properties? Or link to an example with debug frame stuff turned on? I'm sorry I keep pulling you back, I just want to better understand all this...

[drwestco]

Example using "text-radial-offset": 1. The nearest edge of the text is placed 1em from the anchor point (center of icon).

Example using "text-offset": [4, 1]. When the left or right anchor position is chosen, the nearest edge of the text is placed 4em from the anchor point. When top or bottom is chosen, the nearest edge is placed 1em from the anchor point.

It seems like you can then use icon-offset to shift the icon and text-translate to shift the text to match. But as the latter is a paint property, collisions aren't properly considered. Text for 'District Drum Tribe' overlaps icon for 'Motown Memories'.

[drwestco]

Yes, updating existing styles would be preferable, if possible. Thus the discussion instead of a PR. :-)

I don't think text-translate helps, by design. Paint properties explicitly don't factor into collisions.

[HarelM]

If anything, text-offset is the most unintuitive for me, the two numbers representing different offset according to position is "not readable".
But everything in the style spec is arrays, so if we introduce a new "type of array" (or array with more numbers) to text-offset we can facilitate for this request, can't we?

[drwestco]

Yeah, extending text-offset should do. It's just a matter of what the new syntax looks like. It could be an array of x/y pairs, one for each entry in text-variable-anchor; it could be a structured map like my original example; something else?

[HarelM]

I don't think the style spec supports structured maps, only "weird" arrays.
Since I don't like the mixed string and number arrays I would vote for array of two numbers array, and depending on the size (like in css border etc) act accordingly.

[drwestco]

Sounds reasonable. I'll write up my proposed changes for text-offset as a new thread in this discussion.

[drwestco]

Point

A point is a two-element array of numbers, representing an [x, y] coordinate pair. Units and other interpretation of the x/y values depend on where and how the point type is used.

text-offset

Layout property. Optional point or array of points. Units in ems. Defaults to [0,0]. Requires text-field. Disabled by text-radial-offset. Supports interpolate expressions.

Offset distance of text from its anchor. Positive values indicate right and down, while negative values indicate left and up.

If used with text-variable-anchor, a single point used for text-offset will be taken as absolute values. Offsets along the x- and y-axis will be applied automatically based on the anchor position.

If an array of points is provided for text-offset, the number of points should match the number of entries provided via text-variable-anchor. Each point in the array is used as the offset distance of text from its anchor, when the corresponding anchor is used by the renderer. If more entries are provided for text-variable-anchor than text-offset, the last value in text-offset will be used.

Example

{
    "text-offset": [[0, 4], [3, 0]],
    "text-variable-anchor": ["top", "left"]
}

When the renderer chooses the top anchor, [0, 4] will be used for text-offset; the text will be shifted down by 4 ems. When the renderer chooses the left anchor, [3, 0] will be used for text-offset; the text will be shifted right by 3 ems.

[HarelM]

This looks great! Thanks for putting this into words.
A thought that crossed my mind after reading this - if the renderer chooses a location, but then sees that the offset causes symbol collision, what is the expected behavior?

[drwestco]

It's described in the docs for text-variable-anchor:

To increase the chance of placing high-priority labels on the map, you can provide an array of text-anchor locations: the renderer will attempt to place the label at each location, in order, before moving onto the next label.

"location" here means anchor + text-offset.

[drwestco]

This also ties into the Style Validation conversation. We really need some way to represent properties with alternative type signatures.