Add "circle-stroke-*" style properties

[lucaswoj]

We should support outlines on circles.

Our "outline"-like styles are inconsistent. On fills we only support 1px outlines. On symbols we support arbitrary width "halos" (which can also be blurred).

Ideally, we would support all of the following properties for circle outlines:

• circle-stroke-color
• circle-stroke-width
• circle-stroke-opacity
• circle-stroke-blur

ref mapbox/mapbox-gl-js#1713

cc @bhousel @vicapow

[incanus]

Refs #223 with some backstory in mapbox/mapbox-gl-native#1737 & mapbox/mapbox-gl-native#1734.

[vicapow]

cc @baileyid

[lucaswoj]

What is a stroke in GL?

• we have a fill-outline-* property (only 1px wide)
  • in the documentation we refer to this property as providing a " 1px stroke"
• we have a icon-halo-* property (arbitrary width)
• we have a text-halo-* property (arbitrary width)
• we define "line" layers as "A stroked line"

I'm not sure what to call this feature in the context of circles. The TWC team and @samanpwbb feel that "stroke" is the most conventional term. The existing GL terminology might suggest "halo" is the most idiomatic within the context of the GL ecosystem.

What should we call this feature? How can we make our terminology consistent across the platform?

cc @samanpwbb @jfirebaugh @tmcw @danswick @lyzidiamond @1ec5

[1ec5]

Hypothesis: The term "stroke", "outline", "border", or "casing" usually arises in an API because the expected use case is thin and darker than the fill. The term "halo" or "glow" arises because the expected use case is thick, lighter than the fill, and possibly translucent.

[1ec5]

What would the corresponding SVG/CSS properties be?

[lucaswoj]

Good question @1ec5. Here's my best attempt at sussing out the terminology used in common specifications & software:

Related SVG Terminology

• stroke: used for lines, text, and elements

Related CSS Terminology

• text-stroke: used for text
• border: used for elements

Related Photoshop Terminology

• stroke: used for all objects

Related Illustrator Terminology

• stroke: used for all objects

Related Inkscape Terminology

• stroke: used for all objects

[lucaswoj]

Another fun data set:

• "text stroke" -> 390,000 google results
• "text outline" -> 168,000 google results
• "text border" -> 75,400 google results
• "text halo" -> 7,330 google results
• "text casing" -> 6,140 google results

[benjamin-hull]

My own experience doesn't match your hypothesis, @1ec5 - I don't think 'stroke' carries connotations of colour, thickness or opacity. 'Glow', to me, would indicate that the effect might 'fall off' (be fuzzy). I would expect a stroke to be either solid or patterned (dotted, dashed, etc).

SVG's stroke properties (from here: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke) are:

• stroke (actually defines the color, confusingly)
• stroke-dasharray
• stroke-dashoffset
• stroke-linecap
• stroke-linejoin
• stroke-miterlimit
• stroke-opacity
• stroke-width

[1ec5]

Thanks @beejamin, clearly you’ve thought about this more than I have. 😉

The reason I bring up SVG and CSS is that all the geometries in question, even text, are considered to be stroked and filled in SVG (and CSS as used in SVG). Having authored SVG frequently in the past, I always think of “stroke” as the antonym of “fill”. It’s an elegant model, and we can always supplement the “stroke” terminology by mentioning synonyms like “outline” and “halo” in documentation.

The one I’m not quite as sure about is circle-stroke-blur. In SVG+CSS and CSS+HTML, a blur is applied to a shadow or an entire element, not a stroke or outline specifically. A shadow would be considered a separate visual element that either circumscribes the stroke (if outset) or inscribes it (if inset).

[jplante]

We are hoping to support:

• opacity
• color
• width
• pattern (dash array or similar)

[lucaswoj]

Implementing circle-stroke-dasharray is too big a lift to make it into our initial implementation. I've opened #607 to track this feature request.

[jfirebaugh]

Implemented in #579.