Get BlueTopo • bluertopo

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.