---
title: "Layers and RAT metadata"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Layers and RAT metadata}
  %\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`. It opens elevation, uncertainty, and contributor
layers, then reads Raster Attribute Table (RAT) sidecars for contributor
metadata. Elevation is shown with hillshade and contours; uncertainty and
contributor IDs are plotted as their own source layers.

The contributor band contains IDs, not continuous values. Contributor IDs must
not be averaged. RAT sidecars carry contributor metadata, and `bluertopo`
preserves original RAT files.

## Example area

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

## All layers

```{r all-layers, eval=bt_real_examples_enabled()}
all_layers <- bluertopo(
  real_aoi,
  layers = "all",
  coverage = "fill",
  details = TRUE,
  progress = FALSE,
  quiet = TRUE
)
```

```{r layer-table, echo=FALSE, eval=bt_real_examples_enabled()}
layer_table <- data.frame(
  layer = c("elevation", "uncertainty", "contributor"),
  `source band` = c(1L, 2L, 3L),
  meaning = c(
    "source elevation values",
    "source vertical uncertainty values",
    "categorical contributor/source IDs"
  ),
  `default resampling rule` = c(
    "bilinear only when an explicit output grid is requested",
    "bilinear only when an explicit output grid is requested; values are then resampled",
    "nearest-neighbor only; never average contributor IDs"
  ),
  check.names = FALSE
)

bt_display_table(layer_table)
```

## RAT sidecar manifest

```{r rat-manifest, echo=FALSE, eval=bt_real_examples_enabled()}
rat_manifest <- as.data.frame(all_layers$downloads)
rat_manifest <- rat_manifest[rat_manifest$asset_type == "rat", , drop = FALSE]
rat_table <- data.frame(
  tile_id = rat_manifest$tile_id,
  source_basename = rat_manifest$source_basename,
  local_path = bt_short_path(rat_manifest$local_path, keep = 4L),
  verified = rat_manifest$verified,
  actual_sha256 = bt_short_sha(rat_manifest$actual_sha256),
  stringsAsFactors = FALSE
)

bt_display_table(rat_table)
```

## Contributor lookup

```{r rat-lookup, echo=FALSE, eval=bt_real_examples_enabled()}
contributor_lookup <- bt_parse_rat(rat_manifest$local_path)
bt_display_table(contributor_lookup)
```

## Elevation

```{r elevation-plot, 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."}
first_grid <- bt_rasters(all_layers$data)[[1L]]
bt_plot_bathy_map(first_grid[["elevation"]], real_aoi, main = "New York Harbor elevation")
```

## Uncertainty

```{r uncertainty-plot, echo=FALSE, eval=bt_real_examples_enabled(), fig.cap="BlueTopo uncertainty for the selected New York Harbor tiles.", fig.alt="BlueTopo uncertainty raster for the selected New York Harbor tiles."}
terra::plot(first_grid[["uncertainty"]], main = "Uncertainty", col = grDevices::hcl.colors(80, "BluYl"))
terra::plot(terra::project(real_aoi, terra::crs(first_grid)), add = TRUE, border = "#d00000", lwd = 2)
```

## Contributor IDs

```{r contributor-plot, echo=FALSE, eval=bt_real_examples_enabled(), fig.cap="Contributor identifiers for the selected New York Harbor tiles.", fig.alt="BlueTopo contributor identifier raster shown with categorical colors."}
terra::plot(first_grid[["contributor"]], main = "Contributor IDs", col = hcl.colors(12, "Dark 3"))
terra::plot(terra::project(real_aoi, terra::crs(first_grid)), add = TRUE, border = "#d00000", lwd = 2)
```

Contributor values are identifiers that point into RAT metadata. They are not
continuous terrain values.