s2-tilejson

About

TileJSON is a mostly backwards-compatible open standard for representing map tile metadata.

Install

# NPM
npm install s2-tilejson
# PNPM
pnpm add s2-tilejson
# Yarn
yarn add s2-tilejson
# Bun
bun add s2-tilejson

Usage

import { MetadataBuilder } from 's2-tilejson'
import type { Metadata, Shape, LayerMetaData, BBox } from 's2-tilejson'

const metaBuilder = new MetadataBuilder()

// on initial use be sure to update basic metadata:
metaBuilder.setName('OSM')
metaBuilder.setDescription('A free editable map of the whole world.')
metaBuilder.setVersion('1.0.0')
metaBuilder.setScheme('fzxy') // 'fzxy' | 'tfzxy' | 'xyz' | 'txyz' | 'tms'
metaBuilder.setType('vector') // 'vector' | 'json' | 'raster' | 'raster-dem' | 'grid' | 'markers'
metaBuilder.setEncoding('none') // 'gz' | 'br' | 'none'
metaBuilder.addAttribution('OpenStreetMap', 'https://www.openstreetmap.org/copyright/')

// Vector Specific: add layers based on how you want to parse data from a source:

metaBuilder.addLayer('water_lines', {
    minzoom: 0,
    maxzoom: 13,
    drawTypes: [2],
    shape: {
        class: 'string',
        offset: 'f64',
        info: {
            name: 'string',
            value: 'i64'
        }
    } as Shape,
    m_shape: null
} as LayerMetaData)

// as you build tiles, add the tiles metadata:
const lonLatBoundsForTile: BBox = [-180, -90, 180, 90]
// WM:
metaBuilder.addTileWM(zoom, x, y, lonLatBoundsForTile)
// S2:
metaBuilder.addTileS2(face, zoom, x, y, lonLatBoundsForTile)

// finally to get the resulting metadata:
const metadata: Metadata = metaBuilder.commit()

If you're not sure which tilejson you are reading (Mapbox's spec or S2's spec), you can treat the input as either:

import { toMetadata } from 's2-tilejson'

import type { Metadata, Metadatas } from 's2-tilejson'

const metadata: Metadata = toMetadata(input as Metadatas)

this helps with typesafety and type checking. The only major important differences in usecases is that Mapbox spec treats the variable tiles as a list of input URLs and center is an array instead of an object.

Creating and Validating your Shapes

Shapes define the type of data that can be stored in the vector tile. They are explained in the specification.

If you'd like to validate the shape, feel free to use the Ajv library.

import Ajv from 'ajv';
import { ShapeSchema } from 's2-tilejson'; // Path to the schema

import type { Shape } from 's2-tilejson';

const ajv = new Ajv();
const validate = ajv.compile(ShapeSchema);

const shape: Shape = {
  a: 'i64',
  b: ['string'],
  c: {
    d: 'f64',
    e: 'bool',
    f: 'null',
    g: 'f32',
    h: {
      i: 'u64',
    },
  },
};

validate(shape); // true

Development

Requirements

For Typescript, install via bun:

bun i

If you need to install bun, please refer to the bun installation guide.

You need the tool tarpaulin to generate the coverage report. Install it using the following command:

cargo install cargo-tarpaulin

The bacon coverage tool is used to generate the coverage report. To utilize the pycobertura package for a prettier coverage report, install it using the following command:

pip install pycobertura

Running Tests

To run the tests, use the following command:

# TYPESCRIPT
## basic test
bun run test
## live testing
bun run test:dev

# RUST
## basic test
cargo test
# live testing
bacon test

Generating Coverage Report

To generate the coverage report, use the following command:

cargo tarpaulin
# faster
cargo tarpaulin --color always --skip-clean
# bacon
bacon coverage # or type `l` inside the tool