Percent-based and ratio-constrained sprite scaling

[bcamper]

This PR adds two new features for setting the size of sprites on points-based features. Both are designed to eliminate significant boilerplate and hand-calculated code for specifying sprite sizes across zooms; this has particularly come to light with the addition of many new highway shields. This work is distinct from but builds on the recently added density parameter for textures.

Percent scaling

• It's often desirable to specify the size of a sprite as a percentage of its full size, especially to interpolate between zooms. A % qualifier now enables this when setting size:
  • size: 50%
• The percentage is applied to the sprite's size in CSS pixels, consistent with the density parameter for textures. For example:
  • A texture with actual pixel width of 64px and density: 2 has an intended CSS pixel display size of 32px.
  • A setting of size: 100% will display this sprite at 32px CSS pixels (e.g. 32px actual pixels on a 1x display, or 64px on a 2x retina display).
• Percent scaling can also be used with zoom interpolation, including mixing with explicit px sizing:
  • size: [[13, 50%]], [20, 100%]] # scale from 50% to 100% across a zoom range
  • size: [[13, 12px]], [20, 100%]] # scale from 12px square to 100% across a zoom range
• Percent scaling can accept values greater than 100%, e.g. size: 200% will scale the sprite to twice its native size.

Ratio-constrained scaling

• Previously, sprite sizes could be specified as a 1D value, e.g. size: 16px, which would set both the width and height to that value, or as a 2D value, e.g. size: [16px, 24px], which would set the width to 16px and the height to 24px.
• While 1D values are useful for simple colored points, they are often not applicable to sprites (unless the sprite has a square aspect ratio). Instead, if the user wants to scale a sprite to fit a specific width or height (for example, setting all highway shields to have a fixed height of 24px), they needed to manually calculate the corresponding width for each sprite (and specify this at each desired zoom as well).
• A new ratio-constrained scaling syntax allows the user to specify a size for the width OR height, with the unspecified dimension automatically calculated to preserve the sprite's aspect ratio. The syntax for this is to specify size as a 2D array, with the special auto value as one of the dimensions:
  • size: [32px, auto] # scale the sprite to 32px wide, with auto-calc height
  • size: [auto, 16px] # scale the sprite to 16px high, with auto-calc width
• Ratio-constrained scaling can also be used with zoom interpolation, including mixing with percent scaling:
  • size: [[15, [auto, 12px], [20, [auto, 20px]] # scale between two heights, with auto-calc width
  • size: [[13, [auto, 12px]], [20, 100%]] # scale from 12px high at z13, up to full size at z20
• Edge cases and error conditions:
  • Ratio-constrained and percent scaling can be combined in a single 2D value, but this is redundant, since the result is the same as simply scaling based on percent, e.g. size: [50%, auto] is the same as size: 50%.
  • Since it only makes sense to derive either width or height by aspect ratio, specifying both will log a warning and skip features in the layer, e.g. size: [auto, auto].
• Syntax note: the ?px value is a proposal. My original plan was to use a single ? character, but this is reserved YAML syntax, as are many similar candidates. Opted for auto based on PR discussion.

Sprite requirement

• Since both percent-based and ratio-constrained scaling only make sense in the context of a sprite (not a simple colored shader point), specifying these for layers without a texture and sprite defined will log a warning and skip features in the layer, e.g. these draw blocks (assuming no other inherited parameters) both generate warnings and draw nothing
  • draw: { points: { color: red, size: 50% } }
  • draw: { points: { color: red, size: [auto, 20px] } }

[bcamper]

TODO: I noticed that negative sprite sizes in Tangram JS currently flip the sprite upside-down and anchor it from the bottom left. We should clamp negative point size values (both for explicit px values and for %) to zero.

[bcamper]

cc @matteblair @nvkelso

[nvkelso]

Nice!

A new ratio-constrained scaling syntax allows the user to specify a size for the width OR height, with the unspecified dimension automatically calculated to preserve the sprite's aspect ratio. The syntax for this is to specify size as a 2D array, with the special ?px value as one of the dimensions: size: [32px, ?px] # scale the sprite to 32px wide, with auto-calc height size: [?px, 16px] # scale the sprite to 16px high, with auto-calc width Syntax note: the ?px value is a proposal. My original plan was to use a single ? character, but this is reserved YAML syntax, as are many similar candidates.

• Could we not specify anything instead of using a wildcard?
  • size: [32px,]
• Could we use * instead of ? as the wildcard? Probably more YAML collisions?
  • size: [32px, *px], or
  • size: [32px, *]

[meetar]

I've seen things like auto used here:

size: [32px, auto]

[matteblair]

These changes make sense to me, I can't think of any issues with implementing this in Tangram ES.

I was also going to suggest auto for the auto-constraint token. * or *px is interpreted as a YAML anchor, so we can't attach our own semantics to it. An empty value as in [32px,] or [,32px] could technically work (the empty value is interpreted as null) but to me that looks a lot like a typo.

[bcamper]

auto makes sense to me, I forgot that we already use that for point angle. I'll update the code and description.

I also considered * (YAML reserved) and a null value (but decided against it for the reasons cited above, I think something explicit is better and less error-prone).