---
title: "Compare resolution policies"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Compare resolution policies}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 5)
helper <- if (file.exists("vignettes/real-example-helpers.R")) {
  "vignettes/real-example-helpers.R"
} else {
  "real-example-helpers.R"
}
source(helper)
real_mode <- bt_real_examples_enabled()
```

`r if (real_mode) bt_real_example_label else bt_offline_note`

This example uses BlueTopo tiles covering New York Harbor. The workflow
demonstrates tile discovery, checksum-verified asset retrieval, and file-backed
raster access with `terra`. It applies native source-resolution policies to the
AOI, reports selected tile coverage, and renders policy footprints. The current
New York Harbor example is a compact 4 m native-resolution plan, so policy
differences mainly demonstrate selection rules rather than a dramatic visual
change.

Smaller meter values mean finer native source resolution. `resolution` selects
source tiles; it does not resample. `coverage = "fill"` can add fallback source
tiles. `output_resolution` is the argument that changes the output grid.

## Example area

```{r setup, include=FALSE, eval=bt_real_examples_enabled()}
real <- bt_real_example_setup()
real_aoi <- real$aoi
available_resolution <- sort(unique(as.data.frame(real$tiles)$resolution_m))
exact_available <- max(available_resolution)
```

## Policies

```{r policies, eval=bt_real_examples_enabled()}
policies <- list(
  native = list(resolution = "native", coverage = "warn"),
  finest = list(resolution = "finest", coverage = "ignore"),
  `finest + coverage fill` = list(resolution = "finest", coverage = "fill"),
  coarsest = list(resolution = "coarsest", coverage = "ignore"),
  `exact available native resolution` = list(resolution = exact_available, coverage = "ignore"),
  `nearest 6 m` = list(resolution = bluertopo_resolution("nearest", value = 6), coverage = "ignore")
)

policy_tiles <- lapply(policies, function(policy) {
  bluertopo_tiles(
    real_aoi,
    resolution = policy$resolution,
    coverage = policy$coverage,
    quiet = TRUE
  )
})

policy_summary <- do.call(rbind, lapply(names(policy_tiles), function(name) {
  tiles <- policy_tiles[[name]]
  df <- as.data.frame(tiles)
  coverage <- attr(tiles, "coverage")
  data.frame(
    policy = name,
    selected_tile_count = nrow(df),
    selected_resolutions = paste(sort(unique(df$resolution_m)), collapse = ", "),
    selected_coverage_fraction = coverage$selected_coverage_fraction,
    selected_aoi_fraction = coverage$selected_aoi_fraction,
    target_met = coverage$target_met,
    stringsAsFactors = FALSE
  )
}))
```

```{r policy-table, echo=FALSE, eval=bt_real_examples_enabled()}
bt_display_table(policy_summary)
```

## Tile selection maps

```{r policy-maps, echo=FALSE, eval=bt_real_examples_enabled(), fig.cap="BlueTopo tile coverage selected under different native source-resolution policies.", fig.alt="Six maps showing BlueTopo tile selections for native, finest, coverage fill, coarsest, exact, and nearest policies."}
old_par <- par(mfrow = c(2, 3), mar = c(2, 2, 3, 1))
for (name in names(policy_tiles)) {
  bt_plot_tiles(
    policy_tiles[[name]],
    real_aoi,
    main = name,
    place_label = real$place,
    label_resolutions = TRUE
  )
}
par(old_par)
```

## Coverage by policy

```{r policy-coverage-bars, echo=FALSE, eval=bt_real_examples_enabled(), fig.cap="Coverage fractions selected under different native source-resolution policies.", fig.alt="Bar plot comparing selected coverage fractions by native source-resolution policy."}
barplot(
  stats::setNames(policy_summary$selected_coverage_fraction, policy_summary$policy),
  ylim = c(0, 1),
  las = 2,
  col = "#005f73",
  ylab = "selected coverage fraction",
  main = "Coverage by resolution policy"
)
abline(h = 1, col = "#d00000", lwd = 2, lty = 2)
```

Use an explicit output grid only when resampling is intended.

## Elevation context

```{r policy-bathy-map, echo=FALSE, eval=bt_real_examples_enabled(), fig.cap="BlueTopo bathymetry for New York Harbor, displayed with hillshade, contours, and the example-area boundary.", fig.alt="BlueTopo bathymetry for New York Harbor with hillshade, contours, and the example-area boundary."}
policy_elevation <- bluertopo(
  real_aoi,
  layers = "elevation",
  resolution = "native",
  coverage = "fill",
  details = TRUE,
  progress = FALSE,
  quiet = TRUE
)

bt_plot_bathy_map(policy_elevation$data, real_aoi, main = "New York Harbor native policy context")
```