protomapr/vignettes/getting-started.Rmd

---
title: "Getting Started with protomapr"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with protomapr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

*Note: Code examples are not evaluated in this vignette. Copy and run them in your R console to see the interactive maps.*

## Introduction

protomapr adds [Protomaps](https://protomaps.com/) vector tile layers to Leaflet maps in R. Protomaps provides fast, customizable map tiles using the PMTiles format.

## Why Protomaps?

Standard Leaflet maps use `addProviderTiles()` to load raster tiles from services like OpenStreetMap, Stadia, or CartoDB. These work well but have limitations:

| Feature | Raster Tiles (providerTiles) | Vector Tiles (Protomaps) |
|---------|------------------------------|--------------------------|
| Customization | Limited to provider's styles | Full control over colors, labels, features |
| Self-hosting | Requires tile server infrastructure | Single PMTiles file, no server needed |
| File size | Large (pre-rendered images) | Small (compressed vectors) |
| Zoom transitions | Can appear pixelated | Smooth at any zoom level |
| Offline use | Difficult | Easy with local PMTiles file |
| Privacy | Requests go to third-party servers | Self-host for complete privacy |
| Rate limits | Often have API limits | No limits when self-hosted |
| Feature filtering | Not possible | Hide roads, buildings, labels, etc. |

### When to use Protomaps

- **Custom branded maps**: Match your organization's color scheme
- **Minimal basemaps**: Hide distracting features for data visualization overlays
- **Offline/embedded applications**: Bundle a PMTiles file with your app
- **Privacy-sensitive contexts**: No third-party tile requests
- **High-traffic applications**: Avoid API rate limits

### When providerTiles may be simpler

- Quick prototypes where default styling is fine
- Satellite/aerial imagery (Protomaps is vector-only)
- When you don't need customization

## Installation

```{r, eval = FALSE}
# Install from CRAN
install.packages("protomapr")

# Or install development version
# devtools::install_github("yourusername/protomapr")
```

## API Key Setup

Before using the Protomaps tile API, you need a free API key:

1. Sign up at https://protomaps.com/
2. Set your key for the session:

```{r}
library(leaflet)
library(protomapr)

# Set your API key (do this once per session)
set_protomaps_key("your-api-key-here")

# Or set via environment variable
Sys.setenv(PROTOMAPS_API_KEY = "your-api-key-here")
```
For persistent storage, add to your `.Renviron` file: `PROTOMAPS_API_KEY=your-key-here`

## Basic Usage

```{r}
# Create a map with default light theme
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 12) %>%
  addProtomaps(url = protomaps_url())
```

## Built-in Flavors

protomapr includes five built-in flavors:
```{r}
# Light (default)
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 12) %>%
  addProtomaps(url = protomaps_url(), flavor = "light")

# Dark
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 12) %>%
  addProtomaps(url = protomaps_url(), flavor = "dark")

# White (minimal, good for data visualization overlays)
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 12) %>%
  addProtomaps(url = protomaps_url(), flavor = "white")

# Grayscale
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 12) %>%
  addProtomaps(url = protomaps_url(), flavor = "grayscale")

# Black
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 12) %>%
  addProtomaps(url = protomaps_url(), flavor = "black")
```

## Data Sources

### Demo/Development
Use `protomaps_url()` for testing (uses Protomaps daily OpenStreetMap build):
```{r}
leaflet() %>%
  addProtomaps(url = protomaps_url())
```

### Self-hosted (recommended for production)

For production use, self-host a PMTiles file. This eliminates API rate limits, ensures privacy, and enables offline use.

#### Getting PMTiles files

**Option 1: Regional extract (recommended)**

Use [Protomaps Slice](https://slice.openstreetmap.us/) to extract just the region you need:

1. Go to https://slice.openstreetmap.us/
2. Draw a bounding box around your area of interest
3. Download the resulting PMTiles file (typically 10-500MB depending on region size)

**Option 2: Daily world builds**

Full planet builds are available at https://build.protomaps.com/ (~100GB). Only recommended if you need global coverage.

**Option 3: pmtiles CLI**

For scripted workflows, use the [pmtiles CLI tool](https://github.com/protomaps/go-pmtiles):

```bash
# Install (requires Go)
go install github.com/protomaps/go-pmtiles/cmd/pmtiles@latest

# Extract a region from a larger file
pmtiles extract world.pmtiles california.pmtiles --bbox=-124.5,32.5,-114.1,42.0
```

#### Hosting options

**Cloud storage (simplest)**

Upload to S3, Google Cloud Storage, or Cloudflare R2. PMTiles supports HTTP range requests, so no special server is needed.

```{r}
# S3
leaflet() %>%
  addProtomaps(url = "https://your-bucket.s3.amazonaws.com/tiles.pmtiles")

# Cloudflare R2
leaflet() %>%
  addProtomaps(url = "https://your-bucket.r2.cloudflarestorage.com/tiles.pmtiles")
```

**Important:** Enable CORS on your bucket to allow browser requests. Example S3 CORS policy:

```json
[{
  "AllowedOrigins": ["*"],
  "AllowedMethods": ["GET", "HEAD"],
  "AllowedHeaders": ["Range"],
  "ExposeHeaders": ["Content-Length", "Content-Range"]
}]
```

**Local file (Shiny apps)**

For Shiny applications, serve PMTiles from `www/`:

```r
# In your Shiny app, place tiles.pmtiles in www/ folder
leaflet() %>%
  addProtomaps(url = "tiles.pmtiles")
```

**Local development**

For local testing, use a simple HTTP server:

```bash
# Python
cd /path/to/pmtiles/folder
python -m http.server 8000

# Then in R
leaflet() %>%
  addProtomaps(url = "http://localhost:8000/tiles.pmtiles")
```

## Preset Styles

For common use cases, protomapr provides preset styles that are simpler than the built-in flavors:

```{r}
# Ultra-minimal basemap for data visualization
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 10) %>%
  addProtomaps(url = protomaps_url(), style = pmMinimal())

# Minimal with city labels
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 10) %>%
  addProtomaps(url = protomaps_url(), style = pmMinimal(labels = TRUE))

# Dark minimal
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 10) %>%
  addProtomaps(url = protomaps_url(), style = pmStyle("minimal-dark"))

# Soft watercolor aesthetic
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 10) %>%
  addProtomaps(url = protomaps_url(), style = pmStyle("watercolor"))

# Muted with subtle roads
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 10) %>%
  addProtomaps(url = protomaps_url(), style = pmStyle("muted"))
```

### Available presets

| Preset | Description |
|--------|-------------|
| `pmMinimal()` | Hides roads, buildings, land use - shows only land and water |
| `pmStyle("minimal")` | Same as `pmMinimal()` |
| `pmStyle("minimal-dark")` | Dark version of minimal |
| `pmStyle("muted")` | Subtle colors, faint roads, major city labels |
| `pmStyle("watercolor")` | Soft, hand-painted aesthetic |

## Next Steps

See `vignette("custom-styling")` to learn how to customize colors, labels, and map features.

## Acknowledgments

This package wraps [protomaps-leaflet](https://github.com/protomaps/protomaps-leaflet), created by [Brandon Liu](https://bdon.org/). The Protomaps project provides an open-source stack for self-hosted vector maps, including the PMTiles format. Thanks to Brandon for making beautiful, customizable maps accessible to everyone.