Package 'pmtiles'

Description

These helpers build the bucket specification used by pm_upload(), pm_show(), pm_extract(), pm_tile(), and pm_serve_zxy(), so you never have to hand-assemble a "s3://bucket?endpoint=...&region=..." URL. Each helper knows the URL format and required parameters for its provider:

• r2_bucket(): Cloudflare R2 (the recommended PMTiles host; no egress fees)

• s3_bucket(): Amazon S3

• gcs_bucket(): Google Cloud Storage

• azure_bucket(): Azure Blob Storage

• s3_compatible_bucket(): any other S3-compatible service (MinIO, DigitalOcean Spaces, Backblaze B2, Source Cooperative, ...)

Credentials can optionally be supplied to each helper. When provided, they are passed only to the pmtiles subprocess for that one command – they are never written into your R session's environment variables. When omitted, the standard environment variables for the provider are used (e.g. AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY for S3 and R2).

Usage

r2_bucket(
  bucket,
  account_id,
  jurisdiction = NULL,
  access_key = NULL,
  secret_key = NULL
)

s3_bucket(
  bucket,
  region = NULL,
  access_key = NULL,
  secret_key = NULL,
  session_token = NULL
)

gcs_bucket(bucket, credentials_file = NULL)

azure_bucket(container, storage_account, access_key = NULL, sas_token = NULL)

s3_compatible_bucket(
  bucket,
  endpoint,
  region = NULL,
  path_style = FALSE,
  access_key = NULL,
  secret_key = NULL,
  session_token = NULL
)

Arguments

Value

An object of class pmtiles_bucket: the bucket URL plus any credentials to pass to the pmtiles subprocess. Pass it as the bucket argument of pm_upload() and friends, anywhere a bucket string is accepted.

Cloudflare R2

You need three things, all from the Cloudflare dashboard:

1. Account ID: R2 overview page, right-hand Account Details panel.

2. Access key + secret key: Manage R2 API Tokens > Create API Token with "Object Read & Write" permission. The token-creation screen shows the Access Key ID and Secret Access Key once – store them (e.g. in ⁠~/.Renviron⁠).

3. Bucket name: the name you gave the bucket when creating it.

R2's S3 API requires region=auto; the helper sets this for you.

Amazon S3

Credentials follow the standard AWS chain: AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY environment variables, shared config files (⁠~/.aws/credentials⁠), or an attached IAM role. Supply access_key / secret_key only if you want to override that chain for this command.

Google Cloud Storage

Authentication uses Application Default Credentials. Either run ⁠gcloud auth application-default login⁠ once, or create a service account key (IAM & Admin > Service Accounts > Keys) and pass its JSON file path as credentials_file.

Azure Blob Storage

Find the storage account's access keys under Storage account > Security + networking > Access keys in the Azure portal. Pass one as access_key, or use a SAS token via sas_token. If neither is given, the AZURE_STORAGE_KEY / AZURE_STORAGE_SAS_TOKEN environment variables are used.

Other S3-compatible services

Use s3_compatible_bucket() with the provider's endpoint:

Examples

## Not run: 
# Cloudflare R2: upload with credentials from ~/.Renviron
pm_upload(
  "tiles.pmtiles",
  "tiles.pmtiles",
  bucket = r2_bucket(
    "my-tiles",
    account_id = "0123456789abcdef0123456789abcdef",
    access_key = Sys.getenv("R2_ACCESS_KEY_ID"),
    secret_key = Sys.getenv("R2_SECRET_ACCESS_KEY")
  )
)

# Amazon S3, using the standard AWS credential chain
pm_upload(
  "tiles.pmtiles",
  "tiles.pmtiles",
  bucket = s3_bucket("my-tiles", region = "us-east-1")
)

# Google Cloud Storage with a service account key
pm_upload(
  "tiles.pmtiles",
  "tiles.pmtiles",
  bucket = gcs_bucket("my-tiles", credentials_file = "~/keys/gcs.json")
)

# Azure Blob Storage
pm_upload(
  "tiles.pmtiles",
  "tiles.pmtiles",
  bucket = azure_bucket(
    "tiles-container",
    storage_account = "mystorageaccount",
    access_key = Sys.getenv("AZURE_STORAGE_KEY")
  )
)

# DigitalOcean Spaces (any S3-compatible service)
pm_upload(
  "tiles.pmtiles",
  "tiles.pmtiles",
  bucket = s3_compatible_bucket(
    "my-tiles",
    endpoint = "https://nyc3.digitaloceanspaces.com",
    access_key = Sys.getenv("DO_SPACES_KEY"),
    secret_key = Sys.getenv("DO_SPACES_SECRET")
  )
)

# The helpers work everywhere a bucket is accepted
bucket <- r2_bucket("my-tiles", account_id = "0123456789abcdef0123456789abcdef")
pm_show("tiles.pmtiles", bucket = bucket)
pm_extract("tiles.pmtiles", "subset.pmtiles", bucket = bucket, maxzoom = 10)

## End(Not run)

Description

Cluster an unclustered PMTiles archive, optimizing its size and layout. Archives created by tippecanoe, planetiler, and the pmtiles CLI are already clustered and do not need this operation.

Usage

pm_cluster(input, no_deduplication = FALSE, verbose = TRUE)

Arguments

Value

Invisibly returns the path to the clustered archive.

Examples

## Not run: 
# Cluster an archive
pm_cluster("archive.pmtiles")

# Cluster without deduplication (faster)
pm_cluster("archive.pmtiles", no_deduplication = TRUE)

## End(Not run)

Description

Convert an MBTiles database to PMTiles format. The conversion process automatically deduplicates tiles unless disabled.

Usage

pm_convert(
  input,
  output,
  force = FALSE,
  no_deduplication = FALSE,
  tmpdir = NULL,
  verbose = TRUE
)

Arguments

Value

Invisibly returns the path to the output archive.

Examples

## Not run: 
# Convert MBTiles to PMTiles
pm_convert("input.mbtiles", "output.pmtiles")

# Convert without deduplication (faster)
pm_convert("input.mbtiles", "output.pmtiles", no_deduplication = TRUE)

# Force overwrite existing file
pm_convert("input.mbtiles", "output.pmtiles", force = TRUE)

## End(Not run)

Description

Generate vector tiles from GeoJSON, FlatGeobuf, or CSV input using tippecanoe. This function requires tippecanoe to be installed on your system. See https://github.com/felt/tippecanoe for installation instructions.

Usage

pm_create(
  input,
  output,
  layer_name = NULL,
  min_zoom = NULL,
  max_zoom = NULL,
  guess_maxzoom = FALSE,
  smallest_maximum_zoom_guess = NULL,
  base_zoom = NULL,
  extend_zooms_if_still_dropping = FALSE,
  full_detail = NULL,
  low_detail = NULL,
  minimum_detail = NULL,
  extra_detail = NULL,
  exclude = NULL,
  include = NULL,
  exclude_all = FALSE,
  drop_rate = NULL,
  drop_densest_as_needed = FALSE,
  drop_fraction_as_needed = FALSE,
  drop_smallest_as_needed = FALSE,
  drop_lines = FALSE,
  drop_polygons = FALSE,
  coalesce = FALSE,
  coalesce_smallest_as_needed = FALSE,
  coalesce_densest_as_needed = FALSE,
  coalesce_fraction_as_needed = FALSE,
  cluster_distance = NULL,
  cluster_maxzoom = NULL,
  simplification = NULL,
  no_line_simplification = FALSE,
  simplify_only_low_zooms = FALSE,
  no_tiny_polygon_reduction = FALSE,
  detect_shared_borders = FALSE,
  no_simplification_of_shared_nodes = FALSE,
  preserve_input_order = FALSE,
  reorder = FALSE,
  hilbert = FALSE,
  maximum_tile_bytes = NULL,
  maximum_tile_features = NULL,
  no_feature_limit = FALSE,
  no_tile_size_limit = FALSE,
  generate_ids = TRUE,
  calculate_feature_density = FALSE,
  read_parallel = FALSE,
  attribution = NULL,
  description = NULL,
  buffer = NULL,
  other_options = NULL,
  force = TRUE,
  keep_geojson = FALSE,
  quiet = FALSE
)

Arguments

Details

This function wraps the tippecanoe command-line tool. Tippecanoe must be installed separately:

• macOS: brew install tippecanoe

• Ubuntu: sudo apt-get install tippecanoe

• From source: https://github.com/felt/tippecanoe

The function handles sf objects by converting them to temporary GeoJSON files. For faster GeoJSON writing with large datasets, install the yyjsonr package, which can be significantly faster than the default sf::st_write().

Value

Path to output file (invisibly)

See Also

pm_layer() for creating layers with per-layer options

Examples

## Not run: 
library(sf)

# Simple usage with sf object
pm_create(
  my_sf_data,
  "output.pmtiles",
  max_zoom = 14
)

# Complex parcel tileset
pm_create(
  "parcels.geojson",
  "parcels.pmtiles",
  layer_name = "parcels",
  min_zoom = 10,
  max_zoom = 18,
  full_detail = 15,
  preserve_input_order = TRUE,
  no_tiny_polygon_reduction = TRUE,
  coalesce_densest_as_needed = TRUE,
  coalesce_fraction_as_needed = TRUE,
  extend_zooms_if_still_dropping = TRUE,
  simplification = 1,
  detect_shared_borders = TRUE,
  other_options = c("-pf", "-pk", "-ai")
)

# Point clustering
pm_create(
  points_sf,
  "points.pmtiles",
  max_zoom = 14,
  cluster_distance = 10,
  cluster_maxzoom = "g",
  generate_ids = TRUE
)

# With attribute filtering
pm_create(
  roads_sf,
  "roads.pmtiles",
  include = c("name", "highway", "surface"),
  drop_densest_as_needed = TRUE,
  simplification = 10
)

# Multi-layer with shared options (simple)
pm_create(
  input = list(
    counties = counties_sf,
    tracts = tracts_sf
  ),
  output = "census.pmtiles",
  min_zoom = 2,
  max_zoom = 12
)

# Multi-layer with per-layer options (using pm_layer)
pm_create(
  input = list(
    pm_layer(
      input = counties_sf,
      layer_name = "counties",
      min_zoom = 2,
      max_zoom = 8
    ),
    pm_layer(
      input = tracts_sf,
      layer_name = "tracts",
      min_zoom = 8,
      max_zoom = 14,
      drop_densest_as_needed = TRUE
    )
  ),
  output = "census.pmtiles",
  generate_ids = TRUE
)

## End(Not run)

Description

Modify parts of the PMTiles archive header or replace the JSON metadata. Editing only the header modifies the file in-place, while editing metadata creates a new copy.

Usage

pm_edit(input, header_json = NULL, metadata = NULL, verbose = TRUE)

Arguments

Value

Invisibly returns the path to the edited archive.

Editable Header Fields

The following header fields can be modified:

• tile_type: Type of tiles (e.g., "mvt", "png", "jpg")

• tile_compression: Compression format

• minzoom: Minimum zoom level

• maxzoom: Maximum zoom level

• bounds: Geographic bounds

• center: Center point and zoom

Other header fields are not editable.

Important Notes

• Editing only the header modifies the file in-place

• Writing new metadata requires creating a new archive copy

• The new copy will replace the original file

Examples

## Not run: 
# Get current header and metadata
header <- pm_show("archive.pmtiles", header_json = TRUE)
metadata <- pm_show("archive.pmtiles", metadata = TRUE)

# Modify and save to JSON files
jsonlite::write_json(header, "header.json", auto_unbox = TRUE)
jsonlite::write_json(metadata, "metadata.json", auto_unbox = TRUE)

# Edit the archive
pm_edit("archive.pmtiles",
        header_json = "header.json",
        metadata = "metadata.json")

## End(Not run)

Description

Create a smaller PMTiles archive from a larger one by extracting a subset of zoom levels or a geographic region. The source archive can be local or remote.

Usage

pm_extract(
  input,
  output,
  bbox = NULL,
  region = NULL,
  minzoom = NULL,
  maxzoom = NULL,
  bucket = NULL,
  download_threads = 4,
  overfetch = 0.05,
  dry_run = FALSE,
  verbose = TRUE
)

Arguments

Details

Extracting a full sub-pyramid from zoom 0 to maxzoom is an efficient operation. However, using a minzoom > 0 may require many more requests and should only be used when necessary.

Value

Invisibly returns the path to the output archive.

Examples

## Not run: 
# Extract zoom levels 0-10
pm_extract("large.pmtiles", "subset.pmtiles", maxzoom = 10)

# Extract by bounding box
pm_extract(
  "large.pmtiles",
  "bbox_subset.pmtiles",
  bbox = c(-122.5, 37.7, -122.3, 37.9)
)

# Extract by GeoJSON region
pm_extract(
  "large.pmtiles",
  "region_subset.pmtiles",
  region = "boundary.geojson",
  maxzoom = 12
)

# Extract from remote archive
pm_extract(
  "large.pmtiles",
  "local_copy.pmtiles",
  bucket = "s3://my-bucket",
  maxzoom = 10,
  download_threads = 8
)

## End(Not run)

Description

Creates a layer specification for use with pm_create() when building multi-layer PMTiles with per-layer tippecanoe options. Each layer can have its own zoom levels, drop rates, simplification settings, and other options.

Usage

pm_layer(
  input,
  layer_name,
  min_zoom = NULL,
  max_zoom = NULL,
  guess_maxzoom = NULL,
  smallest_maximum_zoom_guess = NULL,
  base_zoom = NULL,
  extend_zooms_if_still_dropping = NULL,
  full_detail = NULL,
  low_detail = NULL,
  minimum_detail = NULL,
  extra_detail = NULL,
  exclude = NULL,
  include = NULL,
  exclude_all = NULL,
  drop_rate = NULL,
  drop_densest_as_needed = NULL,
  drop_fraction_as_needed = NULL,
  drop_smallest_as_needed = NULL,
  drop_lines = NULL,
  drop_polygons = NULL,
  coalesce = NULL,
  coalesce_smallest_as_needed = NULL,
  coalesce_densest_as_needed = NULL,
  coalesce_fraction_as_needed = NULL,
  cluster_distance = NULL,
  cluster_maxzoom = NULL,
  simplification = NULL,
  no_line_simplification = NULL,
  simplify_only_low_zooms = NULL,
  no_tiny_polygon_reduction = NULL,
  detect_shared_borders = NULL,
  no_simplification_of_shared_nodes = NULL,
  preserve_input_order = NULL,
  reorder = NULL,
  hilbert = NULL,
  maximum_tile_bytes = NULL,
  maximum_tile_features = NULL,
  no_feature_limit = NULL,
  no_tile_size_limit = NULL,
  generate_ids = NULL,
  calculate_feature_density = NULL,
  read_parallel = NULL,
  buffer = NULL,
  other_options = NULL
)

Arguments

Value

A list with class "pm_layer" containing the input and all specified options.

See Also

pm_create()

Examples

## Not run: 
library(sf)

# Create a multi-layer PMTiles with per-layer options
pm_create(
  input = list(
    pm_layer(
      input = counties_sf,
      layer_name = "counties",
      min_zoom = 2,
      max_zoom = 8
    ),
    pm_layer(
      input = tracts_sf,
      layer_name = "tracts",
      min_zoom = 8,
      max_zoom = 14,
      drop_densest_as_needed = TRUE
    )
  ),
  output = "census.pmtiles",
  generate_ids = TRUE
)

## End(Not run)

Description

Combine two or more disjoint PMTiles archives into a single archive. Archives are disjoint when no tile coordinate appears in more than one input – for example, tilesets covering non-overlapping geographic regions at the same zoom levels, or the same region at non-overlapping zoom ranges.

Usage

pm_merge(inputs, output, verbose = TRUE)

Arguments

Details

Merging is performed by the go-pmtiles CLI (⁠pmtiles merge⁠). The input archives must be disjoint; merging archives that contain the same tile coordinates is an error. All inputs must also share the same tile type and tile compression.

The merged archive's JSON metadata and center are copied from the first input only. In particular, vector_layers metadata comes from the first archive – so inputs should use the same layer name(s), or layers present only in later inputs will be missing from the merged metadata even though their tiles are included. To recombine tilesets with differing layers, re-create the archive from source data instead (see pm_create(), which supports multi-layer output via pm_layer()).

Value

Invisibly returns the path to the output archive.

See Also

pm_create(), pm_extract(), pm_convert()

Examples

## Not run: 
# Merge two regional tilesets into one archive
pm_merge(
  c("west_region.pmtiles", "east_region.pmtiles"),
  output = "combined.pmtiles"
)

## End(Not run)

Description

Start a local HTTP server to serve PMTiles files with CORS headers enabled. This allows PMTiles to be consumed by web maps (like mapgl) using the PMTiles.js client library. The server runs in the background and can be stopped with pm_stop_server().

Usage

pm_serve(path, port = 8080, background = TRUE)

Arguments

Details

This function serves the raw PMTiles files with CORS headers, allowing them to be consumed by PMTiles.js in the browser. This works with mapgl's PMTiles protocol and pm_view() for quick visualization.

For a file at tiles/data.pmtiles, it will be available at: ⁠http://localhost:PORT/data.pmtiles⁠

File size: Works well for files up to ~1GB. For larger files, consider pm_serve_zxy() or serving from a Node.js server like http-server.

The server uses httpuv with custom CORS headers and HTTP range request support. When background = TRUE, the server runs as a background daemon.

Value

If background = TRUE, returns a list with:

• url: Base URL of the server

• port: Port number

• dir: Directory being served

• daemon: Server daemon ID (for stopping)

If background = FALSE, blocks until interrupted and returns nothing.

See Also

pm_stop_server(), pm_view()

Examples

## Not run: 
# Serve a single PMTiles file
server <- pm_serve("data.pmtiles", port = 8080)
# File available at: http://localhost:8080/data.pmtiles

# Use in mapgl
mapgl::add_pmtiles_source(url = paste0(server$url, "/data.pmtiles"))

# Serve a directory of PMTiles files
server <- pm_serve("tiles/", port = 8080)

# Stop the server when done
pm_stop_server(server)

# Or run in foreground (blocks)
pm_serve("data.pmtiles", background = FALSE)

## End(Not run)

Description

Start a local tile server that serves PMTiles archives as standard Z/X/Y tile endpoints (e.g., ⁠/\{tileset\}/\{z\}/\{x\}/\{y\}.mvt⁠). This uses the native ⁠pmtiles serve⁠ command and works with any map client, not just PMTiles.js.

Unlike pm_serve() which serves raw .pmtiles files for direct consumption by PMTiles.js, this function extracts individual tiles on-demand, making the tiles accessible to any mapping library that supports standard tile URLs.

Usage

pm_serve_zxy(
  path = ".",
  bucket = NULL,
  port = 8080,
  cors = "*",
  cache_size = 64,
  public_url = NULL,
  background = FALSE
)

Arguments

Value

If background = FALSE, blocks until server is stopped (Ctrl+C). If background = TRUE, invisibly returns the processx::process object.

Tile Endpoints

The server provides these endpoints:

• Tiles: ⁠http://localhost:PORT/TILESET/\{z\}/\{x\}/\{y\}.ext⁠

  • Extension (.mvt, .png, .jpg, etc.) is auto-detected from PMTiles metadata

• TileJSON: ⁠http://localhost:PORT/TILESET.json⁠ (requires public_url)

  • Returns TileJSON metadata for the tileset

This approach works with any map client and is particularly useful for:

• Large PMTiles files (multi-GB)

• Serving directly from cloud storage

• Clients that don't support the PMTiles protocol

Cloud Storage

You can serve tiles directly from cloud storage without downloading:

Cloudflare R2:

pm_serve_zxy(
  bucket = "s3://my-bucket?endpoint=https://account.r2.cloudflarestorage.com&region=auto"
)

AWS S3:

pm_serve_zxy(bucket = "s3://my-bucket")

Requires appropriate environment variables for authentication (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY).

Background Mode

When background = TRUE, the server runs in a background process. Use pm_stop_server() to stop background servers.

Comparison with pm_serve()

• pm_serve(): Serves raw .pmtiles files for PMTiles.js (HTTP Range requests)

• pm_serve_zxy(): Serves individual Z/X/Y tiles for any map client

Use pm_serve_zxy() when you need standard tile URLs or want to serve from cloud storage. Use pm_serve() for quick local preview with PMTiles.js.

Examples

## Not run: 
# Serve all PMTiles in current directory
pm_serve_zxy()

# Serve specific directory on custom port
pm_serve_zxy(path = "~/pmtiles", port = 9000)

# Serve from Cloudflare R2
pm_serve_zxy(
  bucket = "s3://my-bucket?endpoint=https://account.r2.cloudflarestorage.com&region=auto",
  public_url = "https://tiles.example.com"
)

# Run in background
server <- pm_serve_zxy(background = TRUE)
# ... do other work ...
pm_stop_server(server)

## End(Not run)

Description

Inspect a local or remote PMTiles archive and display header information and metadata.

Usage

pm_show(
  input,
  bucket = NULL,
  metadata = FALSE,
  header_json = FALSE,
  tilejson = FALSE,
  public_url = NULL
)

Arguments

Value

• If metadata = TRUE or header_json = TRUE or tilejson = TRUE: Returns a parsed list from the JSON output

• Otherwise: Returns invisible NULL and prints archive information

Cloud Storage

PMTiles supports reading from cloud storage buckets. The easiest way to specify one is with a bucket helper (see bucket_helpers):

• Cloudflare R2: bucket = r2_bucket("my-tiles", account_id = "...")

• S3: bucket = s3_bucket("my-tiles", region = "us-east-1")

• Azure: bucket = azure_bucket("container", storage_account = "...")

• Google Cloud: bucket = gcs_bucket("my-tiles")

Raw URL strings such as "s3://BUCKET?endpoint=https://example.com&region=auto" are also accepted. Authentication uses credentials supplied to the bucket helper, or standard cloud provider environment variables (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY for S3).

Examples

## Not run: 
# Show local archive info
pm_show("path/to/archive.pmtiles")

# Get metadata as list
metadata <- pm_show("archive.pmtiles", metadata = TRUE)

# Show remote archive on Cloudflare R2
pm_show(
  "archive.pmtiles",
  bucket = r2_bucket("my-bucket", account_id = "your-account-id")
)

# Get TileJSON
tilejson <- pm_show(
  "archive.pmtiles",
  tilejson = TRUE,
  public_url = "https://example.com/tiles"
)

## End(Not run)

Description

Stop a PMTiles server that was started with pm_serve() or pm_serve_zxy().

Usage

pm_stop_server(server = NULL)

Arguments

Value

Invisibly returns TRUE if server was stopped, FALSE otherwise.

See Also

pm_serve(), pm_serve_zxy()

Examples

## Not run: 
# Start servers
server1 <- pm_serve("data.pmtiles")
server2 <- pm_serve_zxy(background = TRUE)

# Stop specific server
pm_stop_server(server1)

# Or stop by port
pm_stop_server(8080)

# Or stop all servers
pm_stop_server()

## End(Not run)

Description

Fetch one tile from a local or remote PMTiles archive and save it to a file.

Usage

pm_tile(input, z, x, y, output = NULL, bucket = NULL)

Arguments

Value

If output is specified, writes tile to file and returns the output path invisibly. If output is NULL, returns the tile data as a raw vector.

Examples

## Not run: 
# Get tile data
tile_data <- pm_tile("archive.pmtiles", z = 0, x = 0, y = 0)

# Save tile to file
pm_tile("archive.pmtiles", z = 5, x = 10, y = 12, output = "tile.mvt")

## End(Not run)

Description

Upload a local PMTiles archive to cloud storage (S3, Cloudflare R2, Google Cloud Storage, Azure, or any S3-compatible service). The easiest way to specify the destination is with a bucket helper – see r2_bucket() and friends – which builds the bucket URL and can carry credentials for you.

Usage

pm_upload(input, remote, bucket, max_concurrency = 2, verbose = TRUE)

Arguments

Value

Invisibly returns TRUE on success.

Specifying the bucket

The bucket helpers handle each provider's URL format and authentication details (see bucket_helpers for provider-by-provider setup guides):

# Cloudflare R2
bucket = r2_bucket("my-tiles", account_id = "your-account-id")

# Amazon S3
bucket = s3_bucket("my-tiles", region = "us-east-1")

# Google Cloud Storage
bucket = gcs_bucket("my-tiles")

# Azure Blob Storage
bucket = azure_bucket("my-container", storage_account = "myaccount")

A raw URL string is also accepted, e.g. "s3://bucket?endpoint=https://account.r2.cloudflarestorage.com&region=auto".

Authentication

Credentials can be supplied directly to the bucket helpers (passed only to the pmtiles subprocess), or via the provider's standard environment variables:

• S3 / R2 / S3-compatible: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY

• Google Cloud Storage: Application Default Credentials or GOOGLE_APPLICATION_CREDENTIALS

• Azure: AZURE_STORAGE_ACCOUNT plus AZURE_STORAGE_KEY or AZURE_STORAGE_SAS_TOKEN

See Also

bucket_helpers

Examples

## Not run: 
# Upload to Cloudflare R2, with credentials stored in ~/.Renviron
pm_upload(
  "local.pmtiles",
  "remote.pmtiles",
  bucket = r2_bucket(
    "my-tiles",
    account_id = "your-cloudflare-account-id",
    access_key = Sys.getenv("R2_ACCESS_KEY_ID"),
    secret_key = Sys.getenv("R2_SECRET_ACCESS_KEY")
  )
)

# Upload to S3 using the standard AWS credential chain
pm_upload(
  "local.pmtiles",
  "remote.pmtiles",
  bucket = s3_bucket("my-bucket", region = "us-east-1")
)

## End(Not run)

Description

Check that a PMTiles archive is ordered correctly and has correct header information. This verifies the archive structure without checking individual tile contents.

Usage

pm_verify(input)

Arguments

Value

Invisibly returns TRUE if verification succeeds, throws an error otherwise.

Examples

## Not run: 
# Verify an archive
pm_verify("archive.pmtiles")

## End(Not run)

Description

Display the version information of the PMTiles command-line tool.

Usage

pm_version()

Value

Character string containing version information.

Examples

## Not run: 
pm_version()

## End(Not run)

Description

Quickly visualize a PMTiles archive or TileJSON endpoint on an interactive map using mapgl. Automatically detects the tile type and applies appropriate styling. For local files, automatically starts a background server.

Usage

pm_view(
  input,
  source_layer = NULL,
  style = NULL,
  port = 8080,
  layer_type = c("auto", "fill", "line", "circle"),
  fill_color = "#088",
  fill_opacity = 0.5,
  line_color = "#088",
  line_width = 1,
  circle_color = "#088",
  circle_radius = 5,
  inspect_features = FALSE,
  highlight = FALSE,
  promote_id = NULL,
  ...
)

Arguments

Value

A mapgl map object.

Local vs Remote Files

Local files: If input is a local file path, pm_view() automatically:

1. Starts a background PMTiles server via pm_serve()

2. Extracts metadata to determine source layer and geometry type

3. Creates an appropriate map visualization

The server runs in the background and will be automatically stopped when the R session ends. You can manually stop it with pm_stop_server().

Remote files: If input is a URL (starts with ⁠http://⁠ or ⁠https://⁠), uses the URL directly without starting a local server.

TileJSON endpoints: If input ends with .json, it's treated as a TileJSON endpoint. The function fetches the TileJSON metadata and uses add_vector_source() to display the tiles.

Geometry Detection

When layer_type = "auto", the function inspects the metadata to determine the geometry type and applies appropriate styling:

• Polygon/MultiPolygon → fill layer

• LineString/MultiLineString → line layer

• Point/MultiPoint → circle layer

Feature Inspection and Highlighting

Set inspect_features = TRUE to show tooltips with feature attributes on hover. This works for any tileset.

Set highlight = TRUE to enable hover highlighting effects (features change color/style when hovered). Important: This requires the tileset to have an ID property configured. You can either:

• Configure IDs during tile generation (recommended)

• Use promote_id = "column_name" to promote an existing attribute as the ID

If the tileset lacks proper IDs, highlighting will not work even if enabled.

Examples

## Not run: 
# View a local PMTiles file
pm_view("data.pmtiles")

# Customize the display
pm_view("data.pmtiles",
        fill_color = "#ff0000",
        fill_opacity = 0.7)

# View remote PMTiles
pm_view("https://example.com/tiles.pmtiles")

# View TileJSON endpoint
pm_view("http://localhost:8080/tiles.json")

# Use specific source layer
pm_view("data.pmtiles", source_layer = "buildings")

# Enable feature inspection with tooltips
pm_view("data.pmtiles", inspect_features = TRUE)

# Enable hover highlighting (requires ID property in tileset)
pm_view("data.pmtiles",
        inspect_features = TRUE,
        highlight = TRUE,
        promote_id = "id")

# Further customize with mapgl
pm_view("data.pmtiles") |>
  mapgl::fit_bounds(c(-122.5, 37.7, -122.3, 37.9))

## End(Not run)