Differences in Symbol Sizing When Using GeoJSON Properties vs. Constants in Expressions

[albasitum]

Hello! I was experimenting with defining an approximated function that allows me to maintain a "constant" size for texts, icons, etc when zooming in/out. However somehow I am seeing different behaviours depending on if I extract values using properties on the GeoJSON compared to if I define the values using constants. Maybe I am missing something, but I think it should behave the same way no matter what the source is when evaluating expressions, as long as the values being evaluated are the same.

maplibre-gl-js version: 5.1.0

browser: Google Chrome Version 133.0.6943.53 (Official Build) (64-bit)

Link to Demonstration

https://codepen.io/albasitum/pen/QwWjYEy

[HarelM]

That's an interesting issue.
Thanks for taking the time to report this.
I guess there's a need to dig into the expression engine to understand why this is interpreted differently using these different expressions...
The evaluation is done in maplibre-style-spec repo, if you want to try and tackle this issue.

[cxcorp]

I created two test cases using maplibre-style-spec's expression integration test setup:

maplibre-style-spec/test/integration/expression/tests/interpolate/exponential-zoom-get-property/test.json:

{
  "expression": [
    "interpolate",
    ["exponential", 2],
    ["zoom"],
    12,
    ["*", 0.5, ["get", "scale"]],
    22,
    ["*", 175, ["get", "scale"]]
  ],
  "inputs": [
    [{ "zoom": 12 }, { "properties": { "scale": 5 } }],
    [{ "zoom": 15 }, { "properties": { "scale": 5 } }],
    [{ "zoom": 18 }, { "properties": { "scale": 5 } }],
    [{ "zoom": 20 }, { "properties": { "scale": 5 } }],
    [{ "zoom": 22 }, { "properties": { "scale": 5 } }]
  ],
  "expected": {
    "compiled": {
      "result": "success",
      "isFeatureConstant": false,
      "isZoomConstant": false,
      "type": "number"
    },
    "outputs": [
      2.5, 8.470185728250243, 56.2316715542522, 219.98533724340177, 875
    ]
  }
}

maplibre-style-spec/test/integration/expression/tests/interpolate/exponential-zoom-multiply-by-constant/test.json:

{
  "expression": [
    "interpolate",
    ["exponential", 2],
    ["zoom"],
    12,
    ["*", 0.5, 5],
    22,
    ["*", 175, 5]
  ],
  "inputs": [
    [{ "zoom": 12 }, { "properties": { "scale": 5 } }],
    [{ "zoom": 15 }, { "properties": { "scale": 5 } }],
    [{ "zoom": 18 }, { "properties": { "scale": 5 } }],
    [{ "zoom": 20 }, { "properties": { "scale": 5 } }],
    [{ "zoom": 22 }, { "properties": { "scale": 5 } }]
  ],
  "expected": {
    "compiled": {
      "result": "success",
      "isFeatureConstant": true,
      "isZoomConstant": false,
      "type": "number"
    },
    "outputs": [
      2.5, 8.470185728250243, 56.2316715542522, 219.98533724340177, 875
    ]
  }
}

Both tests passed, and as you can see, both have identical outputs. The biggest difference is that the former expression becomes a composite expression, whereas the latter becomes a camera expression.

The symbol layout seems to have separate behavior for interpolating the text size at render time composite expressions:

maplibre-gl-js/src/symbol/symbol_layout.ts

Lines 38 to 51 in b52cb12

	// The symbol layout process needs `text-size` evaluated at up to five different zoom levels, and
	// `icon-size` at up to three:
	//
	// 1. `text-size` at the zoom level of the bucket. Used to calculate a per-feature size for source `text-size`
	// expressions, and to calculate the box dimensions for icon-text-fit.
	// 2. `icon-size` at the zoom level of the bucket. Used to calculate a per-feature size for source `icon-size`
	// expressions.
	// 3. `text-size` and `icon-size` at the zoom level of the bucket, plus one. Used to calculate collision boxes.
	// 4. `text-size` at zoom level 18. Used for something line-symbol-placement-related.
	// 5. For composite `*-size` expressions: two zoom levels of curve stops that "cover" the zoom level of the
	// bucket. These go into a vertex buffer and are used by the shader to interpolate the size at render time.
	//
	// (1) and (2) are stored in `bucket.layers[0].layout`. The remainder are below.
	//

[cxcorp]

I think I have found the reason that the red layer (both zoom and feature dependent, thus composite expression) becomes smaller than the yellow layer (only zoom dependent, camera expression).

camera expression text size is interpolated in JS and the value is sent off to the shader as-is , whereas composite expression text sizes are interpolated in the shader. To do this, the min and max values are calculated along with the delta (0..1 for interpolating) and sent off to the shader. There seems to be some sort of encoding done for the min-max values: they are multiplied by SIZE_PACK_FACTOR = 128, and then in the shader after interpolating the value is divided by 128.0.

maplibre-gl-js/src/symbol/symbol_size.ts

Lines 8 to 10 in b52cb12

	const MAX_GLYPH_ICON_SIZE = 255;
	const SIZE_PACK_FACTOR = 128;
	const MAX_PACKED_SIZE = MAX_GLYPH_ICON_SIZE * SIZE_PACK_FACTOR;

maplibre-gl-js/src/symbol/symbol_layout.ts

Lines 462 to 470 in b52cb12

	textSizeData = [
	SIZE_PACK_FACTOR * sizes.compositeTextSizes[0].evaluate(feature, {}, canonical),
	SIZE_PACK_FACTOR * sizes.compositeTextSizes[1].evaluate(feature, {}, canonical)
	];
	if (textSizeData[0] > MAX_PACKED_SIZE || textSizeData[1] > MAX_PACKED_SIZE) {
	warnOnce(`${bucket.layerIds[0]}: Value for "text-size" is >= ${MAX_GLYPH_ICON_SIZE}. Reduce your "text-size".`);
	}
	}

maplibre-gl-js/src/shaders/symbol_sdf.vertex.glsl

Lines 62 to 68 in b52cb12

	if (!u_is_size_zoom_constant && !u_is_size_feature_constant) {
	size = mix(a_size_min, a_size[1], u_size_t) / 128.0;
	} else if (u_is_size_zoom_constant && !u_is_size_feature_constant) {
	size = a_size_min / 128.0;
	} else {
	size = u_size;
	}

However, as clued by the warning printed in the console in the example code:

scaled-symbol-layer: Value for "text-size" is >= 255. Reduce your "text-size".

the "max value" gets clamped to MAX_PACKED_SIZE (128 * 255):

maplibre-gl-js/src/data/bucket/symbol_bucket.ts

Lines 125 to 143 in b52cb12

	const aSizeX = sizeVertex ? Math.min(MAX_PACKED_SIZE, Math.round(sizeVertex[0])) : 0;
	const aSizeY = sizeVertex ? Math.min(MAX_PACKED_SIZE, Math.round(sizeVertex[1])) : 0;
	array.emplaceBack(
	// a_pos_offset
	anchorX,
	anchorY,
	Math.round(ox * 32),
	Math.round(oy * 32),
	// a_data
	tx, // x coordinate of symbol on glyph atlas texture
	ty, // y coordinate of symbol on glyph atlas texture
	(aSizeX << 1) + (isSDF ? 1 : 0),
	aSizeY,
	pixelOffsetX * 16,
	pixelOffsetY * 16,
	minFontScaleX * 256,
	minFontScaleY * 256
	);

so effectively the clamping changes the "max" of the interpolation for the red layer from 5*175=875 to 255, and the size gets interpolated in the shader with the wrong "max", instead of interpolating with the correct "max" value and then just clamping the size when it reaches a specific size.

I don't really know where the bug is or if there even is a bug. Is it correct that the other one is a composite expression whereas the other is a camera expression? Is it correct that the max gets clamped to 255 instead of the effective value? Does the interpolation even need to be done on the shader? Why does MAX_GLYPH_ICON_SIZE exist, and could the pack factor be increased? Is the packing even needed?

So many questions, sorry. I think this is as much as I can help.

[HarelM]

These are great questions and a great analysis.
I'm guessing the answer to these questions can be found in the history (probably on the mapbox repo as this was never changed here).
I'm guessing the warning in the console is a way to let the developer know this is a limitation of this library, and I'm guessing this was done crude bug fix...

[cxcorp]

Dug around some more context from the mapbox repo for this. No answers or recommendations in this reply unfortunately.

There is an issue in their repo from 2018 which matches this issue: mapbox/mapbox-gl-js#7563

mapbox/mapbox-gl-js#7163 mentions the limitation that this issue runs into:

Basically, even though it's logically sound, the way we do composite zoom expression evaluation just can't handle very large or very small values.
mapbox/mapbox-gl-js#7163 (comment)

About the need for integer packing the floats into uint16s (which is what the PACKING_FACTOR apparently is for):

You're right that we do have to economize on the number of attributes we upload, but in this case the choice to go with 16-bit ints is to reduce the size of the buffers we upload (and thus increase rendering speed). We would use 16-bit floats if we had them on all platforms, but IIRC we can't count on them.
mapbox/mapbox-gl-js#7163 (comment)

These issues had a closed pull request where something related to the issues was implemented, but I did not look due to the license threat. It was from January 2020 though which if I understood correctly was before the license change and thus maybe still 3-BSD licensed and okay to peek at?

Finally, there is a still-open issue from 2020 tracking the limitation on text-size: mapbox/mapbox-gl-js#9857 However, there is no specific mention of composite expressions there.

As for the packing code itself, I think that has been there since support was added for property functions in text-size (2017): mapbox/mapbox-gl-js#4228, mapbox/mapbox-gl-js#4455, although originally the packing factor was 10.

Then it was changed to 256 in 2018 in mapbox/mapbox-gl-js#7125, supporting text-sizes values between 0-256 with precision 1/256. That was then changed to 128 when "images in labels" was implemented in 2019: mapbox/mapbox-gl-js#8904

[HarelM]

The fork was at December 2020, so I think the PR (and probably also the fact that it's closed and wasn't merged) is a fair game.
I believe performance might have been a consideration here, but I tend to think that devices are stronger now and removing this 128 limitation might be OK.
IDK...