---
title: "Example gallery"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Example gallery}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 6, fig.height = 4)
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`. Raster Attribute Table (RAT) sidecars are retained
with the source GeoTIFF assets.

## What the examples show

```{r gallery-table, echo=FALSE}
gallery <- data.frame(
  Example = c(
    "Discover tiles and coverage",
    "Download original assets",
    "Extract elevation with terra",
    "Compare resolution policies",
    "Mixed grids and output grid",
    "Layers and RAT metadata"
  ),
  `Main function` = c(
    "bluertopo_tiles()",
    "bluertopo_download()",
    "bluertopo()",
    "bluertopo_tiles()",
    "bluertopo()",
    "bluertopo()"
  ),
  Shows = c(
    "AOI intersection, selected footprints, coverage diagnostics",
    "Verified NOAA GeoTIFF and RAT sidecar assets",
    "File-backed terra object and provenance",
    "Native source-resolution selection effects",
    "SpatRasterCollection versus explicit output grid",
    "Elevation, uncertainty, contributor IDs, and RAT metadata"
  ),
  `Output type` = c(
    "Tables and footprint figure",
    "Manifest tables and status figure",
    "terra summary tables and raster figure",
    "Policy comparison tables and maps",
    "Grid summary tables and raster figure",
    "Layer/RAT tables and raster figures"
  ),
  check.names = FALSE
)

bt_display_table(gallery)
```

## Example area

```{r real-setup, include=FALSE, eval=bt_real_examples_enabled()}
real <- bt_real_example_setup()
real_aoi <- real$aoi
real_tiles <- real$tiles
```

## Locator map

```{r tile-footprints, echo=FALSE, eval=bt_real_examples_enabled(), fig.cap="BlueTopo tile coverage for the New York Harbor example area.", fig.alt="BlueTopo tile footprints colored by native source resolution with the New York Harbor example area boundary."}
bt_plot_locator_map(
  real_tiles,
  real_aoi,
  place_label = real$place,
  main = "New York Harbor BlueTopo tile footprints"
)
```

```{r selected-tiles, echo=FALSE, eval=bt_real_examples_enabled()}
bt_display_table(bt_tile_table(real_tiles, include_urls = TRUE))
```

## Download plan

```{r planned-assets, echo=FALSE, eval=bt_real_examples_enabled()}
planned <- real$planned_assets
planned$planned_mb <- bt_bytes_mb(planned$planned_bytes)
bt_display_table(planned[c("tile_id", "asset_type", "source_basename", "planned_mb")])
```

## Terra preview

```{r terra-preview, 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."}
preview <- bluertopo(
  real_aoi,
  layers = "elevation",
  resolution = "native",
  coverage = "fill",
  details = TRUE,
  progress = FALSE,
  quiet = TRUE
)

bt_plot_bathy_map(preview$data, real_aoi, main = "New York Harbor BlueTopo bathymetry")
```

`resolution` selects native source tiles. `output_resolution` is used only when
the user explicitly requests an output grid.