Package org.geotools.pmtiles.store
Overview
This package provides a complete GeoTools DataStore
implementation for reading
PMTiles v3 archives with embedded vector tiles. It enables access to cloud-optimized tile archives from local files,
HTTP/HTTPS servers, and cloud storage providers (AWS S3, Azure Blob Storage, Google Cloud Storage).
Architecture
The implementation consists of two main components:
1. PMTiles-Specific Classes
PMTilesDataStore
- Concrete DataStore implementation for PMTilesPMTilesDataStoreFactory
- Factory for creating PMTiles datastores with configuration
2. Generic Vector Tiles Support
org.geotools.vectortiles.store
package - Generic abstractions for any vector tile source
Features
- Cloud-Optimized Access: Efficient byte-range reads minimize data transfer
- Multi-Source Support: Local files, HTTP, S3, Azure Blob, Google Cloud Storage
- Automatic Zoom Selection: Chooses optimal zoom level based on query resolution hints
- Spatial Filtering: Minimizes tile reads using bounding box extraction
- CRS Transformation: Native support for coordinate reference system transformations
- Caching: Configurable in-memory and disk caching for improved performance
- Thread-Safe: Supports concurrent access from multiple threads
Usage Example
// Create datastore from S3
Map<String, Object> params = new HashMap<>();
params.put("pmtiles", "s3://my-bucket/tiles.pmtiles");
params.put("io.tileverse.rangereader.caching.enabled", true);
params.put("io.tileverse.rangereader.caching.blockaligned", true);
PMTilesDataStore datastore = PMTilesDataStoreFactory.INSTANCE.createDataStore(params);
// Query features
String typeName = datastore.getTypeNames()[0];
SimpleFeatureSource source = datastore.getFeatureSource(typeName);
Query query = new Query(typeName);
query.setFilter(BBOX(bbox));
FeatureCollection<SimpleFeatureType, SimpleFeature> features = source.getFeatures(query);
Configuration Parameters
The datastore supports extensive configuration through PMTilesDataStoreFactory
:
Required Parameters
- pmtiles: URI to the PMTiles archive
Optional General Parameters
- namespace: Feature type namespace URI
- io.tileverse.rangereader.caching.enabled: Enable memory caching (default: false)
- io.tileverse.rangereader.caching.blockaligned: Use block-aligned caching (default: false)
- io.tileverse.rangereader.caching.blocksize: Cache block size in bytes
Cloud Provider Authentication
Authentication parameters are automatically loaded from the environment or can be explicitly configured:
- AWS S3: Access key, secret key, region, credential profiles
- Azure Blob: Account key, SAS token, blob name
- Google Cloud Storage: Project ID, application credentials
See PMTilesDataStoreFactory
for all available parameters.
Performance Optimization
For optimal performance:
- Enable memory caching for frequently accessed data
- Use block-aligned caching to align reads with tile boundaries
- Provide resolution hints (
Hints.GEOMETRY_DISTANCE
) for automatic zoom level selection - Use spatial filters (BBOX) to minimize tile reads
Thread Safety
All classes in this package are designed for thread-safe concurrent access, making them suitable for server environments like GeoServer where multiple requests may access the same datastore simultaneously.
Integration with Tileverse Libraries
This package integrates three Tileverse libraries:
- tileverse-rangereader: Provides efficient byte-range access to data sources
- tileverse-pmtiles: Implements the PMTiles format specification
- tileverse-vectortiles: Handles Mapbox Vector Tile encoding/decoding
- tileverse-tilematrixset: Manages tile pyramids and coordinate systems
-
ClassesClassDescriptionBuilder for
DataAccessFactory#Param
instances.GeoTools DataStore implementation for reading PMTiles archives containing Mapbox Vector Tiles.Factory for creatingPMTilesDataStore
instances.