Skip to content

Quick Start

This guide covers the basics of loading bathymetry data and creating visualisations.

Loading data

From GEBCO

The easiest way to get started is to download data directly from the GEBCO OPeNDAP server:

import bathy

data = bathy.load_gebco_opendap(
    lon_range=(-12, -5),
    lat_range=(46, 50),
    save_path="data/my_region.nc",  # Optional: save for reuse
)

If save_path exists, the download is skipped and data is loaded from the file.

Using preset regions

For convenience, common oceanographic regions are available:

import bathy

# See available regions
print(bathy.list_regions())

# Load a preset region
data = bathy.load_gebco_opendap(region="mediterranean")

From local files

Load from NetCDF or GeoTIFF:

# NetCDF
data = bathy.load_bathymetry("path/to/gebco.nc", lon_range=(-10, -5), lat_range=(50, 55))

# GeoTIFF
data = bathy.load_bathymetry("path/to/bathymetry.tif")

Basic visualisation

# Elevation map
bathy.plot_bathy(data)

# With contours
bathy.plot_bathy(data, contours=[-200, -1000, -2000, -4000])

# Hillshade
bathy.plot_hillshade(data)

# Slope map
bathy.plot_slope(data)

# Depth zones
bathy.plot_depth_zones(data)

All plot functions return (fig, ax) so you can annotate or save:

fig, ax = bathy.plot_bathy(data)
ax.set_title("Celtic Sea")
fig.savefig("celtic_sea.png", dpi=300)

Creating profiles

Extract a bathymetric profile between two points:

# Create profile with 1 km point spacing
prof = bathy.extract_profile(
    data,
    start=(-11, 48),
    end=(-6, 48),
    point_spacing=1000.0,
    name="East-West Profile",
)

# Plot the profile
bathy.plot_profile(prof)

# Get statistics
bathy.profile_stats(prof)

Smoothing

Gaussian smooth a grid to suppress noise before derived analysis:

smoothed = bathy.smooth(data, sigma_km=2.0)

# Chain with other analysis
bathy.plot_slope(smoothed)

Contour extraction

Extract depth contours as vector geometries for export or spatial analysis:

# Contours at specific depths
gdf = bathy.contours(data, levels=[-200, -1000, -2000])

# Regular interval
gdf = bathy.contours(data, interval=500)

# Export to file
gdf.to_file("contours.gpkg")

Interactive map

Explore bathymetry on an interactive Leaflet basemap with toggleable analysis overlays:

# Basic interactive map
bathy.plot_interactive(data)

# With analysis overlays
bathy.plot_interactive(data, overlays={
    "Slope": bathy.slope(data),
    "Rugosity": bathy.rugosity(data),
})

Summary statistics

# Overall statistics (delegates to xarray describe)
bathy.summary(data)

# Hypsometric index
hi = bathy.hypsometric_index(data)
print(f"Hypsometric Index: {hi:.3f}")