From 28db5f5ec5c827a5a67e4b1e546506758686010c Mon Sep 17 00:00:00 2001 From: mapsam Date: Wed, 12 Jul 2017 14:32:48 -0700 Subject: [PATCH 1/6] some reading --- README.md | 24 +++++++++++++++++++----- test/index.test.js | 7 +++++++ 2 files changed, 26 insertions(+), 5 deletions(-) create mode 100644 test/index.test.js diff --git a/README.md b/README.md index 1d035d8..4a5e790 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,28 @@ # mbtiles -Utilities and [tilelive][1] integration for the [MBTiles][2] format. +Node.js utilities and [tilelive](https://github.com/mapbox/tilelive.js) integration for the [MBTiles](http://mbtiles.org) format. [![Build Status](https://travis-ci.org/mapbox/node-mbtiles.svg?branch=master)](https://travis-ci.org/mapbox/node-mbtiles) [![Build status](https://ci.appveyor.com/api/projects/status/04wbok5rs3eroffe)](https://ci.appveyor.com/project/Mapbox/node-mbtiles) -### Installation +# Installation - npm install @mapbox/mbtiles +``` +npm install @mapbox/mbtiles +``` +```javascript +var MBTiles = require('@mapbox/mbtiles'); +``` -[1]: https://github.com/mapbox/tilelive.js -[2]: http://mbtiles.org +# API + +### MBTiles utilities + +**Constructor** + +```javascript +new MBTiles('./path/to/file.mbtiles', function(err, mbtiles) { + // mbtiles object +}); +``` diff --git a/test/index.test.js b/test/index.test.js new file mode 100644 index 0000000..0ef764e --- /dev/null +++ b/test/index.test.js @@ -0,0 +1,7 @@ +var MBTiles = require('..'); + +new MBTiles(__dirname + '/fixtures/plain_1.mbtiles', function(err, mbtiles) { + if (err) throw err; + console.log(MBTiles.list()); + +}); From 1b5ff6ebfe7ab8cc580dca987893363614fc1104 Mon Sep 17 00:00:00 2001 From: mapsam Date: Mon, 8 Jan 2018 12:04:15 -0800 Subject: [PATCH 2/6] core api functionality --- README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 48 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4a5e790..c17da1c 100644 --- a/README.md +++ b/README.md @@ -17,12 +17,57 @@ var MBTiles = require('@mapbox/mbtiles'); # API -### MBTiles utilities +### Constructor -**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.* ```javascript new MBTiles('./path/to/file.mbtiles', function(err, mbtiles) { - // mbtiles object + console.log(mbtiles) // mbtiles object with methods listed below }); ``` + +### Reading + +**`getTile`** + +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. + +```javascript +mbtiles.getTile(z, x, y, function(err, data, headers) { + // `data` is your gzipped buffer - use zlib to gunzip or inflate +}); +``` + +**`getInfo`** + +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. + +```javascript +mbtiles.getInfo(function(err, info) { + console.log(info); // info +}); +``` + +### Writing + +**`startWriting`** AND **`stopWriting`** + +In order to write a new (or currently existing) MBTiles file you need to "start" and "stop" writing. First, [construct](#constructor) the MBTiles object. + +```javascript +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). + +**`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. From bb4970815d159a833b74c9a531b0dd53ca765816 Mon Sep 17 00:00:00 2001 From: mapsam Date: Mon, 8 Jan 2018 12:04:24 -0800 Subject: [PATCH 3/6] test note --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index c17da1c..bb1daae 100644 --- a/README.md +++ b/README.md @@ -71,3 +71,9 @@ Add a new tile buffer to a specific ZXY. This can be a raster tile or a _gzipped **`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. + +# Test + +``` +npm test +``` From c5eded628ad4c22c3d48a91ab821ecc4a0fb957f Mon Sep 17 00:00:00 2001 From: mapsam Date: Mon, 8 Jan 2018 12:14:25 -0800 Subject: [PATCH 4/6] grids --- README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bb1daae..531ecfb 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ new MBTiles('./path/to/file.mbtiles', function(err, mbtiles) { ### Reading -**`getTile`** +**`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. @@ -39,7 +39,7 @@ mbtiles.getTile(z, x, y, function(err, data, headers) { }); ``` -**`getInfo`** +**`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. @@ -49,6 +49,16 @@ mbtiles.getInfo(function(err, info) { }); ``` +**`getGrid(z, x, y, callback)`** + +Get a [UTFGrid](https://github.com/mapbox/utfgrid-spec) tile from the MBTiles table. + +```javascript +mbtiles.getGrid(z, x, y, function(err, data) { + // continue onwards +}); +``` + ### Writing **`startWriting`** AND **`stopWriting`** @@ -68,10 +78,51 @@ mbtiles.startWriting(function(err) { 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). +```javascript +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. +```javascript +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](https://github.com/mapbox/utfgrid-spec) tile into the MBTiles store. Grids are in JSON format. + +```javascript +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 +}); +``` + # Test ``` From 1bcf9b5bd54f62889ebdf0b1252a98a8fea56d3d Mon Sep 17 00:00:00 2001 From: mapsam Date: Mon, 8 Jan 2018 12:20:55 -0800 Subject: [PATCH 5/6] remove index test --- test/index.test.js | 7 ------- 1 file changed, 7 deletions(-) delete mode 100644 test/index.test.js diff --git a/test/index.test.js b/test/index.test.js deleted file mode 100644 index 0ef764e..0000000 --- a/test/index.test.js +++ /dev/null @@ -1,7 +0,0 @@ -var MBTiles = require('..'); - -new MBTiles(__dirname + '/fixtures/plain_1.mbtiles', function(err, mbtiles) { - if (err) throw err; - console.log(MBTiles.list()); - -}); From e80eae493013ccf7445bb3f84c3eeae8bb7d5795 Mon Sep 17 00:00:00 2001 From: mapsam Date: Tue, 9 Jan 2018 09:23:09 -0800 Subject: [PATCH 6/6] add tilelive example --- README.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/README.md b/README.md index 531ecfb..9647c13 100644 --- a/README.md +++ b/README.md @@ -123,6 +123,37 @@ mbtiles.putGrid(0, 0, 0, grid, function(err) { }); ``` +## Hook up to tilelive + +When working at scale, node-mbtiles is meant to be used within a [Tilelive](https://github.com/mapbox/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: + +```javascript +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 ```