diff options
author | Minh Nguyễn <mxn@1ec5.org> | 2016-12-23 17:47:51 -0800 |
---|---|---|
committer | Minh Nguyễn <mxn@1ec5.org> | 2017-01-04 21:39:08 -0800 |
commit | 0fac9d5674453f587a4c86f71b06da668f8cae27 (patch) | |
tree | 65aa1e2ab5a470c897befa375e43b7ae407505b8 /platform | |
parent | 50ae3eb3c0985567a0f86d08337d7cb8bed79a6c (diff) | |
download | qtlocation-mapboxgl-0fac9d5674453f587a4c86f71b06da668f8cae27.tar.gz |
[ios, macos] Added guide for working with GeoJSON
Diffstat (limited to 'platform')
-rw-r--r-- | platform/darwin/docs/guides/Working with GeoJSON Data.md | 89 | ||||
-rw-r--r-- | platform/ios/jazzy.yml | 1 | ||||
-rwxr-xr-x | platform/ios/scripts/document.sh | 2 | ||||
-rw-r--r-- | platform/macos/docs/guides/Info.plist Keys.md (renamed from platform/macos/docs/Info.plist Keys.md) | 8 | ||||
-rw-r--r-- | platform/macos/jazzy.yml | 1 | ||||
-rwxr-xr-x | platform/macos/scripts/document.sh | 2 |
6 files changed, 97 insertions, 6 deletions
diff --git a/platform/darwin/docs/guides/Working with GeoJSON Data.md b/platform/darwin/docs/guides/Working with GeoJSON Data.md new file mode 100644 index 0000000000..0fffed06dd --- /dev/null +++ b/platform/darwin/docs/guides/Working with GeoJSON Data.md @@ -0,0 +1,89 @@ +# Working with GeoJSON Data + +This SDK offers several ways to work with [GeoJSON](http://geojson.org/) files. +GeoJSON is a standard file format for representing geographic data. + +## Adding a GeoJSON file to the map + +You can use +[Mapbox Studio’s Datasets editor](https://www.mapbox.com/studio/datasets/) to +upload a GeoJSON file and include it in your custom map style. The GeoJSON data +will be hosted on Mapbox servers. When a user loads your style, the SDK +automatically loads the GeoJSON data for display. + +Alternatively, if you need to host the GeoJSON file elsewhere or bundle it with +your application, you can use a GeoJSON file as the basis of an `MGLShapeSource` +object. Pass the file’s URL into the +`-[MGLShapeSource initWithIdentifier:URL:options:]` initializer and add the +shape source to the map using the `-[MGLStyle addSource:]` method. The URL may +be a local file URL, an HTTP URL, or an HTTPS URL. + +Once you’ve added the GeoJSON file to the map via an `MGLShapeSource` object, +you can configure the appearance of its data and control what data is visible +using `MGLStyleLayer` objects, you can +[access the data programmatically](#Extracting GeoJSON data from the map). + +## Converting GeoJSON data into shape objects + +If you have GeoJSON data in the form of source code (also known as “GeoJSON +text”), you can convert it into an `MGLShape`, `MGLFeature`, or +`MGLShapeCollectionFeature` object that the `MGLShapeSource` class understands +natively. First, create an `NSData` object out of the source code string or file +contents, then pass that data object into the +`+[MGLShape shapeWithData:encoding:error:]` method. Finally, you can pass the +resulting shape or feature object into the +`-[MGLShapeSource initWithIdentifier:shape:options:]` initializer and add it to +the map, or you can use the object and its properties to power non-map-related +functionality in your application. + +## Extracting GeoJSON data from the map + +Any `MGLShape`, `MGLFeature`, or `MGLShapeCollectionFeature` object has an +`-[MGLShape geoJSONDataUsingEncoding:]` method that you can use to create a +GeoJSON source code representation of the object. You can extract a feature +object from the map using a method such as +`-[MGLMapView visibleFeaturesAtPoint:]`. + +## About GeoJSON deserialization + +The process of converting GeoJSON text into `MGLShape`, `MGLFeature`, or +`MGLShapeCollectionFeature` objects is known as “GeoJSON deserialization”. +GeoJSON geometries, features, and feature collections are known in this SDK as +shapes, features, and shape collection features, respectively. + +Each GeoJSON object type corresponds to a type provided by either this SDK or +the Core Location framework: + +GeoJSON object type | SDK type +--------------------|--------- +`Position` (longitude, latitude) | `CLLocationCoordinate2D` (latitude, longitude) +`Point` | `MGLPointAnnotation` +`MultiPoint` | `MGLPointCollection` +`LineString` | `MGLPolyline` +`MultiLineString` | `MGLMultiPolyline` +`Polygon` | `MGLPolygon` +Linear ring | `MGLPolygon.coordinates`, `MGLPolygon.interiorPolygons` +`MultiPolygon` | `MGLMultiPolygon` +`GeometryCollection` | `MGLShapeCollection` +`Feature` | `MGLFeature` +`FeatureCollection` | `MGLShapeCollectionFeature` + +A `Feature` object in GeoJSON corresponds to an instance of an `MGLShape` +subclass conforming to the `MGLFeature` protocol. There is a distinct +`MGLFeature`-conforming class for each type of geometry that a GeoJSON feature +can contain. This allows features to be used as shapes where convenient. For +example, some features can be added to a map view as annotations. + +In contrast to the GeoJSON standard, it is possible for `MGLShape` subclasses +other than `MGLPointAnnotation` to straddle the antimeridian. + +The following GeoJSON data types correspond straightforwardly to Foundation data +types when they occur as feature identifiers or property values: + +GeoJSON data type | Objective-C representation | Swift representation +-------------------|----------------------------|--------------------- +`null` | `NSNull` | `NSNull` +`true`, `false` | `NSNumber.boolValue` | `NSNumber.boolValue` +Integer | `NSNumber.unsignedLongLongValue`, `NSNumber.longLongValue` | `NSNumber.uint64Value`, `NSNumber.int64Value` +Floating-point number | `NSNumber.doubleValue` | `NSNumber.doubleValue` +String | `NSString` | `String` diff --git a/platform/ios/jazzy.yml b/platform/ios/jazzy.yml index 0a14cc3792..2473d0d1a3 100644 --- a/platform/ios/jazzy.yml +++ b/platform/ios/jazzy.yml @@ -21,6 +21,7 @@ custom_categories: - Runtime Styling - Working with Mapbox Studio - Info.plist Keys + - Working with GeoJSON Data - name: Maps children: - MGLAccountManager diff --git a/platform/ios/scripts/document.sh b/platform/ios/scripts/document.sh index ec349d592d..d66742a33f 100755 --- a/platform/ios/scripts/document.sh +++ b/platform/ios/scripts/document.sh @@ -41,7 +41,7 @@ jazzy \ --github-file-prefix https://github.com/mapbox/mapbox-gl-native/tree/${BRANCH} \ --module-version ${SHORT_VERSION} \ --readme ${README} \ - --documentation="platform/ios/docs/guides/*.md" \ + --documentation="platform/{darwin,ios}/docs/guides/*.md" \ --root-url https://www.mapbox.com/ios-sdk/api/${RELEASE_VERSION}/ \ --theme ${THEME} \ --output ${OUTPUT} diff --git a/platform/macos/docs/Info.plist Keys.md b/platform/macos/docs/guides/Info.plist Keys.md index a92b6fe296..f61ad8c7a7 100644 --- a/platform/macos/docs/Info.plist Keys.md +++ b/platform/macos/docs/guides/Info.plist Keys.md @@ -1,6 +1,6 @@ # Info.plist Keys -The Mapbox macOS SDK supports custom `Info.plist` keys in your application in order to configure various settings. +The Mapbox macOS SDK supports custom `Info.plist` keys in your application in order to configure various settings. ## MGLMapboxAccessToken @@ -8,10 +8,10 @@ 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 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. ## MGLMapboxAPIBaseURL -Use this key if you need to customize the API base URL used throughout the SDK. If unset, the default Mapbox API is used. +Use this key if you need to customize the API base URL used throughout the SDK. If unset, the default Mapbox API is used. -The default value is `https://api.mapbox.com`. +The default value is `https://api.mapbox.com`. diff --git a/platform/macos/jazzy.yml b/platform/macos/jazzy.yml index 27202968ef..f237ba72bc 100644 --- a/platform/macos/jazzy.yml +++ b/platform/macos/jazzy.yml @@ -17,6 +17,7 @@ custom_categories: - name: Guides children: - Info.plist Keys + - Working with GeoJSON Data - name: Maps children: - MGLAccountManager diff --git a/platform/macos/scripts/document.sh b/platform/macos/scripts/document.sh index d03ad91674..22b7685c7e 100755 --- a/platform/macos/scripts/document.sh +++ b/platform/macos/scripts/document.sh @@ -38,7 +38,7 @@ jazzy \ --github-file-prefix https://github.com/mapbox/mapbox-gl-native/tree/${BRANCH} \ --module-version ${SHORT_VERSION} \ --readme ${README} \ - --documentation="platform/macos/docs/Info.plist Keys.md" \ + --documentation="platform/{darwin,macos}/docs/guides/*.md" \ --theme platform/darwin/docs/theme \ --output ${OUTPUT} # https://github.com/realm/jazzy/issues/411 |