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

```{r, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)
```

`bluertopo()` is the main workflow for opening BlueTopo source bathymetry with
`terra`. It discovers the current BlueTopo tile-scheme catalog, intersects that
catalog with an area of interest, downloads verified original source files when
needed, and returns file-backed `terra` rasters.

Reference: NOAA, [BlueTopo](https://nauticalcharts.noaa.gov/data/bluetopo.html).

## Define an AOI

Every AOI must resolve to polygon or multipolygon geometry. `terra`, `sf`, and
file inputs must carry a known coordinate reference system (CRS).

| Input type | Accepted form | CRS handling |
|:---|:---|:---|
| `terra` vector | `SpatVector` | Uses the object's CRS |
| `sf` vector | `sf` or `sfc` | Uses the object's CRS |
| `terra` raster | `SpatRaster` | Uses its extent and CRS |
| `terra` extent | `SpatExtent` | Assumed EPSG:4326 |
| Numeric bbox | `c(xmin, ymin, xmax, ymax)` | Assumed EPSG:4326 |
| Local vector file | A path readable by `terra::vect()` | Uses the file's CRS |
| Geometry text | WKT or GeoJSON polygon text | Assumed EPSG:4326 |

Remote URLs are intentionally refused. Points, lines, missing CRS values,
unordered bounding boxes, and invalid longitude/latitude bounds fail early with
an explanatory `bluertopo_error_aoi` condition.

```{r}
library(bluertopo)

aoi <- vect("project_area.gpkg")

# Or a bbox: c(xmin, ymin, xmax, ymax) in EPSG:4326.
aoi <- c(xmin = -74.045, ymin = 40.675, xmax = -73.995, ymax = 40.715)
```

Pass `sf` objects directly; no conversion is required:

```{r}
library(sf)

aoi_sf <- st_read("project_area.gpkg", quiet = TRUE)
bathy <- bluertopo(aoi_sf)
```

## Discover tiles first

Inspect tile choices before downloading large GeoTIFFs.

```{r}
tiles <- bluertopo_tiles(aoi)

as.data.frame(tiles)[
  c("tile_id", "resolution_m", "delivered_date", "selection_reason")
]
```

## Open bathymetry

By default, `bluertopo()` downloads original NOAA assets into the package cache,
verifies SHA-256 checksums, and opens the elevation band.

```{r}
result <- bluertopo(aoi, details = TRUE)

result$data
result$downloads
result$coverage
```

Set `details = TRUE` when provenance matters. The result includes selected
tiles, download statuses, query metadata, coverage diagnostics, and catalog
provenance.

## Know what comes back

| Call | Return value |
|:---|:---|
| `bluertopo_tile_polygons()` | A `terra::SpatVector` of every current tile footprint; no AOI required |
| `bluertopo_tiles(aoi)` | A `terra::SpatVector` of selected tile footprints and metadata |
| `bluertopo_download(aoi, path)` | A `bluertopo_downloads` data frame with one row per asset |
| `bluertopo(aoi)` | A `terra::SpatRaster`, or a `terra::SpatRasterCollection` for incompatible native grids |
| `bluertopo(aoi, details = TRUE)` | A `bluertopo_result` list containing `data`, `tiles`, `downloads`, `query`, `coverage`, and `provenance` |

## Choose layers

BlueTopo source GeoTIFFs currently expose elevation, vertical uncertainty, and
contributor/source identifier bands.

```{r}
all_layers <- bluertopo(
  aoi,
  layers = "all",
  coverage = "fill"
)
```

## Avoid accidental resampling

Native BlueTopo tiles may differ in CRS, resolution, origin, or alignment. When
selected source grids are incompatible, `bluertopo()` returns a
`terra::SpatRasterCollection` rather than silently resampling.

Request a single output grid only when resampling is an intentional analytical
choice.

```{r}
bathy_10m <- bluertopo(
  aoi,
  resolution = "native",
  output_crs = "EPSG:26918",
  output_resolution = 10,
  combine = "single"
)
```

`crop = TRUE` crops to the AOI extent. `mask = TRUE` additionally removes cells
outside the polygon. `combine = "auto"` preserves compatible native grids as one
raster and returns a collection for incompatible grids. Supplying both
`output_crs` and `output_resolution` creates one explicit resampled output grid.