mapbox / tilejson-spec Goto Github PK
View Code? Open in Web Editor NEWJSON format for describing map tilesets.
JSON format for describing map tilesets.
The property would be a suggested background color for the map div.
Setting the background color to a common map color seems to reduce the effect of background flashing when tiles are getting loaded. For mapbox streets this would be the main land color
This seems like it might be going beyond the scope of tilejson-spec though?
For data-centric layers (e.g. dynamically updated layers containing lots of additional info for features) it will be useful to allow a wildcard definition for the layer fields:
"fields": {
"*": "All attributes"
}
This let's an application know that there are various attributes available, without being limited to a predefined set.
If "bounds" is missing, how do I know valid tile-x/y? If the center is also missing, I don't see any possibility to even get valid tile-xy. This problem would be solved by making the "bounds" key required instead of optional.
In https://github.com/mapbox/tilejson-spec/blob/master/3.0.0/example/osm.json, it could be interesting to set a date as optional.
Knowing when the vector tiles have been updated.
It will work better with vector tiles served from static source like an mbtile.
Otherwise, it's not always relevant if tilejson possible date is not synced with vector tiles due to dynamic vector tiles endpoint.
Maybe It's already solved if considering I optional key management as it seems from https://github.com/mapbox/tilejson-spec/blob/master/3.0.0/example/osm.json#L17 and excerpt from the spec below
Implementations MUST treat unknown keys as if they weren't present. However, implementations MUST expose unknown key value pairs so users can optionally handle these keys. Implementations MUST treat invalid values for keys as if they weren’t present.
@tmcw pointed out that we need a way to know which version of the spec is implemented. We basically need a key for this.
api
? tilejson
?
Some renderers (like ours) require to map a geometry type to a layer. Therefore I propose to have an optional field "geometry_type" for the layer definition. The geometry_type should relate to one of the simple feature types of defined in GeoJson [1]:
... geometry type refers to seven case-sensitive strings: "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon", and "GeometryCollection"
The spec says {x|y|z}, without the $.
When more than one tileset is composited, vector_layers get merged into a single list. source
and source_name
fields are useful for identifying which vector_layers belong to which member of a composite source.
// An example vector layer entry with `source` and `source_name`:
{
description: string,
fields: { [string]: string },
id: string,
maxzoom?: number,
minzoom?: number,
source: string, // Matches id of parent tileset
source_name?: string // Matches name of parent tileset
}
This does bring up a bigger question for me. I find the tileJSON spec's ability to successfully describe composited tileJSON to be lacking. I want to know more details about each tileset in my composite. A nested data structure for composited tileJSON that includes the full original tileJSON for each composited tileset would be a much more convenient document to work with, for example.
An entire tileset has min/maxzoom, but individual layers in a vector tileset may have different min/maxzooms within the tileset's range. It can be helpful for downstream consumers of the tilejson to know where these layers are visible.
cc @samanpwbb
Some tile server implementations support overzooming, where tiles are generated and served at zoom levels beyond a tileset's zoom extent using the lowest available zoom level as the source of truth for overzoomed tiles.
Mapbox's tile server includes an overzoom max of 30 for all vector tilesets, which means tiles can be requested from any tileset from the minzoom
to zoom 30, regardless of the maxzoom
. Requesting tiles beyond z30 from Mapbox results in a 422 error.
If overzoom
were a property on tileJSON, clients would know when to stop requesting tiles without hitting an error or relying on a separate source of truth.
.layer
is a silly name.
Most web tiling toolkits use ${z}/${x}/${y}.png.
Add "crs" (= Coordinate Reference System) as key.
The values and if it should be mandatory has to be discussed.
See also e.g. https://github.com/klokantech/tilejson-spec/tree/custom-projection/2.2.0
I've come across a lot of different tile layer sources over the years which tend to have multiple areas of coverage (multiple bounding boxes). A great example of this would be a high resolution imagery layer that only focuses on urban areas. Currently to limit the tile requests to these areas we have to create a layer number of tile layers, one for each bounding box.
It would be great if we could specify multiple bounding boxes in a single layer, or possibly a MultiPolygon instead. Not sure of how else to handle this. One potential issue with this approach is that processing time of determining if a tile is within the coverage area or not. To improve performance this could be pre-calculated when the tile layer is initially loaded and an index created based on the tile ids. Limiting this to bounding boxes, would simplify things and may be good enough for most scenarios like this.
For a developer, they would simply pass in an array of bounding boxes as an alternative to passing in one.
This isn't much of a change from the API interface point of view, so not much to new learning required. This would also be beneficial to those who use OGC services that have complex coverage areas.
TileJSON should have a means of:
@2x
, @4x
, etc)Without such a specification, consumers must have hard-coded knowledge of a source's support for high-DPI tiles and typically resort to string munging to generate the appropriate URLs. These are exactly the sort of deficiencies that TileJSON is designed to eliminate.
One approach would be to have an array-valued property that lists supported DPI multipliers and a new interpolation key for tile URL templates. E.g.:
{
...
"dpis": [1, 2, 4],
"tiles": ["http://example.com/{z}/{x}/{y}{r}.png"]
}
Where it is specified that {r}
is replaced with the pixel ratio ⇢ string mapping of 1 ⇢ "", 2 ⇢ "@2x", 4 ⇢ "@4x", and consumers may decide which of the pixel ratio options to use based on device characteristics. Alternatively this mapping could be explicitly supplied:
{
...
"dpis": {
"1": "",
"2": "@2x",
"4": "@4x"
},
"tiles": ["http://example.com/{z}/{x}/{y}{r}.png"]
}
These approaches introduce a backward compatibility issue however, in that existing TileJSON consumers will not be prepared to interpolate a new template value and thus cannot consume TileJSON that uses it.
The spec does not currently support any way to describe the layers contained within the tiles. This means that the client has to "somehow know" which layers exist. IMHO this kind of metadata makes a lot of sense to include.
Both Mapbox's API and the tile server Tessera uses the "vector_layers" property for this purpose:
"vector_layers": [
{
"id": "tr_rail",
"description": "",
"minzoom": 0,
"maxzoom": 13,
"fields": {
"FTYPE_CODE": "String",
"NAME": "String",
"STRUC_TYPE": "String",
"TOUR_TYPE": "String"
}
}
]
Mapbox's API includes source
and source_name
properties on individual layers. (The former for the case where a multiple sources are being combined in one query, I presume).
I'm happy to write this up as a PR if desirable.
Similar to center
it would specify an extent that could be used to to set the default center and zoom. Extent would allow a specified area to always be shown, no matter the map size.
I understand that this use case is likely not covered by the current specification, but I wanted to document the need, and also see what contributors here recommend for satisfying the requirements as closely to the specification as possible.
I have raster imagery for a city that is relatively high resolution that needs to be tiled and displayed at the full source resolution at maximum zoom. Naturally the meters per pixel resolution of my source imagery does not align with the meters per pixel resolution of an integer zoom level at the latitude for the map.
To display imagery at its full source resolution I need to use a fractional zoom level that aligns the meters per pixel resolution of the map with the source imagery's meters per pixel resolution. Ideally the source imagery is tiled at the same fractional zoom level and then served to the client when at that maximum fractional zoom.
My current thought is to tile the imagery at the appropriate fractional zoom (to preserve resolution) as well as for each integer zoom below that fractional zoom. Let mapbox tile the imagery at all zoom levels other than maximum and when at maximum zoom have application code request and overlay the fractional zoom tiles manually. Not pretty but it would satisfy the requirements.
Do contributors here have any recommendations for how to go about this? Or potential alternatives? Any chance a future version of the specification would handle fractional zoom tiles?
👋 We are ramping up efforts to document the current spec as well as discuss a future version with all contributors. This ticket serves as the overarching plan forward. @mapsam and I are excited to be leading out this process and collaborating with you all.
No doubt there is a need to have a clear set of tileset metadata in order to support interoperability between different tile-based geo tools. This is the need TileJSON aims to fill. However, the TileJSON spec has not been consistently maintained for a number of years due to original owners moving on to other projects or organizations, which has led to inconsistencies. @mapsam and I are picking up the torch to address this.
We are committed to ensuring the current spec as well as future spec additions are properly documented and all changes fully transparent. To achieve this, all proposed changes will follow TileJSON spec’s contributing procedures. @mapsam and I are also committed to shepherding TileJSON spec’s Code of Conduct during this ramp up. Please reach out to either of us if you have any questions about these docs.
v3.0
Goal: Solidify our understanding of the current spec, documenting, then release v3.0
. This will enable us all to discuss and implement our visions for how we want things to be in Phase 2 (see below).
Phase 1 will center around fully documenting the already-existing spec as well as any relevant historical context. We are prioritizing this due to there being an ownership gap and a general lack of clarity in the past around fast changes and maintenance of the spec. We’ll plan to create PRs for each of the next actions below, where we will continue discussion for each.
We are aiming to finish Phase 1 by May 2018.
v4.0
Goal: Discuss modifying current properties and adding new features, then release v4.0
v4.0
is impacted by the upcoming Vector Tile 3 specThanks for your continued commitment! 🙌
cc @mapbox/core-tech
Landing on the repository one can see all spec versions up to 2.2
There is a branch with a v3 that is not visible unless one knows where to look.
Wondering what's the situation, one can imagine that maybe:
I have just been working with some Esri vector tiles, which support a variable zoom depth. That is, tiles are generated to higher zoom levels in areas that contain more detail, and aren't generated in comparatively empty areas.
https://developers.arcgis.com/rest/services-reference/vector-tilemap.htm
It has obvious benefits when statically generating large tilesets that cover both urban and rural areas. The downside is that you also need to communicate to the client where tiles are available. Esri does this through a hefty tilemap
JSON file, but there probably more efficient ways.
Is it worth putting something like this in TileJSON? Or maybe it doesn't make sense if Mapbox isn't going to support it.
It would be useful to be able to have tileSize as a TileJSON property to make it easier to use non-default sized raster tiles.
As explained in mapbox/mapbox-gl-native#2723 (comment), native map controls need attribution information in a format other than HTML source code. We should allow the attribution
property to be set to something more structured that can be converted to the appropriate data structures on the client side. For example, it could be an array of objects, each with a required title
property (interpreted as literal text) and an optional url
property (for linking):
{
"attribution": [
{
"title": "© OpenStreetMap contributors",
"url": "http://www.openstreetmap.org/about/"
},
{
"title": "Creative Commons Attribution-ShareAlike 2.0",
"url": "http://www.openstreetmap.org/copyright/"
}
]
}
Other considerations:
title
property be localizable? If so, perhaps it should be set to an object mapping ISO 639 language codes to literal strings.short_title
property beside the title
property.feedback
property beside the attribution
property. Many TileJSON documents hosted by Mapbox include an “Improve This Map” link alongside copyright statements. Native clients may want to open an alternative map feedback tool (mapbox/mapbox-gl-native#6001); as things stand, they’d have to look for and omit a specific URL. In space-constrained environments, the client may choose to omit feedback items from the attribution UI to ensure that all the legally required copyright statements are visible./cc @kkaefer @jfirebaugh
Pending a spec for the format of the geocoder result JSON and implementation in MapBox API.
Is there a reason why the tiles
and grids
urls use a ${z}
style token for replacement?
Out of the box, it looks like modest maps uses {Z}
while leaflet uses {z}
.
Wondering if we should switch and maybe come to a consensus on the right token to use.
For the case where these values aren't tiled/templated, it would be nice to be able to inline the JSON and reduce server round-trips.
Mapbox iOS SDK hints that it may be possible to customize the batch sizing of tile packs. I would like to create a batch for 11-12 since I don't need >=13 and it's throwing me over the 750 limit.
The zoom leveling scheme for the tile batches can be defined in Tile JSON, otherwise the default scheme is used...
@property (nonatomic, readonly, nonnull, copy) NSString *styleURI;
/**
* Minimum zoom level for the tile package.
*
* Note: the implementation loads and stores the loaded tiles
* in batches, each batch has a pre-defined zoom range and it contains
* all child tiles within the range. The zoom leveling scheme for the tile
* batches can be defined in Tile JSON, otherwise the default scheme is used:
* - Global coverage: 0 - 5
* - Regional information: 6 - 10
* - Local information: 11 - 14
* - Streets detail: 15 - 16
*
* Internally, the implementation maps the given tile pack zoom range
* and geometry to a set of pre-defined batches to load, therefore
* it is highly recommended to choose the `minZoom` and `maxZoom` values
* in accordance with the tile batches zoom ranges (see the list above).
*/
👋 Plan is to start ramping up efforts to update and document this spec. This repo is missing needed documentation for moving forward, in particular Contributing.md
and Code_of_Conduct.md
, which I will break out into separate PRs.
I'm pretty sure that there are TileJSON files - as well as services and data - around which contain maskLevel.
The logic is described here: https://github.com/mapbox/tilelive-vector
Should'nt this be part of the spec.?
The current text of 3.0.0 has a couple of problems for raster layers
Note: When describinng a set of raster tiles or other tile format that does not have a "layers" concept (i.e.
"format": "jpeg"
), the vector_layers key is not required.
There's a few issues that should be changed for 3.0.1
format
. Previous versions of the spec had a format key, but that is no longer defined in the spec, so it's unclear to users what "format": "jpeg"
meansWe're starting to see a lot of tilejson with a vector_layers key. We should document this for standardization and so that the meaning the keys are documented.
Some examples
https://gist.github.com/springmeyer/bbf49c89180485f477b9
https://github.com/mapbox/mapbox-studio/blob/mb-pages/test/fixtures-mapboxapi/mapbox.mapbox-streets-v5.json
Edit: fixed link
What do people think about adding an interpretation field for raster sources?
Currently Mapbox use TileJSON for
a 3 band RGB raster to be displayed as is https://api.mapbox.com/v4/mapbox.satellite.json
a 1 band raster encoded as a 3 band RGB.
https://api.mapbox.com/v4/mapbox.terrain-rgb.json (https://blog.mapbox.com/blog/terrain-rgb/)
In the terrain-rgb case the formula for getting back to the 1 band raster is "-10000 + ((R * 256 * 256 + G * 256 + B) * 0.1)".
Should the TileJSON spec distinguise these two types and contain the formula to get the real values like in (2)?
/cc @MateoV
TileJSON doesn't seem to support Mapbox's own vector tiles spec. Am I misunderstanding something, or is this an omission?
I can see two ways to support it:
data
element should allow URLs that end in .pbf and return PBF files. But then, with the REQUIRED tiles
attribute, it would be a bit awkward to conform to the spec for a purely vector source...tiles
element should allow URLs that end in .pbf and return PBF files.Either way I guess the scope of the spec is changing, since presumably it was originally envisaged that this was strictly for raster tiles and here it is being used for vector data...
Opening from #35 (comment)
What are the governance plans for the specification?
For background, the general requirement for an open standard would be a mix of users and implementers, implementers not dominated by one area of implementation at the cost of others, and not dominated by any one organization. This makes sure that an open spec represents everyone's interests, not just one companies.
Hey @pnorman, as stated above, myself (@mapsam) and @GretaCB will be the lead authors and deciding committee of these two versions. We are following the CONTRIBUTING.md, which states all questions and suggestions should be opened up as GitHub issues. Thanks for the input so far!
I'd like to see an open committee to make the standards process openly owned by the community, with a balance of interests. A diverse committee is generally believed to lead to better specifications.
Currently, all that the specification has to say about the x, y and z URL parameters is
{z}, {x} and {y}, if present, are replaced with the corresponding integers
There is no specification of what corresponding means. The specification should probably either explicitly define how x, y and z are calculated from geographical coordinates, or link to another standard that specifies it.
The vector_layers
field references format
field, but it is not declared in the spec. https://github.com/mapbox/tilejson-spec/tree/master/3.0.0#33-vector_layers
Note: When describinng a set of raster tiles or other tile format that does not have a "layers" concept (i.e.
"format": "jpeg"
), thevector_layers
key is not required.
It appears that the tiles
property is not clear enough regarding the support of relative and absolute URLs.
I lately opened a issue on mapbox-gl-js that relative URLs are not correctly handled but the bug was closed with the info that absolute URLs are needed in the tiles
property. From the current description it is not 100% clear that his is actually a requirement:
Lines 73 to 79 in 4820170
It appears that some services like ESRI ArcGIS only specify relative URLs which need to be combined with the URL where the TileJSON is hosted.
Either the spec should mention that only absolute endpoints are supported or it should clearly define how relative URLs should be handled, especially in regards to leading slashes.
If I have a tile source that goes from west of Australia to east right of New Zealand, I would expect to be able to write the bounds
as:
[90, -70, -170, 70] // left, bottom, right, top
Unfortunately this doesn't seem to produce a valid tilejson (in Mapbox GL JS no tiles are requested for this source).
It's not possible to workaround this by just switching the left/right longitudes, because that represents all the negative space where there is no data. Leaving the only possible workaround to specify the entire -180°/180° range:
[-180, -70, 180, 70],
This results in a lot of unnecessary requests to the server that just result in 404 responses, and also prevents the ability to draw a border around the bounds. However it works from a user perspective because all data is shown.
Extending the bounds beyond 180° to 190° (below) results in appropriate requests, but nothing between 180° and 190°(with Mapbox GL JS as the implementation).
[90, -70, 190, 70]
Should the spec be able to support bounds where the left longitude is greater than the right longitude?
I recently added subdomain support to leaflet-tilejson (kartena/leaflet-tilejson#10) for subdomains, as it is hard to implement subdomains with TileJSON in Leaflet. I would like to recommend officially adding {s}
as a valid variable in tiles, and an associated subdomains
property, which can be provided as an Array or a string, just like Leaflet supports.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.