From 855e6b6b47765df11b5343b069a3e09c40e64e9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Thu, 30 Jul 2026 23:38:25 +0200 Subject: [PATCH 01/28] Reorganize section overview --- doc/overview.md | 43 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 38 insertions(+), 5 deletions(-) diff --git a/doc/overview.md b/doc/overview.md index 72fa5c9538c..f3dda202ff8 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -1,6 +1,25 @@ -# Overview +# Why PyGMT -## About +```{include} ../README.md +:start-after: +:end-before: +``` + +Afterward, try the [Intro to PyGMT](intro/index.rst) on your own, visit the +[Gallery](gallery/index.rst) for more impressions, go through the +[Tutorials](tutorials/index.rst) to learn things in more detail, look at the +available map [Projections](projections/index.rst), and finally do not forget +to check out some [external PyGMT examples](external_resources)! + + +## Project goals + +```{include} ../README.md +:start-after: +:end-before: +``` + +## Background PyGMT is a Python wrapper for the [Generic Mapping Tools (GMT)](https://github.com/GenericMappingTools/gmt), @@ -20,10 +39,24 @@ PDF and PNG. The project was started in 2017 by [Leonardo Uieda](https://www.leouieda.com) and [Paul Wessel](https://en.wikipedia.org/wiki/Pål_Wessel) (the co-creator and main -developer of GMT) at the University of Hawaiʻi at Mānoa. The development of PyGMT -has been supported by NSF grants [OCE-1558403](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1558403) -and [EAR-1948602](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1948602). +developer of GMT) at the University of Hawaiʻi at Mānoa. We welcome any feedback and ideas! Let us know by submitting [issues on GitHub](https://github.com/GenericMappingTools/pygmt/issues) or by posting on our [Discourse forum](https://forum.generic-mapping-tools.org/c/questions/pygmt-q-a). + + +## Support + +```{include} ../README.md +:start-after: +:end-before: +``` + + +## Related projects + +```{include} ../README.md +:start-after: +:end-before: +``` From 90b0a9318d588163a3ee44c0e53f125681905a62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Mon, 3 Aug 2026 10:35:31 +0200 Subject: [PATCH 02/28] Add 'project goals' to docs --- doc/overview.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/overview.md b/doc/overview.md index f3dda202ff8..9b7cf34ba33 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -14,10 +14,13 @@ to check out some [external PyGMT examples](external_resources)! ## Project goals -```{include} ../README.md -:start-after: -:end-before: -``` +- Make GMT more accessible to new users. +- Build a Pythonic API for GMT. +- Interface with the GMT C API directly using ctypes (no system calls). +- Support for rich display in the Jupyter notebook. +- Integration with the [scientific Python ecosystem](https://scientific-python.org/): + `numpy.ndarray` or `pandas.DataFrame` for data tables, `xarray.DataArray` for grids, + and `geopandas.GeoDataFrame` for geographical data. ## Background From daaee72fe7be5751644bdfab6ad921c33b29fe18 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Mon, 3 Aug 2026 10:37:04 +0200 Subject: [PATCH 03/28] Add 'Support' to docs and rename to 'Funding' --- doc/overview.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/doc/overview.md b/doc/overview.md index 9b7cf34ba33..6939fb9f722 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -48,14 +48,11 @@ We welcome any feedback and ideas! Let us know by submitting [issues on GitHub](https://github.com/GenericMappingTools/pygmt/issues) or by posting on our [Discourse forum](https://forum.generic-mapping-tools.org/c/questions/pygmt-q-a). +## Funding -## Support - -```{include} ../README.md -:start-after: -:end-before: -``` - +The development of PyGMT has been supported by NSF grants +[OCE-1558403](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1558403) and +[EAR-1948602](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1948602). ## Related projects From c3c6e006b469bb431ded4df038b7496fa1826da2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Mon, 3 Aug 2026 10:38:01 +0200 Subject: [PATCH 04/28] Add 'Related projects' to docs --- doc/overview.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/overview.md b/doc/overview.md index 6939fb9f722..95d8337ac03 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -56,7 +56,7 @@ The development of PyGMT has been supported by NSF grants ## Related projects -```{include} ../README.md -:start-after: -:end-before: -``` +Other official wrappers for GMT: + +- [GMT.jl](https://github.com/GenericMappingTools/GMT.jl): A Julia wrapper for GMT. +- [gmtmex](https://github.com/GenericMappingTools/gmtmex): A Matlab/Octave wrapper for GMT. From a84ecb49ccee070051fe2ab2a825f5884cdd4122 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Mon, 3 Aug 2026 10:38:45 +0200 Subject: [PATCH 05/28] Switch order of 'Funding' and 'Related projects' --- doc/overview.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/overview.md b/doc/overview.md index 95d8337ac03..00076ddb138 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -48,15 +48,15 @@ We welcome any feedback and ideas! Let us know by submitting [issues on GitHub](https://github.com/GenericMappingTools/pygmt/issues) or by posting on our [Discourse forum](https://forum.generic-mapping-tools.org/c/questions/pygmt-q-a). -## Funding - -The development of PyGMT has been supported by NSF grants -[OCE-1558403](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1558403) and -[EAR-1948602](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1948602). - ## Related projects Other official wrappers for GMT: - [GMT.jl](https://github.com/GenericMappingTools/GMT.jl): A Julia wrapper for GMT. - [gmtmex](https://github.com/GenericMappingTools/gmtmex): A Matlab/Octave wrapper for GMT. + +## Funding + +The development of PyGMT has been supported by NSF grants +[OCE-1558403](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1558403) and +[EAR-1948602](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1948602). From 0ecc2123cecd70ea4534ca67fe97dcf68856e3a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Mon, 3 Aug 2026 10:48:14 +0200 Subject: [PATCH 06/28] Remove 'funding', 'related projects', and 'min versions' content from README and add links to docs --- README.md | 26 +++----------------------- 1 file changed, 3 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index a2673667a20..12a9281f8e2 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,10 @@ For other ways to install PyGMT and more examples, please visit the ## Documentation +- [Minimum Supported Versions](https://www.pygmt.org/dev/minversions.html) - [Citing PyGMT](https://www.pygmt.org/dev/citing.html) +- [Related Projects](https://www.pygmt.org/dev/overview.html#related-projects) +- [Funding](https://www.pygmt.org/dev/overview.html#funding) ## Contacting us @@ -122,26 +125,3 @@ to see how you can help and give feedback. PyGMT is free software: you can redistribute it and/or modify it under the terms of the **BSD 3-clause License**. A copy of this license is provided in [LICENSE.txt](https://github.com/GenericMappingTools/pygmt/blob/main/LICENSE.txt). - -## Support - -The development of PyGMT has been supported by NSF grants -[OCE-1558403](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1558403) and -[EAR-1948602](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1948602). - -## Related projects - -Other official wrappers for GMT: - -- [GMT.jl](https://github.com/GenericMappingTools/GMT.jl): A Julia wrapper for GMT. -- [gmtmex](https://github.com/GenericMappingTools/gmtmex): A Matlab/Octave wrapper for GMT. - - - -## Minimum supported versions - -PyGMT has adopted [SPEC 0](https://scientific-python.org/specs/spec-0000/) alongside the -rest of the scientific Python ecosystem, and made a few extensions based on the needs of -the project. Please see [Minimum Supported Versions](https://www.pygmt.org/dev/minversions.html) -for the detailed policy and the minimum supported versions of GMT, Python and core -package dependencies. From ac59bd9b168ea8132d321f919a7a4636a3f304d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Mon, 3 Aug 2026 11:01:22 +0200 Subject: [PATCH 07/28] Restructure 'Why PyGMT' and 'About' sections in README and docs --- README.md | 26 ++++---------------------- doc/overview.md | 8 +++----- 2 files changed, 7 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 12a9281f8e2..f26ecb07209 100644 --- a/README.md +++ b/README.md @@ -20,36 +20,17 @@ [![GitHub Actions GMT Dev Tests status](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests_dev.yaml/badge.svg)](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests_dev.yaml) [![Test coverage status](https://codecov.io/gh/GenericMappingTools/pygmt/graph/badge.svg?token=78Fu4EWstx)](https://app.codecov.io/gh/GenericMappingTools/pygmt) - ## Why PyGMT? -A beautiful map is worth a thousand words. To truly understand how powerful PyGMT is, -play with it online on [Binder](https://github.com/GenericMappingTools/try-gmt)! For a -quicker introduction, check out our [3 minute overview](https://youtu.be/4iPnITXrxVU)! - -Afterwards, feel free to look at our [Tutorials](https://www.pygmt.org/latest/tutorials), -visit the [Gallery](https://www.pygmt.org/latest/gallery), and check out some -[external PyGMT examples](https://www.pygmt.org/latest/external_resources.html)! - -[![Quick Introduction to PyGMT YouTube Video](https://raw.githubusercontent.com/GenericMappingTools/pygmt/refs/heads/main/doc/_static/scipy2022-youtube-thumbnail.jpg)](https://www.youtube.com/watch?v=4iPnITXrxVU) - -## About - PyGMT is a library for processing geospatial and geophysical data and making publication-quality maps and figures. It provides a Pythonic interface for the [Generic Mapping Tools (GMT)](https://github.com/GenericMappingTools/gmt), a command-line program widely used across the Earth, Ocean, and Planetary sciences and beyond. -## Project goals - -- Make GMT more accessible to new users. -- Build a Pythonic API for GMT. -- Interface with the GMT C API directly using ctypes (no system calls). -- Support for rich display in the Jupyter notebook. -- Integration with the [scientific Python ecosystem](https://scientific-python.org/): - `numpy.ndarray` or `pandas.DataFrame` for data tables, `xarray.DataArray` for grids, - and `geopandas.GeoDataFrame` for geographical data. +A beautiful map is worth a thousand words. To truly understand how powerful PyGMT is, +play with it online on [Binder](https://github.com/GenericMappingTools/try-gmt)! For a +quicker introduction, check out our [3 minute overview](https://youtu.be/4iPnITXrxVU)! ## Quickstart @@ -77,6 +58,7 @@ For other ways to install PyGMT and more examples, please visit the ## Documentation +- [Gallery](https://www.pygmt.org/latest/gallery/index.html) and [Tutorials](https://www.pygmt.org/latest/tutorials/index.html) - [Minimum Supported Versions](https://www.pygmt.org/dev/minversions.html) - [Citing PyGMT](https://www.pygmt.org/dev/citing.html) - [Related Projects](https://www.pygmt.org/dev/overview.html#related-projects) diff --git a/doc/overview.md b/doc/overview.md index 00076ddb138..2647ae57dff 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -1,9 +1,8 @@ # Why PyGMT -```{include} ../README.md -:start-after: -:end-before: -``` +A beautiful map is worth a thousand words. To truly understand how powerful PyGMT is, +play with it online on [Binder](https://github.com/GenericMappingTools/try-gmt)! For a +quicker introduction, check out our [3 minute overview](https://youtu.be/4iPnITXrxVU)! Afterward, try the [Intro to PyGMT](intro/index.rst) on your own, visit the [Gallery](gallery/index.rst) for more impressions, go through the @@ -11,7 +10,6 @@ Afterward, try the [Intro to PyGMT](intro/index.rst) on your own, visit the available map [Projections](projections/index.rst), and finally do not forget to check out some [external PyGMT examples](external_resources)! - ## Project goals - Make GMT more accessible to new users. From 6f896e3fa01c6bec1038784c0c7006fc17812fca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Mon, 3 Aug 2026 11:05:00 +0200 Subject: [PATCH 08/28] Remove links at the beginning of the README and try line breaksfor badges --- README.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index f26ecb07209..5debcb7fbe3 100644 --- a/README.md +++ b/README.md @@ -5,17 +5,13 @@ # A Python interface for the [Generic Mapping Tools](https://www.generic-mapping-tools.org/) -[Documentation (development version)](https://www.pygmt.org/dev) | [Contact](https://forum.generic-mapping-tools.org) | [TryOnline](https://github.com/GenericMappingTools/try-gmt) - [![GitHub Release](https://img.shields.io/github/v/release/GenericMappingTools/pygmt?color=1f77b4)](https://github.com/GenericMappingTools/pygmt/releases) [![Latest version on PyPI](https://img.shields.io/pypi/v/pygmt?color=1f77b4)](https://pypi.org/project/pygmt) [![Latest version on conda-forge](https://img.shields.io/conda/v/conda-forge/pygmt?color=1f77b4)](https://anaconda.org/conda-forge/pygmt) -[![PyPI Python Version](https://img.shields.io/pypi/pyversions/pygmt?color=1f77b4)](https://pypi.org/project/pygmt) - +[![PyPI Python Version](https://img.shields.io/pypi/pyversions/pygmt?color=1f77b4)](https://pypi.org/project/pygmt)
[![PyGMT paper](https://img.shields.io/badge/G3%20Paper%20DOI-10.1029/2026GC013105-2ca02c)](https://doi.org/10.1029/2026GC013105) [![Digital Object Identifier for the Zenodo archive](https://img.shields.io/badge/Zenodo%20DOI-10.5281/zenodo.3781524-2ca02c)](https://doi.org/10.5281/zenodo.3781524) -[![GitHub license](https://img.shields.io/github/license/GenericMappingTools/pygmt?color=2ca02c)](https://github.com/GenericMappingTools/pygmt/blob/main/LICENSE.txt) - +[![GitHub license](https://img.shields.io/github/license/GenericMappingTools/pygmt?color=2ca02c)](https://github.com/GenericMappingTools/pygmt/blob/main/LICENSE.txt)
[![GitHub Actions Tests status](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests.yaml/badge.svg)](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests.yaml) [![GitHub Actions GMT Dev Tests status](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests_dev.yaml/badge.svg)](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests_dev.yaml) [![Test coverage status](https://codecov.io/gh/GenericMappingTools/pygmt/graph/badge.svg?token=78Fu4EWstx)](https://app.codecov.io/gh/GenericMappingTools/pygmt) From d56b23de706ad5dc690eff8dbf56011d8dc4dea6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Mon, 3 Aug 2026 11:40:04 +0200 Subject: [PATCH 09/28] Directly add intro text on landing page, use RST to inserte PyGMT logo --- doc/index.md | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/doc/index.md b/doc/index.md index 0454257fa8b..6b85fc3a25c 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,20 +1,30 @@ + + ```{title} Home ``` - - -```{include} ../README.md -:start-after: -:end-before: -:relative-images: + + +:::{div} sd-d-flex-row sd-align-major-center +```{image} ./_static/pygmtlogo.png +:width: 600px ``` +::: + + +:::{div} sd-text-center sd-fs-3 sd-pt-3 sd-pb-3 +A Python interface for the [Generic Mapping Tools](https://www.generic-mapping-tools.org/) +::: + +:::{div} sd-text-center sd-fs-5 sd-pb-3 +PyGMT is a library for processing geospatial and geophysical data and making +publication-quality maps and figures. It provides a Pythonic interface for the +[Generic Mapping Tools (GMT)](https://github.com/GenericMappingTools/gmt), a command-line +program widely used across the Earth, Ocean, and Planetary sciences and beyond. +::: + + ```{toctree} :maxdepth: 2 :hidden: From 2b28bd2cfcf6b54fd6229d6a11e94f7e29c24fe6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Tue, 4 Aug 2026 10:55:45 +0200 Subject: [PATCH 10/28] Add 'Related projects' and 'Funding' back to README --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index 5debcb7fbe3..8e48a685f72 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,19 @@ to see how you can help and give feedback. *This disclaimer was adapted from the* [MetPy project](https://github.com/Unidata/MetPy). +## Related projects + +Other official wrappers for GMT: + +- [GMT.jl](https://github.com/GenericMappingTools/GMT.jl): A Julia wrapper for GMT. +- [gmtmex](https://github.com/GenericMappingTools/gmtmex): A Matlab/Octave wrapper for GMT. + +## Funding + +The development of PyGMT has been supported by NSF grants +[OCE-1558403](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1558403) and +[EAR-1948602](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1948602). + ## License PyGMT is free software: you can redistribute it and/or modify it under the terms of the From 11a2f41632361eb012b0f0c6410f2c1df0762fab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Thu, 6 Aug 2026 22:06:15 +0200 Subject: [PATCH 11/28] Remove changes in index.md --- doc/index.md | 34 ++++++++++++---------------------- 1 file changed, 12 insertions(+), 22 deletions(-) diff --git a/doc/index.md b/doc/index.md index 6b85fc3a25c..0454257fa8b 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,29 +1,19 @@ - - ```{title} Home ``` - - -:::{div} sd-d-flex-row sd-align-major-center -```{image} ./_static/pygmtlogo.png -:width: 600px -``` - -::: - - -:::{div} sd-text-center sd-fs-3 sd-pt-3 sd-pb-3 -A Python interface for the [Generic Mapping Tools](https://www.generic-mapping-tools.org/) -::: - -:::{div} sd-text-center sd-fs-5 sd-pb-3 -PyGMT is a library for processing geospatial and geophysical data and making -publication-quality maps and figures. It provides a Pythonic interface for the -[Generic Mapping Tools (GMT)](https://github.com/GenericMappingTools/gmt), a command-line -program widely used across the Earth, Ocean, and Planetary sciences and beyond. -::: + +```{include} ../README.md +:start-after: +:end-before: +:relative-images: +``` ```{toctree} :maxdepth: 2 From eb3d3affe087612460fae01dc15378df16061a34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Thu, 6 Aug 2026 22:08:40 +0200 Subject: [PATCH 12/28] Change subsection'Why PyGMT' to 'Overview' --- doc/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/overview.md b/doc/overview.md index 2647ae57dff..a65ed63d63c 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -1,4 +1,4 @@ -# Why PyGMT +# Overview A beautiful map is worth a thousand words. To truly understand how powerful PyGMT is, play with it online on [Binder](https://github.com/GenericMappingTools/try-gmt)! For a From 495ca7da1884e8c4d3d3d5943ecd982f54433787 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Thu, 6 Aug 2026 22:11:24 +0200 Subject: [PATCH 13/28] Add subsubsection 'License' --- doc/overview.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/overview.md b/doc/overview.md index a65ed63d63c..29e182044a1 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -58,3 +58,9 @@ Other official wrappers for GMT: The development of PyGMT has been supported by NSF grants [OCE-1558403](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1558403) and [EAR-1948602](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1948602). + +## License + +PyGMT is free software: you can redistribute it and/or modify it under the terms of the +BSD 3-clause License. A copy of this license is provided in +[LICENSE.txt](https://github.com/GenericMappingTools/pygmt/blob/main/LICENSE.txt). From f348d8b4a4182d2315621d8cad722783a19931ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Thu, 6 Aug 2026 22:16:53 +0200 Subject: [PATCH 14/28] Add 'Why PyGMT' as subsubsection --- doc/overview.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/overview.md b/doc/overview.md index 29e182044a1..93343452f5d 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -1,5 +1,7 @@ # Overview +## Why PyGMT + A beautiful map is worth a thousand words. To truly understand how powerful PyGMT is, play with it online on [Binder](https://github.com/GenericMappingTools/try-gmt)! For a quicker introduction, check out our [3 minute overview](https://youtu.be/4iPnITXrxVU)! From 20b17b5cd16ea0d6347beef0e75478b5a5d2cdda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Thu, 6 Aug 2026 22:29:12 +0200 Subject: [PATCH 15/28] Exclude changes in README --- README.md | 59 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 43 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 8e48a685f72..a3f17cf59a4 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ # A Python interface for the [Generic Mapping Tools](https://www.generic-mapping-tools.org/) +[Documentation (development version)](https://www.pygmt.org/dev) | [Contact](https://forum.generic-mapping-tools.org) | [TryOnline](https://github.com/GenericMappingTools/try-gmt) + [![GitHub Release](https://img.shields.io/github/v/release/GenericMappingTools/pygmt?color=1f77b4)](https://github.com/GenericMappingTools/pygmt/releases) [![Latest version on PyPI](https://img.shields.io/pypi/v/pygmt?color=1f77b4)](https://pypi.org/project/pygmt) [![Latest version on conda-forge](https://img.shields.io/conda/v/conda-forge/pygmt?color=1f77b4)](https://anaconda.org/conda-forge/pygmt) @@ -16,17 +18,36 @@ [![GitHub Actions GMT Dev Tests status](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests_dev.yaml/badge.svg)](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests_dev.yaml) [![Test coverage status](https://codecov.io/gh/GenericMappingTools/pygmt/graph/badge.svg?token=78Fu4EWstx)](https://app.codecov.io/gh/GenericMappingTools/pygmt) + ## Why PyGMT? +A beautiful map is worth a thousand words. To truly understand how powerful PyGMT is, +play with it online on [Binder](https://github.com/GenericMappingTools/try-gmt)! For a +quicker introduction, check out our [3 minute overview](https://youtu.be/4iPnITXrxVU)! + +Afterwards, feel free to look at our [Tutorials](https://www.pygmt.org/latest/tutorials), +visit the [Gallery](https://www.pygmt.org/latest/gallery), and check out some +[external PyGMT examples](https://www.pygmt.org/latest/external_resources.html)! + +[![Quick Introduction to PyGMT YouTube Video](https://raw.githubusercontent.com/GenericMappingTools/pygmt/refs/heads/main/doc/_static/scipy2022-youtube-thumbnail.jpg)](https://www.youtube.com/watch?v=4iPnITXrxVU) + +## About + PyGMT is a library for processing geospatial and geophysical data and making publication-quality maps and figures. It provides a Pythonic interface for the [Generic Mapping Tools (GMT)](https://github.com/GenericMappingTools/gmt), a command-line program widely used across the Earth, Ocean, and Planetary sciences and beyond. -A beautiful map is worth a thousand words. To truly understand how powerful PyGMT is, -play with it online on [Binder](https://github.com/GenericMappingTools/try-gmt)! For a -quicker introduction, check out our [3 minute overview](https://youtu.be/4iPnITXrxVU)! +## Project goals + +- Make GMT more accessible to new users. +- Build a Pythonic API for GMT. +- Interface with the GMT C API directly using ctypes (no system calls). +- Support for rich display in the Jupyter notebook. +- Integration with the [scientific Python ecosystem](https://scientific-python.org/): + `numpy.ndarray` or `pandas.DataFrame` for data tables, `xarray.DataArray` for grids, + and `geopandas.GeoDataFrame` for geographical data. ## Quickstart @@ -54,11 +75,7 @@ For other ways to install PyGMT and more examples, please visit the ## Documentation -- [Gallery](https://www.pygmt.org/latest/gallery/index.html) and [Tutorials](https://www.pygmt.org/latest/tutorials/index.html) -- [Minimum Supported Versions](https://www.pygmt.org/dev/minversions.html) - [Citing PyGMT](https://www.pygmt.org/dev/citing.html) -- [Related Projects](https://www.pygmt.org/dev/overview.html#related-projects) -- [Funding](https://www.pygmt.org/dev/overview.html#funding) ## Contacting us @@ -98,6 +115,18 @@ to see how you can help and give feedback. *This disclaimer was adapted from the* [MetPy project](https://github.com/Unidata/MetPy). +## License + +PyGMT is free software: you can redistribute it and/or modify it under the terms of the +**BSD 3-clause License**. A copy of this license is provided in +[LICENSE.txt](https://github.com/GenericMappingTools/pygmt/blob/main/LICENSE.txt). + +## Support + +The development of PyGMT has been supported by NSF grants +[OCE-1558403](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1558403) and +[EAR-1948602](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1948602). + ## Related projects Other official wrappers for GMT: @@ -105,14 +134,12 @@ Other official wrappers for GMT: - [GMT.jl](https://github.com/GenericMappingTools/GMT.jl): A Julia wrapper for GMT. - [gmtmex](https://github.com/GenericMappingTools/gmtmex): A Matlab/Octave wrapper for GMT. -## Funding + -The development of PyGMT has been supported by NSF grants -[OCE-1558403](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1558403) and -[EAR-1948602](https://www.nsf.gov/awardsearch/show-award/?AWD_ID=1948602). - -## License +## Minimum supported versions -PyGMT is free software: you can redistribute it and/or modify it under the terms of the -**BSD 3-clause License**. A copy of this license is provided in -[LICENSE.txt](https://github.com/GenericMappingTools/pygmt/blob/main/LICENSE.txt). +PyGMT has adopted [SPEC 0](https://scientific-python.org/specs/spec-0000/) alongside the +rest of the scientific Python ecosystem, and made a few extensions based on the needs of +the project. Please see [Minimum Supported Versions](https://www.pygmt.org/dev/minversions.html) +for the detailed policy and the minimum supported versions of GMT, Python and core +package dependencies. From d7bf6254f714e56104b81896095c2edf2a72b4c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= <94163266+yvonnefroehlich@users.noreply.github.com> Date: Fri, 7 Aug 2026 14:19:40 +0200 Subject: [PATCH 16/28] Improve formulation Co-authored-by: Dongdong Tian --- doc/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/overview.md b/doc/overview.md index 93343452f5d..911247720e9 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -50,7 +50,7 @@ our [Discourse forum](https://forum.generic-mapping-tools.org/c/questions/pygmt- ## Related projects -Other official wrappers for GMT: +Other official GMT wrappers include: - [GMT.jl](https://github.com/GenericMappingTools/GMT.jl): A Julia wrapper for GMT. - [gmtmex](https://github.com/GenericMappingTools/gmtmex): A Matlab/Octave wrapper for GMT. From fa9bc8aa54042bcce9aa45a2cb9cfe229f45e942 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Fri, 7 Aug 2026 15:05:31 +0200 Subject: [PATCH 17/28] Move 'Project goals' after 'Background' --- doc/overview.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/overview.md b/doc/overview.md index 911247720e9..eb2fdc63175 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -12,16 +12,6 @@ Afterward, try the [Intro to PyGMT](intro/index.rst) on your own, visit the available map [Projections](projections/index.rst), and finally do not forget to check out some [external PyGMT examples](external_resources)! -## Project goals - -- Make GMT more accessible to new users. -- Build a Pythonic API for GMT. -- Interface with the GMT C API directly using ctypes (no system calls). -- Support for rich display in the Jupyter notebook. -- Integration with the [scientific Python ecosystem](https://scientific-python.org/): - `numpy.ndarray` or `pandas.DataFrame` for data tables, `xarray.DataArray` for grids, - and `geopandas.GeoDataFrame` for geographical data. - ## Background PyGMT is a Python wrapper for the @@ -48,6 +38,16 @@ We welcome any feedback and ideas! Let us know by submitting [issues on GitHub](https://github.com/GenericMappingTools/pygmt/issues) or by posting on our [Discourse forum](https://forum.generic-mapping-tools.org/c/questions/pygmt-q-a). +## Project goals + +- Make GMT more accessible to new users. +- Build a Pythonic API for GMT. +- Interface with the GMT C API directly using ctypes (no system calls). +- Support for rich display in the Jupyter notebook. +- Integration with the [scientific Python ecosystem](https://scientific-python.org/): + `numpy.ndarray` or `pandas.DataFrame` for data tables, `xarray.DataArray` for grids, + and `geopandas.GeoDataFrame` for geographical data. + ## Related projects Other official GMT wrappers include: From 60e3c3d4f21be3c6b249f5f96a4abb0120ef624c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Fri, 7 Aug 2026 17:23:35 +0200 Subject: [PATCH 18/28] Add intro sentence to 'Project goals' --- doc/overview.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/overview.md b/doc/overview.md index eb2fdc63175..0b5290ac136 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -40,6 +40,8 @@ our [Discourse forum](https://forum.generic-mapping-tools.org/c/questions/pygmt- ## Project goals +From the beginning, the project has aimed to achieve the following goals: + - Make GMT more accessible to new users. - Build a Pythonic API for GMT. - Interface with the GMT C API directly using ctypes (no system calls). From e440e68673ed7b815df108cfa358be4de0b296d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Fri, 7 Aug 2026 17:46:50 +0200 Subject: [PATCH 19/28] Add content on currently status of the project --- doc/overview.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/overview.md b/doc/overview.md index 0b5290ac136..10717bb4632 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -31,8 +31,11 @@ contact with the original PostScript files and get only the more convenient form PDF and PNG. The project was started in 2017 by [Leonardo Uieda](https://www.leouieda.com) and -[Paul Wessel](https://en.wikipedia.org/wiki/Pål_Wessel) (the co-creator and main -developer of GMT) at the University of Hawaiʻi at Mānoa. +[Paul Wessel](https://en.wikipedia.org/wiki/Pål_Wessel) (the co-creator and main developer +of GMT) at the University of Hawaiʻi at Mānoa. Currently the project is maintained by an +[international team](../team) with contributions from +[multiple contributors](https://github.com/GenericMappingTools/pygmt/graphs/contributors) +(see also [AUTHORS.md](https://github.com/GenericMappingTools/pygmt/blob/main/AUTHORS.md)). We welcome any feedback and ideas! Let us know by submitting [issues on GitHub](https://github.com/GenericMappingTools/pygmt/issues) or by posting on From b6b7a1e553b523c56ea9be7874dfd82c8f506232 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= <94163266+yvonnefroehlich@users.noreply.github.com> Date: Sat, 8 Aug 2026 11:18:15 +0200 Subject: [PATCH 20/28] Remove '../' from link Co-authored-by: Dongdong Tian --- doc/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/overview.md b/doc/overview.md index 10717bb4632..252f20fd0c9 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -33,7 +33,7 @@ PDF and PNG. The project was started in 2017 by [Leonardo Uieda](https://www.leouieda.com) and [Paul Wessel](https://en.wikipedia.org/wiki/Pål_Wessel) (the co-creator and main developer of GMT) at the University of Hawaiʻi at Mānoa. Currently the project is maintained by an -[international team](../team) with contributions from +[international team](team.md) with contributions from [multiple contributors](https://github.com/GenericMappingTools/pygmt/graphs/contributors) (see also [AUTHORS.md](https://github.com/GenericMappingTools/pygmt/blob/main/AUTHORS.md)). From 4ef630dfe52825fec8d542cf7cefd3eed61e1860 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= <94163266+yvonnefroehlich@users.noreply.github.com> Date: Sat, 8 Aug 2026 11:20:53 +0200 Subject: [PATCH 21/28] Make grammar more consistent in list of project goals Co-authored-by: Dongdong Tian --- doc/overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/overview.md b/doc/overview.md index 252f20fd0c9..af08d3b6053 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -48,8 +48,8 @@ From the beginning, the project has aimed to achieve the following goals: - Make GMT more accessible to new users. - Build a Pythonic API for GMT. - Interface with the GMT C API directly using ctypes (no system calls). -- Support for rich display in the Jupyter notebook. -- Integration with the [scientific Python ecosystem](https://scientific-python.org/): +- Support rich display in the Jupyter notebook. +- Integrate with the [scientific Python ecosystem](https://scientific-python.org/): `numpy.ndarray` or `pandas.DataFrame` for data tables, `xarray.DataArray` for grids, and `geopandas.GeoDataFrame` for geographical data. From 30729b1637d07448311e8f038e738946110fed57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= <94163266+yvonnefroehlich@users.noreply.github.com> Date: Sat, 8 Aug 2026 11:21:35 +0200 Subject: [PATCH 22/28] Remove link to AUTHORS.md Co-authored-by: Dongdong Tian --- doc/overview.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/overview.md b/doc/overview.md index af08d3b6053..5b783b9ca28 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -34,8 +34,7 @@ The project was started in 2017 by [Leonardo Uieda](https://www.leouieda.com) an [Paul Wessel](https://en.wikipedia.org/wiki/Pål_Wessel) (the co-creator and main developer of GMT) at the University of Hawaiʻi at Mānoa. Currently the project is maintained by an [international team](team.md) with contributions from -[multiple contributors](https://github.com/GenericMappingTools/pygmt/graphs/contributors) -(see also [AUTHORS.md](https://github.com/GenericMappingTools/pygmt/blob/main/AUTHORS.md)). +[multiple contributors](https://github.com/GenericMappingTools/pygmt/graphs/contributors). We welcome any feedback and ideas! Let us know by submitting [issues on GitHub](https://github.com/GenericMappingTools/pygmt/issues) or by posting on From e62ea00a236fe0cc354c61dcc628e7106563bba2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= <94163266+yvonnefroehlich@users.noreply.github.com> Date: Sat, 8 Aug 2026 11:22:45 +0200 Subject: [PATCH 23/28] Polish formulations in subsection 'Why PyGMT' Co-authored-by: Dongdong Tian --- doc/overview.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/overview.md b/doc/overview.md index 5b783b9ca28..b235eff9706 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -2,15 +2,15 @@ ## Why PyGMT -A beautiful map is worth a thousand words. To truly understand how powerful PyGMT is, -play with it online on [Binder](https://github.com/GenericMappingTools/try-gmt)! For a -quicker introduction, check out our [3 minute overview](https://youtu.be/4iPnITXrxVU)! - -Afterward, try the [Intro to PyGMT](intro/index.rst) on your own, visit the -[Gallery](gallery/index.rst) for more impressions, go through the -[Tutorials](tutorials/index.rst) to learn things in more detail, look at the -available map [Projections](projections/index.rst), and finally do not forget -to check out some [external PyGMT examples](external_resources)! +A beautiful map is worth a thousand words. To experience the power of PyGMT, try it +online with [Binder or Google Colab](https://github.com/GenericMappingTools/try-gmt) +without installing anything on your computer. + +For a quick introduction, check out our [3-minute overview](https://youtu.be/4iPnITXrxVU). +Afterward, try the [Intro to PyGMT](intro/index.rst) tutorial on your own, explore the +[Gallery](gallery/index.rst) for inspiration, follow the [Tutorials](tutorials/index.rst) +to learn more, explore available map [Projections](projections/index.rst), and finally +check out some [external PyGMT examples](external_resources). ## Background From feec799b0d8b37f9a2c781262f8a1e5352c61d66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Sat, 8 Aug 2026 11:29:22 +0200 Subject: [PATCH 24/28] Add a subsection 'Community' --- doc/overview.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/overview.md b/doc/overview.md index b235eff9706..c7a45b2b130 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -30,13 +30,15 @@ and JPG for use on the web and elsewhere. In fact, PyGMT users will usually not contact with the original PostScript files and get only the more convenient formats like PDF and PNG. -The project was started in 2017 by [Leonardo Uieda](https://www.leouieda.com) and +## Community + +The PyGMT project was started in 2017 by [Leonardo Uieda](https://www.leouieda.com) and [Paul Wessel](https://en.wikipedia.org/wiki/Pål_Wessel) (the co-creator and main developer -of GMT) at the University of Hawaiʻi at Mānoa. Currently the project is maintained by an -[international team](team.md) with contributions from +of GMT) at the University of Hawaiʻi at Mānoa. Currently, the project is community-driven +and maintained by an [international team](team.md), with contributions from [multiple contributors](https://github.com/GenericMappingTools/pygmt/graphs/contributors). -We welcome any feedback and ideas! Let us know by submitting +We welcome any feedback, ideas, and contributions! Let us know by submitting [issues on GitHub](https://github.com/GenericMappingTools/pygmt/issues) or by posting on our [Discourse forum](https://forum.generic-mapping-tools.org/c/questions/pygmt-q-a). From 772b35d01a1e445ec8d9666081da44eaa1daa078 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Sat, 8 Aug 2026 11:31:22 +0200 Subject: [PATCH 25/28] Mention PyGMT paper in subsection 'Background' --- doc/overview.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/overview.md b/doc/overview.md index c7a45b2b130..d58d9dc2f8c 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -28,7 +28,9 @@ and allowing different backends. GMT uses the and very fast. The PostScript figures can be converted to other formats like PDF, PNG, and JPG for use on the web and elsewhere. In fact, PyGMT users will usually not have any contact with the original PostScript files and get only the more convenient formats like -PDF and PNG. +PDF and PNG. For more information about the design and development of PyGMT, see the +[PyGMT paper](https://doi.org/10.1029/2026GC013105) published in +*Geochemistry, Geophysics, Geosystems*. ## Community From 2d050d70bcc9df9703b10b1d05bc19bfe1e67596 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= <94163266+yvonnefroehlich@users.noreply.github.com> Date: Sat, 8 Aug 2026 11:47:34 +0200 Subject: [PATCH 26/28] Mention PyGMT paper in seperate paragraph Co-authored-by: Dongdong Tian --- doc/overview.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/overview.md b/doc/overview.md index d58d9dc2f8c..e3dfba13bfa 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -28,7 +28,9 @@ and allowing different backends. GMT uses the and very fast. The PostScript figures can be converted to other formats like PDF, PNG, and JPG for use on the web and elsewhere. In fact, PyGMT users will usually not have any contact with the original PostScript files and get only the more convenient formats like -PDF and PNG. For more information about the design and development of PyGMT, see the +PDF and PNG. + +For more information about the design and development of PyGMT, see the [PyGMT paper](https://doi.org/10.1029/2026GC013105) published in *Geochemistry, Geophysics, Geosystems*. From 72c43dcdbc366572e0984a8689c8843924921e12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Sat, 8 Aug 2026 11:50:41 +0200 Subject: [PATCH 27/28] Move 'Community' after 'Project goals' --- doc/overview.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/overview.md b/doc/overview.md index e3dfba13bfa..bc229adbed5 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -34,18 +34,6 @@ For more information about the design and development of PyGMT, see the [PyGMT paper](https://doi.org/10.1029/2026GC013105) published in *Geochemistry, Geophysics, Geosystems*. -## Community - -The PyGMT project was started in 2017 by [Leonardo Uieda](https://www.leouieda.com) and -[Paul Wessel](https://en.wikipedia.org/wiki/Pål_Wessel) (the co-creator and main developer -of GMT) at the University of Hawaiʻi at Mānoa. Currently, the project is community-driven -and maintained by an [international team](team.md), with contributions from -[multiple contributors](https://github.com/GenericMappingTools/pygmt/graphs/contributors). - -We welcome any feedback, ideas, and contributions! Let us know by submitting -[issues on GitHub](https://github.com/GenericMappingTools/pygmt/issues) or by posting on -our [Discourse forum](https://forum.generic-mapping-tools.org/c/questions/pygmt-q-a). - ## Project goals From the beginning, the project has aimed to achieve the following goals: @@ -58,6 +46,18 @@ From the beginning, the project has aimed to achieve the following goals: `numpy.ndarray` or `pandas.DataFrame` for data tables, `xarray.DataArray` for grids, and `geopandas.GeoDataFrame` for geographical data. +## Community + +The PyGMT project was started in 2017 by [Leonardo Uieda](https://www.leouieda.com) and +[Paul Wessel](https://en.wikipedia.org/wiki/Pål_Wessel) (the co-creator and main developer +of GMT) at the University of Hawaiʻi at Mānoa. Currently, the project is community-driven +and maintained by an [international team](team.md), with contributions from +[multiple contributors](https://github.com/GenericMappingTools/pygmt/graphs/contributors). + +We welcome any feedback, ideas, and contributions! Let us know by submitting +[issues on GitHub](https://github.com/GenericMappingTools/pygmt/issues) or by posting on +our [Discourse forum](https://forum.generic-mapping-tools.org/c/questions/pygmt-q-a). + ## Related projects Other official GMT wrappers include: From 03445b6a863f27e43d8b58ac5e4aed24289c61a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Sat, 8 Aug 2026 12:09:10 +0200 Subject: [PATCH 28/28] Remove trailing white space --- doc/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/overview.md b/doc/overview.md index bc229adbed5..61957337743 100644 --- a/doc/overview.md +++ b/doc/overview.md @@ -28,7 +28,7 @@ and allowing different backends. GMT uses the and very fast. The PostScript figures can be converted to other formats like PDF, PNG, and JPG for use on the web and elsewhere. In fact, PyGMT users will usually not have any contact with the original PostScript files and get only the more convenient formats like -PDF and PNG. +PDF and PNG. For more information about the design and development of PyGMT, see the [PyGMT paper](https://doi.org/10.1029/2026GC013105) published in