Skip to content

Latest commit

 

History

History
171 lines (134 loc) · 5.71 KB

README.md

File metadata and controls

171 lines (134 loc) · 5.71 KB
Raw

YAGA IndexedDB Tile Cache

Build Status Coverage Status FOSSA Status

A tile storage and cache that uses the browsers IndexedDB to store the spatial map tiles.

Key features

  • On the fly downloading, storing and serving
  • Maximal age and auto upgrading of tiles as long as there is a connection
  • Seeding in your browser with a bounding box and a zoom level range
  • Possibility to serve tiles as base64 data-url including its content type
  • Well tested and documented
  • Written in and for TypeScript

How to use

At first you have to install this library with npm or yarn:

npm install --save @yaga/indexed-db-tile-cache
# OR
yarn install --save @yaga/indexed-db-tile-cache

After that you can import this module into your application with the typical node.js or TypeScript way.

keep in mind that you have to use browserify to package the libraries from the node.js environment into your browser ones, such as Buffer or request.

Working with a tile-cache

JavaScript

const indexedDbTileCache = require('@yaga/indexed-db-tile-cache');
// if you use the precompiled version you can use it similar, just with this change:
// const indexedDbTileCache = window.yaga.tileCache;

const options = {
        databaseName: "tile-cache-data", // optional
        databaseVersion: 1, // optional
        objectStoreName: "OSM", // optional
        tileUrl: "http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", // optional
        tileUrlSubDomains: ["a", "b", "c"], // optional
        crawlDelay: 500, // optional
        maxAge: 1000 * 60 * 60 * 24 * 7, // optional
};

const tileCache = new indexedDbTileCache.IndexedDbTileCache(options);

// get a tile from cache or download if not available:
tileCache.getTileAsDataUrl({x:0, y: 0, z: 0}).then(function(dataUrl) {
    const img = document.createElement("img");
    img.src = dataUrl;
    document.body.appendChild(img);
}, function(err) {
    console.error(err);
});

// seed an area:
tileCache.on("seed-progress", function (progress) {
    console.log(progess.remains + ' of ' + progress.total + 'tiles remains...');
});
tileCache.seedBBox({
    maxLat: 10,
    maxLng: 10,
    minLat: 1,
    minLng: 1,
}).then(function(duration) {
    console.log('Seeding completed in ' + duration + 'ms');
}, function(err) {
    console.error(err);
});

TypeScript

import {
    IIndexedDbTileCacheOptions,
    IIndexedDbTileCacheSeedProgress,
    IndexedDbTileCache,
} from "@yaga/indexed-db-tile-cache";

const options: IIndexedDbTileCacheOptions = {
        databaseName: "tile-cache-data", // optional
        databaseVersion: 1, // optional
        objectStoreName: "OSM", // optional
        tileUrl: "http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", // optional
        tileUrlSubDomains: ["a", "b", "c"], // optional
        crawlDelay: 500, // optional
        maxAge: 1000 * 60 * 60 * 24 * 7, // optional
};

const tileCache = new IndexedDbTileCache(options);

// get a tile from cache or download if not available:
tileCache.getTileAsDataUrl({x:0, y: 0, z: 0}).then((dataUrl: string) => {
    const img = document.createElement("img");
    img.src = dataUrl;
    document.body.appendChild(img);
}, (err) => {
    console.error(err);
});

// seed an area:
tileCache.on("seed-progress", (progress: IIndexedDbTileCacheSeedProgress) => {
    console.log(`${ progess.remains } of ${ progress.total } tiles remains...`);
});
tileCache.seedBBox({
    maxLat: 10,
    maxLng: 10,
    minLat: 1,
    minLng: 1,
}).then((duration: number) => {
    console.log(`Seeding completed in ${ duration }ms`);
}, (err) => {
    console.error(err);
});

There are more methods available, for further information take a look at the API documentation...

Precompiled version

If you just want to use this library without having the pros of a module loader, you can also run the npm dist task for a packaged and precompiled version.

At first run:

npm run dist

After that you have a dist.js and a dist.min.js in this project root folder. Now you can use this library like this:

<html>
  <head>
    <script src="dist.min.js"></script>
    <script>
      const tileCache = new yaga.tileCache.IndexedDbTileCache();
    </script>
  </head>
</html>

NPM script tasks

  • npm test: Runs the software tests with karma and leaves a coverage report under the folder coverage.
  • npm run browser-test: Prepares the tests to run directly in your browser. After running this command you have to open browser-test/index.html in your browser of choice.
  • npm run dist: Creates an isolated package (without module loader) and registers the module under window.yaga.tileCache.*.
  • npm run doc: Creates the API documentation with typedoc and places the documentation in the folder typedoc.

Contribution

Make an issue on GitHub, or even better a pull request and try to fulfill the software tests.

License

This library is under ISC License © by Arne Schubert and the YAGA Development Team.

FOSSA Status