---
title: "Mixed grids and output grid"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Mixed grids and output grid}
  %\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`

New York Harbor is the primary public AOI for the examples, but its current
small plan is a compatible 4 m grid. This example uses BlueTopo tiles covering
Key West and Boca Chica Channel because the documented secondary AOI currently
intersects 4 m and 8 m source grids and therefore demonstrates mixed native-grid
behavior.

Mixed native grids are preserved unless the user asks for a single output grid.
`combine = "single"` needs an explicit output grid when native grids are
incompatible. Resampled uncertainty values are not original source cells, and
contributor resampling must be nearest-neighbor.

## Example area

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

## Native mixed-grid extraction

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

if (!inherits(native$data, "SpatRasterCollection")) {
  stop("The documented real AOI no longer produces mixed native grids.", call. = FALSE)
}
```

```{r native-table, echo=FALSE, eval=bt_real_examples_enabled()}
native_table <- bt_raster_summary(native$data)
native_table$output_object_class <- paste(class(native$data), collapse = ", ")
native_table <- native_table[c(
  "output_object_class",
  "group_name",
  "crs",
  "resolution",
  "source_count",
  "layer_names"
)]

bt_display_table(native_table)
```

## Native grid footprints

```{r native-footprints, echo=FALSE, eval=bt_real_examples_enabled(), fig.cap="BlueTopo tile coverage selected for the Key West mixed-grid example area.", fig.alt="BlueTopo tile footprints selected for mixed native grids near Key West and Boca Chica Channel."}
bt_plot_locator_map(
  native$tiles,
  real_aoi,
  place_label = real$place,
  main = "Key West and Boca Chica mixed native grids"
)
```

## Explicit single output grid

```{r single, eval=bt_real_examples_enabled()}
single <- suppressWarnings(bluertopo(
  real_aoi,
  layers = "elevation",
  resolution = "native",
  coverage = "fill",
  output_crs = "EPSG:26917",
  output_resolution = 100,
  combine = "single",
  details = TRUE,
  progress = FALSE,
  quiet = TRUE
))
```

```{r single-table, echo=FALSE, eval=bt_real_examples_enabled()}
single_raster <- single$data
single_table <- data.frame(
  output_object_class = paste(class(single_raster), collapse = ", "),
  crs = paste0("EPSG:", terra::crs(single_raster, describe = TRUE)$code),
  resolution = paste(round(terra::res(single_raster), 3), collapse = " x "),
  extent = paste(round(as.vector(terra::ext(single_raster)), 1), collapse = ", "),
  resampled_flag = attr(single_raster, "bluertopo_resampled") %in% TRUE,
  stringsAsFactors = FALSE
)

bt_display_table(single_table)
```

```{r output-raster, echo=FALSE, eval=bt_real_examples_enabled(), fig.cap="BlueTopo elevation resampled to the specified output grid.", fig.alt="Hillshaded BlueTopo elevation raster on one explicit output grid with contours."}
bt_plot_bathy_map(single$data, real_aoi, main = "Explicit output grid bathymetry")
```

The explicit grid is useful for workflows that require one raster, but it is a
resampling operation. Native source-resolution selection remains separate from
output-grid creation.