Unverified Commit 9a8989a2 authored by Torben Barsballe's avatar Torben Barsballe Committed by GitHub
Browse files

Merge pull request #3337 from tbarsballe/mbexpressions-doc

Mapbox Styles expressions documentation
parents 5003db5a 825fb310
......@@ -93,8 +93,123 @@ MapBox Types
"line-dasharray": [2, 4]
}
Expressions
^^^^^^^^^^^
The value for any layout property, paint property, or filter may be specified as an expression. An expression defines a formula for computing the value of the property using the operators described below. The set of expression operators provided by Mapbox GL includes:
- Mathematical operators for performing arithmetic and other operations on numeric values
- Logical operators for manipulating boolean values and making conditional decisions
- String operators for manipulating strings
- Data operators, providing access to the properties of source features
- Camera operators, providing access to the parameters defining the current map view
Expressions are represented as JSON arrays. The first element of an expression array is a string naming the expression operator, e.g. ``"*"`` or ``"case"``. Subsequent elements (if any) are the arguments to the expression. Each argument is either a literal value (a string, number, boolean, or null), or another expression array.
[expression_name, argument_0, argument_1, ...]
**Data expressions**
A *data expression* is any expression that access feature data -- that is, any expression that uses one of the data operators: ``get``, ``has``, ``id``, ``geometry-type``, ``properties``, or ``feature-state``. Data expressions allow a feature's properties or state to determine its appearance. They can be used to differentiate features within the same layer and to create data visualizations.
::
{
"circle-color": [
"rgb",
// red is higher when feature.properties.temperature is higher
["get", "temperature"],
// green is always zero
0,
// blue is higher when feature.properties.temperature is lower
["-", 100, ["get", "temperature"]]
]
}
This example uses the ``get`` operator to obtain the temperature value of each feature. That value is used to compute arguments to the ``rgb`` operator, defining a color in terms of its red, green, and blue components.
Data expressions are allowed as the value of the ``filter`` property, and as values for most paint and layout properties. However, some paint and layout properties do not yet support data expressions. The level of support is indicated by the "data-driven styling" row of the "SDK Support" table for each property. Data expressions with the ``feature-state`` operator are allowed only on paint properties.
**Camera expressions**
A *camera expression* is any expression that uses the ``zoom operator``. Such expressions allow the the appearance of a layer to change with the map's zoom level. Camera expressions can be used to create the appearance of depth and to control data density.
::
{
"circle-radius": [
"interpolate", ["linear"], ["zoom"],
// zoom is 5 (or less) -> circle radius will be 1px
5, 1,
// zoom is 10 (or greater) -> circle radius will be 5px
10, 5
]
}
This example uses the ``interpolate`` operator to define a linear relationship between zoom level and circle size using a set of input-output pairs. In this case, the expression indicates that the circle radius should be 1 pixel when the zoom level is 5 or below, and 5 pixels when the zoom is 10 or above. In between, the radius will be linearly interpolated between 1 and 5 pixels
Camera expressions are allowed anywhere an expression may be used. However, when a camera expression used as the value of a layout or paint property, it must be in one of the following forms::
[ "interpolate", interpolation, ["zoom"], ... ]
Or::
[ "step", ["zoom"], ... ]
Or::
[
"let",
... variable bindings...,
[ "interpolate", interpolation, ["zoom"], ... ]
]
Or::
[
"let",
... variable bindings...,
[ "step", ["zoom"], ... ]
]
That is, in layout or paint properties, ``["zoom"]`` may appear only as the input to an outer ``interpolate`` or ``step`` expression, or such an expression within a ``let`` expression.
There is an important difference between layout and paint properties in the timing of camera expression evaluation. Paint property camera expressions are re-evaluated whenever the zoom level changes, even fractionally. For example, a paint property camera expression will be re-evaluated continuously as the map moves between zoom levels 4.1 and 4.6. On the other hand, a layout property camera expression is evaluated only at integer zoom levels. It will not be re-evaluated as the zoom changes from 4.1 to 4.6 -- only if it goes above 5 or below 4.
**Composition**
A single expression may use a mix of data operators, camera operators, and other operators. Such composite expressions allows a layer's appearance to be determined by a combination of the zoom level and individual feature properties.
::
{
"circle-radius": [
"interpolate", ["linear"], ["zoom"],
// when zoom is 0, set each feature's circle radius to the value of its "rating" property
0, ["get", "rating"],
// when zoom is 10, set each feature's circle radius to four times the value of its "rating" property
10, ["*", 4, ["get", "rating"]]
]
}
An expression that uses both data and camera operators is considered both a data expression and a camera expression, and must adhere to the restrictions described above for both.
**Type system**
The input arguments to expressions, and their result values, use the same set of types as the rest of the style specification: boolean, string, number, color, and arrays of these types. Furthermore, expressions are type safe: each use of an expression has a known result type and required argument types, and the SDKs verify that the result type of an expression is appropriate for the context in which it is used. For example, the result type of an expression in the ``filter`` property must be boolean, and the arguments to the ``+`` operator must be numbers.
When working with feature data, the type of a feature property value is typically not known ahead of time by the SDK. In order to preserve type safety, when evaluating a data expression, the SDK will check that the property value is appropriate for the context. For example, if you use the expression ``["get", "feature-color"]`` for the ``circle-color`` property, the SDK will verify that the ``feature-color`` value of each feature is a string identifying a valid color. If this check fails, an error will be indicated in an SDK-specific way (typically a log message), and the default value for the property will be used instead.
In most cases, this verification will occur automatically wherever it is needed. However, in certain situations, the SDK may be unable to automatically determine the expected result type of a data expression from surrounding context. For example, it is not clear whether the expression ``["<", ["get", "a"], ["get", "b"]]`` is attempting to compare strings or numbers. In situations like this, you can use one of the type assertion expression operators to indicate the expected type of a data expression: ``["<", ["number", ["get", "a"]], ["number", ["get", "b"]]]``. A type assertion checks that the feature data actually matches the expected type of the data expression. If this check fails, it produces an error and causes the whole expression to fall back to the default value for the property being defined. The assertion operators are ``array``, ``boolean``, ``number``, and ``string``.
Expressions perform only one kind of implicit type conversion: a data expression used in a context where a color is expected will convert a string representation of a color to a color value. In all other cases, if you want to convert between types, you must use one of the type conversion expression operators: ``to-boolean``, ``to-number``, ``to-string``, or ``to-color``. For example, if you have a feature property that stores numeric values in string format, and you want to use those values as numbers rather than strings, you can use an expression such as ``["to-number", ["get", "property-name"]]``.
Function
^^^^^^^^
.. note:: As of GeoTools 20.0 / MapBox 0.41.0, functions are deprecated. Use expressions instead.
The value for any layout or paint property may be specified as a function. Functions allow you to make the appearance of a map feature change with the current zoom level and/or the feature's properties.
stops
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment