Hillshade new types (#1088)

* add hillshade-method

* add illumination altitude and basic method

* start of adding color-array and number-array types

* add NumberArray and ColorArray types

* lint

* code coverage

* fix docs

* Switch number-array and color-array to camelCase to match other types.
Provide an example of a field requiring backwards compatibility.

* throw error if attempting to interpolate between arrays with mismatched lengths

* lint

* update sdk-support

* update Changelog

* unit test stylistic changes

* improve variable names

* add "additional methods" line to hillshade sdk-support table.

* add numberArray and colorArray function unit tests

* add unit tests

* add unit tests

* remove unit tests that fail typecheck

* add values tests

* add identity funciton unit tests

* add parsing tests for numberArray and ColorArray

* add padding parsing unit test

* normalizePropertyExpression unit tests

* Add normalizePropertyExpression tests for constants. Fix isFunction()

* add unit tests for normalizePropertyExpression

* change if/else to switch/case

* improve test naming and organization

* update hillshade documentation wording

* fix docs wording

* refactoring

* improve(?) readability of coercion logic.

* Provide more details for hillshade methods

* add image showing examples of each hillshade method

Author: NathanMOlson

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### ✨ Features and improvements
 - `glyphs` is now optional even if a symbol layer specifies `text-field`; if it is unset, `text-font` is interpreted as a fallback font list ([#1068](https://github.com/maplibre/maplibre-style-spec/pull/1068))
+- `hillshade` layer now supports multiple methods, and the `multidirectional` method supports array values for illumination properties ([#1088](https://github.com/maplibre/maplibre-style-spec/pull/1088))
 
 ### 🐞 Bug fixes
 - Fix RuntimeError class, make it inherited from Error ([#983](https://github.com/maplibre/maplibre-style-spec/issues/983))

build/generate-docs.ts

@@ -175,6 +175,8 @@ function typeToMarkdownLink(type: string): string {
         case 'formatted':
         case 'resolvedimage':
         case 'padding':
+        case 'numberarray':
+        case 'colorarray':
             return ` [${type}](types.md#${type.toLocaleLowerCase()})`;
         case 'filter':
             return ` [${type}](expressions.md)`;
@@ -214,7 +216,11 @@ function convertPropertyToMarkdown(key: string, value: JsonObject, keyPrefix = '
     }
 
     if (value.minimum !== undefined || value.maximum !== undefined) {
-        markdown += ` in range ${formatRange(value.minimum, value.maximum)}`;
+        if (value.type === 'numberArray') {
+            markdown += ` with value(s) in range ${formatRange(value.minimum, value.maximum)}`;
+        } else {
+            markdown += ` in range ${formatRange(value.minimum, value.maximum)}`;
+        }
     }
 
     markdown += '. ';

build/generate-style-spec.ts

@@ -39,6 +39,10 @@ function propertyType(property) {
                 return '{[_: string]: SourceSpecification}';
             case 'projection:':
                 return 'ProjectionSpecification';
+            case 'numberArray':
+                return 'NumberArraySpecification';
+            case 'colorArray':
+                return 'ColorArraySpecification';
             case '*':
                 return 'unknown';
             default:
@@ -127,6 +131,8 @@ export type ProjectionDefinitionT = [string, string, number];
 export type ProjectionDefinitionSpecification = string | ProjectionDefinitionT | PropertyValueSpecification<ProjectionDefinitionT>
 
 export type PaddingSpecification = number | number[];
+export type NumberArraySpecification = number | number[];
+export type ColorArraySpecification = string | string[];
 
 export type VariableAnchorOffsetCollectionSpecification = Array<string | [number, number]>;
 

docs/assets/hillshade_methods.png

@@ -206,3 +206,26 @@ There are also additional presets that yield commonly used expressions:
 | Preset | Full value | Description |
 |--------|------------|-------------|
 | `globe` | `["interpolate", ["linear"], ["zoom"],`<br>`10, "vertical-perspective", 12, "mercator"]` | Adaptive globe: interpolates from vertical-perspective to mercator projection between zoom levels 10 and 12. |
+
+
+## `numberArray`
+
+A single number value, or an array of number values.
+
+```json
+{
+    "hillshade-illumination-direction": 24,
+    "hillshade-illumination-direction": [45, 57.3]
+}
+```
+
+## `colorArray`
+
+A single color value, or an array of color values.
+
+```json
+{
+    "hillshade-highlight-color": "#ffff00",
+    "hillshade-highlight-color": ["#ffff00", "rgb(255, 255, 0)", "yellow"]
+}
+```

docs/types.md

@@ -5,6 +5,8 @@ import {Formatted} from '../types/formatted';
 import {ResolvedImage} from '../types/resolved_image';
 import {Color} from '../types/color';
 import {Padding} from '../types/padding';
+import {NumberArray} from '../types/number_array';
+import {ColorArray} from '../types/color_array';
 import {VariableAnchorOffsetCollection} from '../types/variable_anchor_offset_collection';
 
 import type {Expression} from '../expression';
@@ -97,6 +99,30 @@ export class Coercion implements Expression {
                 }
                 throw new RuntimeError(`Could not parse padding from value '${typeof input === 'string' ? input : JSON.stringify(input)}'`);
             }
+            case 'numberArray': {
+                let input;
+                for (const arg of this.args) {
+                    input = arg.evaluate(ctx);
+
+                    const val = NumberArray.parse(input);
+                    if (val) {
+                        return val;
+                    }
+                }
+                throw new RuntimeError(`Could not parse numberArray from value '${typeof input === 'string' ? input : JSON.stringify(input)}'`);
+            }
+            case 'colorArray': {
+                let input;
+                for (const arg of this.args) {
+                    input = arg.evaluate(ctx);
+
+                    const val = ColorArray.parse(input);
+                    if (val) {
+                        return val;
+                    }
+                }
+                throw new RuntimeError(`Could not parse colorArray from value '${typeof input === 'string' ? input : JSON.stringify(input)}'`);
+            }
             case 'variableAnchorOffsetCollection': {
                 let input;
                 for (const arg of this.args) {

src/expression/definitions/coercion.ts

@@ -1,10 +1,12 @@
 import UnitBezier from '@mapbox/unitbezier';
 
-import {array, ArrayType, ColorType, ColorTypeT, NumberType, NumberTypeT, PaddingType, PaddingTypeT, VariableAnchorOffsetCollectionType, VariableAnchorOffsetCollectionTypeT, typeToString, verifyType, ProjectionDefinitionType} from '../types';
+import {array, ArrayType, ColorType, ColorTypeT, NumberType, NumberTypeT, PaddingType, PaddingTypeT, NumberArrayTypeT, ColorArrayTypeT, VariableAnchorOffsetCollectionType, VariableAnchorOffsetCollectionTypeT, typeToString, verifyType, ProjectionDefinitionType, ColorArrayType, NumberArrayType} from '../types';
 import {findStopLessThanOrEqualTo} from '../stops';
 import {Color} from '../types/color';
 import {interpolateArray, interpolateNumber} from '../../util/interpolate-primitives';
 import {Padding} from '../types/padding';
+import {ColorArray} from '../types/color_array';
+import {NumberArray} from '../types/number_array';
 import {VariableAnchorOffsetCollection} from '../types/variable_anchor_offset_collection';
 import {ProjectionDefinition} from '../types/projection_definition';
 
@@ -23,7 +25,7 @@ export type InterpolationType = {
     name: 'cubic-bezier';
     controlPoints: [number, number, number, number];
 };
-type InterpolatedValueType = NumberTypeT | ColorTypeT | ProjectionDefinitionTypeT | PaddingTypeT | VariableAnchorOffsetCollectionTypeT | ArrayType<NumberTypeT>;
+type InterpolatedValueType = NumberTypeT | ColorTypeT | ProjectionDefinitionTypeT | PaddingTypeT | NumberArrayTypeT | ColorArrayTypeT | VariableAnchorOffsetCollectionTypeT | ArrayType<NumberTypeT>;
 export class Interpolate implements Expression {
     type: InterpolatedValueType;
 
@@ -109,7 +111,7 @@ export class Interpolate implements Expression {
         const stops: Stops = [];
 
         let outputType: Type = null;
-        if (operator === 'interpolate-hcl' || operator === 'interpolate-lab') {
+        if ((operator === 'interpolate-hcl' || operator === 'interpolate-lab') && context.expectedType != ColorArrayType) {
             outputType = ColorType;
         } else if (context.expectedType && context.expectedType.kind !== 'value') {
             outputType = context.expectedType;
@@ -139,6 +141,8 @@ export class Interpolate implements Expression {
             !verifyType(outputType, ProjectionDefinitionType) &&
             !verifyType(outputType, ColorType) &&
             !verifyType(outputType, PaddingType) &&
+            !verifyType(outputType, NumberArrayType) &&
+            !verifyType(outputType, ColorArrayType) &&
             !verifyType(outputType, VariableAnchorOffsetCollectionType) &&
             !verifyType(outputType, array(NumberType))
         ) {
@@ -183,6 +187,10 @@ export class Interpolate implements Expression {
                         return Color.interpolate(outputLower, outputUpper, t);
                     case 'padding':
                         return Padding.interpolate(outputLower, outputUpper, t);
+                    case 'colorArray':
+                        return ColorArray.interpolate(outputLower, outputUpper, t);
+                    case 'numberArray':
+                        return NumberArray.interpolate(outputLower, outputUpper, t);
                     case 'variableAnchorOffsetCollection':
                         return VariableAnchorOffsetCollection.interpolate(outputLower, outputUpper, t);
                     case 'array':
@@ -191,9 +199,19 @@ export class Interpolate implements Expression {
                         return ProjectionDefinition.interpolate(outputLower, outputUpper, t);
                 }
             case 'interpolate-hcl':
-                return Color.interpolate(outputLower, outputUpper, t, 'hcl');
+                switch (this.type.kind) {
+                    case 'color':
+                        return Color.interpolate(outputLower, outputUpper, t, 'hcl');
+                    case 'colorArray':
+                        return ColorArray.interpolate(outputLower, outputUpper, t, 'hcl');
+                }
             case 'interpolate-lab':
-                return Color.interpolate(outputLower, outputUpper, t, 'lab');
+                switch (this.type.kind) {
+                    case 'color':
+                        return Color.interpolate(outputLower, outputUpper, t, 'lab');
+                    case 'colorArray':
+                        return ColorArray.interpolate(outputLower, outputUpper, t, 'lab');
+                }
         }
     }
 
@@ -261,6 +279,8 @@ export const interpolateFactory = {
     color: Color.interpolate,
     number: interpolateNumber,
     padding: Padding.interpolate,
+    numberArray: NumberArray.interpolate,
+    colorArray: ColorArray.interpolate,
     variableAnchorOffsetCollection: VariableAnchorOffsetCollection.interpolate,
     array: interpolateArray
 }

src/expression/definitions/interpolate.ts

@@ -1,10 +1,11 @@
 import {createPropertyExpression, Feature, GlobalProperties, StylePropertyExpression} from '../expression';
 import {expressions} from './definitions';
 import v8 from '../reference/v8.json' with {type: 'json'};
-import {createExpression, ICanonicalTileID, StyleExpression, StylePropertySpecification} from '..';
+import {Color, createExpression, ICanonicalTileID, StyleExpression, StylePropertySpecification} from '..';
 import {ExpressionParsingError} from './parsing_error';
 import {getGeometry} from '../../test/lib/geometry';
 import {VariableAnchorOffsetCollection} from './types/variable_anchor_offset_collection';
+import {expectToMatchColor} from '../../test/lib/util';
 
 // filter out internal "error" and "filter-*" expressions from definition list
 const filterExpressionRegex = /filter-/;
@@ -668,4 +669,90 @@ describe('projection expression', () => {
         }
     })
 
+    test('interpolate numberArray', () => {
+        const response = createExpression(['interpolate', ['linear'], ['zoom'], 8, ['literal', [2,3]], 10, ['literal', [4,5]]],  {
+            type: 'numberArray',
+            'property-type': 'data-constant',
+            expression: {
+                interpolated: true,
+                parameters: ['zoom']
+            },
+            transition: false
+        });
+
+        if (response.result === 'success') {
+            expect(response.value.evaluate({zoom: 8}).values).toEqual([2,3]);
+            expect(response.value.evaluate({zoom: 9}).values).toEqual([3,4]);
+            expect(response.value.evaluate({zoom: 10}).values).toEqual([4,5]);
+        } else {
+            throw new Error('Failed to parse Interpolate expression');
+        }
+    })
+
+    test('interpolate ColorArray', () => {
+        const response = createExpression(['interpolate', ['linear'], ['zoom'], 8, ['literal', ['white','black']], 10, ['literal', ['black','white']]],  {
+            type: 'colorArray',
+            'property-type': 'data-constant',
+            expression: {
+                interpolated: true,
+                parameters: ['zoom']
+            },
+            transition: false
+        });
+
+        if (response.result === 'success') {
+            expect(response.value.evaluate({zoom: 8}).values).toEqual([Color.parse('white'), Color.parse('black')]);
+            expect(response.value.evaluate({zoom: 9}).values).toEqual([new Color(0.5, 0.5, 0.5), new Color(0.5, 0.5, 0.5)]);
+            expect(response.value.evaluate({zoom: 10}).values).toEqual([Color.parse('black'), Color.parse('white')]);
+        } else {
+            throw new Error('Failed to parse Interpolate expression');
+        }
+    })
+
+    test('interpolate-hcl ColorArray', () => {
+        const response = createExpression(['interpolate-hcl', ['linear'], ['zoom'], 8, ['literal', ['white','black']], 10, ['literal', ['black','white']]],  {
+            type: 'colorArray',
+            'property-type': 'data-constant',
+            expression: {
+                interpolated: true,
+                parameters: ['zoom']
+            },
+            transition: false
+        });
+
+        if (response.result === 'success') {
+            expect(response.value.evaluate({zoom: 8}).values).toEqual([Color.parse('white'), Color.parse('black')]);
+            expect(response.value.evaluate({zoom: 9}).values).toHaveLength(2);
+            for (let i = 0; i < 2; i++) {
+                expectToMatchColor(response.value.evaluate({zoom: 9}).values[i], 'rgb(46.63266% 46.63266% 46.63266% / 1)');
+            }
+            expect(response.value.evaluate({zoom: 10}).values).toEqual([Color.parse('black'), Color.parse('white')]);
+        } else {
+            throw new Error('Failed to parse Interpolate expression');
+        }
+    })
+
+    test('interpolate-lab ColorArray', () => {
+        const response = createExpression(['interpolate-lab', ['linear'], ['zoom'], 8, ['literal', ['white','black']], 10, ['literal', ['black','white']]],  {
+            type: 'colorArray',
+            'property-type': 'data-constant',
+            expression: {
+                interpolated: true,
+                parameters: ['zoom']
+            },
+            transition: false
+        });
+
+        if (response.result === 'success') {
+            expect(response.value.evaluate({zoom: 8}).values).toEqual([Color.parse('white'), Color.parse('black')]);
+            expect(response.value.evaluate({zoom: 9}).values).toHaveLength(2);
+            for (let i = 0; i < 2; i++) {
+                expectToMatchColor(response.value.evaluate({zoom: 9}).values[i], 'rgb(46.63266% 46.63266% 46.63266% / 1)');
+            }
+            expect(response.value.evaluate({zoom: 10}).values).toEqual([Color.parse('black'), Color.parse('white')]);
+        } else {
+            throw new Error('Failed to parse Interpolate expression');
+        }
+    })
+
 });