# Get BlueTopo

`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.

## 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.

    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:

    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.

    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.

    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.

    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.

    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.