MBTiles Offline

MBTiles binding for NodeJS 4+ using Callbacks and/or Promises.

Install

$ npm install --save mbtiles-offline

Usage

const MBTiles = require('mbtiles-offline')
const db = new MBTiles('example.mbtiles')

db.metadata()
//= Promise{ JSON }

db.save([1, 2, 3], Buffer([0, 1]))
db.save([2, 2, 3], Buffer([3, 4]))

db.findOne([1, 2, 3])
//= Promise { <Buffer 00 01> }

db.findAll()
//= Promise{ [[1, 2, 3], [2, 2, 3]] }

db.count()
//= Promise { 2 }

db.delete([1, 2, 3])
db.delete([2, 2, 3])

db.count()
//= Promise { 0 }

Features

| Name | Description | | ------------------------- | :----------------------------------------------- | | metadata | Retrieve Metadata from MBTiles | | update | Update Metadata | | save | Save buffer data to individual Tile | | delete | Delete individual Tile | | count | Count total tiles | | findOne | Finds one Tile and returns buffer | | findAll | Finds all Tiles | | tables | Build SQL Tables | | index | Build SQL Index | | getMinZoom | Retrieves Minimum Zoom level | | getMaxZoom | Retrieves Maximum Zoom level | | getFormat | Retrieves Image Format | | getBounds | Retrieves Bounds | | validate | Validate MBTiles according to the specifications | | hash | Creates hash from a single Tile | | hashes | Creates a hash table for all tiles |

NodeJS Support

Windows, MacOSX, Linux & Electron

• Node.js v8
• Node.js v7
• Node.js v6
• Node.js v5
• Node.js v4

Schemas

XYZ

Slippy Map is the most commonly used Tile schema for service maps as tiles, providers such as Google/ArcGIS & OpenStreetMap use this schema.

const tile1 = [1, 2, 3]
const tile2 = [2, 2, 3]
const tile3 = [1, 3, 3]
const tile4 = [2, 3, 3]
const img = Buffer([0, 1])
const db = new MBTiles('xyz.mbtiles', 'xyz')

db.save(tile1, img)
db.save(tile1, img)
db.findOne(tile1)
//= Promise { <Buffer 00 01> }
db.findAll()
//= Promise{ [[1, 2, 3], [2, 2, 3]] }

TMS

Tile Map Service is an OGC protocol for serving maps as tiles. MBTiles uses TMS as it's internal tile storage schema (TMS has an inverse Y compared to the XYZ schema).

const tile1 = [1, 5, 3]
const tile2 = [2, 5, 3]
const tile3 = [1, 4, 3]
const tile4 = [2, 4, 3]
const img = Buffer([0, 1])
const db = new MBTiles('tms.mbtiles', 'tms')

db.save(tile1, img)
db.save(tile2, img)
db.findOne(tile1)
//= Promise { <Buffer 00 01> }
db.findAll()
//= Promise{ [[1, 5, 3], [2, 5, 3]] }

Quadkey

Bing Map Tile System, a quadkey is defined as a string which represent a Tile [x,y,z].

const tile1 = '021'
const tile2 = '030'
const tile3 = '023'
const tile4 = '032'
const img = Buffer([0, 1])
const db = new MBTiles('quadkey.mbtiles', 'quadkey')

db.save(tile1, img)
db.save(tile2, img)
db.findOne(tile1)
//= Promise { <Buffer 00 01> }
db.findAll()
//= Promise { ['021', '030'] }

API

index

MBTiles

constructor

MBTiles

Parameters

• uri string Path to MBTiles
• schema string Tile schema ('xyz', 'tms', 'quadkey') (optional, default 'xyz')

Examples

const db = new MBTiles('example.mbtiles')
//= mbtiles

Returns MBTiles MBTiles

save

Save buffer data to individual Tile

Parameters

• tile Tile Tile [x, y, z]
• image Buffer Tile image

Examples

db.save([x, y, z], buffer).then(status => {
  //= status
}).catch(error => {
  //= error
})

Returns Promise<boolean> true/false

metadata

Retrieves Metadata from MBTiles

Examples

db.metadata().then(metadata => {
  //= metadata
}).catch(error => {
  //= error
})

Returns Promise<Metadata> Metadata as an Object

metadataSync

Sync: Retrieves Metadata from MBTiles

Parameters

• callback Function a method that takes (error: {Error}, metadata: {Object})

Examples

db.metadata((error, metadata) => {
  //= error
  //= metadata
})

Returns void

delete

Delete individual Tile

Parameters

• tile Tile Tile [x, y, z]

Examples

db.delete([x, y, z]).then(status => {
  //= status
}).catch(error => {
  //= error
})

Returns Promise<boolean> true/false

getMinZoom

Retrieves Minimum Zoom level

Examples

db.getMinZoom().then(minZoom => {
  //= minZoom
}).catch(error => {
  //= error
})

Returns Promise<number>

getMaxZoom

Retrieves Maximum Zoom level

Examples

db.getMaxZoom().then(maxZoom => {
  //= maxZoom
}).catch(error => {
  //= error
})

Returns Promise<number>

getFormat

Retrieves Image Format

Examples

db.getFormat().then(format => {
  //= format
}).catch(error => {
  //= error
})

Returns Promise<Formats>

getBounds

Retrieves Bounds

Parameters

• zoom number Zoom level

Examples

db.getBounds().then(bbox => {
  //= bbox
}).catch(error => {
  //= error
})

Returns Promise<BBox>

count

Count the amount of Tiles

Parameters

• tiles Array<Tile>? Only find given tiles

Examples

db.count().then(count => {
  //= count
}).catch(error => {
  //= error
})

Returns Promise<number>

update

Update Metadata

Parameters

• metadata Metadata Metadata according to MBTiles spec 1.1.0 (optional, default {})
  • metadata.attribution string Attribution
  • metadata.bounds BBox BBox [west, south, east, north] or Polygon GeoJSON
  • metadata.center Center Center [lng, lat] or [lng, lat, height]
  • metadata.description string Description
  • metadata.format Formats Format 'png' | 'jpg' | 'webp' | 'pbf'
  • metadata.minzoom number Minimum zoom level
  • metadata.maxzoom number Maximum zoom level
  • metadata.name string Name
  • metadata.url string URL source or tile scheme
  • metadata.type Types Type 'baselayer' | 'overlay' (optional, default 'baselayer')
  • metadata.version Versions Version '1.0.0' | '1.1.0' | '1.2.0' (optional, default '1.1.0')

Examples

const options = {
  name: 'Foo',
  description: 'Bar',
  minzoom: 1,
  maxzoom: 3,
  format: 'png',
  bounds: [-110, -40, 95, 50]
}
db.update(options).then(metadata => {
  //= metadata
}).catch(error => {
  //= error
})

Returns Promise<Metadata> Metadata

validate

Validate MBTiles according to the specifications

Examples

db.validate().then(status => {
  //= status
}).catch(error => {
  //= error
})

Returns Promise<boolean> true/false

findAll

Finds all Tile unique hashes

Parameters

• tiles Array<Tile>? Only find given tiles (optional, default [])

Examples

const tile1 = [33, 40, 6]
const tile2 = [20, 50, 7]
db.findAll([tile1, tile2]).then(tiles => {
  //= tiles
}).catch(error => {
  //= error
})

Returns Promise<Array<Tile>> An array of Tiles [x, y, z]

findOneSync

Sync: Finds one Tile and returns Buffer

Parameters

• tile Tile Tile [x, y, z]
• callback Function a method that takes (image: {Buffer})

Examples

db.findOneSync([x, y, z], (error, image) => {
  //= error
  //= image
})

Returns void

findOne

Finds one Tile and returns Buffer

Parameters

• tile Tile Tile [x, y, z]

Examples

db.findOne([x, y, z]).then(image => {
  //= image
}).catch(error => {
  //= error
})

Returns Promise<Buffer> Tile Data

tables

Build SQL tables

Examples

db.tables().then(status => {
  //= status
}).catch(error => {
  //= error
})

Returns Promise<boolean> true/false

index

Build SQL index

Examples

db.index().then(status => {
  //= status
}).catch(error => {
  //= error
})

Returns Promise<boolean> true/false

hash

Creates hash from a single Tile

Parameters

• tile Tile

Examples

const hash = db.hash([5, 25, 12])
//= 16797721

Returns number hash

hashes

Creates a hash table for all tiles

Parameters

• tiles Array<Tile>? Only find given tiles

Examples

await db.save([0, 0, 3], Buffer([0, 1]))
await db.save([0, 1, 3], Buffer([2, 3]))
db.hashes()
//= Promise { Set { 64, 65 } }

Returns Promise<Set<number>> hashes