Skip to main content

Geometry Provider

MapillaryJS needs a scalable way to index camera captures when determining adjacency. It uses discrete S2 geometry cells to solve that in the S2GeometryProvider. If you want to use another geo indexing algorithm, for example when requesting data from a service, you can implement your own geometry provider.

You will learn
  • How to create your own geometry provider by extending the GeometryProviderBase class
  • How to make MapillaryJS use your geometry provider to load adjacent data

Implementing the Provider#

The GeometryProviderBase class has four abstract methods that you need to implement.

class MyGeometryProvider extends GeometryProviderBase {    public bboxToCellIds(sw, ne) {        // ...    }
    public getAdjacent(cellId) {        // ...    }
    public getVertices(cellId) {        // ...    }
    public lngLatToCellId(lngLat) {        // ...    }}

MapillaryJS operates on a metric scale and uses measurments relevant from a street imagery perspective. Returning cells with a size of roughly 10,000 square meters is recommended.

Let us go through them one by one.


Converts a geodetic bounding box to the the minimum set of cell ids containing the bounding box.


Returns the cell ids of all adjacent cells. In the case of approximately rectangular cells this is typically the eight orthogonally and diagonally adjacent cells.


Returns the vertices of the cell outline. The vertices form an unclosed polygon in the 2D longitude, latitude space. No assumption on the position of the first vertex relative to the others can be made.


Converts geodetic coordinates to a cell id.

Attaching the Provider#

Now that we have implemented our geometry provider, we just need to attach it to the Viewer through the data provider. We will use the built in S2GeometryProvider and our procedural data provider in the live example.


Try to change cell level parameter of the S2GeometryProvider constructor to see how it affects the cell size.

Live Editor
SyntaxError: Unexpected token (1:8)
1 : return ()


  • You can define the geo indexing algorithm used by MapillaryJS by extending the GeometryProviderBase class.
  • Attach your custom geometry provider to the MapillaryJS viewer through the data provider.

If you want to request data based on Geohashes, take a look at the deprecated GeohashGeometryProvider.