Nothing's plumb meaningless

    @mapbox/mbtiles

    0.12.1 • Public • Published

    mbtiles

    Node.js utilities and tilelive integration for the MBTiles format.

    Build Status Build status

    Installation

    npm install @mapbox/mbtiles
    
    var MBTiles = require('@mapbox/mbtiles');

    API

    Constructor

    All MBTiles instances need to be constructed before any of the methods become available. NOTE: All methods described below assume you've taken this step.

    new MBTiles('./path/to/file.mbtiles?mode={ro, rw, rwc}', function(err, mbtiles) {
      console.log(mbtiles) // mbtiles object with methods listed below
    });

    The mode query parameter is a opening flag of mbtiles. It is optional, default as rwc. Available flags are:

    • ro: readonly mode, will throw error if the mbtiles does not exist.
    • rw: read and write mode, will throw error if the mbtiles does not exist.
    • rwc: read, write and create mode, will create a new mbtiles if the mbtiles does not exist.

    Reading

    getTile(z, x, y, callback)

    Get an individual tile from the MBTiles table. This can be a raster or gzipped vector tile. Also returns headers that are important for serving over HTTP.

    mbtiles.getTile(z, x, y, function(err, data, headers) {
      // `data` is your gzipped buffer - use zlib to gunzip or inflate
    });

    getInfo(callback)

    Get info of an MBTiles file, which is stored in the metadata table. Includes information like zoom levels, bounds, vector_layers, that were created during generation. This performs fallback queries if certain keys like bounds, minzoom, or maxzoom have not been provided.

    mbtiles.getInfo(function(err, info) {
      console.log(info); // info
    });

    getGrid(z, x, y, callback)

    Get a UTFGrid tile from the MBTiles table.

    mbtiles.getGrid(z, x, y, function(err, data) {
      // continue onwards
    });

    Writing

    startWriting AND stopWriting

    In order to write a new (or currently existing) MBTiles file you need to "start" and "stop" writing. First, construct the MBTiles object.

    mbtiles.startWriting(function(err) {
      // start writing with mbtiles methods (putTile, putInfo, etc)
      mbtiles.stopWriting(function(err) {
        // stop writing to your mbtiles object
      });
    });

    putTile(z, x, y, buffer, callback)

    Add a new tile buffer to a specific ZXY. This can be a raster tile or a gzipped vector tile (we suggest using require('zlib') to gzip your tiles).

    var zlib = require('zlib');
     
    zlib.gzip(fs.readFileSync('./path/to/file.mvt'), function(err, buffer) {
      mbtiles.putTile(0, 0, 0, buffer, function(err) {
        // continue onward
      });
    });

    putInfo(data, callback)

    Put an information object into the metadata table. Any nested JSON will be stringified and stored in the "json" row of the metadata table. This will replace any matching key/value fields in the table.

    var exampleInfo = {
      "name": "hello-world",
      "description":"the world in vector tiles",
      "format":"pbf",
      "version": 2,
      "minzoom": 0,
      "maxzoom": 4,
      "center": "0,0,1",
      "bounds": "-180.000000,-85.051129,180.000000,85.051129",
      "type": "overlay",
      "json": `{"vector_layers": [ { "id": "${layername}", "description": "", "minzoom": 0, "maxzoom": 4, "fields": {} } ] }`
    };
     
    mbtiles.putInfo(exampleInfo, function(err) {
      // continue onward
    });

    putGrid(z, x, y, grid, callback)

    Inserts a UTFGrid tile into the MBTiles store. Grids are in JSON format.

    var fs = require('fs');
    var grid = JSON.parse(fs.readFileSync('./path/to/grid.json', 'utf8'));
    mbtiles.putGrid(0, 0, 0, grid, function(err) {
      // continue onward
    });

    Hook up to tilelive

    When working at scale, node-mbtiles is meant to be used within a Tilelive ecosystem. For example, you could set up an MBTiles file as a "source" and an S3 destination as a "sink" (using tilelive-s3). Assuming you have a system set up with an mbtiles:// protocol that points to a specific file and authorized to write to the s3 bucket:

    var tilelive = require('@mapbox/tilelive');
    var MBTiles = require('@mapbox/mbtiles');
    var s3 = require('@mapbox/tilelive-s3');
     
    s3.registerProtocols(tilelive);
    MBTiles.registerProtocols(tilelive);
     
    var sourceUri = 'mbtiles:///User/hello/path/to/file.mbtiles';
    var sinkUri = 's3://my-bucket/tiles/{z}/{x}/{y}';
     
    // load the mbtiles source
    tilelive.load(sourceUri, function(err, src) {
      // load the s3 sink
      tilelive.load(sinkUri, function(err, dest) {
     
        var options = {}; // prepare options for tilelive copy
        options.listScheme = src.createZXYStream(); // create ZXY stream from mbtiles
     
        // now copy all tiles to the destination
        tilelive.copy(src, dst, options, function(err) {
          console.log('tiles are now on s3!');
        });
      });
    });

    Test

    npm test
    

    Keywords

    Install

    npm i @mapbox/mbtiles

    DownloadsWeekly Downloads

    1,862

    Version

    0.12.1

    License

    none

    Unpacked Size

    48.5 kB

    Total Files

    10

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar