A client library for VersaTiles containers.

Install

npm i @versatiles/container

Usage Example

import VersaTiles from '@versatiles/container';
import fs from 'fs';

const container = new VersaTiles('https://example.org/planet.versatiles');
const header = await container.getHeader();
const tile = await container.getTileUncompressed(z,x,y);
fs.writeFileSync('tile.' + header.tile_format, tile);

API

Classes

Class: Container

The VersaTiles class is a wrapper around a .versatiles container file. It provides methods
to access tile data, metadata, and other properties within the container. ^[src]

Constructor: new Container(source, options)

Constructs a new instance of the VersaTiles class. ^[src]

Parameters:

• source: string | Reader
  The data source for the tiles. This can be a URL starting with http:// or https://, a path to a local file, or a custom Reader function that reads data chunks based on offset and length.
• options: OpenOptions (optional)
  Optional settings that configure tile handling.

Method: getHeader()

Asynchronously retrieves the header information from the .versatiles container. ^[src]

Returns: Promise<Header>

Method: getMetadata()

Asynchronously retrieves the metadata associated with the .versatiles container.
Metadata typically includes information about vector_layers for vector tiles. If the container does not include metadata, this method returns null. ^[src]

Returns: Promise<undefined | string>

Method: getTile(z, x, y)

Asynchronously retrieves a specific tile's data as a Buffer. If the tile data is compressed as
defined in the container header, the returned Buffer will contain the compressed data. To obtain uncompressed data, use the getTileUncompressed method. If the specified tile does not exist, the method returns null. ^[src]

Parameters:

• z: number
  The zoom level of the tile.
• x: number
  The x coordinate of the tile within its zoom level.
• y: number
  The y coordinate of the tile within its zoom level.

Returns: Promise<null | Buffer>

Method: getTileUncompressed(z, x, y)

Asynchronously retrieves a specific tile's uncompressed data as a Buffer. This method first
retrieves the compressed tile data using getTile and then decompresses it based on the compression setting in the container header. If the specified tile does not exist, the method returns null. ^[src]

Parameters:

• z: number
  The zoom level of the tile.
• x: number
  The x coordinate of the tile within its zoom level.
• y: number
  The y coordinate of the tile within its zoom level.

Returns: Promise<null | Buffer>

Interfaces

Interface: Header

interface {
  bbox: [number, number, number, number];
  blockIndexLength: number;
  blockIndexOffset: number;
  magic: string;
  metaLength: number;
  metaOffset: number;
  tileCompression: [Compression](#type_compression);
  tileFormat: [Format](#type_format);
  tileMime: string;
  version: string;
  zoomMax: number;
  zoomMin: number;
}

Interface: OpenOptions

interface {
  tms: boolean;
}

Type Aliases

Type: Compression

Type: "br" | "gzip" | "raw"

Type: Format

Type: "avif" | "bin" | "geojson" | "jpg" | "json" | "pbf" | "png" | "svg" | "topojson" | "webp"

Type: Reader

Type: (position: number, length: number) => Promise<Buffer>

License

Unlicense

Future work

This library could be extended to run in a web browser to read VersaTiles containers via fetch.