From 30b919196b72351c43a5834b66a36068c0588fe0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Minh=20Nguye=CC=82=CC=83n?= Date: Tue, 9 May 2017 18:36:20 -0700 Subject: [ios, macos] Factored out tile URL template guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Factored out redundant tile URL template documentation from the MGLRasterSource and MGLVectorSource documentation into a jazzy guide. This documentation used to live in one place, on a method on MGLTileSource, but that method had to be moved to MGLTileSource’s concrete subclasses. A jazzy guide is easier to link to, in any case. --- .../darwin/docs/guides/Tile URL Templates.md.ejs | 109 +++++++++++++++++++++ platform/darwin/scripts/generate-style-code.js | 13 ++- platform/darwin/src/MGLRasterSource.h | 91 +---------------- platform/darwin/src/MGLVectorSource.h | 91 +---------------- platform/ios/docs/guides/Tile URL Templates.md | 99 +++++++++++++++++++ platform/ios/jazzy.yml | 1 + platform/macos/docs/guides/Tile URL Templates.md | 98 ++++++++++++++++++ platform/macos/jazzy.yml | 1 + 8 files changed, 326 insertions(+), 177 deletions(-) create mode 100644 platform/darwin/docs/guides/Tile URL Templates.md.ejs create mode 100644 platform/ios/docs/guides/Tile URL Templates.md create mode 100644 platform/macos/docs/guides/Tile URL Templates.md diff --git a/platform/darwin/docs/guides/Tile URL Templates.md.ejs b/platform/darwin/docs/guides/Tile URL Templates.md.ejs new file mode 100644 index 0000000000..78fb297138 --- /dev/null +++ b/platform/darwin/docs/guides/Tile URL Templates.md.ejs @@ -0,0 +1,109 @@ +<% + const os = locals.os; + const iOS = os === 'iOS'; + //const macOS = os === 'macOS'; + //const cocoaPrefix = iOS ? 'UI' : 'NS'; +-%> + +# 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: + +* `http://www.example.com/tiles/{z}/{x}/{y}.pbf` could be + evaluated as `http://www.example.com/tiles/14/6/9.pbf`. +* `http://www.example.com/tiles/{z}/{x}/{y}{ratio}.png` could be + evaluated as `http://www.example.com/tiles/14/6/9@2x.png`. + +Tile URL templates are also used to define tilesets in TileJSON manifests or +[`raster`](https://www.mapbox.com/mapbox-gl-js/style-spec/#sources-raster-tiles) +and +[`vector`](https://www.mapbox.com/mapbox-gl-js/style-spec/#sources-vector-tiles) +sources in style JSON files. See the +[TileJSON specification](https://github.com/mapbox/tilejson-spec/tree/master/2.2.0) +for information about tile URL templates in the context of a TileJSON or style +JSON file. + +Tile sources support the following placeholder strings in tile URL templates, +all of which are optional: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Placeholder stringDescription
{x}The index of the tile along the map’s x axis according to Spherical + Mercator projection. If the value is 0, the tile’s left edge corresponds + to the 180th meridian west. If the value is 2z−1, + the tile’s right edge corresponds to the 180th meridian east.
{y}The index of the tile along the map’s y axis according to Spherical + Mercator projection. If the value is 0, the tile’s tile edge corresponds + to arctan(sinh(π)), or approximately 85.0511 degrees north. If the value + is 2z−1, the tile’s bottom edge corresponds to + −arctan(sinh(π)), or approximately 85.0511 degrees south. The y axis is + inverted if the options parameter contains + MGLTileSourceOptionTileCoordinateSystem with a value of + MGLTileCoordinateSystemTMS.
{z}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, + 1⁄16 of the world, and so on. For tiles loaded by + a MGLRasterSource 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 + MGLTileSourceOptionTileSize key of the options + parameter.
{bbox-epsg-3857}The tile’s bounding box, expressed as a comma-separated list of the + tile’s western, southern, eastern, and northern extents according to + Spherical Mercator (EPSG:3857) projection. The bounding box is typically + used with map services conforming to the + Web Map Service + protocol.
{quadkey}A quadkey indicating both the tile’s location and its zoom level. The + quadkey is typically used with + Bing Maps. +
{ratio}A suffix indicating the resolution of the tile image. The suffix is the + empty string for standard resolution displays and @2x for +<% if (iOS) { -%> + Retina displays, including displays for which UIScreen.scale + is 3. +<% } else { -%> + Retina displays. +<% } -%> +
{prefix}Two hexadecimal digits chosen such that each visible tile has a + different prefix. The prefix is typically used for domain sharding.
+ +For more information about the `{x}`, `{y}`, and `{z}` placeholder strings, +consult the +[OpenStreetMap Wiki](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames). diff --git a/platform/darwin/scripts/generate-style-code.js b/platform/darwin/scripts/generate-style-code.js index 330a8f1d03..7efc8d441c 100644 --- a/platform/darwin/scripts/generate-style-code.js +++ b/platform/darwin/scripts/generate-style-code.js @@ -522,8 +522,9 @@ global.setSourceLayer = function() { const layerH = ejs.compile(fs.readFileSync('platform/darwin/src/MGLStyleLayer.h.ejs', 'utf8'), { strict: true }); 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 forStyleAuthorsMD = 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/Using Style Functions at Runtime.md.ejs', 'utf8'), { strict: true }); +const templatesMD = ejs.compile(fs.readFileSync('platform/darwin/docs/guides/Tile URL Templates.md.ejs', 'utf8'), { strict: true }); const layers = _(spec.layer.type.values).map((value, layerType) => { const layoutProperties = Object.keys(spec[`layout_${layerType}`]).reduce((memo, name) => { @@ -635,12 +636,12 @@ global.guideExample = function (guide, exampleId, os) { return '```swift\n' + example + '\n```'; }; -fs.writeFileSync(`platform/ios/docs/guides/For Style Authors.md`, guideMD({ +fs.writeFileSync(`platform/ios/docs/guides/For Style Authors.md`, forStyleAuthorsMD({ os: 'iOS', renamedProperties: renamedPropertiesByLayerType, layers: layers, })); -fs.writeFileSync(`platform/macos/docs/guides/For Style Authors.md`, guideMD({ +fs.writeFileSync(`platform/macos/docs/guides/For Style Authors.md`, forStyleAuthorsMD({ os: 'macOS', renamedProperties: renamedPropertiesByLayerType, layers: layers, @@ -651,3 +652,9 @@ fs.writeFileSync(`platform/ios/docs/guides/Using Style Functions at Runtime.md`, fs.writeFileSync(`platform/macos/docs/guides/Using Style Functions at Runtime.md`, ddsGuideMD({ os: 'macOS', })); +fs.writeFileSync(`platform/ios/docs/guides/Tile URL Templates.md`, templatesMD({ + os: 'iOS', +})); +fs.writeFileSync(`platform/macos/docs/guides/Tile URL Templates.md`, templatesMD({ + os: 'macOS', +})); diff --git a/platform/darwin/src/MGLRasterSource.h b/platform/darwin/src/MGLRasterSource.h index 519784f4f1..4f4b7c96c3 100644 --- a/platform/darwin/src/MGLRasterSource.h +++ b/platform/darwin/src/MGLRasterSource.h @@ -108,96 +108,13 @@ MGL_EXPORT Returns a raster source initialized an identifier, tile URL templates, and options. + Tile URL templates are strings that specify the URLs of the raster tile images + to load. See the “Tile URL Templates” + guide for information about the format of a tile URL template. + After initializing and configuring the source, add it to a map view’s style using the `-[MGLStyle addSource:]` method. - #### Tile URL templates - - Tile URL templates are strings that specify the URLs of the tile images to - load. Each 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: - - - - Tile sources support the following placeholder strings in tile URL templates, - all of which are optional: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Placeholder stringDescription
{x}The index of the tile along the map’s x axis according to Spherical - Mercator projection. If the value is 0, the tile’s left edge corresponds - to the 180th meridian west. If the value is 2z−1, - the tile’s right edge corresponds to the 180th meridian east.
{y}The index of the tile along the map’s y axis according to Spherical - Mercator projection. If the value is 0, the tile’s tile edge corresponds - to arctan(sinh(π)), or approximately 85.0511 degrees north. If the value - is 2z−1, the tile’s bottom edge corresponds to - −arctan(sinh(π)), or approximately 85.0511 degrees south. The y axis is - inverted if the options parameter contains - MGLTileSourceOptionTileCoordinateSystem with a value of - MGLTileCoordinateSystemTMS.
{z}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, - 1⁄16 of the world, and so on. For tiles loaded by - a MGLRasterSource 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 - MGLTileSourceOptionTileSize key of the - options parameter.
{bbox-epsg-3857}The tile’s bounding box, expressed as a comma-separated list of the - tile’s western, southern, eastern, and northern extents according to - Spherical Mercator (EPSG:3857) projection. The bounding box is typically - used with map services conforming to the - Web Map Service - protocol.
{quadkey}A quadkey indicating both the tile’s location and its zoom level. The - quadkey is typically used with - Bing Maps. -
{ratio}A suffix indicating the resolution of the tile image. The suffix is the - empty string for standard resolution displays and @2x for - Retina displays, including displays for which - NSScreen.backingScaleFactor or UIScreen.scale - is 3.
{prefix}Two hexadecimal digits chosen such that each visible tile has a - different prefix. The prefix is typically used for domain sharding.
- - For more information about the `{x}`, `{y}`, and `{z}` placeholder strings, - consult the - OpenStreetMap Wiki. - @param identifier A string that uniquely identifies the source in the style to which it is added. @param tileURLTemplates An array of tile URL template strings. Only the first diff --git a/platform/darwin/src/MGLVectorSource.h b/platform/darwin/src/MGLVectorSource.h index a48434f7a3..968be3c0e0 100644 --- a/platform/darwin/src/MGLVectorSource.h +++ b/platform/darwin/src/MGLVectorSource.h @@ -74,96 +74,13 @@ MGL_EXPORT Returns a vector source initialized an identifier, tile URL templates, and options. + Tile URL templates are strings that specify the URLs of the vector tiles to + load. See the “Tile URL Templates” + guide for information about the format of a tile URL template. + After initializing and configuring the source, add it to a map view’s style using the `-[MGLStyle addSource:]` method. - #### Tile URL templates - - Tile URL templates are strings that specify the URLs of the tile images to - load. Each 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: - - - - Tile sources support the following placeholder strings in tile URL templates, - all of which are optional: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Placeholder stringDescription
{x}The index of the tile along the map’s x axis according to Spherical - Mercator projection. If the value is 0, the tile’s left edge corresponds - to the 180th meridian west. If the value is 2z−1, - the tile’s right edge corresponds to the 180th meridian east.
{y}The index of the tile along the map’s y axis according to Spherical - Mercator projection. If the value is 0, the tile’s tile edge corresponds - to arctan(sinh(π)), or approximately 85.0511 degrees north. If the value - is 2z−1, the tile’s bottom edge corresponds to - −arctan(sinh(π)), or approximately 85.0511 degrees south. The y axis is - inverted if the options parameter contains - MGLTileSourceOptionTileCoordinateSystem with a value of - MGLTileCoordinateSystemTMS.
{z}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, - 1⁄16 of the world, and so on. For tiles loaded by - a MGLRasterSource 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 - MGLTileSourceOptionTileSize key of the - options parameter.
{bbox-epsg-3857}The tile’s bounding box, expressed as a comma-separated list of the - tile’s western, southern, eastern, and northern extents according to - Spherical Mercator (EPSG:3857) projection. The bounding box is typically - used with map services conforming to the - Web Map Service - protocol.
{quadkey}A quadkey indicating both the tile’s location and its zoom level. The - quadkey is typically used with - Bing Maps. -
{ratio}A suffix indicating the resolution of the tile image. The suffix is the - empty string for standard resolution displays and @2x for - Retina displays, including displays for which - NSScreen.backingScaleFactor or UIScreen.scale - is 3.
{prefix}Two hexadecimal digits chosen such that each visible tile has a - different prefix. The prefix is typically used for domain sharding.
- - For more information about the `{x}`, `{y}`, and `{z}` placeholder strings, - consult the - OpenStreetMap Wiki. - @param identifier A string that uniquely identifies the source in the style to which it is added. @param tileURLTemplates An array of tile URL template strings. Only the first diff --git a/platform/ios/docs/guides/Tile URL Templates.md b/platform/ios/docs/guides/Tile URL Templates.md new file mode 100644 index 0000000000..f61d2ea33a --- /dev/null +++ b/platform/ios/docs/guides/Tile URL Templates.md @@ -0,0 +1,99 @@ + +# 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: + +* `http://www.example.com/tiles/{z}/{x}/{y}.pbf` could be + evaluated as `http://www.example.com/tiles/14/6/9.pbf`. +* `http://www.example.com/tiles/{z}/{x}/{y}{ratio}.png` could be + evaluated as `http://www.example.com/tiles/14/6/9@2x.png`. + +Tile URL templates are also used to define tilesets in TileJSON manifests or +[`raster`](https://www.mapbox.com/mapbox-gl-js/style-spec/#sources-raster-tiles) +and +[`vector`](https://www.mapbox.com/mapbox-gl-js/style-spec/#sources-vector-tiles) +sources in style JSON files. See the +[TileJSON specification](https://github.com/mapbox/tilejson-spec/tree/master/2.2.0) +for information about tile URL templates in the context of a TileJSON or style +JSON file. + +Tile sources support the following placeholder strings in tile URL templates, +all of which are optional: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Placeholder stringDescription
{x}The index of the tile along the map’s x axis according to Spherical + Mercator projection. If the value is 0, the tile’s left edge corresponds + to the 180th meridian west. If the value is 2z−1, + the tile’s right edge corresponds to the 180th meridian east.
{y}The index of the tile along the map’s y axis according to Spherical + Mercator projection. If the value is 0, the tile’s tile edge corresponds + to arctan(sinh(π)), or approximately 85.0511 degrees north. If the value + is 2z−1, the tile’s bottom edge corresponds to + −arctan(sinh(π)), or approximately 85.0511 degrees south. The y axis is + inverted if the options parameter contains + MGLTileSourceOptionTileCoordinateSystem with a value of + MGLTileCoordinateSystemTMS.
{z}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, + 1⁄16 of the world, and so on. For tiles loaded by + a MGLRasterSource 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 + MGLTileSourceOptionTileSize key of the options + parameter.
{bbox-epsg-3857}The tile’s bounding box, expressed as a comma-separated list of the + tile’s western, southern, eastern, and northern extents according to + Spherical Mercator (EPSG:3857) projection. The bounding box is typically + used with map services conforming to the + Web Map Service + protocol.
{quadkey}A quadkey indicating both the tile’s location and its zoom level. The + quadkey is typically used with + Bing Maps. +
{ratio}A suffix indicating the resolution of the tile image. The suffix is the + empty string for standard resolution displays and @2x for + Retina displays, including displays for which UIScreen.scale + is 3. +
{prefix}Two hexadecimal digits chosen such that each visible tile has a + different prefix. The prefix is typically used for domain sharding.
+ +For more information about the `{x}`, `{y}`, and `{z}` placeholder strings, +consult the +[OpenStreetMap Wiki](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames). diff --git a/platform/ios/jazzy.yml b/platform/ios/jazzy.yml index e0ce29beba..638abaaf6c 100644 --- a/platform/ios/jazzy.yml +++ b/platform/ios/jazzy.yml @@ -23,6 +23,7 @@ custom_categories: - Working with Mapbox Studio - Working with GeoJSON Data - For Style Authors + - Tile URL Templates - Info.plist Keys - Gesture Recognizers - name: Maps diff --git a/platform/macos/docs/guides/Tile URL Templates.md b/platform/macos/docs/guides/Tile URL Templates.md new file mode 100644 index 0000000000..01672c6686 --- /dev/null +++ b/platform/macos/docs/guides/Tile URL Templates.md @@ -0,0 +1,98 @@ + +# 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: + +* `http://www.example.com/tiles/{z}/{x}/{y}.pbf` could be + evaluated as `http://www.example.com/tiles/14/6/9.pbf`. +* `http://www.example.com/tiles/{z}/{x}/{y}{ratio}.png` could be + evaluated as `http://www.example.com/tiles/14/6/9@2x.png`. + +Tile URL templates are also used to define tilesets in TileJSON manifests or +[`raster`](https://www.mapbox.com/mapbox-gl-js/style-spec/#sources-raster-tiles) +and +[`vector`](https://www.mapbox.com/mapbox-gl-js/style-spec/#sources-vector-tiles) +sources in style JSON files. See the +[TileJSON specification](https://github.com/mapbox/tilejson-spec/tree/master/2.2.0) +for information about tile URL templates in the context of a TileJSON or style +JSON file. + +Tile sources support the following placeholder strings in tile URL templates, +all of which are optional: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Placeholder stringDescription
{x}The index of the tile along the map’s x axis according to Spherical + Mercator projection. If the value is 0, the tile’s left edge corresponds + to the 180th meridian west. If the value is 2z−1, + the tile’s right edge corresponds to the 180th meridian east.
{y}The index of the tile along the map’s y axis according to Spherical + Mercator projection. If the value is 0, the tile’s tile edge corresponds + to arctan(sinh(π)), or approximately 85.0511 degrees north. If the value + is 2z−1, the tile’s bottom edge corresponds to + −arctan(sinh(π)), or approximately 85.0511 degrees south. The y axis is + inverted if the options parameter contains + MGLTileSourceOptionTileCoordinateSystem with a value of + MGLTileCoordinateSystemTMS.
{z}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, + 1⁄16 of the world, and so on. For tiles loaded by + a MGLRasterSource 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 + MGLTileSourceOptionTileSize key of the options + parameter.
{bbox-epsg-3857}The tile’s bounding box, expressed as a comma-separated list of the + tile’s western, southern, eastern, and northern extents according to + Spherical Mercator (EPSG:3857) projection. The bounding box is typically + used with map services conforming to the + Web Map Service + protocol.
{quadkey}A quadkey indicating both the tile’s location and its zoom level. The + quadkey is typically used with + Bing Maps. +
{ratio}A suffix indicating the resolution of the tile image. The suffix is the + empty string for standard resolution displays and @2x for + Retina displays. +
{prefix}Two hexadecimal digits chosen such that each visible tile has a + different prefix. The prefix is typically used for domain sharding.
+ +For more information about the `{x}`, `{y}`, and `{z}` placeholder strings, +consult the +[OpenStreetMap Wiki](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames). diff --git a/platform/macos/jazzy.yml b/platform/macos/jazzy.yml index 3c24b351cc..53f260b242 100644 --- a/platform/macos/jazzy.yml +++ b/platform/macos/jazzy.yml @@ -20,6 +20,7 @@ custom_categories: - Working with GeoJSON Data - For Style Authors - Using Style Functions at Runtime + - Tile URL Templates - Info.plist Keys - name: Maps children: -- cgit v1.2.1