---
title: "Extract elevation with terra"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Extract elevation with terra}
  %\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.

`bluertopo()` returns terra objects and, with `details = TRUE`, exposes selected
tiles, downloads, query metadata, provenance, and coverage diagnostics. Normal
native extraction does not intentionally resample.

## Example area

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

## Extract elevation

```{r extract, eval=bt_real_examples_enabled()}
result <- bluertopo(
  real_aoi,
  layers = "elevation",
  resolution = "native",
  coverage = "fill",
  details = TRUE,
  progress = FALSE,
  quiet = TRUE
)
```

## Object summary

```{r object-summary, echo=FALSE, eval=bt_real_examples_enabled()}
rasters <- bt_rasters(result$data)
object_summary <- data.frame(
  element = c(
    "object type",
    "result$data class",
    "number of layers",
    "layer names",
    "CRS summary",
    "resolution",
    "source count"
  ),
  value = c(
    if (inherits(result$data, "SpatRasterCollection")) "SpatRasterCollection" else "SpatRaster",
    paste(class(result$data), collapse = ", "),
    sum(vapply(rasters, terra::nlyr, numeric(1L))),
    paste(unique(unlist(lapply(rasters, names), use.names = FALSE)), collapse = ", "),
    paste(unique(vapply(rasters, function(r) {
      paste0("EPSG:", terra::crs(r, describe = TRUE)$code)
    }, "")), collapse = ", "),
    paste(unique(vapply(rasters, function(r) paste(round(terra::res(r), 3), collapse = " x "), "")), collapse = "; "),
    length(unique(unlist(lapply(rasters, terra::sources), use.names = FALSE)))
  ),
  stringsAsFactors = FALSE
)

bt_display_table(object_summary)
```

## File-backed sources

```{r source-table, echo=FALSE, eval=bt_real_examples_enabled()}
bt_display_table(bt_sources_table(result$data))
```

## Coverage

```{r coverage-table, echo=FALSE, eval=bt_real_examples_enabled()}
bt_display_table(bt_coverage_table(result$coverage))
```

## Provenance

```{r provenance-table, echo=FALSE, eval=bt_real_examples_enabled()}
bt_display_table(bt_catalog_table(real))
```

## Elevation preview

```{r elevation-figure, 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."}
bt_plot_bathy_map(result$data, real_aoi, main = "New York Harbor BlueTopo bathymetry")
```

When native source grids differ, the result can be a `SpatRasterCollection`.
Each member can still be file-backed by verified original assets.