init
This commit is contained in:
commit
116abafc09
58 changed files with 5749 additions and 0 deletions
258
vignettes/getting-started.Rmd
Normal file
258
vignettes/getting-started.Rmd
Normal file
|
|
@ -0,0 +1,258 @@
|
|||
---
|
||||
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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue