Add scale to default Marker options

[adrianababakanian]

Motivation

Some developers may want to use the default Marker el (a light-blue, droplet-shaped SVG) as-is in terms of visual appearance, but with a modified size. As documented in the API reference here, there are currently no sizing-related options in the Marker's options parameter.

Design Alternatives

This example in the documentation shows how to add custom icons with markers by defining a DOM node for each GeoJSON feature (var el = document.createElement('div')), but it would be quite a bit of work to re-create the default marker just to modify its size. The fact that the marker is created with SVG components introduces an additional complication when left to the end-user, since scaling SVGs is not entirely intuitive (this reference explains the concept well, in my opinion).

Design

For consistency with how similar CSS terminology would affect the SVG marker added to the map, I recommend that we add scale to the options parameter rather than width or height. A scale is admittedly less flexible than being able to explicitly specify a width and height, but ultimately benefits the end user so that they don't have to strategize the dimensions to prevent distortion.

Demonstrating how scale is more intuitive than width or height for SVGs:

Mock-Up

/* Display a Marker at 2x the default size: width="27px", height="41px" */
var marker = new mapboxgl.Marker({
	scale: 2 // a number greater than or equal to zero
})

Concepts

As mentioned in the Design section, I think that scale is an appropriate terminology to be introduced to the Marker's options parameter.

Implementation

Minimal changes are required in the Mapbox GL ecosystem. /src/ui/marker.js is the most relevant file. A _scale: number class variable should be added, and the svg object representing the marker could be modified accordingly by:

svg.setAttributeNS(null, 'transform', `scale(${this._scale})`);

[stevage]

Just a comment that the terminology used in the symbol layer type is icon-size, which behaves exactly like a scale. You can't be consistent with the whole world but maybe it makes more sense to be internally consistent (within mapbox-gl) rather than externally consistent (with CSS)?

[adrianababakanian]

That's a great point @stevage , I'll consider switching from scale to size before merging the PR. Honestly, the scale terminology is more intuitive to me, but since icon-size is in fact

units in factor of the original icon size

from the style specification, the internal naming parity might be worth it.

[andrewtuplin]

I need a fixed-size icon that doesn't scale for zoom in/zoom out.
For example, if you imagine a map with a vehicle icon on it, when you zoom out, you probably don't want a vehicle that expands to the size of a city, you'd like to keep something that continues to occupy the same amount of space on the road.