bluertopo

bluertopo discovers, downloads, verifies, and opens National Oceanic and Atmospheric Administration (NOAA) BlueTopo bathymetry for an area of interest using terra. The package keeps source GeoTIFF and RAT sidecar files intact by default, records query and catalog provenance, and makes native source-resolution choices explicit.

Reference: NOAA, BlueTopo and BlueTopo specifications.

Installation

# install.packages("pak")
pak::pak("el-cordero/bluer-topo")

Define an area of interest

Every area of interest (AOI) must be polygon or multipolygon geometry. Spatial objects and files must have a known coordinate reference system (CRS).

AOI input	Example	CRS rule
`terra::SpatVector`	`terra::vect("my_area.gpkg")`	Uses the object’s CRS
`sf::sf` or `sf::sfc`	`sf::st_read("my_area.gpkg")`	Uses the object’s CRS
`terra::SpatRaster`	`terra::rast("template.tif")`	Uses the raster extent and CRS
`terra::SpatExtent`	`terra::ext(-74.1, -73.9, 40.6, 40.8)`	Interpreted as EPSG:4326
Numeric bbox	`c(xmin, ymin, xmax, ymax)`	Interpreted as EPSG:4326
Local vector path	`"my_area.gpkg"`	Uses the file’s CRS
WKT or GeoJSON string	Polygon text	Interpreted as EPSG:4326

Remote AOI URLs, points, lines, missing CRS values, unordered bounding boxes, and invalid longitude/latitude bounds are rejected with an explanatory error.

Basic workflow

library(bluertopo)

aoi <- vect("my_area.gpkg")

bathy <- bluertopo(aoi)
plot(bathy)

An sf object can be passed without converting it to terra first:

aoi_sf <- sf::st_read("my_area.gpkg", quiet = TRUE)
bathy_sf <- bluertopo(aoi_sf)

Choose the right function

Function	Use it when you need	Return type
`bluertopo_tile_polygons()`	Every current BlueTopo tile polygon, with no AOI	`terra::SpatVector`
`bluertopo_tiles()`	Tile discovery and coverage planning only	`terra::SpatVector`
`bluertopo_download()`	Verified original GeoTIFF/RAT files and manifests	`bluertopo_downloads` data frame
`bluertopo()`	Elevation, uncertainty, or contributor rasters	`terra::SpatRaster` or `terra::SpatRasterCollection`
`bluertopo(..., details = TRUE)`	Rasters plus tiles, downloads, query, coverage, and provenance	`bluertopo_result` list

Provenance workflow

result <- bluertopo(aoi, details = TRUE)

result$tiles
result$downloads
result$coverage
result$provenance

Get all BlueTopo tile polygons

No AOI is needed to retrieve the complete current tile scheme:

tile_polygons <- bluertopo_tile_polygons()
plot(tile_polygons)

output_file <- file.path(tempdir(), "bluetopo-tile-polygons.gpkg")
writeVector(tile_polygons, output_file, overwrite = TRUE)

Download original BlueTopo assets

Use bluertopo_download() when the durable deliverable is the original GeoTIFF plus optional RAT sidecars rather than an extracted raster object.

files <- bluertopo_download(
  aoi,
  path = file.path(tempdir(), "bluertopo-downloads")
)

verify = "sha256" is the default and requires NOAA-provided checksums. verify = "none" is available only for explicitly unverified workflows. verify = "size" is rejected unless trustworthy expected byte counts are available before any transfer starts.

Native resolution policies

resolution filters NOAA BlueTopo source tiles by their native cell size. Smaller meter values mean finer native source detail. output_resolution requests an explicit output grid and therefore resamples the output.

# Exact native resolution
bathy_8m <- bluertopo(aoi, resolution = 8)

# Highest native detail, with lower-resolution fallback for coverage
bathy_best <- bluertopo(aoi, resolution = "finest", coverage = "fill")

# Lowest native detail
bathy_low <- bluertopo(aoi, resolution = "coarsest")

# Closest available native resolution to 10 m
bathy_near <- bluertopo(
  aoi,
  resolution = bluertopo_resolution("nearest", value = 10, tie = "finer")
)

# Keep source tiles from 4 through 16 m
bathy_range <- bluertopo(
  aoi,
  resolution = bluertopo_resolution("between", min_m = 4, max_m = 16)
)

Mixed source grids

Native BlueTopo tiles can span multiple UTM zones, resolutions, or grid alignments. When the selected source files are not compatible, bluertopo() returns a terra::SpatRasterCollection unless the user explicitly requests an output grid.

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

Use crop = TRUE to crop to the AOI extent and mask = TRUE to remove cells outside the AOI polygon. Supplying both output_crs and output_resolution requests a resampled output grid; omitting both preserves native source grids.

Cache operations

Package cache operations are intentionally conservative. bluertopo_cache_clear() clears only the configured bluertopo cache, requires confirmation in noninteractive sessions, and refuses to remove content unless a package-owned cache marker is present. The default cache is session-temporary; set options(bluertopo.cache_dir = "/path/to/cache") when a persistent cache is wanted.

bluertopo_cache_dir()
bluertopo_cache_clear(confirm = TRUE)

Examples

The Examples tab on the pkgdown site uses BlueTopo source tiles for New York Harbor, with a documented secondary AOI only for the mixed-grid page. Normal package tests use small synthetic fixtures so checks remain network-free.

Reference

NOAA. BlueTopo. https://nauticalcharts.noaa.gov/data/bluetopo.html

NOAA. BlueTopo specifications. https://nauticalcharts.noaa.gov/data/bluetopo_specs.html