How should ODK Collect style vector maps?

One of the new things in Collect 1.23 is support for vector MBTiles in the geospatial activities (GeoPoint, GeoTrace, and GeoShape). Previously, you could put a raster MBTiles file in the /sdcard/odk/layers directory, and it would appear in the menu of available basemaps; selecting it would case the raster tiles to be shown on the map. In 1.23, you can also provide an MBTiles file that contains vector tiles. It will appear in the menu of available "Reference layers", and it will be drawn on top of your selected basemap.

However, vector MBTiles files don't include styling information, as far as I know. As a temporary measure, ODK Collect 1.23 draws the vector lines in various colours, choosing a random (but stable) colour for each layer. But the result is still somewhat strange-looking and unfamiliar, especially if you're used to seeing nicely rendered OSM maps.

(In Mapbox terms, we have a source of data, but we don't have any layers that describe how to render the data. The way we construct the map now is by starting with the basemap style (e.g. Mapbox Streets), then adding the MBTiles file as a source, and finally generating a simple line-drawing layer for each vector layer in the MBTiles file. We pick a colour for each layer by hashing the layer name.)

So now we have a design question: how should styling information be provided?

These are a few (non-exclusive) options we have considered so far. (In the below, I have mostly assumed that "style file" means a Mapbox JSON style file, though I'm open to other solutions.)

  1. Apply a default style file. We don't know if one style file will generally work for all or most of the MBTiles files people will use in practice. It seems like they would often be extracted from OSM data, so perhaps one could assume a standard set of attributes? Is it conceivably possible that a default style file would do the trick?

  2. Provide a list of stock style files. If there are a small number of common style files that would cover most cases, perhaps we can provide those as options. How realistic is this?

  3. Allow a style file to be sideloaded onto the phone. This would be the most flexible, and this functionality seems necessary for any serious use. But how should a style file refer to an MBTiles file on the local filesystem? In the Mapbox JSON format, tile sources are specified with URLs. (Actually, each source gets a list of URL templates, so that the load can be spread over multiple tile servers.) I don't see anything in the current spec about referencing local source files. One possible extension to the Mapbox JSON spec would be to allow the relative path to an MBTiles file as the "tiles" property of a source (it would be one string instead of an array of string); or to define a new property for this purpose.

  4. Include style information in the MBTiles file. Using a style file would be the most powerful method, but it would require managing multiple files, and creates the possibility of broken references if the source files have the wrong names or are in the wrong locations. As an alternative, we could define a way to embed styling information in the MBTiles file itself, so that each MBTiles file is a self-contained, viewable object. For example, we could add a "layers" property to the metadata table, containing a JSON array of layer definitions.

Finally, I should note that Mapbox has an existing method for achieving roughly similar goals; there is a way to define an offline region and download an offline package that contains all the tiles and styling resources. However, I don't believe the format for this package file is public.

We're looking for suggestions and guidance from you—our Mapbox friends, developers, and implementors who dream of being able to use ODK Collect fully offline. For the use cases you have in mind, whether it's using offline tiles to serve as a basemap, replacing the existing online basemaps; or whether it's using offline tiles as a reference overlay—what is workable for you? Can you describe the process you imagine using to deploy a collection project with offline maps in the field?

As always, thank you for your wisdom and input!

1 Like

Tagging a few folks who I'm imagining will have something to say about this: @Marena @langstonsmith @mikel @Ivangayton @paul.uithol @smit1678 @LN @mathieubossaert

Please feel free to invite others!