pygmrt 0.1.0

A minimal Python package for downloading bathymetry and topography tiles from GMRT

PyGMRT

A minimal Python package for downloading bathymetry and topography tiles from the Global Multi-Resolution Topography (GMRT) Synthesis.

Features

• Simple API: Single function to download GMRT tiles
• Multiple resolutions: High (1 arc-second), medium (4 arc-second), low (16 arc-second)
• GeoTIFF format: Direct integration with rasterio and other geospatial tools
• Antimeridian support: Handles bounding boxes that cross the 180° longitude
• No API key required: Direct access to GMRT GridServer

Installation

Using UV (recommended)

If you don't have UV installed, follow the instructions at uv. Then install PyGMRT from PyPI:

uv add pygmrt

Or install from source

git clone https://github.com/leonard-seydoux/pygmrt.git
cd pygmrt
uv sync

Using pip

Similarly, you can either install from PyPI:

pip install pygmrt

Or install from source:

# Or install from source
git clone https://github.com/leonard-seydoux/pygmrt.git
cd pygmrt
pip install -e .

Quick Start

from rasterio.plot import show
from pygmrt.tiles import download_tiles

# Get tiles
tiles = download_tiles(bbox=[55.05, -21.5, 55.95, -20.7], resolution="low")

# Show with minimal processing
show(tiles)

Other examples

The playground notebook 02_playground.ipynb contains more advanced examples, including shaded relief visualizations with matplotlib and cartopy. The following figures were generated with that notebook.

API reference

The main function of the package is pygmrt.tiles.download_tiles, with the signature given below.

def download_tiles(
    bbox, 
    save_directory="./geotiff/",
    resolution="medium",
    overwrite=False,
):
    """
    Download tiles and return the rasterio dataset.

    Parameters
    ----------
    bbox : sequence of float
        Bounding box in WGS84 degrees as ``[west, south, east, north]``.
    save_directory : str or pathlib.Path
        Destination directory path where files will be written. Created if
        needed.
    resolution : {"low", "medium", "high"}, default "medium"
        Named resolution level; mapped internally to provider-specific datasets.
    overwrite : bool, default False
        If ``False``, reuse existing files. If ``True``, force re-download.

    Returns
    -------
    rasterio.DatasetReader
        Opened rasterio dataset for the downloaded GeoTIFF. The caller is
        responsible for closing the dataset.

    Raises
    ------
    ValueError
        If invalid argument combinations or bbox values are provided.
    PermissionError
        If the destination directory is not writable.
    RuntimeError
        If download attempts ultimately fail.
"""

Development

Setting up development environment

git clone https://github.com/leonard-seydoux/pygmrt.git
cd pygmrt

# Install in development mode with UV
uv sync --all-extras

# Or with pip
pip install -e ".[dev,docs]"

Running tests

# With UV
uv run pytest

# With pip
pytest

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• GMRT Synthesis for providing open access to global bathymetry data
• Lamont-Doherty Earth Observatory for maintaining the GMRT database