diff options
Diffstat (limited to 'platform/ios/docs')
21 files changed, 378 insertions, 274 deletions
diff --git a/platform/ios/docs/guides/Adding Markers to a Map.md b/platform/ios/docs/guides/Adding Markers to a Map.md new file mode 100644 index 0000000000..b33b536d44 --- /dev/null +++ b/platform/ios/docs/guides/Adding Markers to a Map.md @@ -0,0 +1,62 @@ +# Adding Markers to a Map + +Mapbox offers a few different ways to add markers to a map, each with different tradeoffs. Below is an overview of the variety of approaches that can be used. + +## **Annotations API** + +Our annotations API includes the `MGLAnnotationImage`, and `MGLAnnotationView` classes. These are most similar to MapKit’s annotation class and provide a familiar interface for working with markers and callouts. + +| <img src="img/adding-points-to-a-map/annotation-image.png" alt="MGLAnnotationImage" style="height: 500px;"/> | <img src="img/adding-points-to-a-map/annotation-view.png" alt="MGLAnnotationView" style="height: 500px;"/> | +|----------------------|---------------------| +| `MGLAnnotationImage` | `MGLAnnotationView` | + +**MGLAnnotationImage** is an annotation class that is easily customizable with any `UIImage`. +It is highly performant, as the images are rendered directly using OpenGL. However, if you need to animate your annotations or control z-layer ordering, consider working with **MGLAnnotationView** which supports any animation that can be applied to a `UIView`. View hierarchy can be manipulated by using instance methods available on `UIView` such as `-[UIView bringSubviewToFront:]`. + +**MGLAnnotationView** is an annotation class that is an easily customizable `UIView`. Use this class if you need your markers to be dynamic or animated. `MGLAnnotationView` has a significant advantage over `MGLAnnotationImage` when you need every annotation to be unique. For example, annotation views are ideal for showing user locations on a map using high-resolution profile pictures. However, the map can slow down when many annotation views are visible at the same time, so if you need to add a very large number of markers, consider using our runtime styling APIs instead. + +Both `MGLAnnotationImage` and `MGLAnnotationView` can become interactive by adding a [few lines of code](https://www.mapbox.com/ios-sdk/examples/marker/). When the user taps an annotation, the annotation’s name appears in a basic callout. An annotation view can additionally respond to [drag-and-drop gestures](https://www.mapbox.com/ios-sdk/examples/draggable-views/). + +## **Runtime styling API** + +For full control of how markers are displayed on a map, consider using our [runtime styling](runtime-styling.html) APIs. Like `MGLAnnotationImage`, it is a performant approach to adding markers because they rendered directly using OpenGL. However, the runtime styling APIs also provide support for rendering labels together with icons, finer control of z-ordering, and clustering, so consider using this set of APIs if you need to display a large amount of highly customizable markers. + +Our runtime styling API is the most powerful option if you need to create rich data visualizations within in your map, but it is the most complex and has a steeper learning curve than our annotations API. + +The runtime styling API includes our `MGLSymbolStyleLayer` and `MGLCircleStyleLayer` classes that can be used to dynamically display on markers on map when used in conjunction with either an `MGLVectorSource` or an `MGLShapeSource`. + +If you need to implement callouts with the `MGLSymbolStyleLayer` or `MGLCircleStyleLayer`, you will need to implement your own tap gesture recognizer that calls `-[MGLMapView visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:]` to get the tapped point feature, then show a `UIView` you provide. Additionally, if you need to animate markers when using the runtime styling APIs, consider using a timer to update the source data coordinates accordingly. + +| <img src="img/adding-points-to-a-map/circle-layer.png" alt="MGLCircleStyleLayer" style="height: 500px;"/> | <img src="img/adding-points-to-a-map/symbol-layer.png" alt="MGLSymbolStyleLayer" style="height: 500px;"/> | +|----------------------|---------------------| +| `MGLCircleStyleLayer` | `MGLSymbolStyleLayer` | + +The **MGLCircleStyleLayer** class is the style layer class responsible for displaying the source’s point features as circle-shaped markers. You can specify circle fill and outline colors, as well as size. You can also dynamically change the circle’s styling properties based on any attributes your source data contains. + +The **MGLSymbolStyleLayer** class is the style layer class responsible for displaying the source’s point features as icons and labels. You can use custom images as icons and also combine text labels, placing them exactly where you specify. You can also dynamically change the symbol’s styling properties based on any attributes your source data contains. + +Still undecided on which approach will work best for your use case? [Reach out to our support team](https://www.mapbox.com/contact/). + +See the table below for a summary of APIs that can be used to add markers to a map: + +✅ Recommended + +⚠️ Supported with caveats + +➖ Unavailable or not supported + + +| Feature | MGLAnnotationView | MGLAnnotationImage | MGLSymbolStyleLayer | MGLCircleStyleLayer | +|----------------------------------------------------|--------------------------------------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------| +| Customizability | ✅ Text labels, interactive subviews | ⚠️ Static images only | ✅ Full support for text labels and label placement | ✅Customize circle color and outline | +| Borrows familiar concepts from | MapKit, Google Maps SDK | ➖ | Mapbox GL JS, Mapbox Studio | Mapbox GL JS, Mapbox Studio | +| Can use images | ✅ | ✅ | ✅ | ➖ | +| Can use text | ✅ | ➖ | ✅ | ➖ | +| Control Z-index | ✅ | ➖ | ⚠️ Add multiple layers at, above, or below a specified layer index to control ordering | ⚠️ Add multiple layers at, above, or below a specified layer index to control ordering | +| Drag and drop | ✅ | ➖ | ➖ | ➖ | +| Core Animation support | ✅ | ➖ | ➖ | ➖ | +| Add/move/replace data | ✅ | ✅ | ⚠️ Partial data updates are less performant than using annotations | ⚠️ Partial data updates are less performant than using annotations | +| SceneKit support | ✅ | ➖ | ➖ | ➖ | +| Can be dynamically styled based on data attributes | ✅ Subclass `MGLPointAnnotation` to add custom attributes | ✅ Subclass `MGLPointAnnotation` to add custom attributes | ✅ | ✅ | +| Supports callouts | ✅ Built-in callouts included | ✅ Built-in callouts included | ⚠️ Implement your own gesture recognizer that uses feature querying, then create custom UIViews to mimic native callouts | ⚠️ Implement your own gesture recognizer that uses feature querying, then create custom UIViews to mimic native callouts | +| Supports clustering | ⚠️ Use a [third-party plugin](https://github.com/hulab/ClusterKit/) | ➖ | ✅ | ✅ | diff --git a/platform/ios/docs/guides/Adding Points to a Map.md b/platform/ios/docs/guides/Adding Points to a Map.md deleted file mode 100644 index 2844075cc7..0000000000 --- a/platform/ios/docs/guides/Adding Points to a Map.md +++ /dev/null @@ -1,82 +0,0 @@ -# Adding Points to a Map - -Mapbox offers a few different ways to add points to a map, each with different tradeoffs. - -## MGLPointAnnotation - -It’s straightforward to add an annotation to a map. You can use `MGLPointAnnotation` as is, or you can subclass it to add annotations with richer data. - -```swift -let annotation = MGLPointAnnotation() -annotation.coordinate = CLLocationCoordinate2D(latitude: 45.5076, longitude: -122.6736) -annotation.title = "Bobby's Coffee" -annotation.subtitle = "Coffeeshop" -mapView.addAnnotation(annotation) -``` - -See the `MGLMapViewDelegate` method `-mapView:annotationCanShowCallout:` and similar methods for allowing interaction with a callout ([example](https://www.mapbox.com/ios-sdk/examples/callout-delegate/)). - -## Displaying annotations - -There are two basic ways to display the annotations you’ve added to a map, each with their own tradeoffs. - -### Annotation Images (`MGLAnnotationImage`) - -Annotation images are the quickest and most performant way to display annotations, but are also the most basic. - -By default, annotations added to the map are displayed with a red pin ([example](https://www.mapbox.com/ios-sdk/examples/marker/)). To use custom images, you can implement `MGLMapViewDelegate` `-mapView:imageForAnnotation:` ([example](https://www.mapbox.com/ios-sdk/examples/marker-image/)). - -**Pros** - -* The easiest way to display a marker on a map -* Easily customizable with any `UIImage` -* High performance, as the images are rendered directly in OpenGL - -**Cons** - -* Annotation images are purely static and cannot be animated -* No control over z-ordering - -### Annotation Views (`MGLAnnotationView`) - -If you’re looking to add custom `UIView`s or have annotations that are dynamic or animatable, consider an `MGLAnnotationView` instead of an `MGLAnnotationImage` ([example](https://www.mapbox.com/ios-sdk/examples/annotation-views/)). - -Annotation views have significant advantages over annotation images when you need every annotation to be unique. For example, annotation views are ideal for showing user locations on a map using high-resolution profile pictures. - -To use annotation views, implement `MGLMapViewDelegate` `-mapView:viewForAnnotation` and provide a custom `MGLAnnotationView` (`UIView`) subclass. - -**Pros** - -* Custom, native UIViews -* No limit on style or image size -* Full support for animations -* Relative control over z-ordering using the `zPosition` property on `CALayer` -* Familiar API for MapKit users - -**Cons** - -* Performance implications: - * `UIView`s are inherently slow to render compared to OpenGL, more apparent if you’re adding many views or moving the map rapidly - * In some cases, you might consider runtime styling - -## Advanced: Runtime Styling - -For absolute full control of how points are displayed on a map, consider [runtime styling](runtime-styling.html). - -You can use `MGLPointFeature` or any other [style primitives](Style%20Primitives.html) to add points and shapes to an `MGLShapeSource`. - -From there, you can create one or many `MGLSymbolStyleLayer` or `MGLCircleStyleLayer` layers to filter and style points for display on the map ([example](https://www.mapbox.com/ios-sdk/examples/runtime-multiple-annotations)). - -**Pros** - -* Most powerful option -* Highest performance (rendered in GL directly) -* SDK-level support for labels rendered together with icons -* Finer control of z-ordering - * Rendering respects ordering within the data source - * Otherwise layers are lightweight so you can create a new layer for each level you need - -**Cons** - -* Currently you must implement your own tap gesture recognizer together with `MGLMapView.visibleFeaturesAtPoint` to recognize taps and manually show callouts ([example](https://www.mapbox.com/ios-sdk/examples/select-layer/)). -* Currently no SDK support for animations. If you need animations, consider using an NSTimer and updating the layer properties accordingly. diff --git a/platform/ios/docs/guides/For Style Authors.md b/platform/ios/docs/guides/For Style Authors.md index c4aabb0410..b3beea8540 100644 --- a/platform/ios/docs/guides/For Style Authors.md +++ b/platform/ios/docs/guides/For Style Authors.md @@ -127,21 +127,22 @@ source object is a member of one of the following subclasses of `MGLSource`: In style JSON | In the SDK --------------|----------- +`vector` | `MGLVectorTileSource` +`raster` | `MGLRasterTileSource` +`raster-dem` | `MGLRasterDEMSource` `geojson` | `MGLShapeSource` -`raster` | `MGLRasterSource` -`vector` | `MGLVectorSource` `image` | `MGLImageSource` `canvas` and `video` sources are not supported. ### Tile sources -Raster and vector sources may be defined in TileJSON configuration files. This -SDK supports the properties defined in the style specification, which are a +Raster and vector tile sources may be defined in TileJSON configuration files. +This SDK supports the properties defined in the style specification, which are a subset of the keys defined in version 2.1.0 of the [TileJSON](https://github.com/mapbox/tilejson-spec/tree/master/2.1.0) specification. As an alternative to authoring a custom TileJSON file, you may -supply various tile source options when creating a raster or vector source. +supply various tile source options when creating a raster or vector tile source. These options are detailed in the `MGLTileSourceOption` documentation: In style JSON | In TileJSON | In the SDK @@ -311,6 +312,11 @@ defined by the style specification. ### Expression operators +Many expression operators defined in the style specification have corresponding +symbols to be used with the `+[NSExpression expressionWithFormat:]`, +`+[NSExpression expressionForFunction:arguments:]`, or +`+[NSExpression expressionForFunction:selectorName:arguments:]` method: + In style specification | Method, function, or predicate type | Format string syntax -----------------------|-------------------------------------|--------------------- `array` | | @@ -320,15 +326,15 @@ In style specification | Method, function, or predicate type | Format string syn `string` | | `to-boolean` | `boolValue` | `to-color` | | -`to-number` | `mgl_numberWithFallbackValues:` | -`to-string` | `stringValue` | +`to-number` | `mgl_numberWithFallbackValues:` | `CAST(zipCode, 'NSNumber')` +`to-string` | `stringValue` | `CAST(ele, 'NSString')` `typeof` | | -`geometry-type` | | -`id` | | -`properties` | | -`at` | | +`geometry-type` | `NSExpression.geometryTypeVariableExpression` | `$geometryType` +`id` | `NSExpression.featureIdentifierVariableExpression` | `$featureIdentifier` +`properties` | `NSExpression.featureAttributesVariableExpression` | `$featureAttributes` +`at` | `objectFrom:withIndex:` | `array[n]` `get` | `+[NSExpression expressionForKeyPath:]` | Key path -`has` | | +`has` | `mgl_does:have:` | `mgl_does:have:(self, 'key')` `length` | `count:` | `count({1, 2, 2, 3, 4, 7, 9})` `!` | `NSNotPredicateType` | `NOT (p0 OR … OR pn)` `!=` | `NSNotEqualToPredicateOperatorType` | `key != value` @@ -339,17 +345,16 @@ In style specification | Method, function, or predicate type | Format string syn `>=` | `NSGreaterThanOrEqualToPredicateOperatorType` | `key >= value` `all` | `NSAndPredicateType` | `p0 AND … AND pn` `any` | `NSOrPredicateType` | `p0 OR … OR pn` -`case` | `+[NSExpression expressionForConditional:trueExpression:falseExpression:]` | `TERNARY(condition, trueExpression, falseExpression)` -`coalesce` | | -`match` | | -`interpolate` | `mgl_interpolateWithCurveType:parameters:stops:` | -`step` | `mgl_stepWithMinimum:stops:` | -`let` | `mgl_expressionWithContext:` | +`case` | `+[NSExpression expressionForConditional:trueExpression:falseExpression:]` or `MGL_IF` or `+[NSExpression mgl_expressionForConditional:trueExpression:falseExpresssion:]` | `TERNARY(1 = 2, YES, NO)` or `MGL_IF(1 = 2, YES, 2 = 2, YES, NO)` +`coalesce` | `mgl_coalesce:` | `mgl_coalesce({x, y, z})` +`match` | `MGL_MATCH` or `+[NSExpression mgl_expressionForMatchingExpression:inDictionary:defaultExpression:]` | `MGL_MATCH(x, 0, 'zero match', 1, 'one match', 'two match', 'default')` +`interpolate` | `mgl_interpolate:withCurveType:parameters:stops:` or `+[NSExpression mgl_expressionForInterpolatingExpression:withCurveType:parameters:stops:]` | +`step` | `mgl_step:withMinimum:stops:` or `+[NSExpression mgl_expressionForSteppingExpression:fromExpression:stops:]` | +`let` | `mgl_expressionWithContext:` | `MGL_LET('ios', 11, 'macos', 10.13, $ios + $macos)` `var` | `+[NSExpression expressionForVariable:]` | `$variable` -`concat` | `stringByAppendingString:` | +`concat` | `mgl_join:` or `-[NSExpression mgl_expressionByAppendingExpression:]` | `mgl_join({'Old', ' ', 'MacDonald'})` `downcase` | `lowercase:` | `lowercase('DOWNTOWN')` `upcase` | `uppercase:` | `uppercase('Elysian Fields')` - `rgb` | `+[UIColor colorWithRed:green:blue:alpha:]` | `rgba` | `+[UIColor colorWithRed:green:blue:alpha:]` | `to-rgba` | | @@ -359,27 +364,34 @@ In style specification | Method, function, or predicate type | Format string syn `%` | `modulus:by:` | `^` | `raise:toPower:` | `2 ** 2` `+` | `add:to:` | `1 + 2` -`acos` | | -`asin` | | -`atan` | | -`cos` | | +`abs` | `abs:` | `abs(-1)` +`acos` | `mgl_acos:` | `mgl_acos(1)` +`asin` | `mgl_asin:` | `mgl_asin(0)` +`atan` | `mgl_atan:` | `mgl_atan(20)` +`ceil` | `ceiling:` | `ceiling(0.99999)` +`cos` | `mgl_cos:` | `mgl_cos(0)` `e` | | `%@` representing `NSNumber` containing `M_E` +`floor` | `floor:` | `floor(-0.99999)` `ln` | `ln:` | `ln(2)` `ln2` | | `%@` representing `NSNumber` containing `M_LN2` `log10` | `log:` | `log(1)` -`log2` | | +`log2` | `mgl_log2:` | `mgl_log2(1024)` `max` | `max:` | `max({1, 2, 2, 3, 4, 7, 9})` `min` | `min:` | `min({1, 2, 2, 3, 4, 7, 9})` `pi` | | `%@` representing `NSNumber` containing `M_PI` -`sin` | | +`round` | `mgl_round:` | `mgl_round(1.5)` +`sin` | `mgl_sin:` | `mgl_sin(0)` `sqrt` | `sqrt:` | `sqrt(2)` -`tan` | | -`zoom` | | `$zoom` -`heatmap-density` | | `$heatmapDensity` +`tan` | `mgl_tan:` | `mgl_tan(0)` +`zoom` | `NSExpression.zoomLevelVariableExpression` | `$zoom` +`heatmap-density` | `NSExpression.heatmapDensityVariableExpression` | `$heatmapDensity` + +For operators that have no corresponding `NSExpression` symbol, use the +`MGL_FUNCTION()` format string syntax. ## Filtering sources -You can filter a shape or vector source by setting the +You can filter a shape or vector tile source by setting the `MGLVectorStyleLayer.predicate` property to an `NSPredicate` object. Below is a table of style JSON operators and the corresponding operators used in the predicate format string: diff --git a/platform/ios/docs/guides/Info.plist Keys.md b/platform/ios/docs/guides/Info.plist Keys.md index bc2f3f5786..cf00ec5499 100644 --- a/platform/ios/docs/guides/Info.plist Keys.md +++ b/platform/ios/docs/guides/Info.plist Keys.md @@ -8,7 +8,7 @@ Set the [Mapbox access token](https://www.mapbox.com/help/define-access-token/) Mapbox-hosted vector tiles and styles require an API access token, which you can obtain from the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). Access tokens associate requests to Mapbox’s vector tile and style APIs with your Mapbox account. They also deter other developers from using your styles without your permission. -As an alternative, you can use `+[MGLAccountManager setAccessToken:]` to set a token in code. See [our guide](https://www.mapbox.com/help/ios-private-access-token/) for some tips on keeping access tokens in open source code private. +As an alternative, you can use `MGLAccountManager.accessToken` to set a token in code. See [our guide](https://www.mapbox.com/help/ios-private-access-token/) for some tips on keeping access tokens in open source code private. ## MGLMapboxAPIBaseURL diff --git a/platform/ios/docs/guides/Migrating to Expressions.md b/platform/ios/docs/guides/Migrating to Expressions.md new file mode 100644 index 0000000000..96d4df6853 --- /dev/null +++ b/platform/ios/docs/guides/Migrating to Expressions.md @@ -0,0 +1,266 @@ +<!-- + This file is generated. + Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`. +--> + +# Migrating from Style Functions to Expressions + +[Runtime Styling](runtime-styling.html) enables you to modify every aspect of the map’s appearance dynamically as a user interacts with your application. Developers can specify in advance how a layout or paint attribute will vary as the zoom level changes or how the appearance of individual features vary based on metadata provided by a content source. + +With Mapbox Maps SDK for iOS v4.0.0, style functions have been replaced with expressions. These provide even more tools for developers who want to style their maps dynamically. This guide outlines some tips for migrating from style functions to expressions, and offers an overview of some things that developers can do with expressions. + +An expression is represented at runtime by the `NSExpression` class. Expressions can be used to style paint and layout properties based on zoom level, data attributes, or a combination of the two. + +A constant expression can also be assigned to a style property. For example, the opacity of a fill style layer can be set to a constant value between 0 and 1. + +The documentation for each individual style layer property notes which non-constant expressions are enabled for that property. Style functions supported four interpolation modes: exponential, interval, categorical, and identity. + +This guide uses earthquake data from the [U.S. Geological Survey](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php). Under each interpolation mode, the style function implementation will be shown, followed by the current syntax. + +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. To learn more about supported expressions, see our ["Predicates and Expressions"](predicates-and-expressions.html) guide. The "Predicates and Expressions" guide also outlines Mapbox custom functions that can be used to dynamically style a map. + +## Stops +Stops are dictionary keys that are associated with layer attribute values. Constant values no longer need to be wrapped as style values when they are values in a stops dictionary. + + +Style function syntax: + +```swift +let stops = [ + 0: MGLStyleValue<UIColor>(rawValue: .yellow), + 2.5: MGLStyleValue(rawValue: .orange), + 5: MGLStyleValue(rawValue: .red), + 7.5: MGLStyleValue(rawValue: .blue), + 10: MGLStyleValue(rawValue: .white), +] +``` + +Current syntax: +```swift +let stops: [NSNumber: UIColor] = [ + 0: .yellow, + 2.5: .orange, + 5: .red, + 7.5: .blue, + 10: .white, +] +``` + + +## Interpolation mode + +Style functions supported four interpolation modes: exponential/linear, interval, categorical, and identity. For more information about supported custom expressions, please see the "Predicates and Expressions" guide. + +### Linear + +`+[NSExpression(MGLAdditions) mgl_expressionForInterpolatingExpression:withCurveType:parameters:stops:]` takes the interpolation type as a parameter. If you previously used the default interpolation base, use the curve type `MGLExpressionInterpolationMode.linear`. See the [`mgl_interpolate:withCurveType:parameters:stops:`](predicates-and-expressions.html#code-mgl_interpolate-withcurvetype-parameters-stops-code) documentation for more details. + +The stops dictionary below, shows colors that continuously shift from yellow to orange to red to blue to white based on the attribute value. + +Style function syntax: + +```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) +mapView.style?.addSource(source) + +let stops = [ + 0: MGLStyleValue<UIColor>(rawValue: .yellow), + 2.5: MGLStyleValue(rawValue: .orange), + 5: MGLStyleValue(rawValue: .red), + 7.5: MGLStyleValue(rawValue: .blue), + 10: MGLStyleValue(rawValue: .white), +] + +let layer = MGLCircleStyleLayer(identifier: "circles", source: source) +layer.circleColor = MGLStyleValue(interpolationMode: .exponential, + sourceStops: stops, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .green)]) +layer.circleRadius = MGLStyleValue(rawValue: 10) +mapView.style?.insertLayer(layer, below: symbolLayer) +``` + +Current syntax: + +```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) +mapView.style?.addSource(source) + +let stops: [NSNumber: UIColor] = [ + 0: .yellow, + 2.5: .orange, + 5: .red, + 7.5: .blue, + 10: .white, +] + +let layer = MGLCircleStyleLayer(identifier: "circles", source: source) +layer.circleColor = NSExpression(format: "mgl_interpolate:withCurveType:parameters:stops:(mag, 'linear', nil, %@)", + stops) +layer.circleRadius = NSExpression(forConstantValue: 10) +mapView.style?.insertLayer(layer, below: symbolLayer) +``` + +### Exponential + +If you previously used an interpolation base greater than `0` (other than `1`), you can use `MGLExpressionInterpolationMode.exponential` as the curve type for `+[NSExpression(MGLAdditions) mgl_expressionForInterpolatingExpression:withCurveType:parameters:stops:]` or `'exponential'` as the curve type for [`mgl_interpolate:withCurveType:parameters:stops:`](predicates-and-expressions.html#code-mgl_interpolate-withcurvetype-parameters-stops-code). The `parameters` argument takes that interpolation base. This interpolates between values exponentially, creating an accelerated ramp effect. + +Here’s a visualization from Mapbox Studio (see [Working with Mapbox Studio](working-with-mapbox-studio.html)) comparing interpolation base values of `1.5` and `0.5` based on zoom. In order to convert camera style functions, use `$zoomLevel` or `MGL_FUNCTION('zoomLevel')` as the attribute key. + +<img src="img/data-driven-styling/exponential-function.png" height=344/> +<img src="img/data-driven-styling/exponential-function-1.png" height=344/> + +The example below increases a layer’s `circleRadius` exponentially based on a map’s zoom level. The interpolation base is `1.5`. + +Style function syntax: + +```swift +let stops = [ + 12: MGLStyleValue<NSNumber>(rawValue: 0.5), + 14: MGLStyleValue(rawValue: 2), + 18: MGLStyleValue(rawValue: 18), +] + +layer.circleRadius = MGLStyleValue(interpolationMode: .exponential, + cameraStops: stops, + options: [.interpolationBase: 1.5]) +``` + +Current syntax: + +```swift +let stops = [ + 12: 0.5, + 14: 2, + 18: 18, +] + +layer.circleRadius = NSExpression(format: "mgl_interpolate:withCurveType:parameters:stops:($zoomLevel, 'exponential', 1.5, %@)", + stops) +``` + +### Interval + +Steps, or intervals, create 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 layout or paint value assigned to that key. You can use the `+[NSExpression(MGLAdditions) mgl_expressionForSteppingExpression:fromExpression:stops:]` method or the custom function [`mgl_step:from:stops:`](predicates-and-expressions.html#code-mgl_step-from-stops-code) for cases where you previously used interval interpolation mode. The first parameter takes the feature attribute name and the second parameter (`from:`) optionally takes the default or fallback value for that function. The final parameter takes a stops dictionary as an argument. + +When we use the stops dictionary given above with an `'mgl_step:from:stops:'`, 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. + +Style function syntax: + +```swift +let stops = [ + 0: MGLStyleValue<UIColor>(rawValue: .yellow), + 2.5: MGLStyleValue(rawValue: .orange), + 5: MGLStyleValue(rawValue: .red), + 7.5: MGLStyleValue(rawValue: .blue), + 10: MGLStyleValue(rawValue: .white), +] + +layer.circleColor = MGLStyleValue(interpolationMode: .interval, + sourceStops: stops, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .green)]) +```` + +Current syntax: + +```swift +let stops: [NSNumber: UIColor] = [ + 0: .yellow, + 2.5: .orange, + 5: .red, + 7.5: .blue, + 10: .white, +] + +layer.circleColor = NSExpression(format: "mgl_step:from:stops:(mag, %@, %@)", + UIColor.green, stops) +``` + +### Categorical + +Categorical interpolation mode took a stops dictionary. If the value for a specified feature attribute name matched one in that stops dictionary, the style value for that attribute value would be used. Categorical style functions can now be replaced with `MGL_MATCH`. + +`MGL_MATCH` takes an initial condition, which in this case is an attribute key. This is followed by possible matches for that key and the value to assign to the layer property if there is a match. The final argument can be a default style value that is to be used if none of the specified values match. + +There are three main types of events in the USGS 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 blue to catch any events that do not fall into any of those categories. + +Style function syntax: + +```swift +let categoricalStops = [ + "earthquake": MGLStyleValue<UIColor>(rawValue: .orange), + "explosion": MGLStyleValue(rawValue: .red), + "quarry blast": MGLStyleValue(rawValue: .yellow), +] + +layer.circleColor = MGLStyleValue(interpolationMode: .categorical, + sourceStops: categoricalStops, + attributeName: "type", + options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .blue)]) +``` + +Current syntax: +```swift +let defaultColor = UIColor.blue +layer.circleColor = NSExpression(format: "MGL_MATCH(type, 'earthquake', %@, 'explosion', %@, 'quarry blast', %@, %@)", + UIColor.orange, UIColor.red, UIColor.yellow, defaultColor) +``` + +If your use case does not require a default value, you can either apply a predicate to your layer prior to styling it, or use the format string `"valueForKeyPath:"`. + +### Identity + +Identity interpolation mode used the attribute’s value as the style layer property value. In this example, you might set the `circleRadius` to the earthquake’s magnitude. In order to use a feature attribute value to style a layer property, set the property value to `[NSExpression expressionForKeyPath:]`, which take the feature attribute name as an argument. + +Style function syntax: + +```swift +layer.circleRadius = MGLStyleValue(interpolationMode: .identity, + sourceStops: nil, + attributeName: "mag", + options: [.defaultValue: MGLStyleValue<NSNumber>(rawValue: 0)]) +``` + +Current syntax: +```swift +layer.circleRadius = NSExpression(forKeyPath: "mag") +``` + + + +Some built-in functions can be applied to attribute values to style layer property values. To set the circle radius to three times the earthquake’s magnitude, create a `multiply:by:` function that takes the attribute value and the multiplier as arguments, or use a format string. + +```swift +layer.circleRadius = NSExpression(forFunction: "multiply:by:", arguments: [NSExpression(forKeyPath: "mag"), 3]) +``` + + + +You can also cast attribute values in order to use them. One example is to cast an integer as an `NSString` and use it as a text value. + +```swift +let magnitudeLayer = MGLSymbolStyleLayer(identifier: "mag-layer", source: source) +magnitudeLayer.text = NSExpression(format: "CAST(mag, 'NSString')") +mapView.style?.addLayer(magnitudeLayer) +``` + + + +### Constant Values + +For constant values that do not necessarily change based on camera or attribute values, use `[NSExpression expressionForConstantValue:]` (previously `[MGLStyleValue valueWithRawValue:]`). + +## Resources + +* [USGS Earthquake Feed](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) +* [For Style Authors](for-style-authors.html) +* [Predicates and Expressions](predicates-and-expressions.html) diff --git a/platform/ios/docs/guides/Tile URL Templates.md b/platform/ios/docs/guides/Tile URL Templates.md index f61d2ea33a..4c8064f781 100644 --- a/platform/ios/docs/guides/Tile URL Templates.md +++ b/platform/ios/docs/guides/Tile URL Templates.md @@ -4,12 +4,12 @@ --> # Tile URL Templates -`MGLTileSource` objects, specifically `MGLRasterSource` and `MGLVectorSource` -objects, can be created using an initializer that accepts an array of tile URL -templates. Tile URL templates are strings that specify the URLs of the vector -tiles or raster tile images to load. A template resembles an absolute URL, but -with any number of placeholder strings that the source evaluates based on the -tile it needs to load. For example: +`MGLTileSource` objects, specifically `MGLRasterTileSource` and +`MGLVectorTileSource` objects, can be created using an initializer that accepts +an array of tile URL templates. Tile URL templates are strings that specify the +URLs of the vector tiles or raster tile images to load. A template resembles an +absolute URL, but with any number of placeholder strings that the source +evaluates based on the tile it needs to load. For example: * `http://www.example.com/tiles/{z}/{x}/{y}.pbf` could be evaluated as `http://www.example.com/tiles/14/6/9.pbf`. @@ -56,7 +56,7 @@ all of which are optional: <td>The tile’s zoom level. At zoom level 0, each tile covers the entire world map; at zoom level 1, it covers ¼ of the world; at zoom level 2, <sup>1</sup>⁄<sub>16</sub> of the world, and so on. For tiles loaded by - a <code>MGLRasterSource</code> object, whether the tile zoom level + a <code>MGLRasterTileSource</code> object, whether the tile zoom level matches the map’s current zoom level depends on the value of the source’s tile size as specified in the <code>MGLTileSourceOptionTileSize</code> key of the <code>options</code> diff --git a/platform/ios/docs/guides/Using Style Functions at Runtime.md b/platform/ios/docs/guides/Using Style Functions at Runtime.md deleted file mode 100644 index 0b4e842e0e..0000000000 --- a/platform/ios/docs/guides/Using Style Functions at Runtime.md +++ /dev/null @@ -1,154 +0,0 @@ -<!-- - This file is generated. - Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`. ---> - -# Using Style Functions at Runtime - -[Runtime Styling](runtime-styling.html) enables you to modify every aspect of the map’s appearance dynamically as a user interacts with your application. Much of the runtime styling API allows you to specify _style functions_ instead of constant values. A style function allows you to specify in advance how a layout or paint attribute will vary as the zoom level changes or how the appearance of individual features vary based on metadata provided by a content source. - -Style functions spare you the inconvenience of manually calculating intermediate values between different zoom levels or creating a multitude of style layers to handle homogeneous features in the map content. For example, if your content source indicates the prices of hotels in an area, you can color-code the hotels by price, relying on a style function to smoothly interpolate among desired colors without having to specify the color for each exact price. - -_Data-driven styling_ specifically refers to the use of style functions to vary the map’s appearance based on data in a content source. - -You can also specify style functions in a style JSON file, to be applied automatically when the map loads. See the [Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-js/style-spec/#types-function) for details. - -  - -This guide uses earthquake data from the [U.S. Geological Survey](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) and data-driven styling 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. - -A style function is represented at runtime by the `MGLStyleFunction` class. There are three subclasses of `MGLStyleFunction`: - -* `MGLCameraStyleFunction` is a style value that changes with zoom level. For example, you can make the radius of a circle increase according to zoom level. -* `MGLSourceStyleFunction` is a style value that changes with the attributes of a feature. For example, you can adjust the radius of a circle based on the magnitude of an earthquake. -* `MGLCompositeStyleFunction` is 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 each individual style layer property notes which style functions are enabled for that property. - -## Stops - -Stops are dictionary keys that are associated with layer attribute values. With feature attribute values as stops, you can use a dictionary with a zoom level for a key and an expression or constant value for the value. For example, you can use a stop dictionary with the zoom levels 0, 10, and 20 as keys and the colors yellow, orange, and red as the values. Alternatively, attribute values can be the keys. - -```swift -let stops: [Float: UIColor] = [ - 0: .yellow, - 2.5: .orange, - 5: .red, - 7.5: .blue, - 10: .white, -] -``` - -## 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. - -### Linear - -`MGLInterpolationModeExponential` interpolates linearly or exponentially between style function stop values. By default, the `MGLStyleFunction` options parameter `MGLStyleFunctionOptionInterpolationBase` equals `1`, which represents linear interpolation and doesn’t need to be included in the options dictionary. - -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) -mapView.style?.addSource(source) - -let stops: [Float: UIColor] = [ - 0: .yellow, - 2.5: .orange, - 5: .red, - 7.5: .blue, - 10: .white, -] - -let layer = MGLCircleStyleLayer(identifier: "circles", source: source) -layer.circleColor = NSExpression(format: "FUNCTION(mag, 'mgl_interpolateWithCurveType:parameters:stops:', 'linear', nil, %@)", - stops) -layer.circleRadius = NSExpression(forConstantValue: 10) -mapView.style?.insertLayer(layer, below: symbolLayer) -``` - - - -### Exponential - -By combining `MGLInterpolationModeExponential` with an `MGLStyleFunctionOptionInterpolationBase` greater than `0` (other than `1`), you can interpolate between values exponentially, create an accelerated ramp effect. - -Here’s a visualization from Mapbox Studio (see [Working with Mapbox Studio](working-with-mapbox-studio.html)) comparing interpolation base values of `1.5` and `0.5` based on zoom. - -<img src="img/data-driven-styling/exponential-function.png" height=344/> -<img src="img/data-driven-styling/exponential-function-1.png" height=344/> - -The example below increases a layer’s `circleRadius` exponentially based on a map’s zoom level. The `MGLStyleFunctionOptionInterpolationBase` is `1.5`. - -```swift -let stops = [ - 12: 0.5, - 14: 2, - 18: 18, -] - -layer.circleRadius = NSExpression(format: "FUNCTION($zoomLevel, 'mgl_interpolateWithCurveType:parameters:stops:', 'exponential', 1.5, %@)", - stops) -``` - -### 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 -let stops: [Float: UIColor] = [ - 0: .yellow, - 2.5: .orange, - 5: .red, - 7.5: .blue, - 10: .white, -] - -layer.circleColor = NSExpression(format: "FUNCTION(mag, 'mgl_stepWithMinimum:stops:', %@, %@)", - UIColor.green, stops) -``` - - - -### Categorical - -At each stop, `MGLInterpolationModeCategorical` produces an output value equal to 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 blue to catch any events that do not fall into any of those categories. - -```swift -let colors: [String: UIColor] = [ - "earthquake": .orange, - "explosion": .red, - "quarry blast": .yellow, -] -let defaultColor = UIColor.blue - -layer.circleColor = NSExpression( - format: "TERNARY(FUNCTION(%@, 'valueForKeyPath:', type) != nil, FUNCTION(%@, 'valueForKeyPath:', type), %@)", - colors, colors, defaultColor) -``` - -  - -### 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` should be set to `nil`. - -```swift -layer.circleRadius = NSExpression(forKeyPath: "mag") -``` - - - -##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/img/adding-points-to-a-map/annotation-image.png b/platform/ios/docs/img/adding-points-to-a-map/annotation-image.png Binary files differnew file mode 100644 index 0000000000..b9aa946363 --- /dev/null +++ b/platform/ios/docs/img/adding-points-to-a-map/annotation-image.png diff --git a/platform/ios/docs/img/adding-points-to-a-map/annotation-view.png b/platform/ios/docs/img/adding-points-to-a-map/annotation-view.png Binary files differnew file mode 100644 index 0000000000..90c181f664 --- /dev/null +++ b/platform/ios/docs/img/adding-points-to-a-map/annotation-view.png diff --git a/platform/ios/docs/img/adding-points-to-a-map/circle-layer.png b/platform/ios/docs/img/adding-points-to-a-map/circle-layer.png Binary files differnew file mode 100644 index 0000000000..5edf88e0da --- /dev/null +++ b/platform/ios/docs/img/adding-points-to-a-map/circle-layer.png diff --git a/platform/ios/docs/img/adding-points-to-a-map/symbol-layer.png b/platform/ios/docs/img/adding-points-to-a-map/symbol-layer.png Binary files differnew file mode 100644 index 0000000000..cff39b0bce --- /dev/null +++ b/platform/ios/docs/img/adding-points-to-a-map/symbol-layer.png diff --git a/platform/ios/docs/img/runtime-styling/CustomAnnotations.gif b/platform/ios/docs/img/runtime-styling/CustomAnnotations.gif Binary files differindex dee99d01fd..71d4c4a8a0 100644 --- a/platform/ios/docs/img/runtime-styling/CustomAnnotations.gif +++ b/platform/ios/docs/img/runtime-styling/CustomAnnotations.gif diff --git a/platform/ios/docs/img/runtime-styling/DynamicStyles.gif b/platform/ios/docs/img/runtime-styling/DynamicStyles.gif Binary files differindex b42d30c602..8854474ede 100644 --- a/platform/ios/docs/img/runtime-styling/DynamicStyles.gif +++ b/platform/ios/docs/img/runtime-styling/DynamicStyles.gif diff --git a/platform/ios/docs/img/runtime-styling/Emoji.gif b/platform/ios/docs/img/runtime-styling/Emoji.gif Binary files differindex fc50b28972..afb7a42693 100644 --- a/platform/ios/docs/img/runtime-styling/Emoji.gif +++ b/platform/ios/docs/img/runtime-styling/Emoji.gif diff --git a/platform/ios/docs/img/runtime-styling/HexBins.gif b/platform/ios/docs/img/runtime-styling/HexBins.gif Binary files differindex c810085f22..6078ac9e8d 100644 --- a/platform/ios/docs/img/runtime-styling/HexBins.gif +++ b/platform/ios/docs/img/runtime-styling/HexBins.gif diff --git a/platform/ios/docs/img/runtime-styling/Population.gif b/platform/ios/docs/img/runtime-styling/Population.gif Binary files differindex 81b6c6310f..8de14e6422 100644 --- a/platform/ios/docs/img/runtime-styling/Population.gif +++ b/platform/ios/docs/img/runtime-styling/Population.gif diff --git a/platform/ios/docs/img/runtime-styling/SnowLevels.gif b/platform/ios/docs/img/runtime-styling/SnowLevels.gif Binary files differindex 8ee2f9fddd..463e0398d2 100644 --- a/platform/ios/docs/img/runtime-styling/SnowLevels.gif +++ b/platform/ios/docs/img/runtime-styling/SnowLevels.gif diff --git a/platform/ios/docs/img/studio-workflow/add-properties.gif b/platform/ios/docs/img/studio-workflow/add-properties.gif Binary files differindex 740fae655b..6cab64c050 100644 --- a/platform/ios/docs/img/studio-workflow/add-properties.gif +++ b/platform/ios/docs/img/studio-workflow/add-properties.gif diff --git a/platform/ios/docs/img/studio-workflow/create-polygons.gif b/platform/ios/docs/img/studio-workflow/create-polygons.gif Binary files differindex 6eb2c0afb8..6383dd31df 100644 --- a/platform/ios/docs/img/studio-workflow/create-polygons.gif +++ b/platform/ios/docs/img/studio-workflow/create-polygons.gif diff --git a/platform/ios/docs/img/studio-workflow/property-values.png b/platform/ios/docs/img/studio-workflow/property-values.png Binary files differindex 95704241f9..2b85db80d6 100644 --- a/platform/ios/docs/img/studio-workflow/property-values.png +++ b/platform/ios/docs/img/studio-workflow/property-values.png diff --git a/platform/ios/docs/img/studio-workflow/stop-functions.png b/platform/ios/docs/img/studio-workflow/stop-functions.png Binary files differindex 4affecf005..8480cb2d53 100644 --- a/platform/ios/docs/img/studio-workflow/stop-functions.png +++ b/platform/ios/docs/img/studio-workflow/stop-functions.png |
