Metadata-Version: 2.3
Name: bathy
Version: 0.3.0
Summary: Lightweight Python package for exploring bathymetry data.
Keywords: bathymetry,geomorphology,oceanography
Author: eslrgs
Author-email: eslrgs <euan-soutter@hotmail.co.uk>
License: MIT License
         
         Copyright (c) 2025 Euan Soutter
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Dist: xarray>=2024.1.0
Requires-Dist: netcdf4>=1.6.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: scipy>=1.11.0
Requires-Dist: geographiclib>=2.0
Requires-Dist: geopandas>=0.14.0
Requires-Dist: pydap>=3.5.8
Requires-Dist: cmocean>=4.0.0
Requires-Dist: rioxarray>=0.15.0
Requires-Dist: polars>=1.0.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: pooch>=1.7.0
Requires-Dist: owslib>=0.31.0
Requires-Dist: folium>=0.17.0
Requires-Dist: pyqt6>=6.5.0 ; extra == 'draw'
Requires-Dist: jupyter>=1.0.0 ; extra == 'notebook'
Requires-Dist: ipykernel>=6.0.0 ; extra == 'notebook'
Requires-Dist: ipywidgets>=8.0.0 ; extra == 'notebook'
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/eslrgs/bathy
Project-URL: Repository, https://github.com/eslrgs/bathy
Project-URL: Documentation, https://eslrgs.github.io/bathy/
Project-URL: Issues, https://github.com/eslrgs/bathy/issues
Provides-Extra: draw
Provides-Extra: notebook
Description-Content-Type: text/markdown

# 🌐 bathy

![Status](https://img.shields.io/badge/status-experimental-red)
[![CI](https://github.com/eslrgs/bathy/actions/workflows/ci.yml/badge.svg)](https://github.com/eslrgs/bathy/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://eslrgs.github.io/bathy)
![Python](https://img.shields.io/badge/python-3.12+-yellow)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

`bathy`, from Greek *βαθύς* (bathýs), meaning "deep", is a Python package for bathymetric analysis and visualisation.

**[Documentation](https://eslrgs.github.io/bathy)** · [Installation](#installation) · [Features](#features) · [Examples](#examples)

## Motivation

I found creating bathymetric plots and profiles in Python surprisingly difficult. `bathy` provides a simple, high-level interface for loading, analysing, and visualising bathymetry data, so you can go from raw grid to reproducible quantitative analysis to finished figure with minimal effort.

## Basic usage

### Load data

```python
import bathy

# Load from file
data = bathy.load_bathymetry("GEBCO_2025.nc", lon_range=(-10, 0), lat_range=(50, 60))

# Or download from multiple global and regional sources
data = bathy.load_gebco_opendap(lon_range=(-10, 0), lat_range=(50, 60))       # GEBCO ~450 m
data = bathy.load_etopo(lon_range=(-10, 0), lat_range=(50, 60))               # ETOPO 60s/30s/15s
data = bathy.load_emodnet_wcs(lon_range=(-10, 0), lat_range=(50, 60))         # EMODnet ~115 m (Europe)
data = bathy.load_noaa_crm(lon_range=(-72, -70), lat_range=(41, 43))          # NOAA CRM ~90 m (US coasts)
```

### Visualise

```python
bathy.plot_bathy(data)
```

<p align="center">
  <img src="docs/assets/images/plot_bathy.png" width="600" alt="Bathymetry">
</p>

### Analysis overview

```python
bathy.plot_overview(data)
```

<p align="center">
  <img src="docs/assets/images/plot_overview.png" width="600" alt="Overview">
</p>

### Profiles and canyon analysis

```python
prof = bathy.extract_profile(data, (-11.3, 48.7), (-7.3, 47.2), name="Along-slope")
bathy.plot_profile(prof, show_map=True, bathymetry_data=data)
```

<p align="center">
  <img src="docs/assets/images/plot_profile.png" width="600" alt="Profile">
</p>

```python
canyons = bathy.get_canyons(prof, prominence=100)
bathy.plot_canyons(prof, canyons)
```

<p align="center">
  <img src="docs/assets/images/plot_canyons.png" width="600" alt="Canyons">
</p>

## Installation

```bash
pip install bathy
```

Or with uv:

```bash
uv add bathy
```

## Features

| Category | Description |
|---|---|
| **IO** | Load from local files (NetCDF, GeoTIFF), GEBCO, ETOPO, EMODnet, or NOAA CRM. Export to GeoTIFF. 28 preset regions included. |
| **Grid operations** | Clip, resample (by degrees or metres), reproject, merge overlapping grids, fill NaN gaps |
| **Analysis** | Slope, aspect, curvature, rugosity, BPI, geomorphons, contours, smoothing, hypsometric analysis, volume & area calculations |
| **Plotting** | Publication-ready bathymetry, hillshade, slope, aspect, overview, 3D surface, depth zones, histograms, interactive maps |
| **Profiles** | Extract profiles between points, generate cross-sections, load from file or GeoDataFrame |
| **Profile analysis** | Statistics, gradient, concavity, knickpoints, canyon detection, comparison across profiles |
| **Draw** | Interactive PyQt6 desktop tool for drawing and editing profiles with drag, undo, and waypoint editing |

See the [full API reference](https://eslrgs.github.io/bathy) for details.

## Examples

See [examples/basic_usage.ipynb](examples/basic_usage.ipynb), [examples/downloading_data.ipynb](examples/downloading_data.ipynb), [examples/profiles.ipynb](examples/profiles.ipynb), [examples/grid_operations.ipynb](examples/grid_operations.ipynb), and [examples/draw_profile.py](examples/draw_profile.py).

### Profile drawing

Draw profiles interactively in a PyQt6 desktop window. Requires `uv pip install bathy[draw]`.

```bash
uv run bathy-draw path/to/data.nc
```

- Left-click to add waypoints, right-click to finish a profile, double-click to stop
- Drag waypoints to reposition, press **z** to undo, shift-click to delete
- Save/load profiles as GeoPackage, toggle visibility per profile

## Development

```bash
git clone https://github.com/eslrgs/bathy.git
cd bathy
uv sync
pre-commit install
```

```bash
just format  # Format and lint
just test    # Run tests
```

## Use of AI

This project was developed with assistance from AI, which was used for code generation, documentation, and testing.

## License

MIT License - see [LICENSE](LICENSE) for details.
