From 789a49d46d5511cfe6b6631a7f9f0a5fed1aefbb Mon Sep 17 00:00:00 2001 From: Jordan Kiley Date: Fri, 17 Mar 2017 19:13:24 -0400 Subject: [ios, macos] update iOS SDK guides (#8354) - Added DDS guide - Updated "For Style Authors" guide --- .../darwin/docs/guides/Data-Driven Styling.md.ejs | 123 ++++++++++++++++++++ .../darwin/docs/guides/For Style Authors.md.ejs | 29 ++++- platform/darwin/scripts/generate-style-code.js | 7 ++ platform/darwin/src/MGLStyleValue.h | 8 +- platform/ios/docs/guides/Data-Driven Styling.md | 117 +++++++++++++++++++ platform/ios/docs/guides/For Style Authors.md | 125 ++++++++++++++++++++- .../docs/img/data-driven-styling/categorical1.png | Bin 0 -> 105968 bytes .../docs/img/data-driven-styling/categorical2.png | Bin 0 -> 125698 bytes .../ios/docs/img/data-driven-styling/citibikes.png | Bin 0 -> 152843 bytes .../docs/img/data-driven-styling/exponential.png | Bin 0 -> 86910 bytes .../ios/docs/img/data-driven-styling/identity.png | Bin 0 -> 68837 bytes .../ios/docs/img/data-driven-styling/interval.png | Bin 0 -> 83927 bytes .../img/data-driven-styling/polylineExample.png | Bin 0 -> 156800 bytes platform/ios/jazzy.yml | 1 + platform/macos/docs/guides/Data-Driven Styling.md | 117 +++++++++++++++++++ platform/macos/docs/guides/For Style Authors.md | 123 +++++++++++++++++++- platform/macos/jazzy.yml | 1 + 17 files changed, 642 insertions(+), 9 deletions(-) create mode 100644 platform/darwin/docs/guides/Data-Driven Styling.md.ejs create mode 100644 platform/ios/docs/guides/Data-Driven Styling.md create mode 100644 platform/ios/docs/img/data-driven-styling/categorical1.png create mode 100644 platform/ios/docs/img/data-driven-styling/categorical2.png create mode 100644 platform/ios/docs/img/data-driven-styling/citibikes.png create mode 100644 platform/ios/docs/img/data-driven-styling/exponential.png create mode 100644 platform/ios/docs/img/data-driven-styling/identity.png create mode 100644 platform/ios/docs/img/data-driven-styling/interval.png create mode 100644 platform/ios/docs/img/data-driven-styling/polylineExample.png create mode 100644 platform/macos/docs/guides/Data-Driven Styling.md diff --git a/platform/darwin/docs/guides/Data-Driven Styling.md.ejs b/platform/darwin/docs/guides/Data-Driven Styling.md.ejs new file mode 100644 index 0000000000..ead073b1c5 --- /dev/null +++ b/platform/darwin/docs/guides/Data-Driven Styling.md.ejs @@ -0,0 +1,123 @@ + +<% + const os = locals.os; + const iOS = os === 'iOS'; + const macOS = os === 'macOS'; + const cocoaPrefix = iOS ? 'UI' : 'NS'; +-%> + + +# Data-Driven Styling + +Mapbox’s data-driven styling features allow you to use data properties to style your maps. You can style objects within the same layer differently based on their individual attributes. This enables you to style icons, routes, parks, and more based on feature attributes. + +![available bikes](img/data-driven-styling/citibikes.png) ![subway lines](img/data-driven-styling/polylineExample.png) + +# How to use Data-Driven Styling +This guide uses earthquake data from the [U.S. Geological Survey](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) to style a map based on attributes. For more information about how to work with GeoJSON data in our iOS SDK, please see our [working with GeoJSON data](working-with-geojson-data.html) guide. + +`MGLStyleFunction` + +There are three subclasses of `MGLStyleFunction`: + +* `MGLCameraStyleFunction` - For a style value that changes with zoom level. For example, you can make the radius of a circle to increase based on zoom level. In iOS SDK v3.4, this was a `MGLStyleFunction`. +* `MGLSourceStyleFunction` - For a style value that changes with the attributes of a feature. You can adjust the radius of a circle based on the magnitude of an earthquake, for example. +* `MGLCompositeStyleFunction` - For a style value that changes with both zoom level and attribute values. For example, you can add a circle layer where each circle has a radius based on both zoom level and the magnitude of an earthquake. + +The documentation for individual style properties will note which style functions are enabled for that property. + +## Stops + +Stops are key-value pairs that that determine a style value. With a `MGLCameraSourceFunction` stop, you can use a dictionary with a zoom level for a key and a `MGLStyleValue` for the value. For example, you can use a stops dictionary with zoom levels 0, 10, and 20 as keys, and yellow, orange, and red as the values. A `MGLSourceStyleFunction` uses the relevant attribute value as the key. + +## Interpolation Mode + +The effect a key has on the style value is determined by the interpolation mode. There are four interpolation modes that can be used with a source style function: exponential, interval, categorical, and identity. You can also use exponential and interval interpolation modes with a camera style function. + +### Exponential (or Linear) + +`MGLInterpolationModelExponential` creates a linear or exponential effect based on the values. The key value is the starting point for interpolation, and the style value is based on where an attribute value falls between two keys. By default, `MGLInterpolationModeExponential` uses an interpolation base of 1. This causes a linear relationship between the style value and stop key. + +The stops dictionary below, for example, shows colors that continuously shift from yellow to orange to red to blue to white based on the attribute value. + +``` swift + let url = URL(string: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson") + let symbolSource = MGLSource(identifier: "source") + let symbolLayer = MGLSymbolStyleLayer(identifier: "place-city-sm", source: symbolSource) + + let source = MGLShapeSource(identifier: "earthquakes", url: url, options: nil) + style.addSource(source) + + let stops = [0: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.yellow), + 2.5: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.orange), + 5: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.red), + 7.5: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.blue), + 10: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.white)] + + let layer = MGLCircleStyleLayer(identifier: "circles", source: source) + layer.circleColor = MGLStyleValue(interpolationMode: .exponential, + sourceStops: stops, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .green)]) + layer.circleRadius = MGLStyleValue(rawValue: 10) + style.insertLayer(layer, below: symbolLayer) +``` + +![exponential mode](img/data-driven-styling/exponential.png) + +### Interval + +`MGLInterpolationModeInterval` creates a range using the keys from the stops dictionary. The range is from the given key to just less than the next key. The attribute values that fall into that range are then styled using the style value assigned to that key. + +When we use the stops dictionary given above with an interval interpolation mode, we create ranges where earthquakes with a magnitude of 0 to just less than 2.5 would be yellow, 2.5 to just less than 5 would be orange, and so on. + +``` swift +layer.circleColor = MGLStyleValue(interpolationMode: .interval, + sourceStops: stops, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .green)]) +``` + +![interval mode](img/data-driven-styling/interval.png) + +### Categorical + +Returns the output value that is equal to the stop for the function input. We’re going to use a different stops dictionary than we did for the previous two modes. + +There are three main types of events in the dataset: earthquakes, explosions, and quarry blasts. In this case, the color of the circle layer will be determined by the type of event, with a default value of green to catch any events that do not fall into any of those categories. + +``` swift +let categoricalStops = ["earthquake": MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.orange), + "explosion": MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.red), + "quarry blast": MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.yellow)] + +layer.circleColor = MGLStyleValue(interpolationMode: .categorical, + sourceStops: categoricalStops, + attributeName: "type", + options: [.defaultValue: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.blue)]) + +``` + +![categorical mode](img/data-driven-styling/categorical1.png) ![categorical mode](img/data-driven-styling/categorical2.png) + +### Identity + +`MGLInterpolationModeIdentity` uses the attribute’s value as the style value. For example, you can set the `circleRadius` to the earthquake’s magnitude. Since the attribute value itself will be used as the style value, `sourceStops` can be set to `nil`. + +``` swift +layer.circleRadius = MGLStyleValue(interpolationMode: .identity, + sourceStops: nil, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue(rawValue: 0)]) + +``` + +![identity mode](img/data-driven-styling/identity.png) + +##Resources + +* [USGS](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) +* [For Style Authors](for-style-authors.html) diff --git a/platform/darwin/docs/guides/For Style Authors.md.ejs b/platform/darwin/docs/guides/For Style Authors.md.ejs index 60797967d0..92ce4c1594 100644 --- a/platform/darwin/docs/guides/For Style Authors.md.ejs +++ b/platform/darwin/docs/guides/For Style Authors.md.ejs @@ -8,7 +8,7 @@ -%> # Information for Style Authors @@ -41,7 +41,7 @@ underneath. <% if (iOS) { -%> The user location annotation view, the attribution button, any buttons in callout views, and any items in the navigation bar are influenced by your -application’s tint color, so choose a tint color that constrasts well with your +application’s tint color, so choose a tint color that contrasts well with your map style. <% } -%> If you intend your style to be used in the dark, consider the impact that Night @@ -160,6 +160,7 @@ In the style specification | In the SDK ---------------------------|--------- class | style class filter | predicate +function type | interpolation mode id | identifier image | style image layer | style layer @@ -239,6 +240,30 @@ whose names differ from the style specification are listed below: <% for (const type in renamedProperties) { -%> <% if (renamedProperties.hasOwnProperty(type)) { -%> +### <%- camelize(type) %> style functions + +The runtime styling API introduces `MGLStyleFunction` to the <%- os %> SDK. +[Data-driven styling](data-driven-styling.html) expands `MGLStyleFunction`. +Individual style property documentation includes which subclasses of +`MGLStyleFunction` are enabled for that property. You can use `MGLStyleValue` +methods to create a `MGLStyleFunction`. + +In style specification | In the SDK | [MGLStyleValue valueWithInterpolationMode:...] +-----------------------|-------------------------------|------------- +`zoom function` | `MGLCameraStyleFunction` | `cameraStops:options:` +`property function` | `MGLSourceStyleFunction` | `sourceStops:attributeName:options:` +`zoom-and-property functions`| `MGLCompositeStyleFunction` | `compositeStops:attributeName:options:` + +Data-driven styling also introduces interpolation mode, which defines the +relationship between style values and attributes or zoom levels. + +In style specification | In the SDK +-----------------------------|----------- +`exponential` | `MGLInterpolationModeExponential` +`interval` | `MGLInterpolationModeInterval` +`categorical` | `MGLInterpolationModeCategorical` +`identity` | `MGLInterpolationModeIdentity` + ### <%- camelize(type) %> style layers In style JSON | In Objective-C | In Swift diff --git a/platform/darwin/scripts/generate-style-code.js b/platform/darwin/scripts/generate-style-code.js index 9746c11408..9c4569709d 100644 --- a/platform/darwin/scripts/generate-style-code.js +++ b/platform/darwin/scripts/generate-style-code.js @@ -528,6 +528,7 @@ const layerH = ejs.compile(fs.readFileSync('platform/darwin/src/MGLStyleLayer.h. const layerM = ejs.compile(fs.readFileSync('platform/darwin/src/MGLStyleLayer.mm.ejs', 'utf8'), { strict: true}); const testLayers = ejs.compile(fs.readFileSync('platform/darwin/test/MGLStyleLayerTests.mm.ejs', 'utf8'), { strict: true}); const guideMD = ejs.compile(fs.readFileSync('platform/darwin/docs/guides/For Style Authors.md.ejs', 'utf8'), { strict: true }); +const ddsGuideMD = ejs.compile(fs.readFileSync('platform/darwin/docs/guides/Data-Driven Styling.md.ejs', 'utf8'), { strict: true }); const layers = _(spec.layer.type.values).map((value, layerType) => { const layoutProperties = Object.keys(spec[`layout_${layerType}`]).reduce((memo, name) => { @@ -614,3 +615,9 @@ fs.writeFileSync(`platform/macos/docs/guides/For Style Authors.md`, guideMD({ renamedProperties: renamedPropertiesByLayerType, layers: layers, })); +fs.writeFileSync(`platform/ios/docs/guides/Data-Driven Styling.md`, ddsGuideMD({ + os: 'iOS', +})); +fs.writeFileSync(`platform/macos/docs/guides/Data-Driven Styling.md`, ddsGuideMD({ + os: 'macOS', +})); diff --git a/platform/darwin/src/MGLStyleValue.h b/platform/darwin/src/MGLStyleValue.h index eb9d40ca6b..70074c8a13 100644 --- a/platform/darwin/src/MGLStyleValue.h +++ b/platform/darwin/src/MGLStyleValue.h @@ -17,10 +17,10 @@ typedef NSString *MGLStyleFunctionOption NS_STRING_ENUM; The exponential interpolation base controls the rate at which the function’s output values increase. A value of 1 causes the function to increase linearly - by zoom level. A higher exponential interpolation base causes the function’s - output values to vary exponentially, increasing more rapidly towards the high - end of the function’s range. The default value of this property is 1, for a - linear curve. + based on zoom level or attribute value. A higher exponential interpolation base + causes the function’s output values to vary exponentially, increasing more rapidly + towards the high end of the function’s range. The default value of this property + is 1, for a linear curve. This attribute corresponds to the base diff --git a/platform/ios/docs/guides/Data-Driven Styling.md b/platform/ios/docs/guides/Data-Driven Styling.md new file mode 100644 index 0000000000..418c7bb4fc --- /dev/null +++ b/platform/ios/docs/guides/Data-Driven Styling.md @@ -0,0 +1,117 @@ + + + +# Data-Driven Styling + +Mapbox’s data-driven styling features allow you to use data properties to style your maps. You can style objects within the same layer differently based on their individual attributes. This enables you to style icons, routes, parks, and more based on feature attributes. + +![available bikes](img/data-driven-styling/citibikes.png) ![subway lines](img/data-driven-styling/polylineExample.png) + +# How to use Data-Driven Styling +This guide uses earthquake data from the [U.S. Geological Survey](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) to style a map based on attributes. For more information about how to work with GeoJSON data in our iOS SDK, please see our [working with GeoJSON data](working-with-geojson-data.html) guide. + +`MGLStyleFunction` + +There are three subclasses of `MGLStyleFunction`: + +* `MGLCameraStyleFunction` - For a style value that changes with zoom level. For example, you can make the radius of a circle to increase based on zoom level. In iOS SDK v3.4, this was a `MGLStyleFunction`. +* `MGLSourceStyleFunction` - For a style value that changes with the attributes of a feature. You can adjust the radius of a circle based on the magnitude of an earthquake, for example. +* `MGLCompositeStyleFunction` - For a style value that changes with both zoom level and attribute values. For example, you can add a circle layer where each circle has a radius based on both zoom level and the magnitude of an earthquake. + +The documentation for individual style properties will note which style functions are enabled for that property. + +## Stops + +Stops are key-value pairs that that determine a style value. With a `MGLCameraSourceFunction` stop, you can use a dictionary with a zoom level for a key and a `MGLStyleValue` for the value. For example, you can use a stops dictionary with zoom levels 0, 10, and 20 as keys, and yellow, orange, and red as the values. A `MGLSourceStyleFunction` uses the relevant attribute value as the key. + +## Interpolation Mode + +The effect a key has on the style value is determined by the interpolation mode. There are four interpolation modes that can be used with a source style function: exponential, interval, categorical, and identity. You can also use exponential and interval interpolation modes with a camera style function. + +### Exponential (or Linear) + +`MGLInterpolationModelExponential` creates a linear or exponential effect based on the values. The key value is the starting point for interpolation, and the style value is based on where an attribute value falls between two keys. By default, `MGLInterpolationModeExponential` uses an interpolation base of 1. This causes a linear relationship between the style value and stop key. + +The stops dictionary below, for example, shows colors that continuously shift from yellow to orange to red to blue to white based on the attribute value. + +``` swift + let url = URL(string: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson") + let symbolSource = MGLSource(identifier: "source") + let symbolLayer = MGLSymbolStyleLayer(identifier: "place-city-sm", source: symbolSource) + + let source = MGLShapeSource(identifier: "earthquakes", url: url, options: nil) + style.addSource(source) + + let stops = [0: MGLStyleValue(rawValue: UIColor.yellow), + 2.5: MGLStyleValue(rawValue: UIColor.orange), + 5: MGLStyleValue(rawValue: UIColor.red), + 7.5: MGLStyleValue(rawValue: UIColor.blue), + 10: MGLStyleValue(rawValue: UIColor.white)] + + let layer = MGLCircleStyleLayer(identifier: "circles", source: source) + layer.circleColor = MGLStyleValue(interpolationMode: .exponential, + sourceStops: stops, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue(rawValue: .green)]) + layer.circleRadius = MGLStyleValue(rawValue: 10) + style.insertLayer(layer, below: symbolLayer) +``` + +![exponential mode](img/data-driven-styling/exponential.png) + +### Interval + +`MGLInterpolationModeInterval` creates a range using the keys from the stops dictionary. The range is from the given key to just less than the next key. The attribute values that fall into that range are then styled using the style value assigned to that key. + +When we use the stops dictionary given above with an interval interpolation mode, we create ranges where earthquakes with a magnitude of 0 to just less than 2.5 would be yellow, 2.5 to just less than 5 would be orange, and so on. + +``` swift +layer.circleColor = MGLStyleValue(interpolationMode: .interval, + sourceStops: stops, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue(rawValue: .green)]) +``` + +![interval mode](img/data-driven-styling/interval.png) + +### Categorical + +Returns the output value that is equal to the stop for the function input. We’re going to use a different stops dictionary than we did for the previous two modes. + +There are three main types of events in the dataset: earthquakes, explosions, and quarry blasts. In this case, the color of the circle layer will be determined by the type of event, with a default value of green to catch any events that do not fall into any of those categories. + +``` swift +let categoricalStops = ["earthquake": MGLStyleValue(rawValue: UIColor.orange), + "explosion": MGLStyleValue(rawValue: UIColor.red), + "quarry blast": MGLStyleValue(rawValue: UIColor.yellow)] + +layer.circleColor = MGLStyleValue(interpolationMode: .categorical, + sourceStops: categoricalStops, + attributeName: "type", + options: [.defaultValue: MGLStyleValue(rawValue: UIColor.blue)]) + +``` + +![categorical mode](img/data-driven-styling/categorical1.png) ![categorical mode](img/data-driven-styling/categorical2.png) + +### Identity + +`MGLInterpolationModeIdentity` uses the attribute’s value as the style value. For example, you can set the `circleRadius` to the earthquake’s magnitude. Since the attribute value itself will be used as the style value, `sourceStops` can be set to `nil`. + +``` swift +layer.circleRadius = MGLStyleValue(interpolationMode: .identity, + sourceStops: nil, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue(rawValue: 0)]) + +``` + +![identity mode](img/data-driven-styling/identity.png) + +##Resources + +* [USGS](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) +* [For Style Authors](for-style-authors.html) diff --git a/platform/ios/docs/guides/For Style Authors.md b/platform/ios/docs/guides/For Style Authors.md index c1c74499b2..952be6bec7 100644 --- a/platform/ios/docs/guides/For Style Authors.md +++ b/platform/ios/docs/guides/For Style Authors.md @@ -1,6 +1,6 @@ # Information for Style Authors @@ -28,7 +28,7 @@ make sure the contents of these elements remain legible with the map view underneath. The user location annotation view, the attribution button, any buttons in callout views, and any items in the navigation bar are influenced by your -application’s tint color, so choose a tint color that constrasts well with your +application’s tint color, so choose a tint color that contrasts well with your map style. If you intend your style to be used in the dark, consider the impact that Night Shift may have on your style’s colors. @@ -109,6 +109,7 @@ In the style specification | In the SDK ---------------------------|--------- class | style class filter | predicate +function type | interpolation mode id | identifier image | style image layer | style layer @@ -189,6 +190,30 @@ layer objects. The property names generally correspond to the style JSON properties, except for the use of camelCase instead of kebab-case. Properties whose names differ from the style specification are listed below: +### Circle style functions + +The runtime styling API introduces `MGLStyleFunction` to the iOS SDK. +[Data-driven styling](data-driven-styling.html) expands `MGLStyleFunction`. +Individual style property documentation includes which subclasses of +`MGLStyleFunction` are enabled for that property. You can use `MGLStyleValue` +methods to create a `MGLStyleFunction`. + +In style specification | In the SDK | [MGLStyleValue valueWithInterpolationMode:...] +-----------------------|-------------------------------|------------- +`zoom function` | `MGLCameraStyleFunction` | `cameraStops:options:` +`property function` | `MGLSourceStyleFunction` | `sourceStops:attributeName:options:` +`zoom-and-property functions`| `MGLCompositeStyleFunction` | `compositeStops:attributeName:options:` + +Data-driven styling also introduces interpolation mode, which defines the +relationship between style values and attributes or zoom levels. + +In style specification | In the SDK +-----------------------------|----------- +`exponential` | `MGLInterpolationModeExponential` +`interval` | `MGLInterpolationModeInterval` +`categorical` | `MGLInterpolationModeCategorical` +`identity` | `MGLInterpolationModeIdentity` + ### Circle style layers In style JSON | In Objective-C | In Swift @@ -197,6 +222,30 @@ In style JSON | In Objective-C | In Swift `circle-translate` | `MGLCircleStyleLayer.circleTranslation` | `MGLCircleStyleLayer.circleTranslation` `circle-translate-anchor` | `MGLCircleStyleLayer.circleTranslationAnchor` | `MGLCircleStyleLayer.circleTranslationAnchor` +### Fill style functions + +The runtime styling API introduces `MGLStyleFunction` to the iOS SDK. +[Data-driven styling](data-driven-styling.html) expands `MGLStyleFunction`. +Individual style property documentation includes which subclasses of +`MGLStyleFunction` are enabled for that property. You can use `MGLStyleValue` +methods to create a `MGLStyleFunction`. + +In style specification | In the SDK | [MGLStyleValue valueWithInterpolationMode:...] +-----------------------|-------------------------------|------------- +`zoom function` | `MGLCameraStyleFunction` | `cameraStops:options:` +`property function` | `MGLSourceStyleFunction` | `sourceStops:attributeName:options:` +`zoom-and-property functions`| `MGLCompositeStyleFunction` | `compositeStops:attributeName:options:` + +Data-driven styling also introduces interpolation mode, which defines the +relationship between style values and attributes or zoom levels. + +In style specification | In the SDK +-----------------------------|----------- +`exponential` | `MGLInterpolationModeExponential` +`interval` | `MGLInterpolationModeInterval` +`categorical` | `MGLInterpolationModeCategorical` +`identity` | `MGLInterpolationModeIdentity` + ### Fill style layers In style JSON | In Objective-C | In Swift @@ -205,6 +254,30 @@ In style JSON | In Objective-C | In Swift `fill-translate` | `MGLFillStyleLayer.fillTranslation` | `MGLFillStyleLayer.fillTranslation` `fill-translate-anchor` | `MGLFillStyleLayer.fillTranslationAnchor` | `MGLFillStyleLayer.fillTranslationAnchor` +### Line style functions + +The runtime styling API introduces `MGLStyleFunction` to the iOS SDK. +[Data-driven styling](data-driven-styling.html) expands `MGLStyleFunction`. +Individual style property documentation includes which subclasses of +`MGLStyleFunction` are enabled for that property. You can use `MGLStyleValue` +methods to create a `MGLStyleFunction`. + +In style specification | In the SDK | [MGLStyleValue valueWithInterpolationMode:...] +-----------------------|-------------------------------|------------- +`zoom function` | `MGLCameraStyleFunction` | `cameraStops:options:` +`property function` | `MGLSourceStyleFunction` | `sourceStops:attributeName:options:` +`zoom-and-property functions`| `MGLCompositeStyleFunction` | `compositeStops:attributeName:options:` + +Data-driven styling also introduces interpolation mode, which defines the +relationship between style values and attributes or zoom levels. + +In style specification | In the SDK +-----------------------------|----------- +`exponential` | `MGLInterpolationModeExponential` +`interval` | `MGLInterpolationModeInterval` +`categorical` | `MGLInterpolationModeCategorical` +`identity` | `MGLInterpolationModeIdentity` + ### Line style layers In style JSON | In Objective-C | In Swift @@ -213,6 +286,30 @@ In style JSON | In Objective-C | In Swift `line-translate` | `MGLLineStyleLayer.lineTranslation` | `MGLLineStyleLayer.lineTranslation` `line-translate-anchor` | `MGLLineStyleLayer.lineTranslationAnchor` | `MGLLineStyleLayer.lineTranslationAnchor` +### Raster style functions + +The runtime styling API introduces `MGLStyleFunction` to the iOS SDK. +[Data-driven styling](data-driven-styling.html) expands `MGLStyleFunction`. +Individual style property documentation includes which subclasses of +`MGLStyleFunction` are enabled for that property. You can use `MGLStyleValue` +methods to create a `MGLStyleFunction`. + +In style specification | In the SDK | [MGLStyleValue valueWithInterpolationMode:...] +-----------------------|-------------------------------|------------- +`zoom function` | `MGLCameraStyleFunction` | `cameraStops:options:` +`property function` | `MGLSourceStyleFunction` | `sourceStops:attributeName:options:` +`zoom-and-property functions`| `MGLCompositeStyleFunction` | `compositeStops:attributeName:options:` + +Data-driven styling also introduces interpolation mode, which defines the +relationship between style values and attributes or zoom levels. + +In style specification | In the SDK +-----------------------------|----------- +`exponential` | `MGLInterpolationModeExponential` +`interval` | `MGLInterpolationModeInterval` +`categorical` | `MGLInterpolationModeCategorical` +`identity` | `MGLInterpolationModeIdentity` + ### Raster style layers In style JSON | In Objective-C | In Swift @@ -221,6 +318,30 @@ In style JSON | In Objective-C | In Swift `raster-brightness-min` | `MGLRasterStyleLayer.minimumRasterBrightness` | `MGLRasterStyleLayer.minimumRasterBrightness` `raster-hue-rotate` | `MGLRasterStyleLayer.rasterHueRotation` | `MGLRasterStyleLayer.rasterHueRotation` +### Symbol style functions + +The runtime styling API introduces `MGLStyleFunction` to the iOS SDK. +[Data-driven styling](data-driven-styling.html) expands `MGLStyleFunction`. +Individual style property documentation includes which subclasses of +`MGLStyleFunction` are enabled for that property. You can use `MGLStyleValue` +methods to create a `MGLStyleFunction`. + +In style specification | In the SDK | [MGLStyleValue valueWithInterpolationMode:...] +-----------------------|-------------------------------|------------- +`zoom function` | `MGLCameraStyleFunction` | `cameraStops:options:` +`property function` | `MGLSourceStyleFunction` | `sourceStops:attributeName:options:` +`zoom-and-property functions`| `MGLCompositeStyleFunction` | `compositeStops:attributeName:options:` + +Data-driven styling also introduces interpolation mode, which defines the +relationship between style values and attributes or zoom levels. + +In style specification | In the SDK +-----------------------------|----------- +`exponential` | `MGLInterpolationModeExponential` +`interval` | `MGLInterpolationModeInterval` +`categorical` | `MGLInterpolationModeCategorical` +`identity` | `MGLInterpolationModeIdentity` + ### Symbol style layers In style JSON | In Objective-C | In Swift diff --git a/platform/ios/docs/img/data-driven-styling/categorical1.png b/platform/ios/docs/img/data-driven-styling/categorical1.png new file mode 100644 index 0000000000..969846b41b Binary files /dev/null and b/platform/ios/docs/img/data-driven-styling/categorical1.png differ diff --git a/platform/ios/docs/img/data-driven-styling/categorical2.png b/platform/ios/docs/img/data-driven-styling/categorical2.png new file mode 100644 index 0000000000..5008c522ed Binary files /dev/null and b/platform/ios/docs/img/data-driven-styling/categorical2.png differ diff --git a/platform/ios/docs/img/data-driven-styling/citibikes.png b/platform/ios/docs/img/data-driven-styling/citibikes.png new file mode 100644 index 0000000000..a616672a32 Binary files /dev/null and b/platform/ios/docs/img/data-driven-styling/citibikes.png differ diff --git a/platform/ios/docs/img/data-driven-styling/exponential.png b/platform/ios/docs/img/data-driven-styling/exponential.png new file mode 100644 index 0000000000..87ddc1350e Binary files /dev/null and b/platform/ios/docs/img/data-driven-styling/exponential.png differ diff --git a/platform/ios/docs/img/data-driven-styling/identity.png b/platform/ios/docs/img/data-driven-styling/identity.png new file mode 100644 index 0000000000..632ccdf3d5 Binary files /dev/null and b/platform/ios/docs/img/data-driven-styling/identity.png differ diff --git a/platform/ios/docs/img/data-driven-styling/interval.png b/platform/ios/docs/img/data-driven-styling/interval.png new file mode 100644 index 0000000000..d15aff2025 Binary files /dev/null and b/platform/ios/docs/img/data-driven-styling/interval.png differ diff --git a/platform/ios/docs/img/data-driven-styling/polylineExample.png b/platform/ios/docs/img/data-driven-styling/polylineExample.png new file mode 100644 index 0000000000..cd9b39bae4 Binary files /dev/null and b/platform/ios/docs/img/data-driven-styling/polylineExample.png differ diff --git a/platform/ios/jazzy.yml b/platform/ios/jazzy.yml index 9a119db31e..5d39e276b6 100644 --- a/platform/ios/jazzy.yml +++ b/platform/ios/jazzy.yml @@ -19,6 +19,7 @@ custom_categories: children: - Adding Points to a Map - Runtime Styling + - Data-Driven Styling - Working with Mapbox Studio - Working with GeoJSON Data - For Style Authors diff --git a/platform/macos/docs/guides/Data-Driven Styling.md b/platform/macos/docs/guides/Data-Driven Styling.md new file mode 100644 index 0000000000..8344de23c9 --- /dev/null +++ b/platform/macos/docs/guides/Data-Driven Styling.md @@ -0,0 +1,117 @@ + + + +# Data-Driven Styling + +Mapbox’s data-driven styling features allow you to use data properties to style your maps. You can style objects within the same layer differently based on their individual attributes. This enables you to style icons, routes, parks, and more based on feature attributes. + +![available bikes](img/data-driven-styling/citibikes.png) ![subway lines](img/data-driven-styling/polylineExample.png) + +# How to use Data-Driven Styling +This guide uses earthquake data from the [U.S. Geological Survey](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) to style a map based on attributes. For more information about how to work with GeoJSON data in our iOS SDK, please see our [working with GeoJSON data](working-with-geojson-data.html) guide. + +`MGLStyleFunction` + +There are three subclasses of `MGLStyleFunction`: + +* `MGLCameraStyleFunction` - For a style value that changes with zoom level. For example, you can make the radius of a circle to increase based on zoom level. In iOS SDK v3.4, this was a `MGLStyleFunction`. +* `MGLSourceStyleFunction` - For a style value that changes with the attributes of a feature. You can adjust the radius of a circle based on the magnitude of an earthquake, for example. +* `MGLCompositeStyleFunction` - For a style value that changes with both zoom level and attribute values. For example, you can add a circle layer where each circle has a radius based on both zoom level and the magnitude of an earthquake. + +The documentation for individual style properties will note which style functions are enabled for that property. + +## Stops + +Stops are key-value pairs that that determine a style value. With a `MGLCameraSourceFunction` stop, you can use a dictionary with a zoom level for a key and a `MGLStyleValue` for the value. For example, you can use a stops dictionary with zoom levels 0, 10, and 20 as keys, and yellow, orange, and red as the values. A `MGLSourceStyleFunction` uses the relevant attribute value as the key. + +## Interpolation Mode + +The effect a key has on the style value is determined by the interpolation mode. There are four interpolation modes that can be used with a source style function: exponential, interval, categorical, and identity. You can also use exponential and interval interpolation modes with a camera style function. + +### Exponential (or Linear) + +`MGLInterpolationModelExponential` creates a linear or exponential effect based on the values. The key value is the starting point for interpolation, and the style value is based on where an attribute value falls between two keys. By default, `MGLInterpolationModeExponential` uses an interpolation base of 1. This causes a linear relationship between the style value and stop key. + +The stops dictionary below, for example, shows colors that continuously shift from yellow to orange to red to blue to white based on the attribute value. + +``` swift + let url = URL(string: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson") + let symbolSource = MGLSource(identifier: "source") + let symbolLayer = MGLSymbolStyleLayer(identifier: "place-city-sm", source: symbolSource) + + let source = MGLShapeSource(identifier: "earthquakes", url: url, options: nil) + style.addSource(source) + + let stops = [0: MGLStyleValue(rawValue: NSColor.yellow), + 2.5: MGLStyleValue(rawValue: NSColor.orange), + 5: MGLStyleValue(rawValue: NSColor.red), + 7.5: MGLStyleValue(rawValue: NSColor.blue), + 10: MGLStyleValue(rawValue: NSColor.white)] + + let layer = MGLCircleStyleLayer(identifier: "circles", source: source) + layer.circleColor = MGLStyleValue(interpolationMode: .exponential, + sourceStops: stops, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue(rawValue: .green)]) + layer.circleRadius = MGLStyleValue(rawValue: 10) + style.insertLayer(layer, below: symbolLayer) +``` + +![exponential mode](img/data-driven-styling/exponential.png) + +### Interval + +`MGLInterpolationModeInterval` creates a range using the keys from the stops dictionary. The range is from the given key to just less than the next key. The attribute values that fall into that range are then styled using the style value assigned to that key. + +When we use the stops dictionary given above with an interval interpolation mode, we create ranges where earthquakes with a magnitude of 0 to just less than 2.5 would be yellow, 2.5 to just less than 5 would be orange, and so on. + +``` swift +layer.circleColor = MGLStyleValue(interpolationMode: .interval, + sourceStops: stops, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue(rawValue: .green)]) +``` + +![interval mode](img/data-driven-styling/interval.png) + +### Categorical + +Returns the output value that is equal to the stop for the function input. We’re going to use a different stops dictionary than we did for the previous two modes. + +There are three main types of events in the dataset: earthquakes, explosions, and quarry blasts. In this case, the color of the circle layer will be determined by the type of event, with a default value of green to catch any events that do not fall into any of those categories. + +``` swift +let categoricalStops = ["earthquake": MGLStyleValue(rawValue: NSColor.orange), + "explosion": MGLStyleValue(rawValue: NSColor.red), + "quarry blast": MGLStyleValue(rawValue: NSColor.yellow)] + +layer.circleColor = MGLStyleValue(interpolationMode: .categorical, + sourceStops: categoricalStops, + attributeName: "type", + options: [.defaultValue: MGLStyleValue(rawValue: NSColor.blue)]) + +``` + +![categorical mode](img/data-driven-styling/categorical1.png) ![categorical mode](img/data-driven-styling/categorical2.png) + +### Identity + +`MGLInterpolationModeIdentity` uses the attribute’s value as the style value. For example, you can set the `circleRadius` to the earthquake’s magnitude. Since the attribute value itself will be used as the style value, `sourceStops` can be set to `nil`. + +``` swift +layer.circleRadius = MGLStyleValue(interpolationMode: .identity, + sourceStops: nil, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue(rawValue: 0)]) + +``` + +![identity mode](img/data-driven-styling/identity.png) + +##Resources + +* [USGS](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) +* [For Style Authors](for-style-authors.html) diff --git a/platform/macos/docs/guides/For Style Authors.md b/platform/macos/docs/guides/For Style Authors.md index a0cf39e6dc..9c3665d816 100644 --- a/platform/macos/docs/guides/For Style Authors.md +++ b/platform/macos/docs/guides/For Style Authors.md @@ -1,6 +1,6 @@ # Information for Style Authors @@ -98,6 +98,7 @@ In the style specification | In the SDK ---------------------------|--------- class | style class filter | predicate +function type | interpolation mode id | identifier image | style image layer | style layer @@ -178,6 +179,30 @@ layer objects. The property names generally correspond to the style JSON properties, except for the use of camelCase instead of kebab-case. Properties whose names differ from the style specification are listed below: +### Circle style functions + +The runtime styling API introduces `MGLStyleFunction` to the macOS SDK. +[Data-driven styling](data-driven-styling.html) expands `MGLStyleFunction`. +Individual style property documentation includes which subclasses of +`MGLStyleFunction` are enabled for that property. You can use `MGLStyleValue` +methods to create a `MGLStyleFunction`. + +In style specification | In the SDK | [MGLStyleValue valueWithInterpolationMode:...] +-----------------------|-------------------------------|------------- +`zoom function` | `MGLCameraStyleFunction` | `cameraStops:options:` +`property function` | `MGLSourceStyleFunction` | `sourceStops:attributeName:options:` +`zoom-and-property functions`| `MGLCompositeStyleFunction` | `compositeStops:attributeName:options:` + +Data-driven styling also introduces interpolation mode, which defines the +relationship between style values and attributes or zoom levels. + +In style specification | In the SDK +-----------------------------|----------- +`exponential` | `MGLInterpolationModeExponential` +`interval` | `MGLInterpolationModeInterval` +`categorical` | `MGLInterpolationModeCategorical` +`identity` | `MGLInterpolationModeIdentity` + ### Circle style layers In style JSON | In Objective-C | In Swift @@ -186,6 +211,30 @@ In style JSON | In Objective-C | In Swift `circle-translate` | `MGLCircleStyleLayer.circleTranslation` | `MGLCircleStyleLayer.circleTranslation` `circle-translate-anchor` | `MGLCircleStyleLayer.circleTranslationAnchor` | `MGLCircleStyleLayer.circleTranslationAnchor` +### Fill style functions + +The runtime styling API introduces `MGLStyleFunction` to the macOS SDK. +[Data-driven styling](data-driven-styling.html) expands `MGLStyleFunction`. +Individual style property documentation includes which subclasses of +`MGLStyleFunction` are enabled for that property. You can use `MGLStyleValue` +methods to create a `MGLStyleFunction`. + +In style specification | In the SDK | [MGLStyleValue valueWithInterpolationMode:...] +-----------------------|-------------------------------|------------- +`zoom function` | `MGLCameraStyleFunction` | `cameraStops:options:` +`property function` | `MGLSourceStyleFunction` | `sourceStops:attributeName:options:` +`zoom-and-property functions`| `MGLCompositeStyleFunction` | `compositeStops:attributeName:options:` + +Data-driven styling also introduces interpolation mode, which defines the +relationship between style values and attributes or zoom levels. + +In style specification | In the SDK +-----------------------------|----------- +`exponential` | `MGLInterpolationModeExponential` +`interval` | `MGLInterpolationModeInterval` +`categorical` | `MGLInterpolationModeCategorical` +`identity` | `MGLInterpolationModeIdentity` + ### Fill style layers In style JSON | In Objective-C | In Swift @@ -194,6 +243,30 @@ In style JSON | In Objective-C | In Swift `fill-translate` | `MGLFillStyleLayer.fillTranslation` | `MGLFillStyleLayer.fillTranslation` `fill-translate-anchor` | `MGLFillStyleLayer.fillTranslationAnchor` | `MGLFillStyleLayer.fillTranslationAnchor` +### Line style functions + +The runtime styling API introduces `MGLStyleFunction` to the macOS SDK. +[Data-driven styling](data-driven-styling.html) expands `MGLStyleFunction`. +Individual style property documentation includes which subclasses of +`MGLStyleFunction` are enabled for that property. You can use `MGLStyleValue` +methods to create a `MGLStyleFunction`. + +In style specification | In the SDK | [MGLStyleValue valueWithInterpolationMode:...] +-----------------------|-------------------------------|------------- +`zoom function` | `MGLCameraStyleFunction` | `cameraStops:options:` +`property function` | `MGLSourceStyleFunction` | `sourceStops:attributeName:options:` +`zoom-and-property functions`| `MGLCompositeStyleFunction` | `compositeStops:attributeName:options:` + +Data-driven styling also introduces interpolation mode, which defines the +relationship between style values and attributes or zoom levels. + +In style specification | In the SDK +-----------------------------|----------- +`exponential` | `MGLInterpolationModeExponential` +`interval` | `MGLInterpolationModeInterval` +`categorical` | `MGLInterpolationModeCategorical` +`identity` | `MGLInterpolationModeIdentity` + ### Line style layers In style JSON | In Objective-C | In Swift @@ -202,6 +275,30 @@ In style JSON | In Objective-C | In Swift `line-translate` | `MGLLineStyleLayer.lineTranslation` | `MGLLineStyleLayer.lineTranslation` `line-translate-anchor` | `MGLLineStyleLayer.lineTranslationAnchor` | `MGLLineStyleLayer.lineTranslationAnchor` +### Raster style functions + +The runtime styling API introduces `MGLStyleFunction` to the macOS SDK. +[Data-driven styling](data-driven-styling.html) expands `MGLStyleFunction`. +Individual style property documentation includes which subclasses of +`MGLStyleFunction` are enabled for that property. You can use `MGLStyleValue` +methods to create a `MGLStyleFunction`. + +In style specification | In the SDK | [MGLStyleValue valueWithInterpolationMode:...] +-----------------------|-------------------------------|------------- +`zoom function` | `MGLCameraStyleFunction` | `cameraStops:options:` +`property function` | `MGLSourceStyleFunction` | `sourceStops:attributeName:options:` +`zoom-and-property functions`| `MGLCompositeStyleFunction` | `compositeStops:attributeName:options:` + +Data-driven styling also introduces interpolation mode, which defines the +relationship between style values and attributes or zoom levels. + +In style specification | In the SDK +-----------------------------|----------- +`exponential` | `MGLInterpolationModeExponential` +`interval` | `MGLInterpolationModeInterval` +`categorical` | `MGLInterpolationModeCategorical` +`identity` | `MGLInterpolationModeIdentity` + ### Raster style layers In style JSON | In Objective-C | In Swift @@ -210,6 +307,30 @@ In style JSON | In Objective-C | In Swift `raster-brightness-min` | `MGLRasterStyleLayer.minimumRasterBrightness` | `MGLRasterStyleLayer.minimumRasterBrightness` `raster-hue-rotate` | `MGLRasterStyleLayer.rasterHueRotation` | `MGLRasterStyleLayer.rasterHueRotation` +### Symbol style functions + +The runtime styling API introduces `MGLStyleFunction` to the macOS SDK. +[Data-driven styling](data-driven-styling.html) expands `MGLStyleFunction`. +Individual style property documentation includes which subclasses of +`MGLStyleFunction` are enabled for that property. You can use `MGLStyleValue` +methods to create a `MGLStyleFunction`. + +In style specification | In the SDK | [MGLStyleValue valueWithInterpolationMode:...] +-----------------------|-------------------------------|------------- +`zoom function` | `MGLCameraStyleFunction` | `cameraStops:options:` +`property function` | `MGLSourceStyleFunction` | `sourceStops:attributeName:options:` +`zoom-and-property functions`| `MGLCompositeStyleFunction` | `compositeStops:attributeName:options:` + +Data-driven styling also introduces interpolation mode, which defines the +relationship between style values and attributes or zoom levels. + +In style specification | In the SDK +-----------------------------|----------- +`exponential` | `MGLInterpolationModeExponential` +`interval` | `MGLInterpolationModeInterval` +`categorical` | `MGLInterpolationModeCategorical` +`identity` | `MGLInterpolationModeIdentity` + ### Symbol style layers In style JSON | In Objective-C | In Swift diff --git a/platform/macos/jazzy.yml b/platform/macos/jazzy.yml index 3d74fbc652..9323119718 100644 --- a/platform/macos/jazzy.yml +++ b/platform/macos/jazzy.yml @@ -19,6 +19,7 @@ custom_categories: children: - Working with GeoJSON Data - For Style Authors + - Data-Driven Styling - Info.plist Keys - name: Maps children: -- cgit v1.2.1