Multi-directional hillshade illumination specification

[NathanMOlson]

A newly proposed (#1066) hillshade method, multidirectional, uses multiple illumination sources, each with its own direction and color. The existing illumination spec only supports a single value for direction, highlight color, and shadow color. To specify multiple illumination sources, we could extend the existing fields to accept a single value OR an array of values, or we could add new fields used only by the multidirectional method. Or we could move the illumination definition into a structure and have an array of structures, which would help keep the number of elements in each array the same.

The spec for the existing hillshade method would remain unchanged in all cases, and would look like this:

{
    id: 'hillshade',
    type: 'hillshade',
    source: 'terrainSource',
    paint: {
	'hillshade-method': 'standard',
        'hillshade-illumination-direction': 315,
        'hillshade-illumination-altitude': 45,
        'hillshade-shadow-color': '#000000',
        'hillshade-highlight-color': '#FFFFFF'
    }
}

Here's how the spec would look for the multidirectional method for each option:

Option 1:

{
    id: 'hillshade',
    type: 'hillshade',
    source: 'terrainSource',
    paint: {
	'hillshade-method': 'multidirectional',
        'hillshade-illumination-direction': [315 270],
        'hillshade-illumination-altitude': [45, 25],
        'hillshade-shadow-color': ['#000080', '#800000'],
        'hillshade-highlight-color': ['#FFFF80','#80FFFF']
    }
}

Option 2:

{
    id: 'hillshade',
    type: 'hillshade',
    source: 'terrainSource',
    paint: {
	'hillshade-method': 'multidirectional',
        'hillshade-multidirectional-illumination-directions': [315 270],
        'hillshade-multidirectional-illumination-altitudes': [45, 25],
        'hillshade-multidirectional-shadow-colors': ['#000080', '#800000'],
        'hillshade-multidirectional-highlight-colors': ['#FFFF80','#80FFFF']
    }
}

Option 3:

{
    id: 'hillshade',
    type: 'hillshade',
    source: 'terrainSource',
    paint: {
	'hillshade-method': 'multidirectional',
        'hillshade-illumination': [
	    {
		'illumination-direction': 315,
		'illumination-altitude': 45,
		'shadow-color': '#000080',
		'highlight-color': '#FFFF80'
	    },
	    {
		'illumination-direction': 315,
		'illumination-altitude': 45,
		'shadow-color': '#000080',
		'highlight-color': '#FFFF80'
	    }
        ]
    }
}

[larsmaxfield]

As a user Option 1 and Option 2 are not immediately predictable in how they would apply values and defaults. What happens if I give three directions but one altitude? Does it use that altitude for all three directions, or only for the first and use the default for the other two? Does an error occur if I then specify two shadow colors?

Option 3 would let me set three directions and one altitude to one of them, letting the defaults kick in for all other values.

[HarelM]

Also probably worth mentioning, that option 3 is less likely to facilitate style expressions due to how they are usually used.

[HarelM]

@louwers is using the same style spec property with different types a problem in native (like we did for padding)?

[louwers]

I think it is extra work but not necessarily a problem.