Package {bluertopo}

bluertopo: Download and extract NOAA BlueTopo bathymetry with terra

Description

bluertopo discovers NOAA BlueTopo source tiles, downloads original GeoTIFF/RAT assets with checksum validation, and opens selected raster bands as file-backed terra objects.

Author(s)

Maintainer: Elvin Cordero elvin.cordero@seamountgeo.com [copyright holder]

See Also

Useful links:

• https://el-cordero.github.io/bluer-topo/

• https://github.com/el-cordero/bluer-topo

• Report bugs at https://github.com/el-cordero/bluer-topo/issues

Download and extract NOAA BlueTopo bathymetry

Description

bluertopo() is the main extraction workflow. It discovers BlueTopo tiles for an AOI, downloads verified original source assets by default, and opens selected bands as lazy, file-backed terra objects.

Usage

bluertopo(
  aoi,
  layers = "elevation",
  resolution = "native",
  coverage = "warn",
  min_coverage = 1,
  access = "download",
  cache_dir = bluertopo_cache_dir(),
  refresh = "if_stale",
  crop = TRUE,
  mask = FALSE,
  combine = "auto",
  output_crs = NULL,
  output_resolution = NULL,
  resampling = NULL,
  verify = "sha256",
  workers = NULL,
  progress = interactive(),
  quiet = FALSE,
  details = FALSE
)

Arguments

Value

A terra::SpatRaster, terra::SpatRasterCollection, or a bluertopo_result list as described in Output behavior.

AOI inputs

aoi must resolve to polygon or multipolygon geometry with a known coordinate reference system (CRS). Accepted inputs are:

• a terra::SpatVector;

• an sf::sf data frame or sf::sfc geometry vector;

• a terra::SpatRaster, whose extent and CRS define the AOI;

• a terra::SpatExtent, interpreted as longitude/latitude in EPSG:4326;

• a numeric c(xmin, ymin, xmax, ymax) bounding box in EPSG:4326;

• a local vector-file path readable by terra::vect(); or

• a WKT or GeoJSON character string, interpreted as EPSG:4326.

Remote AOI URLs are refused. Numeric bounding boxes must be ordered and fall within valid longitude/latitude bounds. Point and line geometries are not accepted as areas of interest.

Output behavior

Native source grids are preserved unless both output_crs and output_resolution are supplied. With details = FALSE, the function returns a terra::SpatRaster for one compatible grid or a terra::SpatRasterCollection for multiple incompatible native grids. With details = TRUE, it returns a bluertopo_result list containing:

• data: the raster or raster collection;

• tiles: selected tile footprints and catalog metadata;

• downloads: one record per source asset;

• query: normalized request settings and query hash;

• coverage: geometric coverage diagnostics; and

• provenance: catalog, checksum, source, and vertical-reference records.

Examples

aoi <- c(xmin = -74.045, ymin = 40.675, xmax = -73.995, ymax = 40.715)

# sf and sfc polygons with a known CRS can be passed directly:
# aoi <- sf::st_read("my_area.gpkg")



bathy <- bluertopo(aoi)

Clear package-owned cache content

Description

Deletes only the configured bluertopo package cache after path safeguards.

Usage

bluertopo_cache_clear(
  cache_dir = bluertopo_cache_dir(),
  confirm = interactive()
)

Arguments

Value

A one-row data frame with cache_dir, removed_files, and removed_bytes columns.

Examples

bluertopo_cache_clear(confirm = TRUE)

Locate the bluertopo cache directory

Description

Returns the configured package cache directory without creating it.

Usage

bluertopo_cache_dir()

Details

The default is a session-temporary directory so routine package calls do not write to the user's home directory. Set options(bluertopo.cache_dir = ...) when a persistent cache is wanted.

Value

A length-one character vector containing the normalized cache path.

Examples

bluertopo_cache_dir()

Download original NOAA BlueTopo assets for an AOI

Description

Discovers selected BlueTopo tiles, downloads original GeoTIFF files and optional RAT sidecars, verifies them, and writes download manifests.

Usage

bluertopo_download(
  aoi,
  path,
  resolution = "native",
  coverage = "warn",
  min_coverage = 1,
  rat = TRUE,
  refresh = "if_stale",
  verify = "sha256",
  workers = NULL,
  on_exists = "verify",
  on_error = "stop",
  retries = 3,
  timeout = NULL,
  dry_run = FALSE,
  progress = interactive(),
  quiet = FALSE,
  cache_dir = bluertopo_cache_dir()
)

Arguments

Value

A bluertopo_downloads data frame with one row per planned asset. Important columns include tile_id, asset_type, source_url, local_path, status, verification_mode, verified, byte counts, checksums, attempts, and any recorded error. CSV and JSON copies are written below path unless dry_run = TRUE.

AOI inputs

aoi must resolve to polygon or multipolygon geometry with a known coordinate reference system (CRS). Accepted inputs are:

• a terra::SpatVector;

• an sf::sf data frame or sf::sfc geometry vector;

• a terra::SpatRaster, whose extent and CRS define the AOI;

• a terra::SpatExtent, interpreted as longitude/latitude in EPSG:4326;

• a numeric c(xmin, ymin, xmax, ymax) bounding box in EPSG:4326;

• a local vector-file path readable by terra::vect(); or

• a WKT or GeoJSON character string, interpreted as EPSG:4326.

Remote AOI URLs are refused. Numeric bounding boxes must be ordered and fall within valid longitude/latitude bounds. Point and line geometries are not accepted as areas of interest.

Examples

aoi <- c(xmin = -74.045, ymin = 40.675, xmax = -73.995, ymax = 40.715)



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

Construct a BlueTopo native-resolution policy

Description

bluertopo_resolution() creates an explicit native source-tile selection policy. Smaller meter values are finer source resolution. This object never requests output resampling; use output_resolution in bluertopo() for an explicit output grid.

Usage

bluertopo_resolution(
  strategy,
  value = NULL,
  values = NULL,
  min_m = NULL,
  max_m = NULL,
  n = NULL,
  scope = "global",
  tie = "finer",
  prefer = "finest",
  strict = TRUE,
  min_coverage = 1
)

Arguments

Value

A bluertopo_resolution S3 object containing the normalized policy fields. Pass it to the resolution argument of bluertopo(), bluertopo_tiles(), or bluertopo_download().

Examples

bluertopo_resolution("nearest", value = 10, tie = "finer")
bluertopo_resolution("between", min_m = 4, max_m = 16)

Retrieve all BlueTopo tile polygons

Description

Downloads or reuses the current NOAA BlueTopo tile-scheme catalog and returns every published tile footprint. This function does not require an area of interest and does not download any bathymetry rasters.

Usage

bluertopo_tile_polygons(
  cache_dir = bluertopo_cache_dir(),
  refresh = "if_stale",
  quiet = FALSE
)

Arguments

Value

A terra::SpatVector containing all current BlueTopo tile polygons and their standardized catalog metadata, including tile ID, native resolution, UTM zone, source URLs, and expected SHA-256 checksums.

Examples

tile_polygons <- bluertopo_tile_polygons()

Discover BlueTopo tiles intersecting an AOI

Description

Returns selected NOAA BlueTopo tile footprints and standardized metadata without downloading raster assets.

Usage

bluertopo_tiles(
  aoi,
  resolution = "native",
  coverage = "warn",
  min_coverage = 1,
  cache_dir = bluertopo_cache_dir(),
  refresh = "if_stale",
  quiet = FALSE
)

Arguments

Value

A terra::SpatVector with selected tile metadata. Coverage diagnostics are attached as the "coverage" attribute and the normalized native-resolution policy as "resolution_spec". Important fields include tile ID, native resolution, UTM zone, delivery date, intersection area and fraction, source URLs, expected SHA-256 checksums, selection rank/reason, and whether the tile was added as a coverage fallback.

AOI inputs

aoi must resolve to polygon or multipolygon geometry with a known coordinate reference system (CRS). Accepted inputs are:

• a terra::SpatVector;

• an sf::sf data frame or sf::sfc geometry vector;

• a terra::SpatRaster, whose extent and CRS define the AOI;

• a terra::SpatExtent, interpreted as longitude/latitude in EPSG:4326;

• a numeric c(xmin, ymin, xmax, ymax) bounding box in EPSG:4326;

• a local vector-file path readable by terra::vect(); or

• a WKT or GeoJSON character string, interpreted as EPSG:4326.

Remote AOI URLs are refused. Numeric bounding boxes must be ordered and fall within valid longitude/latitude bounds. Point and line geometries are not accepted as areas of interest.

Examples

aoi <- c(xmin = -74.045, ymin = 40.675, xmax = -73.995, ymax = 40.715)



tiles <- bluertopo_tiles(aoi)