Package 'bluertopo'

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

aoi	A polygonal area of interest in one of the formats listed in AOI inputs below.
layers	A character vector containing "elevation", "uncertainty", or "contributor"; use "all" for all three source bands. Elevation and uncertainty are continuous values. Contributor identifiers are categorical.
resolution	A native source-tile selection policy. Supply a shortcut such as "native", "finest", "coarsest", "best_available", "coarsest_available", or "dominant"; a positive numeric meter value for an exact match; or a bluertopo_resolution() object.
coverage	A character scalar controlling incomplete selected coverage: "ignore", "warn", "error", or "fill". "fill" adds fallback native resolutions in policy order until the target is met when possible.
min_coverage	A numeric value from 0 through 1 giving the target share of published tile-index coverage. This is geometric catalog coverage, not a data-quality measure.
access	A character scalar. "download" stores and SHA-256 verifies source files before opening them; "stream" uses GDAL ⁠/vsicurl/⁠ access without local checksum verification.
cache_dir	A non-empty character path for the package cache. The session-temporary default avoids writing to the user's home directory. Set an explicit path to reuse catalogs, source files, and VRTs across sessions.
refresh	A character scalar controlling catalog access: "if_stale", "never", or "always". "never" requires an existing cached catalog and performs no catalog request.
crop	A length-one logical. If TRUE, crop each output to the AOI bounding extent.
mask	A length-one logical. If TRUE, mask cells outside the AOI polygon and also enable cropping.
combine	A character scalar controlling multiple native grids: "auto" returns one raster when compatible and a collection otherwise; "collection" always returns a collection; "single" requires compatible grids or an explicit output grid.
output_crs	NULL or a non-empty character projected CRS accepted by terra, such as "EPSG:26918" or WKT. Supply it together with output_resolution to request one resampled output grid.
output_resolution	NULL or one positive numeric cell size in output_crs units. It must be supplied together with output_crs.
resampling	NULL, a named character vector, or a named list keyed by layer. Allowed methods are "near", "bilinear", "cubic", "cubicspline", "lanczos", "average", and "mode". Defaults are bilinear for elevation/uncertainty and nearest-neighbor for contributor; contributor cannot use a non-nearest method.
verify	A character scalar download-verification mode: "sha256" (default), "size", or "none". "none" is explicitly unverified.
workers	NULL or the number 1. Higher worker counts are rejected in this release.
progress	A length-one logical controlling routine download progress.
quiet	A length-one logical suppressing routine informational messages.
details	A length-one logical. If TRUE, return data plus tile, download, query, coverage, and provenance records.

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

cache_dir	Length-one character path to a package-owned cache directory.
confirm	A length-one logical. Must be TRUE in noninteractive sessions.

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

aoi	A polygonal area of interest in one of the formats listed in AOI inputs below.
path	A non-empty character path to the destination directory for the original source assets and generated CSV/JSON manifests. The argument is required; there is no default write location.
resolution	A native source-tile selection policy. Supply a shortcut such as "native", "finest", "coarsest", "best_available", "coarsest_available", or "dominant"; a positive numeric meter value for an exact match; or a bluertopo_resolution() object.
coverage	A character scalar controlling incomplete selected coverage: "ignore", "warn", "error", or "fill". "fill" adds fallback native resolutions in policy order until the target is met when possible.
min_coverage	A numeric value from 0 through 1 giving the target share of published tile-index coverage. This is geometric catalog coverage, not a data-quality measure.
rat	A length-one logical. If TRUE, download Raster Attribute Table (RAT) XML sidecars when the catalog provides them.
refresh	A character scalar controlling catalog access: "if_stale", "never", or "always". "never" requires an existing cached catalog and performs no catalog request.
verify	A character scalar download-verification mode: "sha256" (default), "size", or "none". "none" is explicitly unverified.
workers	NULL or the number 1. Higher worker counts are rejected in this release.
on_exists	A character scalar: "verify" reuses only files that pass verification, "skip" leaves existing files untouched, and "replace" downloads them again.
on_error	A character scalar: "stop" aborts after an asset failure; "continue" records the failure and processes the remaining assets.
retries	A positive whole number giving the maximum attempts per asset.
timeout	NULL or a positive numeric timeout in seconds for each HTTP request.
dry_run	A length-one logical. If TRUE, return the planned assets without downloading source files.
progress	A length-one logical controlling routine download progress.
quiet	A length-one logical suppressing routine informational messages.
cache_dir	A non-empty character path for the package cache. The session-temporary default avoids writing to the user's home directory. Set an explicit path to reuse catalogs, source files, and VRTs across sessions.

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

strategy	A character scalar naming a strategy: "native", "finest", "coarsest", "best_available", "coarsest_available", "dominant", "exact", "nearest", "finer_or_equal", "coarser_or_equal", "between", "rank", "finest_n", "coarsest_n", "target", or "coverage". "highest" and "lowest" are aliases for "finest" and "coarsest".
value	NULL or one positive numeric native cell size in meters. Required by "nearest", "target", "finer_or_equal", and "coarser_or_equal".
values	NULL or a numeric vector of positive native cell sizes in meters. Required by "exact".
min_m, max_m	NULL or positive numeric inclusive bounds in meters. Both are required by "between".
n	NULL or a positive whole number used by "rank", "finest_n", and "coarsest_n".
scope	A character scalar. Only "global" is implemented; "local" is reserved and rejected.
tie	A character scalar, "finer" or "coarser", used when two native resolutions are equally close to a target.
prefer	A character scalar, "finest" or "coarsest", controlling ordering for coverage and rank strategies.
strict	A length-one logical. If TRUE, coverage fallback stays within hard resolution constraints.
min_coverage	A numeric value from 0 through 1 used by the "coverage" strategy.

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

cache_dir	A non-empty character path for the package cache. The session-temporary default avoids writing to the user's home directory. Set an explicit path to reuse catalogs, source files, and VRTs across sessions.
refresh	A character scalar controlling catalog access: "if_stale", "never", or "always". "never" requires an existing cached catalog and performs no catalog request.
quiet	A length-one logical suppressing routine informational messages.

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

aoi	A polygonal area of interest in one of the formats listed in AOI inputs below.
resolution	A native source-tile selection policy. Supply a shortcut such as "native", "finest", "coarsest", "best_available", "coarsest_available", or "dominant"; a positive numeric meter value for an exact match; or a bluertopo_resolution() object.
coverage	A character scalar controlling incomplete selected coverage: "ignore", "warn", "error", or "fill". "fill" adds fallback native resolutions in policy order until the target is met when possible.
min_coverage	A numeric value from 0 through 1 giving the target share of published tile-index coverage. This is geometric catalog coverage, not a data-quality measure.
cache_dir	A non-empty character path for the package cache. The session-temporary default avoids writing to the user's home directory. Set an explicit path to reuse catalogs, source files, and VRTs across sessions.
refresh	A character scalar controlling catalog access: "if_stale", "never", or "always". "never" requires an existing cached catalog and performs no catalog request.
quiet	A length-one logical suppressing routine informational messages.

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)

---