| Name | pygmrt JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | None |
| Summary | A minimal Python package for downloading bathymetry and topography tiles from GMRT |
| upload_time | 2025-11-01 12:30:53 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | None |
| keywords |
bathymetry
topography
gmrt
geospatial
oceanography
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
<img src="https://raw.githubusercontent.com/leonard-seydoux/pygmrt/main/docs/images/logo.png" alt="PyGMRT Logo" width=100/>
### PyGMRT
Downloading bathymetry and topography tiles from the<br>
[Global Multi-Resolution Topography (GMRT)](https://www.gmrt.org/) synthesis.
[](https://python.org)
</div>
## Contents
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Example: La Réunion Island Relief](#example-la-réunion-island-relief)
- [Example: Colombia Relief](#example-colombia-relief)
- [API Reference](#api-reference)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)
## Features
PyGMRT provides a simple Python interface to access bathymetry and topography data from the [Global Multi-Resolution Topography](https://www.gmrt.org/) (GMRT) synthesis. The package handles all the complexity of downloading and processing geographic tiles, letting you focus on your analysis.
The core functionality centers around a single function that downloads tiles for any region on Earth. You can choose between three resolution levels: high resolution at 1 arc-second (about 30 meters at the equator), medium resolution at 4 arc-seconds, or low resolution at 16 arc-seconds. All data comes in GeoTIFF format, which works directly with [rasterio](https://rasterio.readthedocs.io/) and other geospatial tools.
The package automatically handles regions that cross the antimeridian (the 180° longitude line). This is often painful when working with global data, but PyGMRT takes care of it transparently. Since the package connects directly to the GMRT GridServer, you don't need API keys or authentication.
## Installation
We recommend using [UV](https://uv.readthedocs.io/), a modern Python package installer that handles dependencies efficiently. Traditional pip works just as well.
If you're using UV, add PyGMRT to your project:
```bash
uv add pygmrt
```
Or install from the latest development version:
```bash
git clone https://github.com/leonard-seydoux/pygmrt.git
cd pygmrt
uv sync
```
For pip users, install directly from PyPI:
```bash
pip install pygmrt
```
Or install from source:
```bash
git clone https://github.com/leonard-seydoux/pygmrt.git
cd pygmrt
pip install -e .
```
## Quick start
The simplest way to download topography data is with a single function call. Here we'll download data for La Réunion Island, a volcanic island in the Indian Ocean. The bounding box is specified as `[west, south, east, north]` in degrees.
```python
# Configure matplotlib to output SVG format for better quality
%config InlineBackend.figure_format = 'svg'
```
```python
from pygmrt.tiles import download_tiles
# Get tiles for La Réunion Island [west, south, east, north]
tiles = download_tiles(bbox=[55.05, -21.5, 55.95, -20.7], resolution="low")
# Print tiles
print(f"Downloaded tiles at: ./{tiles.name}")
print(f"CRS: {tiles.crs}")
print(f"Tiles array shape: {tiles.shape}")
```
Downloaded tiles at: ./geotiff/gmrt_low_55.050_-21.500_55.950_-20.700.tif
CRS: EPSG:4326
Tiles array shape: (783, 821)
## Example: La Réunion Island Relief
La Réunion Island is home to one of the world's most active volcanoes. Its dramatic topography makes an excellent demonstration of PyGMRT's capabilities combined with matplotlib's hillshading.
In this example, we download medium-resolution data and apply illumination effects to create a 3D relief map. We use [pycpt-city](https://github.com/leonard-seydoux/pycpt-city) for the color palette and [Cartopy](https://scitools.org.uk/cartopy/) to handle the geographic projection.
```python
import cartopy.crs as ccrs
import matplotlib.pyplot as plt
import numpy as np
import pycpt
from matplotlib.colors import LightSource
from pygmrt.tiles import download_tiles
# La Réunion bbox [west, south, east, north]
bbox = [55.05, -21.5, 55.95, -20.7]
# Download
tiles = download_tiles(bbox=bbox, resolution="medium")
# Remove NaNs and smooth a bit for better visualization
topo = tiles.read(1)
topo[np.isnan(topo)] = 0
vmax = abs(topo).max()
bbox = tiles.bounds
extent = (bbox.left, bbox.right, bbox.bottom, bbox.top)
palette = pycpt.read("wiki-france")
palette.interpolate(256)
# Create figure
fig = plt.figure(figsize=(7, 7))
ax = plt.axes(projection=ccrs.PlateCarree())
# Hillshade
sun = LightSource(azdeg=0, altdeg=20)
shade = sun.shade(
topo,
cmap=palette.cmap,
norm=palette.norm,
vert_exag=0.05,
blend_mode="soft",
)
ax.imshow(shade, extent=extent, origin="upper", transform=ccrs.PlateCarree())
# Extra map features
palette.colorbar(ax=ax, label="Elevation (m)", shrink=0.5)
ax.set_extent(extent)
gridlines = ax.gridlines(draw_labels=True, color="white")
gridlines.top_labels = False
gridlines.right_labels = False
ax.set_title("La Réunion Island with illumination")
plt.show()
```
## Example: Colombia Relief
Colombia offers a fascinating study in topographic diversity. From the Andes mountains to the Pacific and Caribbean coasts, and the Amazon basin in the southeast. This example shows how PyGMRT handles larger geographic areas.
We use low resolution here since we're covering a substantial area. The custom color palette works well for showing both underwater features and mountain ranges. Notice how the hillshading brings out the texture of the seafloor and the terrestrial topography.
```python
import cartopy.crs as ccrs
import matplotlib.pyplot as plt
import numpy as np
import pycpt
from cartopy import feature as cfeature
from matplotlib.colors import LightSource
from pygmrt.tiles import download_tiles
plt.style.use("matplotlibrc")
# Colombia bbox [west, south, east, north]
bbox = [-80.0, -5.0, -66.0, 13.0]
# Download
tiles = download_tiles(bbox=bbox, resolution="low")
# Remove NaNs and smooth a bit for better visualization
topo = tiles.read(1)
topo[np.isnan(topo)] = 0
vmax = abs(topo).max()
bbox = tiles.bounds
extent = (bbox.left, bbox.right, bbox.bottom, bbox.top)
palette = pycpt.read("colombia")
# Create figure
fig = plt.figure(figsize=(7, 7))
fig.patch.set_facecolor("#00000000")
ax = plt.axes(projection=ccrs.PlateCarree())
# Hillshade
sun = LightSource(azdeg=0, altdeg=60)
shade = sun.shade(
topo,
cmap=palette.cmap,
norm=palette.norm,
vert_exag=0.5,
blend_mode="soft",
)
ax.imshow(shade, extent=extent, origin="upper", transform=ccrs.PlateCarree())
# Extra map features
palette.colorbar(ax=ax, label="Elevation (m)", shrink=0.5)
ax.set_extent(extent)
ax.coastlines(color="k", linewidth=0.8)
ax.add_feature(cfeature.BORDERS, edgecolor="k", linewidth=0.8)
gridlines = ax.gridlines(draw_labels=True, color="white", alpha=0.3)
gridlines.top_labels = False
gridlines.right_labels = False
ax.set_title("Colombia relief")
plt.show()
```
## API Reference
The `download_tiles` function is the main entry point. Here's the complete documentation:
```python
help(download_tiles)
```
Help on function download_tiles in module pygmrt.tiles:
download_tiles(*, bbox: 'Sequence[float]' = None, save_directory: 'str | Path' = './geotiff', resolution: 'Resolution' = 'medium', overwrite: 'bool' = False) -> 'rasterio.DatasetReader'
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
To contribute or experiment with the code, start by cloning the repository:
```bash
git clone https://github.com/leonard-seydoux/pygmrt.git
cd pygmrt
# Install with UV (includes all development dependencies)
uv sync --all-extras
# Or use pip
pip install -e ".[dev,docs]"
```
Run the test suite to verify everything works:
```bash
# With UV
uv run pytest
# Or directly
pytest
```
This documentation is generated from `docs/readme.ipynb`. To rebuild it:
```bash
cd docs
make # Build logo and README
make logo # Generate logo only
make readme # Convert notebook to README
```
The build process handles image generation and ensures URLs point to GitHub for proper display on PyPI.
## Contributing
PyGMRT is open source and welcomes contributions! Found a bug or have an idea? Open an issue or submit a pull request on [GitHub](https://github.com/leonard-seydoux/pygmrt).
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## Acknowledgments
This package builds on the work of several organizations and projects:
- The [Global Multi-Resolution Topography Synthesis](https://www.gmrt.org/) by [Lamont-Doherty Earth Observatory](https://www.ldeo.columbia.edu/) for providing free access to global bathymetry data.
- The [cpt-city](http://seaviewsensing.com/pub/cpt-city/) project for beautiful color palettes, accessible via [pycpt-city](https://github.com/leonard-seydoux/pycpt-city).
Raw data
{
"_id": null,
"home_page": null,
"name": "pygmrt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Leonard Seydoux <leonard.seydoux@gmail.com>",
"keywords": "bathymetry, topography, gmrt, geospatial, oceanography",
"author": null,
"author_email": "Leonard Seydoux <leonard.seydoux@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/9b/fa/fa7a971952c9315312b779c9305a67b14adf263e28d846337e8cb84b5652/pygmrt-0.1.3.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n<img src=\"https://raw.githubusercontent.com/leonard-seydoux/pygmrt/main/docs/images/logo.png\" alt=\"PyGMRT Logo\" width=100/>\n\n### PyGMRT\n\nDownloading bathymetry and topography tiles from the<br>\n[Global Multi-Resolution Topography (GMRT)](https://www.gmrt.org/) synthesis.\n\n[](https://python.org)\n\n\n\n\n\n\n</div>\n\n## Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Example: La R\u00e9union Island Relief](#example-la-r\u00e9union-island-relief)\n- [Example: Colombia Relief](#example-colombia-relief)\n- [API Reference](#api-reference)\n- [Development](#development)\n- [Contributing](#contributing)\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n\n## Features\n\nPyGMRT provides a simple Python interface to access bathymetry and topography data from the [Global Multi-Resolution Topography](https://www.gmrt.org/) (GMRT) synthesis. The package handles all the complexity of downloading and processing geographic tiles, letting you focus on your analysis.\n\nThe core functionality centers around a single function that downloads tiles for any region on Earth. You can choose between three resolution levels: high resolution at 1 arc-second (about 30 meters at the equator), medium resolution at 4 arc-seconds, or low resolution at 16 arc-seconds. All data comes in GeoTIFF format, which works directly with [rasterio](https://rasterio.readthedocs.io/) and other geospatial tools.\n\nThe package automatically handles regions that cross the antimeridian (the 180\u00b0 longitude line). This is often painful when working with global data, but PyGMRT takes care of it transparently. Since the package connects directly to the GMRT GridServer, you don't need API keys or authentication.\n\n## Installation\n\nWe recommend using [UV](https://uv.readthedocs.io/), a modern Python package installer that handles dependencies efficiently. Traditional pip works just as well.\n\nIf you're using UV, add PyGMRT to your project:\n\n```bash\nuv add pygmrt\n```\n\nOr install from the latest development version:\n\n```bash\ngit clone https://github.com/leonard-seydoux/pygmrt.git\ncd pygmrt\nuv sync\n```\n\nFor pip users, install directly from PyPI:\n\n```bash\npip install pygmrt\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/leonard-seydoux/pygmrt.git\ncd pygmrt\npip install -e .\n```\n\n## Quick start\n\nThe simplest way to download topography data is with a single function call. Here we'll download data for La R\u00e9union Island, a volcanic island in the Indian Ocean. The bounding box is specified as `[west, south, east, north]` in degrees.\n\n\n```python\n# Configure matplotlib to output SVG format for better quality\n%config InlineBackend.figure_format = 'svg'\n```\n\n\n```python\nfrom pygmrt.tiles import download_tiles\n\n# Get tiles for La R\u00e9union Island [west, south, east, north]\ntiles = download_tiles(bbox=[55.05, -21.5, 55.95, -20.7], resolution=\"low\")\n\n# Print tiles\nprint(f\"Downloaded tiles at: ./{tiles.name}\")\nprint(f\"CRS: {tiles.crs}\")\nprint(f\"Tiles array shape: {tiles.shape}\")\n```\n\n Downloaded tiles at: ./geotiff/gmrt_low_55.050_-21.500_55.950_-20.700.tif\n CRS: EPSG:4326\n Tiles array shape: (783, 821)\n\n\n## Example: La R\u00e9union Island Relief\n\nLa R\u00e9union Island is home to one of the world's most active volcanoes. Its dramatic topography makes an excellent demonstration of PyGMRT's capabilities combined with matplotlib's hillshading.\n\nIn this example, we download medium-resolution data and apply illumination effects to create a 3D relief map. We use [pycpt-city](https://github.com/leonard-seydoux/pycpt-city) for the color palette and [Cartopy](https://scitools.org.uk/cartopy/) to handle the geographic projection.\n\n\n```python\nimport cartopy.crs as ccrs\nimport matplotlib.pyplot as plt\nimport numpy as np\nimport pycpt\nfrom matplotlib.colors import LightSource\nfrom pygmrt.tiles import download_tiles\n\n# La R\u00e9union bbox [west, south, east, north]\nbbox = [55.05, -21.5, 55.95, -20.7]\n\n# Download\ntiles = download_tiles(bbox=bbox, resolution=\"medium\")\n\n# Remove NaNs and smooth a bit for better visualization\ntopo = tiles.read(1)\ntopo[np.isnan(topo)] = 0\nvmax = abs(topo).max()\nbbox = tiles.bounds\nextent = (bbox.left, bbox.right, bbox.bottom, bbox.top)\npalette = pycpt.read(\"wiki-france\")\npalette.interpolate(256)\n\n# Create figure\nfig = plt.figure(figsize=(7, 7))\nax = plt.axes(projection=ccrs.PlateCarree())\n\n# Hillshade\nsun = LightSource(azdeg=0, altdeg=20)\nshade = sun.shade(\n topo,\n cmap=palette.cmap,\n norm=palette.norm,\n vert_exag=0.05,\n blend_mode=\"soft\",\n)\nax.imshow(shade, extent=extent, origin=\"upper\", transform=ccrs.PlateCarree())\n\n# Extra map features\npalette.colorbar(ax=ax, label=\"Elevation (m)\", shrink=0.5)\nax.set_extent(extent)\ngridlines = ax.gridlines(draw_labels=True, color=\"white\")\ngridlines.top_labels = False\ngridlines.right_labels = False\nax.set_title(\"La R\u00e9union Island with illumination\")\n\nplt.show()\n```\n\n\n \n\n \n\n\n## Example: Colombia Relief\n\nColombia offers a fascinating study in topographic diversity. From the Andes mountains to the Pacific and Caribbean coasts, and the Amazon basin in the southeast. This example shows how PyGMRT handles larger geographic areas.\n\nWe use low resolution here since we're covering a substantial area. The custom color palette works well for showing both underwater features and mountain ranges. Notice how the hillshading brings out the texture of the seafloor and the terrestrial topography.\n\n\n```python\nimport cartopy.crs as ccrs\nimport matplotlib.pyplot as plt\nimport numpy as np\nimport pycpt\nfrom cartopy import feature as cfeature\nfrom matplotlib.colors import LightSource\nfrom pygmrt.tiles import download_tiles\n\nplt.style.use(\"matplotlibrc\")\n\n# Colombia bbox [west, south, east, north]\nbbox = [-80.0, -5.0, -66.0, 13.0]\n\n# Download\ntiles = download_tiles(bbox=bbox, resolution=\"low\")\n\n# Remove NaNs and smooth a bit for better visualization\ntopo = tiles.read(1)\ntopo[np.isnan(topo)] = 0\nvmax = abs(topo).max()\nbbox = tiles.bounds\nextent = (bbox.left, bbox.right, bbox.bottom, bbox.top)\npalette = pycpt.read(\"colombia\")\n\n# Create figure\nfig = plt.figure(figsize=(7, 7))\nfig.patch.set_facecolor(\"#00000000\")\nax = plt.axes(projection=ccrs.PlateCarree())\n\n# Hillshade\nsun = LightSource(azdeg=0, altdeg=60)\nshade = sun.shade(\n topo,\n cmap=palette.cmap,\n norm=palette.norm,\n vert_exag=0.5,\n blend_mode=\"soft\",\n)\nax.imshow(shade, extent=extent, origin=\"upper\", transform=ccrs.PlateCarree())\n\n# Extra map features\npalette.colorbar(ax=ax, label=\"Elevation (m)\", shrink=0.5)\nax.set_extent(extent)\nax.coastlines(color=\"k\", linewidth=0.8)\nax.add_feature(cfeature.BORDERS, edgecolor=\"k\", linewidth=0.8)\ngridlines = ax.gridlines(draw_labels=True, color=\"white\", alpha=0.3)\ngridlines.top_labels = False\ngridlines.right_labels = False\nax.set_title(\"Colombia relief\")\n\nplt.show()\n```\n\n\n \n\n \n\n\n## API Reference\n\nThe `download_tiles` function is the main entry point. Here's the complete documentation:\n\n\n```python\nhelp(download_tiles)\n```\n\n Help on function download_tiles in module pygmrt.tiles:\n \n download_tiles(*, bbox: 'Sequence[float]' = None, save_directory: 'str | Path' = './geotiff', resolution: 'Resolution' = 'medium', overwrite: 'bool' = False) -> 'rasterio.DatasetReader'\n Download tiles and return the rasterio dataset.\n \n Parameters\n ----------\n bbox : sequence of float\n Bounding box in WGS84 degrees as ``[west, south, east, north]``.\n save_directory : str or pathlib.Path\n Destination directory path where files will be written. Created if\n needed.\n resolution : {\"low\", \"medium\", \"high\"}, default \"medium\"\n Named resolution level; mapped internally to provider-specific datasets.\n overwrite : bool, default False\n If ``False``, reuse existing files. If ``True``, force re-download.\n \n Returns\n -------\n rasterio.DatasetReader\n Opened rasterio dataset for the downloaded GeoTIFF. The caller is\n responsible for closing the dataset.\n \n Raises\n ------\n ValueError\n If invalid argument combinations or bbox values are provided.\n PermissionError\n If the destination directory is not writable.\n RuntimeError\n If download attempts ultimately fail.\n \n\n\n## Development\n\nTo contribute or experiment with the code, start by cloning the repository:\n\n```bash\ngit clone https://github.com/leonard-seydoux/pygmrt.git\ncd pygmrt\n\n# Install with UV (includes all development dependencies)\nuv sync --all-extras\n\n# Or use pip\npip install -e \".[dev,docs]\"\n```\n\nRun the test suite to verify everything works:\n\n```bash\n# With UV\nuv run pytest\n\n# Or directly\npytest\n```\n\nThis documentation is generated from `docs/readme.ipynb`. To rebuild it:\n\n```bash\ncd docs\nmake # Build logo and README\nmake logo # Generate logo only\nmake readme # Convert notebook to README\n```\n\nThe build process handles image generation and ensures URLs point to GitHub for proper display on PyPI.\n\n## Contributing\n\nPyGMRT is open source and welcomes contributions! Found a bug or have an idea? Open an issue or submit a pull request on [GitHub](https://github.com/leonard-seydoux/pygmrt).\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\nThis package builds on the work of several organizations and projects:\n\n- The [Global Multi-Resolution Topography Synthesis](https://www.gmrt.org/) by [Lamont-Doherty Earth Observatory](https://www.ldeo.columbia.edu/) for providing free access to global bathymetry data.\n- The [cpt-city](http://seaviewsensing.com/pub/cpt-city/) project for beautiful color palettes, accessible via [pycpt-city](https://github.com/leonard-seydoux/pycpt-city).\n",
"bugtrack_url": null,
"license": null,
"summary": "A minimal Python package for downloading bathymetry and topography tiles from GMRT",
"version": "0.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/leonard-seydoux/pygmrt/issues",
"Documentation": "https://leonard-seydoux.github.io/pygmrt",
"Homepage": "https://github.com/leonard-seydoux/pygmrt",
"Repository": "https://github.com/leonard-seydoux/pygmrt.git"
},
"split_keywords": [
"bathymetry",
" topography",
" gmrt",
" geospatial",
" oceanography"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4b0da8508aa05d4d230e5fcaa6f68e55c2d853b608a297cf85b1f8a7c010c1c3",
"md5": "3466487c8c145d8c150e43289ac916f9",
"sha256": "628c4cf6793d71b14cf2b140ee7f10011bd2e6d7141f8d8cba9022e2dd81727d"
},
"downloads": -1,
"filename": "pygmrt-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3466487c8c145d8c150e43289ac916f9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 10966,
"upload_time": "2025-11-01T12:30:52",
"upload_time_iso_8601": "2025-11-01T12:30:52.167063Z",
"url": "https://files.pythonhosted.org/packages/4b/0d/a8508aa05d4d230e5fcaa6f68e55c2d853b608a297cf85b1f8a7c010c1c3/pygmrt-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9bfafa7a971952c9315312b779c9305a67b14adf263e28d846337e8cb84b5652",
"md5": "6391056995be893e507ef849f914477d",
"sha256": "015d28bb19d76b63a745311e0370d1fef96c6dd87565d58055a2e821e1e913dd"
},
"downloads": -1,
"filename": "pygmrt-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "6391056995be893e507ef849f914477d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 16329,
"upload_time": "2025-11-01T12:30:53",
"upload_time_iso_8601": "2025-11-01T12:30:53.295427Z",
"url": "https://files.pythonhosted.org/packages/9b/fa/fa7a971952c9315312b779c9305a67b14adf263e28d846337e8cb84b5652/pygmrt-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-01 12:30:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "leonard-seydoux",
"github_project": "pygmrt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pygmrt"
}
