From 62353d5d2cd38ad9c65ee887e2b4337c083adf5a Mon Sep 17 00:00:00 2001 From: Brandon Liu Date: Wed, 31 Mar 2021 23:08:42 +0800 Subject: [PATCH 1/2] Update README.md --- README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/README.md b/README.md index f7db625..0c2e986 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,28 @@ PMTiles is a single-file archive format for tiled data. A PMTiles archive can be See also: * [Cloud Optimized GeoTIFFs](https://www.cogeo.org) +## How To Use + +Python library: `pip install pmtiles` + + pmtiles-convert TILES.mbtiles TILES.pmtiles + pmtiles-convert TILES.pmtiles DIRECTORY + pmtiles-show TILES.pmtiles // see info about a PMTiles directory + pmtiles-serve TILES.pmtiles // start an HTTP server that decodes PMTiles into traditional Z/X/Y paths + +See https://github.com/protomaps/PMTiles/tree/master/python/bin for library usage + +JavaScript usage: + +Include the script: + + + +Example of a raster PMTiles archive decoded and displayed in Leaflet: + + const p = new pmtiles.PMTiles('osm_carto.pmtiles',{allow_200:true}) + p.leafletLayer({attribution:'© OpenStreetMap contributors'}).addTo(map) + ## Specification A detailed specification is forthcoming. PMTiles is a binary serialization format designed for two main access patterns: over the network, via HTTP 1.1 Byte Serving (`Range:` requests), or via memory-mapped files on disk. @@ -15,6 +37,7 @@ A detailed specification is forthcoming. PMTiles is a binary serialization forma * Directories are recursive, with a maximum of 21,845 entries per directory. * *21845 is the total tiles of a pyramid with 7 levels, or 1+4+16+64+256+1024+4096+16384* * Deduplication of tile data is handled by multiple entries pointing to the same offset in the archive. +* The order of tile data in the archive is unspecified; an optimized implementation should arrange tiles on a 2D space-filling curve. ### Details * The first 512 kilobytes of a PMTiles archive are reserved, and contain the headers as well as a root directory. From badb4839a8a1cded1f0d5e96a4c51e2208ff56e0 Mon Sep 17 00:00:00 2001 From: Brandon Liu Date: Thu, 1 Apr 2021 09:29:09 +0800 Subject: [PATCH 2/2] clarify README --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 0c2e986..cf520be 100644 --- a/README.md +++ b/README.md @@ -35,15 +35,15 @@ A detailed specification is forthcoming. PMTiles is a binary serialization forma ### Design considerations * Directories are recursive, with a maximum of 21,845 entries per directory. - * *21845 is the total tiles of a pyramid with 7 levels, or 1+4+16+64+256+1024+4096+16384* + * *21845 is the total tiles of a pyramid with 8 levels, or 1+4+16+64+256+1024+4096+16384* * Deduplication of tile data is handled by multiple entries pointing to the same offset in the archive. * The order of tile data in the archive is unspecified; an optimized implementation should arrange tiles on a 2D space-filling curve. ### Details -* The first 512 kilobytes of a PMTiles archive are reserved, and contain the headers as well as a root directory. +* The first 512,000 bytes of a PMTiles archive are reserved, and contain the headers as well as a root directory. * All integer values are little-endian. -* The headers begin with a magic number, "PM" -* 2 bytes: which specify the PMTiles specification version, right now always 1. +* The headers begin with a 2-byte magic number, "PM" +* 2 bytes: the PMTiles specification version, right now always 1. * 4 bytes: the length of metadata (M bytes) * 2 bytes: the number of entries in the root directory (N) * M bytes: the metadata, by convention a JSON object. @@ -52,10 +52,10 @@ A detailed specification is forthcoming. PMTiles is a binary serialization forma ### Directory structure A directory is a sequence of 17 byte entries. An entry consists of: -* 1 byte: the zoom level (Z) of the entry, with the top bit set to 1 instead of 0 to indicate the data is a child directory, not data. +* 1 byte: the zoom level (Z) of the entry, with the top bit set to 1 instead of 0 to indicate the data is a child directory, not tile content. * 3 bytes: the X (column) of the entry. * 3 bytes: the Y (row) of the entry. -* 6 bytes: the offset of where the tile begins in the archive. +* 6 bytes: the offset of where the data begins in the archive. * 4 bytes: the length of the data. ## License