Struct PMTiles 

pub struct PMTiles<R> {

    pub tile_type: TileType,
    pub tile_compression: Compression,
    pub internal_compression: Compression,
    pub min_zoom: u8,
    pub max_zoom: u8,
    pub center_zoom: u8,
    pub min_longitude: f64,
    pub min_latitude: f64,
    pub max_longitude: f64,
    pub max_latitude: f64,
    pub center_longitude: f64,
    pub center_latitude: f64,
    pub meta_data: Map<String, Value>,
    /* private fields */
}

A structure representing a PMTiles archive.

Fields

tile_type: TileType

Type of tiles

tile_compression: Compression

Compression of tiles

internal_compression: Compression

Compression of directories and meta data

min_zoom: u8

Minimum zoom of all tiles this archive

max_zoom: u8

Maximum zoom of all tiles this archive

center_zoom: u8

Center zoom

Implementations may use this to set the default zoom

min_longitude: f64

Minimum longitude of bounds of available tiles

min_latitude: f64

Minimum latitude of bounds of available tiles

max_longitude: f64

Maximum longitude of bounds of available tiles

max_latitude: f64

Maximum latitude of bounds of available tiles

center_longitude: f64

Center longitude

Implementations may use the center longitude and latitude to set the default location

center_latitude: f64

Center latitude

Implementations may use the center longitude and latitude to set the default location

meta_data: Map<String, Value>

JSON meta data of this archive

Implementations

impl PMTiles<Cursor<&[u8]>>

pub fn new(tile_type: TileType, tile_compression: Compression) -> Self

Constructs a new, empty PMTiles archive, with no meta data, an internal_compression of GZIP and all numeric fields set to 0.

Arguments

• tile_type - Type of tiles in this archive
• tile_compression - Compression of tiles in this archive

impl PMTiles<Cursor<&[u8]>>

pub fn new_async(tile_type: TileType, tile_compression: Compression) -> Self

Available on crate feature async only.

Async version of new.

Constructs a new, empty PMTiles archive, that works with asynchronous readers / writers.

Arguments

• tile_type - Type of tiles in this archive
• tile_compression - Compression of tiles in this archive

impl<R> PMTiles<R>

pub fn tile_ids(&self) -> Vec<&u64>

Get vector of all tile ids in this PMTiles archive.

pub fn add_tile(&mut self, tile_id: u64, data: impl Into<Vec<u8>>) -> Result<()>

Adds a tile to this PMTiles archive.

Note that the data should already be compressed if Self::tile_compression is set to a value other than Compression::None. The data will NOT be compressed automatically.
The util-module includes utilities to compress data.

Errors

Will return Err if data converts into an empty Vec.

pub fn remove_tile(&mut self, tile_id: u64)

Removes a tile from this archive.

pub fn num_tiles(&self) -> usize

Returns the number of addressed tiles in this archive.

impl<R: Read + Seek> PMTiles<R>

pub fn get_tile_by_id(&mut self, tile_id: u64) -> Result<Option<Vec<u8>>>

Get data of a tile by its id.

The returned data is the raw data, meaning It is NOT uncompressed automatically, if it was compressed in the first place.
If you need the uncompressed data, take a look at the util-module

Will return Ok with an value of None if no a tile with the specified tile id was found.

Errors

Will return Err if the tile data was not read into memory yet and there was an error while attempting to read it.

pub fn get_tile(&mut self, x: u64, y: u64, z: u8) -> Result<Option<Vec<u8>>>

Returns the data of the tile with the specified coordinates.

See get_tile_by_id for further details on the return type.

Errors

See get_tile_by_id for details on possible errors.

impl<R: AsyncRead + AsyncReadExt + Send + Unpin + AsyncSeekExt> PMTiles<R>

pub async fn get_tile_by_id_async( &mut self, tile_id: u64, ) -> Result<Option<Vec<u8>>>

Available on crate feature async only.

Async version of get_tile_by_id.

Get data of a tile by its id.

The returned data is the raw data, meaning It is NOT uncompressed automatically, if it was compressed in the first place.
If you need the uncompressed data, take a look at the util-module

Will return Ok with an value of None if no a tile with the specified tile id was found.

Errors

Will return Err if the tile data was not read into memory yet and there was an error while attempting to read it.

pub async fn get_tile_async( &mut self, x: u64, y: u64, z: u8, ) -> Result<Option<Vec<u8>>>

Available on crate feature async only.

Async version of get_tile.

Returns the data of the tile with the specified coordinates.

See get_tile_by_id_async for further details on the return type.

Errors

See get_tile_by_id_async for details on possible errors.

impl<R: Read + Seek> PMTiles<R>

pub fn from_reader(input: R) -> Result<Self>

Reads a PMTiles archive from a reader.

This takes ownership of the reader, because tile data is only read when required.

Arguments

• input - Reader

Errors

Will return Err if there was any kind of I/O error while reading from input, the data stream was no valid PMTiles archive or the internal compression of the archive is set to “Unknown”.

Example

let mut file = std::fs::File::open(file_path).unwrap();

let pm_tiles = PMTiles::from_reader(file).unwrap();

pub fn from_reader_partially( input: R, tiles_filter_range: impl RangeBounds<u64>, ) -> Result<Self>

Same as from_reader, but with an extra parameter.

Reads a PMTiles archive from a reader, but only parses tile entries whose tile IDs are included in the filter range. Tiles that are not included in the range will appear as missing.

This can improve performance in cases where only a limited range of tiles is needed, as whole leaf directories may be skipped during parsing.

Arguments

• input - Reader
• tiles_filter_range - Range of Tile IDs to load

Errors

See from_reader for details on possible errors.

Example

let mut file = std::fs::File::open(file_path).unwrap();

let pm_tiles = PMTiles::from_reader_partially(file, ..).unwrap();

pub fn to_writer(self, output: &mut (impl Write + Seek)) -> Result<()>

Writes the archive to a writer.

The archive is always deduped and the directory entries clustered to produce the smallest possible archive size.

This takes ownership of the object so all data does not need to be copied. This prevents large memory consumption when writing large PMTiles archives.

Arguments

• output - Writer to write data to

Errors

Will return Err if Self::internal_compression was set to Compression::Unknown or an I/O error occurred while writing to output.

Example

Write the archive to a file.

let pm_tiles = PMTiles::new(TileType::Png, Compression::None);
let mut file = std::fs::File::create(file_path).unwrap();
pm_tiles.to_writer(&mut file).unwrap();

impl<T: AsRef<[u8]>> PMTiles<Cursor<T>>

pub fn from_bytes(bytes: T) -> Result<Self>

Reads a PMTiles archive from anything that can be turned into a byte slice (e.g. Vec<u8>).

Arguments

• bytes - Input bytes

Errors

Will return Err if there was any kind of I/O error while reading from input, the data stream was no valid PMTiles archive or the internal compression of the archive is set to “Unknown”.

Example

let bytes = include_bytes!("../test/stamen_toner(raster)CC-BY+ODbL_z3.pmtiles");
let pm_tiles = PMTiles::from_bytes(bytes).unwrap();

pub fn from_bytes_partially( bytes: T, tiles_filter_range: impl RangeBounds<u64>, ) -> Result<Self>

Same as from_bytes, but with an extra parameter.

Reads a PMTiles archive from something that can be turned into a byte slice (e.g. Vec<u8>), but only parses tile entries whose tile IDs are included in the filter range. Tiles that are not included in the range will appear as missing.

This can improve performance in cases where only a limited range of tiles is needed, as whole leaf directories may be skipped during parsing.

Arguments

• bytes - Input bytes
• tiles_filter_range - Range of Tile IDs to load

Errors

See from_bytes for details on possible errors.

Example

let bytes = include_bytes!("../test/stamen_toner(raster)CC-BY+ODbL_z3.pmtiles");
let pm_tiles = PMTiles::from_bytes_partially(bytes, ..).unwrap();

impl<R: AsyncRead + AsyncSeekExt + Send + Unpin> PMTiles<R>

pub async fn from_async_reader(input: R) -> Result<Self>

Available on crate feature async only.

Async version of from_reader.

Reads a PMTiles archive from a reader.

This takes ownership of the reader, because tile data is only read when required.

Arguments

• input - Reader

Errors

Will return Err if there was any kind of I/O error while reading from input, the data stream was no valid PMTiles archive or the internal compression of the archive is set to “Unknown”.

Example

let bytes = include_bytes!("../test/stamen_toner(raster)CC-BY+ODbL_z3.pmtiles");
let mut reader = futures::io::Cursor::new(bytes);

let pm_tiles = PMTiles::from_async_reader(reader).await.unwrap();

pub async fn from_async_reader_partially( input: R, tiles_filter_range: impl RangeBounds<u64> + Sync + Send, ) -> Result<Self>

Available on crate feature async only.

Same as from_async_reader, but with an extra parameter.

Reads a PMTiles archive from a reader, but only parses tile entries whose tile IDs are included in the filter range. Tiles that are not included in the range will appear as missing.

This can improve performance in cases where only a limited range of tiles is needed, as whole leaf directories may be skipped during parsing.

Arguments

• input - Reader
• tiles_filter_range - Range of Tile IDs to load

Errors

See from_async_reader for details on possible errors.

Example

let bytes = include_bytes!("../test/stamen_toner(raster)CC-BY+ODbL_z3.pmtiles");
let mut reader = futures::io::Cursor::new(bytes);

let pm_tiles = PMTiles::from_async_reader_partially(reader, ..).await.unwrap();

pub async fn to_async_writer( self, output: &mut (impl AsyncWrite + AsyncSeekExt + Unpin + Send), ) -> Result<()>

Available on crate feature async only.

Async version of to_writer.

Writes the archive to a writer.

The archive is always deduped and the directory entries clustered to produce the smallest possible archive size.

This takes ownership of the object so all data does not need to be copied. This prevents large memory consumption when writing large PMTiles archives.

Arguments

• output - Writer to write data to

Errors

Will return Err if Self::internal_compression was set to Compression::Unknown or an I/O error occurred while writing to output.

Example

Write the archive to a file.

let pm_tiles = PMTiles::new_async(TileType::Png, Compression::None);
let mut out_file = tokio::fs::File::create(file_path).await.unwrap().compat();
pm_tiles.to_async_writer(&mut out_file).await.unwrap();

Trait Implementations

impl<R: Debug> Debug for PMTiles<R>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<R> Default for PMTiles<R>

fn default() -> Self

Returns the “default value” for a type.