bluertopo

# bluertopo

<img src="man/figures/logo.png" align="right" height="139" alt="bluertopo logo" />

[![R-CMD-check](https://github.com/el-cordero/bluer-topo/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/el-cordero/bluer-topo/actions/workflows/R-CMD-check.yaml)
[![pkgdown](https://github.com/el-cordero/bluer-topo/actions/workflows/pkgdown.yaml/badge.svg)](https://github.com/el-cordero/bluer-topo/actions/workflows/pkgdown.yaml)
[![License:
MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/el-cordero/bluer-topo/blob/main/LICENSE.md)

`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](https://nauticalcharts.noaa.gov/data/bluetopo.html) and
[BlueTopo
specifications](https://nauticalcharts.noaa.gov/data/bluetopo_specs.html).

## Installation

``` r
# 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

``` r
library(bluertopo)

aoi <- vect("my_area.gpkg")

bathy <- bluertopo(aoi)
plot(bathy)
```

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

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

``` r
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:

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

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

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

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

``` r
bluertopo_cache_dir()
bluertopo_cache_clear(confirm = TRUE)
```

## Examples

The [Examples
tab](https://el-cordero.github.io/bluer-topo/articles/examples.html) 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.

- [Example
  gallery](https://el-cordero.github.io/bluer-topo/articles/examples.html)
- [Discover tiles and
  coverage](https://el-cordero.github.io/bluer-topo/articles/example-discover-tiles.html)
- [Download original
  assets](https://el-cordero.github.io/bluer-topo/articles/example-download-assets.html)
- [Extract elevation with
  terra](https://el-cordero.github.io/bluer-topo/articles/example-extract-elevation.html)
- [Compare resolution
  policies](https://el-cordero.github.io/bluer-topo/articles/example-resolution-policies.html)
- [Mixed grids and output
  grid](https://el-cordero.github.io/bluer-topo/articles/example-mixed-grids.html)
- [Layers and RAT
  metadata](https://el-cordero.github.io/bluer-topo/articles/example-layers-rat.html)

## Reference

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

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