index.qmd

```{r}
#| label: setup
#| include: false

library(here)

here("R", ".setup.R") |> source()
```

## Overview {.first-h2}

:::: {style="display: grid; grid-template-columns: 1fr auto; gap: 1.5rem; align-items: start;"}
::: {}
This website hosts [PMTiles](https://docs.protomaps.com/pmtiles/) files for spatial visualization and analysis in Brazil.

[PMTiles](https://docs.protomaps.com/pmtiles/) is a format for storing and serving tiled geospatial data. It is designed to be efficient, scalable, and easy to use, making it ideal for web applications and data visualization.

We plan to move these files to a more permanent hosting solution in the future.
:::

::: {style="margin-top: -1rem;"}
![](images/logo.png){width="120"}
:::
::::

::: {.callout-note}
The map below shows Brazil municipality boundaries as PMTiles, sourced from the [`geobr`](https://ipeagit.github.io/geobr/) R package [@pereirab].
:::

::: {.callout-tip}
*Click and drag* to pan. *Right-click and drag* to rotate. *Hover* over a shape to see the municipality name. *Use the controls* to zoom, take a screenshot, or view in fullscreen.
:::

```{r}
#| label: Set the Environment
#| include: false

library(brandr)
library(checkmate)
library(cli)
library(dplyr)
library(fs)
library(geobr)
library(geodata)
library(httr2)
library(magrittr)
library(mapgl)
library(pmtiles) # github.com/walkerke/pmtiles
library(sf)
```

```{r}
#| include: false

here("R", "plot_maplibre.R") |> source()
```

```{r}
#| include: false

raw_data_dir <- here("data-raw")
data_dir <- here("pmtiles")
```

```{r}
#| include: false

for (i in c(data_dir, raw_data_dir)) {
  if (!dir_exists(i)) {
    dir_create(i, recurse = TRUE)
  }
}
```

```{r}
#| label: column screen
#| include: false

file <- file.path(
  "https://cem-usp.github.io/pmtilesbr",
  "pmtiles",
  "geobr-2024-read_municipality-simplified-min-zoom-2-max-zoom-10.pmtiles"
)
```

```{r}
#| include: false

municipality_data <- read_municipality(
  year = 2024,
  simplified = TRUE,
  showProgress = FALSE,
  keep_areas_operacionais = FALSE
)
```

```{r}
#| include: false

municipality_data |> glimpse()
```

```{r}
#| column: screen
#| echo: false

file |>
  plot_maplibre(
    column = "code_muni",
    values = municipality_data |>
      extract2("code_muni"),
    tooltip = "name_muni",
    hover_options = list(
      fill_color = get_brand_color("gray-l50"),
      fill_opacity = 1
    ),
    line_width = 0.01,
    scroll_zoom = FALSE,
    seed = 1998
  )
```

## Why Use PMTiles?

When working with complex geometries in web mapping applications like [Mapbox](https://www.mapbox.com/), [MapLibre](https://maplibre.org/), and [Leaflet](https://leafletjs.com/), performance can become [a real problem](https://walker-data.com/posts/pmtiles-texas-blocks/). Shapes with many vertices make rendering slow, bloat file sizes, and generally make life harder. [PMTiles](https://docs.protomaps.com/pmtiles/) addresses this by letting you serve precompiled tiles directly from the web, rather than bundling them into your application.

## Files

::: {.callout-note}
See the code repository [README](https://github.com/cem-usp/pmtilesbr#pmtilesbr-) to learn more about how the files were created.
:::

::: {.callout-tip}
Unless you really need to, use the simplified versions of the files, which are smaller and faster to load. The non-simplified versions are available for those who need the highest level of detail, but they may not be necessary for most applications.
:::

::: {.panel-tabset .map-tabset}

## `geobr::read_country()`

Sourced from the [`geobr`](https://ipeagit.github.io/geobr/) R package [@pereirab].

#### Parameters

- Year: 2020
- Layer: `"read_country"`
- Simplified: `TRUE`/`FALSE`
- Minimum Zoom: 2
- Maximum Zoom: 10

#### Files

- [`geobr-2020-read_country-min-zoom-2-max-zoom-10.pmtiles`](pmtiles/geobr-2020-read_country-min-zoom-2-max-zoom-10.pmtiles)
- [`geobr-2020-read_country-simplified-min-zoom-2-max-zoom-10.pmtiles`](pmtiles/geobr-2020-read_country-simplified-min-zoom-2-max-zoom-10.pmtiles)

#### View

```{r}
#| label: geobr::read_country()
#| include: false

file <- file.path(
  "https://cem-usp.github.io/pmtilesbr",
  "pmtiles",
  "geobr-2020-read_country-simplified-min-zoom-2-max-zoom-10.pmtiles"
)
```

```{r}
#| include: false
#| eval: false

pm_show(file, tilejson = TRUE)
```

```{r}
#| echo: false

file |>
  plot_maplibre(
    column = "code_muni",
    fill_color = get_brand_color("red"),
    line_width = 1
  )
```

## `geobr::read_region()`

Sourced from the [`geobr`](https://ipeagit.github.io/geobr/) R package [@pereirab].

#### Parameters

- Year: 2020
- Layer: `"read_region"`
- Simplified: `TRUE`/`FALSE`
- Minimum Zoom: 2
- Maximum Zoom: 10

#### Files

- [`geobr-2020-read_region-min-zoom-2-max-zoom-10.pmtiles`](pmtiles/geobr-2020-read_region-min-zoom-2-max-zoom-10.pmtiles)
- [`geobr-2020-read_region-simplified-min-zoom-2-max-zoom-10.pmtiles`](pmtiles/geobr-2020-read_region-simplified-min-zoom-2-max-zoom-10.pmtiles)

#### View

```{r}
#| label: geobr::read_region()
#| include: false

file <- file.path(
  "https://cem-usp.github.io/pmtilesbr",
  "pmtiles",
  "geobr-2020-read_region-simplified-min-zoom-2-max-zoom-10.pmtiles"
)
```

```{r}
#| include: false
#| eval: false

pm_show(file, tilejson = TRUE)
```

```{r}
#| include: false

region_data <- read_region(
  year = 2020,
  simplified = TRUE,
  showProgress = FALSE
)
```

```{r}
#| include: false

region_data |> glimpse()
```

```{r}
#| echo: false

file |>
  plot_maplibre(
    column = "code_region",
    values = region_data |>
      extract2("code_region"),
    tooltip = "name_region_en",
    hover_options = list(
      fill_color = get_brand_color("gray-l50"),
      fill_opacity = 1
    ),
    line_width = 1,
    seed = 2013
  )
```

## `geobr::read_state()`

Sourced from the [`geobr`](https://ipeagit.github.io/geobr/) R package [@pereirab].

#### Parameters

- Year: 2020
- Layer: `"read_state"`
- Simplified: `TRUE`/`FALSE`
- Minimum Zoom: 2
- Maximum Zoom: 10

#### Files

- [`geobr-2020-read_state-min-zoom-2-max-zoom-10.pmtiles`](pmtiles/geobr-2020-read_state-min-zoom-2-max-zoom-10.pmtiles)
- [`geobr-2020-read_state-simplified-min-zoom-2-max-zoom-10.pmtiles`](pmtiles/geobr-2020-read_state-simplified-min-zoom-2-max-zoom-10.pmtiles)

#### View

```{r}
#| label: geobr::read_state()
#| include: false

file <- file.path(
  "https://cem-usp.github.io/pmtilesbr",
  "pmtiles",
  "geobr-2020-read_state-simplified-min-zoom-2-max-zoom-10.pmtiles"
)
```

```{r}
#| include: false
#| eval: false

pm_show(file, tilejson = TRUE)
```

```{r}
#| include: false

state_data <- read_state(
  year = 2020,
  simplified = TRUE,
  showProgress = FALSE
)
```

```{r}
#| include: false

state_data |> glimpse()
```

```{r}
#| echo: false

file |>
  plot_maplibre(
    column = "code_state",
    values = state_data |>
      extract2("code_state"),
    tooltip = "name_state",
    hover_options = list(
      fill_color = get_brand_color("gray-l50"),
      fill_opacity = 1
    ),
    line_width = 1,
    seed = 2000
  )
```

## `geobr::read_municipality()`

Sourced from the [`geobr`](https://ipeagit.github.io/geobr/) R package [@pereirab].

#### Parameters

- Year: 2024
- Layer: `"read_municipality"`
- Simplified: `TRUE`/`FALSE`
- Minimum Zoom: 2
- Maximum Zoom: 10

#### Files

- [`geobr-2024-read_municipality-min-zoom-2-max-zoom-10.pmtiles`](pmtiles/geobr-2024-read_municipality-min-zoom-2-max-zoom-10.pmtiles)
- [`geobr-2024-read_municipality-simplified-min-zoom-2-max-zoom-10.pmtiles`](pmtiles/geobr-2024-read_municipality-simplified-min-zoom-2-max-zoom-10.pmtiles)

#### View

```{r}
#| label: geobr::read_municipality()
#| include: false

file <- file.path(
  "https://cem-usp.github.io/pmtilesbr",
  "pmtiles",
  "geobr-2024-read_municipality-simplified-min-zoom-2-max-zoom-10.pmtiles"
)
```

```{r}
#| include: false
#| eval: false

pm_show(file, tilejson = TRUE)
```

```{r}
#| eval: false
#| include: false

municipality_data <- read_municipality(
  year = 2024,
  simplified = TRUE,
  showProgress = FALSE,
  keep_areas_operacionais = FALSE
)
```

```{r}
#| include: false

municipality_data |> glimpse()
```

```{r}
#| echo: false

file |>
  plot_maplibre(
    column = "code_muni",
    values = municipality_data |>
      extract2("code_muni"),
    tooltip = "name_muni",
    hover_options = list(
      fill_color = get_brand_color("gray-l50"),
      fill_opacity = 1
    ),
    line_width = 0.01,
    seed = 1998
  )
```

## `geodata::world()`

Sourced from the [`geodata`](https://rspatial.github.io/geodata/) R package [@hijmans2024].

#### Parameters

- Layer: `"world"`
- Resolution: 5
- Level: 0
- Version: `"latest"` (created in 2026)
- Minimum Zoom: 0
- Maximum Zoom: 6/10

#### Files

- [`gadm-world-resolution-5-level-0-version-latest-min-zoom-0-max-zoom-6.pmtiles`](pmtiles/gadm-world-resolution-5-level-0-version-latest-min-zoom-0-max-zoom-6.pmtiles)
- [`gadm-world-resolution-5-level-0-version-latest-min-zoom-0-max-zoom-10.pmtiles`](pmtiles/gadm-world-resolution-5-level-0-version-latest-min-zoom-0-max-zoom-10.pmtiles)

#### View

```{r}
#| label: geodata::world()
#| include: false

file <- file.path(
  "https://cem-usp.github.io/pmtilesbr",
  "pmtiles",
  paste0(
    "gadm-world-resolution-5-level-0-version-latest-",
    "min-zoom-0-max-zoom-6.pmtiles"
  )
)
```

```{r}
#| include: false
#| eval: false

pm_show(file, tilejson = TRUE)
```

```{r}
#| include: false

world_data <- world(
  resolution = 5,
  level = 0,
  path = raw_data_dir,
  version = "latest"
) |>
  st_as_sf()
```

```{r}
#| include: false

world_data |> glimpse()
```

```{r}
#| echo: false

file |>
  plot_maplibre(
    column = "GID_0",
    values = world_data |>
      extract2("GID_0"),
    bounds = c(-175, -75, 180, 85),
    tooltip = "NAME_0",
    hover_options = list(
      fill_color = get_brand_color("gray-l50"),
      fill_opacity = 1
    ),
    line_width = 0.5,
    seed = 2025
  )
```

:::

## Citation

::: {.callout-important}
When using this data, you must also cite the original data sources.
:::

To cite this work, please use the following format:

Vartanian, D., Fernandes, C. N., & Giannotti, M. A. (2026). *PMTilesBR: Tiled geospatial data for Brazil* \[Computer software\]. Center for Metropolitan Studies, University of São Paulo. <https://doi.org/10.5281/zenodo.19157888>

A BibLaTeX entry for LaTeX users is:

```latex
@software{vartanian2026,
  title = {PMTilesBR: Tiled geospatial data for Brazil},
  author = {{Daniel Vartanian} and {Camila Nastari Fernandes} and {Mariana Abrantes Giannotti}},
  year = {2026},
  address = {São Paulo},
  institution = {Center for Metropolitan Studies, University of São Paulo},
  langid = {en},
  doi = {https://doi.org/10.5281/zenodo.19157888}
}
```

## License

::: {style="text-align: left;"}
[![License: GPLv3](https://img.shields.io/badge/license-GPLv3-bd0000.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![License: CC BY-NC-SA 4.0](https://img.shields.io/badge/license-CC_BY--NC--SA_4.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc-sa/4.0/)
:::

::: {.callout-important}
The original data sources may be subject to their own licensing terms and conditions.
:::

The code in this repository is licensed under the [GNU General Public License Version 3](https://www.gnu.org/licenses/gpl-3.0), while the files are available under the [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-nc-sa/4.0/) license.

```
Copyright (C) 2026 Center for Metropolitan Studies

The code in this report is free software: you can redistribute it and/or
modify it under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your option)
any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program. If not, see <https://www.gnu.org/licenses/>.
```

## Acknowledgments

:::: {.columns style="display: flex; align-items: center; margin: 1em; padding-top: 0em;"}
::: {.column style="width: 30%; text-align: center;"}
[![](images/cem-icon.svg){width="190"}](https://centrodametropole.fflch.usp.br)
:::
::: {.column style="width: 70%; display: flex; align-items: center;"}
This work was developed with support from the Center for Metropolitan Studies ([CEM](https://centrodametropole.fflch.usp.br)) based at the School of Philosophy, Letters and Human Sciences ([FFLCH](https://www.fflch.usp.br/)) of the University of São Paulo ([USP](https://usp.br/)) and at the Brazilian Center for Analysis and Planning ([CEBRAP](https://cebrap.org.br/)).
:::
::::

:::: {.columns style="display: flex; align-items: center; margin: 1em; padding-top: 0em;"}
::: {.column style="width: 30%; text-align: center;"}
[![](images/fapesp-logo.svg){width="160"}](https://fapesp.br/)
:::
::: {.column style="width: 70%; display: flex; align-items: center;"}
This study was financed, in part, by the São Paulo Research Foundation ([FAPESP](https://fapesp.br/)), Brazil. Process Number [2025/17879-2](https://bv.fapesp.br/en/bolsas/231507/geospatial-data-science-applied-to-food-policies/).
:::
::::

## References {.unnumbered}

::: {#refs}
:::