Package org.geotools.vectortiles.store

package org.geotools.vectortiles.store
Generic GeoTools DataStore abstractions for tiled vector data sources.

Overview

This package provides reusable abstractions for creating GeoTools DataStores that read vector tiles from tile archives or services. While designed primarily for PMTiles, these abstractions can be used with any tiled vector data source that implements the Tileverse VectorTileStore interface.

Architecture

The package follows a layered architecture that separates GeoTools integration concerns from tile-specific logic: 

 ┌─────────────────────────────────────────────┐
 │  GeoTools Query API (Query, Filter, etc.)   │
 └─────────────────┬───────────────────────────┘
                   │
 ┌─────────────────▼───────────────────────────┐
 │  VectorTilesFeatureSource                   │
 │  - Query translation                        │
 │  - Zoom level selection                     │
 │  - Spatial filtering optimization           │
 │  - CRS transformation                       │
 └─────────────────┬───────────────────────────┘
                   │
 ┌─────────────────▼───────────────────────────┐
 │  VectorTilesFeatureReader                   │
 │  - Vector tile → GeoTools feature mapping   │
 │  - Clip mask handling                       │
 │  - Feature filtering                        │
 └─────────────────┬───────────────────────────┘
                   │
 ┌─────────────────▼───────────────────────────┐
 │  Tileverse VectorTileStore                  │
 │  - Tile reading                             │
 │  - Spatial indexing                         │
 │  - MVT decoding                             │
 └─────────────────────────────────────────────┘

Core Classes

Data Store Layer

Feature Access Layer

  • VectorTilesFeatureSource - Feature source with query optimization
  • VectorTilesFeatureReader - Converts vector tile features to GeoTools features
  • VectorTilesSimpleFeature - SimpleFeature wrapper for vector tile features

Utility Classes

  • StreamFeatureReader - Stream-based feature reader with filtering and pagination
  • ExtractMultiBoundsFilterVisitor - Extracts bounding boxes from complex filters as a list of individual envelopes from spatial predicates, for VectorTileStore to skip tiles that would otherwise be included only as the result of union'ing all the bounding boxes in the GeoTools filter.
  • VectorTilesFeaturePropertyAccessorFactory - Property access for filtering at the vector tile level

Main Features

Query Optimization

  • Automatic Zoom Level Selection: Selects the optimal zoom level based on query resolution hints (Hints.GEOMETRY_DISTANCE, GEOMETRY_SIMPLIFICATION, GEOMETRY_GENERALIZATION)
  • Spatial Filtering: Extracts bounding boxes from filters to minimize tile reads
  • Pre-Filtering: Applies filters at the vector tile level before converting to GeoTools features
  • Property Selection: Supports schema subsetting to reduce data transfer

CRS Transformation

  • Efficient Reprojection: Uses affine transformations for in-place coordinate sequence transformation where possible
  • Filter Reprojection: Automatically reprojects spatial filters to the native CRS

Rendering Support

  • Clip Masks: Provides tile boundary clip masks via Hints.GEOMETRY_CLIP for correct rendering
  • Generalization Hints: Supports topology-preserving and non-topology-preserving simplification

Query Capabilities

The vector tiles feature source supports:

  • Filtering: Full GeoTools filter support (spatial, attribute, logical)
  • Reprojection: Automatic CRS transformation
  • Retyping: Property selection and schema subsetting
  • Pagination: Offset and limit support
  • Sorting: Natural order only (tile order)

Feature Type Schema

Feature types are automatically derived from vector layer metadata (TileJSON):

  • Attribute Fields: Mapped from TileJSON field definitions (String, Number, Boolean)
  • Geometry Attribute: Added automatically with the tile matrix set's CRS
  • Type Name: Derived from the layer ID
  • Description: Optional layer description from metadata

Zoom Level Selection Strategy

The zoom level selection algorithm considers:

  1. Query resolution hints (GEOMETRY_DISTANCE, etc.)
  2. Layer-specific min/max zoom levels from TileJSON
  3. Tile matrix set available zoom levels
  4. Query strategy:
    • SPEED: When simplification hints are present, favors lower zoom levels
    • QUALITY: When no simplification hints, favors higher zoom levels

Implementation Guide

To create a new vector tile datastore: 


 // 1. Implement VectorTileStore for your tile source
 public class MyVectorTileStore implements VectorTileStore {
     // Implement tile reading, metadata, etc.
 }

 // 2. Extend VectorTilesDataStore
 public class MyDataStore extends VectorTilesDataStore {
     public MyDataStore(VectorTileStore tileStore) throws IOException {
         super(MyDataStoreFactory.INSTANCE, tileStore);
     }
 }

 // 3. Create a DataStoreFactory
 public class MyDataStoreFactory implements DataStoreFactorySpi {
     public MyDataStore createDataStore(Map<String, ?> params) {
         // Create VectorTileStore and wrap it
     }
 }

Thread Safety

All classes in this package are designed for thread-safe concurrent access. The underlying VectorTileStore must also be thread-safe.

Performance Considerations

  • Feature Count: Returns -1 (expensive to calculate for tiled data)
  • Bounds Calculation: Returns null for filtered queries (requires full scan)
  • Memory Usage: Features are streamed, not loaded entirely into memory
  • Filter Pushdown: Spatial and attribute filters are applied at the vector tile level before feature conversion

Related Packages

See Also: