API Reference

Python API

All public functions are importable from nbs.noaabathymetry:

from nbs.noaabathymetry import fetch_tiles, mosaic_tiles, status_tiles

fetch_tiles

fetch_tiles(
    project_dir: str,
    geometry: str = None,
    data_source: str = None,
    tile_resolution_filter: list = None,
    debug: bool = False,
) -> FetchResult

Discover, download, and update NBS tiles.

Parameters

Returns: FetchResult

Raises

Example

from nbs.noaabathymetry import fetch_tiles

result = fetch_tiles(
    '/home/user/bathymetry',
    geometry='-76.1,36.9,-75.9,37.1',
    data_source='bluetopo',
)

print(f"Tiles in AOI: {result.available_tiles_intersecting_aoi}")
print(f"Newly tracked: {result.new_tiles_tracked}")
print(f"Downloaded: {len(result.downloaded)}")
print(f"Not found on S3: {len(result.not_found)}")
print(f"Already existing: {len(result.existing)}")
for failure in result.failed:
    print(f"  Failed: {failure['tile']} - {failure['reason']}")

mosaic_tiles

mosaic_tiles(
    project_dir: str,
    data_source: str = None,
    relative_to_vrt: bool = True,
    mosaic_resolution_target: float = None,
    tile_resolution_filter: list = None,
    hillshade: bool = False,
    workers: int = None,
    reproject: bool = False,
    output_dir: str = None,
    debug: bool = False,
) -> MosaicResult

Build a per-UTM-zone mosaic from all source tiles.

Parameters

Returns: MosaicResult

Raises

Example

from nbs.noaabathymetry import mosaic_tiles

result = mosaic_tiles(
    '/home/user/bathymetry',
    data_source='bluetopo',
    mosaic_resolution_target=8,
    tile_resolution_filter=[4, 8],
)

for entry in result.built:
    print(f"Built UTM {entry['utm']}: {entry['mosaic']}")
print(f"Skipped (up to date): {len(result.skipped)}")
print(f"Missing mosaics reset: {len(result.missing_reset)}")

FetchResult

Dataclass returned by fetch_tiles.

Example

result = fetch_tiles('/home/user/bathymetry', geometry='aoi.gpkg')
print(result)

# FetchResult(
#     downloaded=['BlueTopo_BC25L4NW_20240315', 'BlueTopo_BC25L4NE_20240315',
#                 'BlueTopo_BC25L6SW_20240315'],
#     failed=[{'tile': 'BlueTopo_BC25L6SE_20240315',
#              'reason': 'incorrect hash for geotiff (expected=a1b2c3d4e5f6... got=9f8e7d6c5b4a...)'}],
#     not_found=['BlueTopo_BC25L8NW_20240315'],
#     existing=['BlueTopo_BC25M4NW_20240301', 'BlueTopo_BC25M4NE_20240301'],
#     filtered_out=[],
#     missing_reset=[],
#     available_tiles_intersecting_aoi=8,
#     new_tiles_tracked=6,
#     tile_resolution_filter=None
# )

MosaicResult

Dataclass returned by mosaic_tiles.

Example

result = mosaic_tiles('/home/user/bathymetry')
print(result)

# MosaicResult(
#     built=[
#         {'utm': '18', 'mosaic': '/home/user/bathymetry/BlueTopo_Mosaic/BlueTopo_Fetched_UTM18.vrt',
#          'ovr': '/home/user/bathymetry/BlueTopo_Mosaic/BlueTopo_Fetched_UTM18.vrt.ovr',
#          'hillshade': None},
#         {'utm': '19', 'mosaic': '/home/user/bathymetry/BlueTopo_Mosaic/BlueTopo_Fetched_UTM19.vrt',
#          'ovr': '/home/user/bathymetry/BlueTopo_Mosaic/BlueTopo_Fetched_UTM19.vrt.ovr',
#          'hillshade': None}
#     ],
#     skipped=['17'],
#     failed=[],
#     missing_reset=[],
#     hillshades=[],
#     tile_resolution_filter=None,
#     mosaic_resolution_target=None
# )

status_tiles

status_tiles(
    project_dir: str,
    data_source: str = None,
    verbosity: str = "normal",
) -> StatusResult

Check local project freshness against the remote tile scheme.

Parameters

Returns: StatusResult

Raises

Example

from nbs.noaabathymetry import status_tiles

result = status_tiles('/home/user/bathymetry')

print(f"Up to date: {len(result.up_to_date)}")
print(f"Updates available: {len(result.updates_available)}")
for entry in result.updates_available:
    print(f"  {entry['tile']}: {entry['local_datetime']} -> {entry['remote_datetime']}")

StatusResult

Dataclass returned by status_tiles.

CLI Reference

The nbs command is installed when you pip install noaabathymetry.

nbs fetch

nbs fetch -d DIR [-g GEOMETRY] [-s SOURCE] [--tile-resolution-filter N [N ...]] [--debug] [--json]

Examples

# Discover tiles within a bounding box and download tracked tiles
nbs fetch -d /home/user/bathymetry -g "-76.1,36.9,-75.9,37.1"

# Fetch from a geopackage, only 4m and 8m tiles
nbs fetch -d /home/user/bathymetry -g /path/to/aoi.gpkg --tile-resolution-filter 4 8

# Fetch BAG data
nbs fetch -d /home/user/bathymetry -g aoi.gpkg -s bag

# Re-download/update without discovering new tiles (existing project, no geometry)
nbs fetch -d /home/user/bathymetry

nbs mosaic

nbs mosaic -d DIR [-s SOURCE] [-r BOOL] [-t RESOLUTION] [--tile-resolution-filter N [N ...]] [--hillshade] [--workers N] [--reproject] [-o OUTPUT_DIR] [--debug] [--json]

Examples

# Build mosaics from fetched BlueTopo tiles
nbs mosaic -d /home/user/bathymetry

# Build at 8m resolution target
nbs mosaic -d /home/user/bathymetry -t 8

# Build only from 4m tiles
nbs mosaic -d /home/user/bathymetry --tile-resolution-filter 4

# Build with 4 parallel workers
nbs mosaic -d /home/user/bathymetry --workers 4

# Build with hillshade generation
nbs mosaic -d /home/user/bathymetry --hillshade

# Build into a custom output directory
nbs mosaic -d /home/user/bathymetry -o my_custom_mosaics

# Build Modeling mosaics
nbs mosaic -d /home/user/bathymetry -s modeling

nbs status

nbs status -d DIR [-s SOURCE] [--verbosity quiet|normal|verbose] [--json]

Examples

# Check for updates
nbs status -d /home/user/bathymetry

# Check with verbose tile listing
nbs status -d /home/user/bathymetry --verbosity verbose

# Quiet mode (return object only, no log output)
nbs status -d /home/user/bathymetry --verbosity quiet

# Check a different data source
nbs status -d /home/user/bathymetry -s bag