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

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 4)
```

```{r setup, message = FALSE}
library(blueterra)
```

Isobath corridors summarize terrain along depth horizons. They are useful when
observations are collected along contours or when terrain structure needs to be
compared at equivalent depths while retaining along-contour variability.

```{r data}
bathy <- read_bathy(blueterra_example("hitw"))
prepared <- prepare_bathy(bathy, depth_range = c(-220, -25), smooth = TRUE)
terrain <- derive_terrain(
  prepared,
  metrics = c("slope", "bpi", "curvature", "surface_area_ratio")
)
```

The example bathymetry stores depth as negative elevation, so contour depths are
passed as negative values.

```{r isobaths}
isobaths <- extract_isobaths(prepared, depths = c(-50, -80, -120))
isobaths[, c("contour_value", "depth_label")]
```

```{r isobath-map, eval=requireNamespace("ggplot2", quietly = TRUE), fig.alt="Isobaths over hillshaded bathymetry."}
plot_bathy(
  prepared,
  contours = TRUE,
  contour_interval = 25,
  vectors = isobaths,
  vector_color = "black",
  title = "Isobaths Over Hillshaded Bathymetry"
)
```

Buffers are measured in map units, so the raster should use a projected CRS.
The example raster is projected; other rasters should be reprojected explicitly
when needed.
Corridors use a 5 m buffer around each source isobath.

```{r corridors}
corridors <- make_isobath_corridors(
  prepared,
  depths = c(-50, -80, -120),
  width = 5
)
corridors[, c("contour_value", "depth_label", "corridor_id")]
```

```{r corridor-map, eval=requireNamespace("ggplot2", quietly = TRUE), fig.alt="Isobath corridors over hillshaded bathymetry."}
plot_isobath_corridors(
  corridors,
  prepared,
  isobaths = isobaths,
  background_contours = FALSE,
  title = "Isobath Corridors and Source Isobaths",
  subtitle = "Corridors use a 5 m buffer around each source isobath"
)
```

The black lines are the source isobaths. The corridor polygons buffer those
depth horizons by 5 m and define the terrain extraction zones used in the
summary.

## Extract and Summarize Terrain

```{r summarize}
cells <- extract_isobath_corridors(terrain, corridors)
head(cells)

summary <- summarize_isobath_terrain(terrain, corridors)
summary[, c("contour_value", "slope_deg_mean", "bpi_3x3_mean", "curvature_mean")]
```

The summary compares terrain structure at the selected depth horizons. BPI
values should be interpreted using the raster's stored vertical convention.