From 9d1471f37a012f0ec9c2ce0a946f5d68df420dcb Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sun, 18 Jan 2026 10:48:01 +0800 Subject: [PATCH 01/15] Add a separate documentation for supported plot and distance units --- doc/techref/index.md | 1 + doc/techref/units.md | 34 ++++++++++++++++++++++++++++++++++ pygmt/src/grdproject.py | 15 +++++++-------- 3 files changed, 42 insertions(+), 8 deletions(-) create mode 100644 doc/techref/units.md diff --git a/doc/techref/index.md b/doc/techref/index.md index a17c19f868e..a0534c5f933 100644 --- a/doc/techref/index.md +++ b/doc/techref/index.md @@ -10,6 +10,7 @@ visit the {gmt-docs}`GMT Technical Reference `. common_parameters.md projections.md +units.md fonts.md text_formatting.md encodings.md diff --git a/doc/techref/units.md b/doc/techref/units.md new file mode 100644 index 00000000000..65192b71be4 --- /dev/null +++ b/doc/techref/units.md @@ -0,0 +1,34 @@ +# Units + +GMT uses two unit groups: **dimension units** (plot units) and **distance units** (Earth distances). + +(plot-units)= +## Dimension Units (Plot Units) + +Use these for map widths, offsets, symbol sizes, pen widths, etc. + +| Code | Unit | Notes | +|------|------|-------| +| `c` | Centimeter | Default for most dimensions | +| `i` | Inch | 1 inch = 2.54 cm | +| `p` | Point | 1 point = 1/72 inch | + +**Defaults:** If no unit is given, GMT uses {gmt-term}`PROJ_LENGTH_UNIT` (default is `c`). +Fonts and pen thicknesses default to `p`. + +(distance-units)= +## Distance Units + +GMT supports various distance units for geographic calculations. + +| Code | Unit | Notes | +|------|------|-------| +| `d` | Degree | Arc degree | +| `m` | Minute of arc | 1/60 degree | +| `s` | Second of arc | 1/3600 degree | +| `e` | Meter | Default distance unit | +| `k` | Kilometer | 1000 meters | +| `f` | Foot | 0.3048 meters | +| `u` | US Survey Foot | 1200/3937 meters | +| `M` | Statute Mile | 1.60934 km | +| `n` | Nautical Mile | 1.852 km | diff --git a/pygmt/src/grdproject.py b/pygmt/src/grdproject.py index a0271403344..823a691b156 100644 --- a/pygmt/src/grdproject.py +++ b/pygmt/src/grdproject.py @@ -82,16 +82,15 @@ def grdproject( # noqa: PLR0913 When set to ``True``, do the inverse transformation, from rectangular to geographical [Default is ``False``]. unit - Set the projected measure unit. Valid values are ``"c"`` (centimeters), - ``"i"`` (inches), and ``"p"`` (points) [Default is set by - :gmt-term:`PROJ_LENGTH_UNIT`]. Cannot be used with ``scaling``. + Set the projected measure unit. See :doc:`/techref/units#plot-units` for + supported units [Default is set by :gmt-term:`PROJ_LENGTH_UNIT`]. Cannot be used + with ``scaling``. scaling Force 1:1 scaling, i.e., output (or input, see ``inverse``) data are in actual - projected meters. To specify other units, set it to ``"f"`` (feet), - ``"k"`` (kilometers), ``"M"`` (statute miles), ``"n"`` (nautical miles), - ``"u"`` (US survey feet), ``"i"`` (inches), ``"c"`` (centimeters), or - ``"p"`` (points). Without ``scaling``, the output (or input, see ``inverse``) is - in the units specified by :gmt-term:`PROJ_LENGTH_UNIT` (but see ``unit``). + projected meters. To specify other units, set it to + a supported distance unit or plot unit (see :doc:`/techref/units`). Without + ``scaling``, the output (or input, see ``inverse``) is in the units specified + by :gmt-term:`PROJ_LENGTH_UNIT` (but see ``unit``). $projection $region $verbose From 05973edd92cbd6e60bc909b109fdb3eb9fe3c822 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 1 Apr 2026 09:58:31 +0000 Subject: [PATCH 02/15] Update docstrings in decorators.py, x2sys_init.py, scalebar.py, sphdistance.py to reference units docs Agent-Logs-Url: https://github.com/GenericMappingTools/pygmt/sessions/db4bb9d5-8c02-4ea8-94c9-eed70904cb89 Co-authored-by: seisman <3974108+seisman@users.noreply.github.com> --- pygmt/helpers/decorators.py | 11 +++++------ pygmt/src/scalebar.py | 3 +-- pygmt/src/sphdistance.py | 5 ++--- pygmt/src/x2sys_init.py | 12 +++--------- 4 files changed, 11 insertions(+), 20 deletions(-) diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index 579cf0c4077..39c44c06635 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -117,12 +117,11 @@ A unit **u** may be appended to the specified *gap*: - - For geographic data (**x**\|\ **y**\|\ **d**), the unit may - be arc- **d**\ (egrees), **m**\ (inutes), and **s**\ (econds), - or (m)\ **e**\ (ters), **f**\ (eet), **k**\ (ilometers), - **M**\ (iles), or **n**\ (autical miles) [Default is (m)\ **e**\ (ters)]. - - For projected data (**X**\|\ **Y**\|\ **D**), the unit may be - **i**\ (nches), **c**\ (entimeters), or **p**\ (oints). + - For geographic data (**x**\|\ **y**\|\ **d**), see + :doc:`/techref/units#distance-units` for supported distance units + [Default is meters]. + - For projected data (**X**\|\ **Y**\|\ **D**), see + :doc:`/techref/units#plot-units` for supported plot units. Append modifier **+a** to specify that *all* the criteria must be met [default imposes breaks if any one criterion is met]. diff --git a/pygmt/src/scalebar.py b/pygmt/src/scalebar.py index 918d10bbcd5..c12ad858ef3 100644 --- a/pygmt/src/scalebar.py +++ b/pygmt/src/scalebar.py @@ -41,8 +41,7 @@ def scalebar( # noqa: PLR0913 ---------- length Length of the scale bar in kilometers. Append a suffix to specify another unit. - Valid units are: **e**: meters; **f**: feet; **k**: kilometers; **M**: statute - miles; **n**: nautical miles; **u**: US survey feet. + See :doc:`/techref/units#distance-units` for supported distance units. height Height of the scale bar [Default is ``"5p"``]. Only works when ``fancy=True``. position diff --git a/pygmt/src/sphdistance.py b/pygmt/src/sphdistance.py index 74d1e72ae89..23cab5efaa8 100644 --- a/pygmt/src/sphdistance.py +++ b/pygmt/src/sphdistance.py @@ -85,9 +85,8 @@ def sphdistance( Optionally, append the resampling interval along Voronoi arcs in spherical degrees. unit : str - Specify the unit used for distance calculations. Choose among **d** - (spherical degrees), **e** (meters), **f** (feet), **k** (kilometers), - **M** (miles), **n** (nautical miles), or **u** (survey feet). + Specify the unit used for distance calculations. See + :doc:`/techref/units#distance-units` for supported distance units. node_table : str Read the information pertaining to each Voronoi polygon (the unique node lon, lat and polygon area) from a separate diff --git a/pygmt/src/x2sys_init.py b/pygmt/src/x2sys_init.py index 1abba77d350..7958fea4d13 100644 --- a/pygmt/src/x2sys_init.py +++ b/pygmt/src/x2sys_init.py @@ -93,15 +93,9 @@ def x2sys_init( **d**\|\ **s**\ *unit*. Set the units used for distance and speed when requested by other programs. Append **d** for distance or **s** for speed, then give the - desired *unit* as: - - - **c**: Cartesian userdist or userdist/usertime - - **e**: meters or m/s - - **f**: feet or ft/s - - **k**: kilometers or km/hr - - **m**: miles or mi/hr - - **n**: nautical miles or knots - - **u**: survey feet or sft/s + desired *unit*. For supported distance units, see + :doc:`/techref/units#distance-units`. Use **c** for Cartesian + userdist or userdist/usertime. [Default is ``units=["dk", "se"]`` (km and m/s) if ``discontinuity`` is set, and ``units=["dc", "sc"]`` otherwise (e.g., for Cartesian units)]. From fd93a03db1e9bf9c411b0d7b4191f9e0a079274d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 1 Apr 2026 09:59:18 +0000 Subject: [PATCH 03/15] Clarify default unit code in decorators.py gap docstring Agent-Logs-Url: https://github.com/GenericMappingTools/pygmt/sessions/db4bb9d5-8c02-4ea8-94c9-eed70904cb89 Co-authored-by: seisman <3974108+seisman@users.noreply.github.com> --- pygmt/helpers/decorators.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index 39c44c06635..37b4b38bd42 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -119,7 +119,7 @@ - For geographic data (**x**\|\ **y**\|\ **d**), see :doc:`/techref/units#distance-units` for supported distance units - [Default is meters]. + [Default unit is **e** (meters)]. - For projected data (**X**\|\ **Y**\|\ **D**), see :doc:`/techref/units#plot-units` for supported plot units. From cbba04fd8c4bd687b8f2259b537fb6961aaddbc7 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 1 Apr 2026 18:48:44 +0800 Subject: [PATCH 04/15] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- pygmt/src/grdproject.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/pygmt/src/grdproject.py b/pygmt/src/grdproject.py index 823a691b156..884104d3580 100644 --- a/pygmt/src/grdproject.py +++ b/pygmt/src/grdproject.py @@ -82,15 +82,16 @@ def grdproject( # noqa: PLR0913 When set to ``True``, do the inverse transformation, from rectangular to geographical [Default is ``False``]. unit - Set the projected measure unit. See :doc:`/techref/units#plot-units` for + Set the projected measure unit. See :ref:`plot-units` for supported units [Default is set by :gmt-term:`PROJ_LENGTH_UNIT`]. Cannot be used with ``scaling``. scaling Force 1:1 scaling, i.e., output (or input, see ``inverse``) data are in actual - projected meters. To specify other units, set it to - a supported distance unit or plot unit (see :doc:`/techref/units`). Without - ``scaling``, the output (or input, see ``inverse``) is in the units specified - by :gmt-term:`PROJ_LENGTH_UNIT` (but see ``unit``). + projected meters. To specify other units, set it to one of the supported + plot-unit codes (e.g., ``c``, ``i``, ``p``, ``e``, ``f``, ``k``, ``M``, ``n``, + ``u``; see :doc:`/techref/units#plot-units`). Without ``scaling``, the output + (or input, see ``inverse``) is in the units specified by + :gmt-term:`PROJ_LENGTH_UNIT` (but see ``unit``). $projection $region $verbose From c2f50e7bcfb78eaf3450224e9b701c895d19849c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 1 Apr 2026 13:49:19 +0000 Subject: [PATCH 05/15] Fix broken unit doc links: replace :doc: with #fragment with :ref: for section anchors Agent-Logs-Url: https://github.com/GenericMappingTools/pygmt/sessions/64c0dfeb-428c-4258-ad81-a452e1d8d4c8 Co-authored-by: seisman <3974108+seisman@users.noreply.github.com> --- pygmt/helpers/decorators.py | 4 ++-- pygmt/src/grdproject.py | 2 +- pygmt/src/scalebar.py | 2 +- pygmt/src/sphdistance.py | 2 +- pygmt/src/x2sys_init.py | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index 37b4b38bd42..762e19f7b40 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -118,10 +118,10 @@ A unit **u** may be appended to the specified *gap*: - For geographic data (**x**\|\ **y**\|\ **d**), see - :doc:`/techref/units#distance-units` for supported distance units + :ref:`distance-units` for supported distance units [Default unit is **e** (meters)]. - For projected data (**X**\|\ **Y**\|\ **D**), see - :doc:`/techref/units#plot-units` for supported plot units. + :ref:`plot-units` for supported plot units. Append modifier **+a** to specify that *all* the criteria must be met [default imposes breaks if any one criterion is met]. diff --git a/pygmt/src/grdproject.py b/pygmt/src/grdproject.py index 884104d3580..f8672e4e13f 100644 --- a/pygmt/src/grdproject.py +++ b/pygmt/src/grdproject.py @@ -89,7 +89,7 @@ def grdproject( # noqa: PLR0913 Force 1:1 scaling, i.e., output (or input, see ``inverse``) data are in actual projected meters. To specify other units, set it to one of the supported plot-unit codes (e.g., ``c``, ``i``, ``p``, ``e``, ``f``, ``k``, ``M``, ``n``, - ``u``; see :doc:`/techref/units#plot-units`). Without ``scaling``, the output + ``u``; see :ref:`plot-units`). Without ``scaling``, the output (or input, see ``inverse``) is in the units specified by :gmt-term:`PROJ_LENGTH_UNIT` (but see ``unit``). $projection diff --git a/pygmt/src/scalebar.py b/pygmt/src/scalebar.py index c12ad858ef3..e17dc5f61cb 100644 --- a/pygmt/src/scalebar.py +++ b/pygmt/src/scalebar.py @@ -41,7 +41,7 @@ def scalebar( # noqa: PLR0913 ---------- length Length of the scale bar in kilometers. Append a suffix to specify another unit. - See :doc:`/techref/units#distance-units` for supported distance units. + See :ref:`distance-units` for supported distance units. height Height of the scale bar [Default is ``"5p"``]. Only works when ``fancy=True``. position diff --git a/pygmt/src/sphdistance.py b/pygmt/src/sphdistance.py index 23cab5efaa8..655ac8cc1de 100644 --- a/pygmt/src/sphdistance.py +++ b/pygmt/src/sphdistance.py @@ -86,7 +86,7 @@ def sphdistance( spherical degrees. unit : str Specify the unit used for distance calculations. See - :doc:`/techref/units#distance-units` for supported distance units. + :ref:`distance-units` for supported distance units. node_table : str Read the information pertaining to each Voronoi polygon (the unique node lon, lat and polygon area) from a separate diff --git a/pygmt/src/x2sys_init.py b/pygmt/src/x2sys_init.py index 7958fea4d13..a8be3c3510d 100644 --- a/pygmt/src/x2sys_init.py +++ b/pygmt/src/x2sys_init.py @@ -94,7 +94,7 @@ def x2sys_init( Set the units used for distance and speed when requested by other programs. Append **d** for distance or **s** for speed, then give the desired *unit*. For supported distance units, see - :doc:`/techref/units#distance-units`. Use **c** for Cartesian + :ref:`distance-units`. Use **c** for Cartesian userdist or userdist/usertime. [Default is ``units=["dk", "se"]`` (km and m/s) if ``discontinuity`` is From a24e532537fdb9da58787a103b1df4d2133d521d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 1 Apr 2026 14:36:29 +0000 Subject: [PATCH 06/15] Add workflow to auto-add ReadTheDocs preview links to PR descriptions Agent-Logs-Url: https://github.com/GenericMappingTools/pygmt/sessions/8ed1ab66-2e61-4f3c-945b-c299cb5d19c6 Co-authored-by: seisman <3974108+seisman@users.noreply.github.com> --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/workflows/rtd-preview.yml | 52 +++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/rtd-preview.yml diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index f0d67669fec..1bbcc828362 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -8,7 +8,7 @@ Fixes # - + **Preview**: **Guidelines** diff --git a/.github/workflows/rtd-preview.yml b/.github/workflows/rtd-preview.yml new file mode 100644 index 00000000000..9cec0698c47 --- /dev/null +++ b/.github/workflows/rtd-preview.yml @@ -0,0 +1,52 @@ +# Add ReadTheDocs preview links to pull request descriptions. +# +# This workflow runs when a pull request is opened and automatically adds the +# ReadTheDocs preview link to the PR description. +# +name: RTD Preview + +on: + pull_request_target: + types: [opened] + +permissions: + pull-requests: write + +jobs: + rtd-preview: + name: Add ReadTheDocs preview link + runs-on: ubuntu-latest + if: github.repository == 'GenericMappingTools/pygmt' + + steps: + - name: Add ReadTheDocs preview link to PR description + uses: actions/github-script@v7.0.1 + with: + script: | + const prNumber = context.payload.pull_request.number; + const rtdUrl = `https://pygmt-dev--${prNumber}.org.readthedocs.build/en/${prNumber}/`; + + // Get the current PR body + const { data: pr } = await github.rest.pulls.get({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: prNumber, + }); + + let body = pr.body || ''; + + // Add RTD link if Preview section exists but has no link yet + const lines = body.split('\n'); + const previewIndex = lines.findIndex(line => /^\s*\*\*Preview\*\*:\s*$/.test(line)); + if (previewIndex !== -1) { + lines[previewIndex] = lines[previewIndex].replace(/(\*\*Preview\*\*:)\s*$/, `$1 ${rtdUrl}`); + await github.rest.pulls.update({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: prNumber, + body: lines.join('\n'), + }); + core.notice(`Added ReadTheDocs preview link: ${rtdUrl}`); + } else { + core.notice('Preview section not found or already has a link. No changes made.'); + } From c7dc07dccc3e3425f03d39543bb582939438bb97 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 1 Apr 2026 23:03:08 +0800 Subject: [PATCH 07/15] Revert "Add workflow to auto-add ReadTheDocs preview links to PR descriptions" This reverts commit a24e532537fdb9da58787a103b1df4d2133d521d. --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/workflows/rtd-preview.yml | 52 ------------------------------- 2 files changed, 1 insertion(+), 53 deletions(-) delete mode 100644 .github/workflows/rtd-preview.yml diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 1bbcc828362..f0d67669fec 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -8,7 +8,7 @@ Fixes # - + **Preview**: **Guidelines** diff --git a/.github/workflows/rtd-preview.yml b/.github/workflows/rtd-preview.yml deleted file mode 100644 index 9cec0698c47..00000000000 --- a/.github/workflows/rtd-preview.yml +++ /dev/null @@ -1,52 +0,0 @@ -# Add ReadTheDocs preview links to pull request descriptions. -# -# This workflow runs when a pull request is opened and automatically adds the -# ReadTheDocs preview link to the PR description. -# -name: RTD Preview - -on: - pull_request_target: - types: [opened] - -permissions: - pull-requests: write - -jobs: - rtd-preview: - name: Add ReadTheDocs preview link - runs-on: ubuntu-latest - if: github.repository == 'GenericMappingTools/pygmt' - - steps: - - name: Add ReadTheDocs preview link to PR description - uses: actions/github-script@v7.0.1 - with: - script: | - const prNumber = context.payload.pull_request.number; - const rtdUrl = `https://pygmt-dev--${prNumber}.org.readthedocs.build/en/${prNumber}/`; - - // Get the current PR body - const { data: pr } = await github.rest.pulls.get({ - owner: context.repo.owner, - repo: context.repo.repo, - pull_number: prNumber, - }); - - let body = pr.body || ''; - - // Add RTD link if Preview section exists but has no link yet - const lines = body.split('\n'); - const previewIndex = lines.findIndex(line => /^\s*\*\*Preview\*\*:\s*$/.test(line)); - if (previewIndex !== -1) { - lines[previewIndex] = lines[previewIndex].replace(/(\*\*Preview\*\*:)\s*$/, `$1 ${rtdUrl}`); - await github.rest.pulls.update({ - owner: context.repo.owner, - repo: context.repo.repo, - pull_number: prNumber, - body: lines.join('\n'), - }); - core.notice(`Added ReadTheDocs preview link: ${rtdUrl}`); - } else { - core.notice('Preview section not found or already has a link. No changes made.'); - } From 824d09f5203e74d36495482630015e1f70d9391e Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 2 Apr 2026 14:34:03 +0800 Subject: [PATCH 08/15] Revert changes in x2sys_init --- pygmt/src/x2sys_init.py | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/pygmt/src/x2sys_init.py b/pygmt/src/x2sys_init.py index a8be3c3510d..1abba77d350 100644 --- a/pygmt/src/x2sys_init.py +++ b/pygmt/src/x2sys_init.py @@ -93,9 +93,15 @@ def x2sys_init( **d**\|\ **s**\ *unit*. Set the units used for distance and speed when requested by other programs. Append **d** for distance or **s** for speed, then give the - desired *unit*. For supported distance units, see - :ref:`distance-units`. Use **c** for Cartesian - userdist or userdist/usertime. + desired *unit* as: + + - **c**: Cartesian userdist or userdist/usertime + - **e**: meters or m/s + - **f**: feet or ft/s + - **k**: kilometers or km/hr + - **m**: miles or mi/hr + - **n**: nautical miles or knots + - **u**: survey feet or sft/s [Default is ``units=["dk", "se"]`` (km and m/s) if ``discontinuity`` is set, and ``units=["dc", "sc"]`` otherwise (e.g., for Cartesian units)]. From fb76186a8fb3dd0eb2bfd5918b324cd58c189fb8 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 2 Apr 2026 14:35:28 +0800 Subject: [PATCH 09/15] Reformat sphdistance.py --- pygmt/src/sphdistance.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pygmt/src/sphdistance.py b/pygmt/src/sphdistance.py index 655ac8cc1de..26bd0309a0c 100644 --- a/pygmt/src/sphdistance.py +++ b/pygmt/src/sphdistance.py @@ -85,8 +85,8 @@ def sphdistance( Optionally, append the resampling interval along Voronoi arcs in spherical degrees. unit : str - Specify the unit used for distance calculations. See - :ref:`distance-units` for supported distance units. + Specify the unit used for distance calculations. See :ref:`distance-units` for + supported distance units. node_table : str Read the information pertaining to each Voronoi polygon (the unique node lon, lat and polygon area) from a separate From 4e3ccefd44163c0bfb86df6d3fdf1df79278aa4d Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Tue, 7 Apr 2026 13:08:24 +0800 Subject: [PATCH 10/15] Fixes --- pygmt/src/scalebar.py | 3 ++- pygmt/src/sphdistance.py | 5 +++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/pygmt/src/scalebar.py b/pygmt/src/scalebar.py index e17dc5f61cb..def2258cd86 100644 --- a/pygmt/src/scalebar.py +++ b/pygmt/src/scalebar.py @@ -41,7 +41,8 @@ def scalebar( # noqa: PLR0913 ---------- length Length of the scale bar in kilometers. Append a suffix to specify another unit. - See :ref:`distance-units` for supported distance units. + Supported units are: **e**, **f**, **k**, **M**, **n**, and **u**. See + :ref:`distance-units` for meanings of the units. height Height of the scale bar [Default is ``"5p"``]. Only works when ``fancy=True``. position diff --git a/pygmt/src/sphdistance.py b/pygmt/src/sphdistance.py index 26bd0309a0c..336df63055c 100644 --- a/pygmt/src/sphdistance.py +++ b/pygmt/src/sphdistance.py @@ -85,8 +85,9 @@ def sphdistance( Optionally, append the resampling interval along Voronoi arcs in spherical degrees. unit : str - Specify the unit used for distance calculations. See :ref:`distance-units` for - supported distance units. + Specify the unit used for distance calculations. Valid values are **d**, **e**, + **f**, **k**, **M**, **n**, and **u**. See :ref:`distance-units` for meanings of + the units. node_table : str Read the information pertaining to each Voronoi polygon (the unique node lon, lat and polygon area) from a separate From d74ae8fac3cb923805a452a3bcd0760df9625da8 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 25 Jun 2026 16:38:12 +0800 Subject: [PATCH 11/15] Improve the docstrings for units --- doc/techref/units.md | 13 ++++++++----- pygmt/src/scalebar.py | 2 +- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/doc/techref/units.md b/doc/techref/units.md index 65192b71be4..fa6efb89cf5 100644 --- a/doc/techref/units.md +++ b/doc/techref/units.md @@ -1,11 +1,14 @@ -# Units +# Dimension and Distance Units -GMT uses two unit groups: **dimension units** (plot units) and **distance units** (Earth distances). +As a geospatial analyis and mapping package, GMT needs to distinguish between two types +of units: those used for plotting and those used for geographic distances. The former +are called **dimension units** (or plot units) and the latter are called +**distance units**. -(plot-units)= -## Dimension Units (Plot Units) +(dimension-units)= +## Dimension Units -Use these for map widths, offsets, symbol sizes, pen widths, etc. +Dimension units are used for map dimensions, symbol sizes, pen widths, etc. | Code | Unit | Notes | |------|------|-------| diff --git a/pygmt/src/scalebar.py b/pygmt/src/scalebar.py index def2258cd86..9d7dffb490b 100644 --- a/pygmt/src/scalebar.py +++ b/pygmt/src/scalebar.py @@ -41,7 +41,7 @@ def scalebar( # noqa: PLR0913 ---------- length Length of the scale bar in kilometers. Append a suffix to specify another unit. - Supported units are: **e**, **f**, **k**, **M**, **n**, and **u**. See + Supported units are: **e**, **f**, **k**, **M**, **n**, and **u**. See :ref:`distance-units` for meanings of the units. height Height of the scale bar [Default is ``"5p"``]. Only works when ``fancy=True``. From 7f6545b98a7e41d2c729ada635e94d498059f59e Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 25 Jun 2026 16:46:50 +0800 Subject: [PATCH 12/15] Improve docstrings --- pygmt/helpers/decorators.py | 10 +++++----- pygmt/src/grdproject.py | 14 +++++++------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index 5ca46539260..83f5b6ff369 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -121,11 +121,11 @@ A unit **u** may be appended to the specified *gap*: - - For geographic data (**x**\|\ **y**\|\ **d**), see - :ref:`distance-units` for supported distance units - [Default unit is **e** (meters)]. - - For projected data (**X**\|\ **Y**\|\ **D**), see - :ref:`plot-units` for supported plot units. + - For geographic data (**x**\|\ **y**\|\ **d**), valid units are **d**, + **m**, **s**, **e**, **f**, **k**, **M**, and **n** [Default is **e**]. + See :ref:`distance-units` for meaning of the units. + - For projected data (**X**\|\ **Y**\|\ **D**), valid units are **c**, + **i**, and **p**. See :ref:`dimension-units` for meaning of the units. Append modifier **+a** to specify that *all* the criteria must be met [default imposes breaks if any one criterion is met]. diff --git a/pygmt/src/grdproject.py b/pygmt/src/grdproject.py index ed14ee027f3..b5f57413980 100644 --- a/pygmt/src/grdproject.py +++ b/pygmt/src/grdproject.py @@ -82,15 +82,15 @@ def grdproject( # noqa: PLR0913 When set to ``True``, do the inverse transformation, from rectangular to geographical [Default is ``False``]. unit - Set the projected measure unit. See :ref:`plot-units` for - supported units [Default is set by :gmt-term:`PROJ_LENGTH_UNIT`]. Cannot be used - with ``scaling``. + Set the projected measure unit. Valid values are ``"c"``, ``"i"``, and ``"p"``. + [Default is set by :gmt-term:`PROJ_LENGTH_UNIT`]. Cannot be used with + ``scaling``. See :ref:`dimension-units` for meanings of the units. scaling Force 1:1 scaling, i.e., output (or input, see ``inverse``) data are in actual - projected meters. To specify other units, set it to one of the supported - plot-unit codes (e.g., ``c``, ``i``, ``p``, ``e``, ``f``, ``k``, ``M``, ``n``, - ``u``; see :ref:`plot-units`). Without ``scaling``, the output - (or input, see ``inverse``) is in the units specified by + projected meters. To specify other units, set it to one of the supported units: + **c**, **i**, **p**, **f**, **k**, **M**, **n**, and **u**. See + :docs:`/techref/units` for meanings of the units. Without ``scaling``, the + output (or input, see ``inverse``) is in the units specified by :gmt-term:`PROJ_LENGTH_UNIT` (but see ``unit``). $projection $region From cfa2ec01cce2512721e1cf383afd47f0ba54acf9 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 25 Jun 2026 16:55:43 +0800 Subject: [PATCH 13/15] Polish docstrings --- doc/techref/units.md | 2 +- pygmt/src/grdproject.py | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/techref/units.md b/doc/techref/units.md index fa6efb89cf5..db5eda1f843 100644 --- a/doc/techref/units.md +++ b/doc/techref/units.md @@ -1,6 +1,6 @@ # Dimension and Distance Units -As a geospatial analyis and mapping package, GMT needs to distinguish between two types +As a geospatial analysis and mapping package, GMT needs to distinguish between two types of units: those used for plotting and those used for geographic distances. The former are called **dimension units** (or plot units) and the latter are called **distance units**. diff --git a/pygmt/src/grdproject.py b/pygmt/src/grdproject.py index b5f57413980..27a94ca629c 100644 --- a/pygmt/src/grdproject.py +++ b/pygmt/src/grdproject.py @@ -89,9 +89,9 @@ def grdproject( # noqa: PLR0913 Force 1:1 scaling, i.e., output (or input, see ``inverse``) data are in actual projected meters. To specify other units, set it to one of the supported units: **c**, **i**, **p**, **f**, **k**, **M**, **n**, and **u**. See - :docs:`/techref/units` for meanings of the units. Without ``scaling``, the - output (or input, see ``inverse``) is in the units specified by - :gmt-term:`PROJ_LENGTH_UNIT` (but see ``unit``). + :ref:`dimension-units` and :ref:`distance-units` for meanings of the units. + Without ``scaling``, the output (or input, see ``inverse``) is in the units + specified by :gmt-term:`PROJ_LENGTH_UNIT` (but see ``unit``). $projection $region $verbose From f9630cc86df6bed42cb3450dfd673be2d0dee454 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 25 Jun 2026 17:06:19 +0800 Subject: [PATCH 14/15] Polish more docstrings --- pygmt/helpers/decorators.py | 4 ++-- pygmt/params/position.py | 2 +- pygmt/src/binstats.py | 2 +- pygmt/src/grd2xyz.py | 4 ++-- pygmt/src/grdtrack.py | 8 ++++---- pygmt/src/histogram.py | 4 ++-- pygmt/src/shift_origin.py | 2 +- pygmt/src/surface.py | 4 ++-- pygmt/src/ternary.py | 6 +++--- pygmt/src/text.py | 8 ++++---- pygmt/src/velo.py | 2 +- pygmt/src/wiggle.py | 7 +++---- 12 files changed, 26 insertions(+), 27 deletions(-) diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index 83f5b6ff369..b6e41057bb6 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -123,9 +123,9 @@ - For geographic data (**x**\|\ **y**\|\ **d**), valid units are **d**, **m**, **s**, **e**, **f**, **k**, **M**, and **n** [Default is **e**]. - See :ref:`distance-units` for meaning of the units. + See :ref:`distance-units` for meanings of the units. - For projected data (**X**\|\ **Y**\|\ **D**), valid units are **c**, - **i**, and **p**. See :ref:`dimension-units` for meaning of the units. + **i**, and **p**. See :ref:`dimension-units` for meanings of the units. Append modifier **+a** to specify that *all* the criteria must be met [default imposes breaks if any one criterion is met]. diff --git a/pygmt/params/position.py b/pygmt/params/position.py index 06fb724e79b..4780ed9d53f 100644 --- a/pygmt/params/position.py +++ b/pygmt/params/position.py @@ -54,7 +54,7 @@ class Position(BaseParam): ``cstype="plotcoords"`` Plot Coordinates Use plot coordinates as distances from the lower-left plot origin. Specify - ``refpoint`` as (*x*, *y*) with units (e.g., inches, centimeters, points). + ``refpoint`` as (*x*, *y*) with :ref:`dimension units `. Useful for precise layout control. **Example:** ``refpoint=("2c", "2.5c"), cstype="plotcoords"`` diff --git a/pygmt/src/binstats.py b/pygmt/src/binstats.py index 56ef3a30fca..1c07f668c19 100644 --- a/pygmt/src/binstats.py +++ b/pygmt/src/binstats.py @@ -110,7 +110,7 @@ def binstats( search *radius* [Default is no normalization]. search_radius : float or str Set the *search_radius* that determines which data points are - considered close to a node. Append the distance unit. + considered close to a node. Append a :ref:`distance unit `. Not compatible with ``tiling``. weight : str Input data have an extra column containing observation point weight. diff --git a/pygmt/src/grd2xyz.py b/pygmt/src/grd2xyz.py index cc67aaf6394..728a8f9fca2 100644 --- a/pygmt/src/grd2xyz.py +++ b/pygmt/src/grd2xyz.py @@ -76,8 +76,8 @@ def grd2xyz( this is simply the product of the *x* and *y* increments (except for gridline-registered grids at all sides [half] and corners [quarter]). For geographic grids we default to a length unit of **k**. Change - this by appending **+u**\ *unit*. For such grids, the area - varies with latitude and also sees special cases for + this by appending **+u**\ *unit* (see :ref:`distance-units`). For such grids, + the area varies with latitude and also sees special cases for gridline-registered layouts at sides, corners, and poles. convention : str [*flags*]. diff --git a/pygmt/src/grdtrack.py b/pygmt/src/grdtrack.py index 1606f37a268..03c2d43c16e 100644 --- a/pygmt/src/grdtrack.py +++ b/pygmt/src/grdtrack.py @@ -128,10 +128,10 @@ def grdtrack( either a "west-to-east" or "south-to-north" view. By default the entire profiles are output. Choose to only output the left or right halves of the profiles by appending **+l** or **+r**, respectively. Append - suitable units to *length*; it sets the unit used for *ds* [and - *spacing*] (See :gmt-docs:`Units `). The default - unit for geographic grids is meters while Cartesian grids implies the - user unit. The output columns will be *lon*, *lat*, *dist*, *azimuth*, + suitable :ref:`distance units ` to *length*; it sets the unit + used for *ds* [and *spacing*]. The default unit for geographic grids is meters + while Cartesian grids implies the user unit. The output columns will be + *lon*, *lat*, *dist*, *azimuth*, *z1*, *z2*, ..., *zn* (The *zi* are the sampled values for each of the *n* grids). dfile : str diff --git a/pygmt/src/histogram.py b/pygmt/src/histogram.py index f89b0b047ea..aeaa923a712 100644 --- a/pygmt/src/histogram.py +++ b/pygmt/src/histogram.py @@ -95,8 +95,8 @@ def histogram( # noqa: PLR0913 bar_width Use an alternative histogram bar width than the default set via ``series``. Give either an alternative width in data units, or the user - may append a valid plot dimension unit (**c**\|\ **i**\|\ **p**) for a - fixed dimension instead. + may append a :ref:`dimension unit ` for a fixed dimension + instead. bar_offset Shift all bars along the axis by *offset*. It may be given in data units of plot dimension units by appending the relevant unit. diff --git a/pygmt/src/shift_origin.py b/pygmt/src/shift_origin.py index dc9312189cd..2fab1d2b2f3 100644 --- a/pygmt/src/shift_origin.py +++ b/pygmt/src/shift_origin.py @@ -38,7 +38,7 @@ def shift_origin( The shifts *xshift* and *yshift* in x- and y-directions are relative to the current plot origin. The default unit for shifts is centimeters (**c**) but can be changed to other units via :gmt-term:`PROJ_LENGTH_UNIT`. Optionally, append the length unit - (**c** for centimeters, **i** for inches, or **p** for points) to the shifts. + (see :ref:`dimension-units`) to the shifts. For *xshift*, character **w** can be used, which represents the bounding box **width** of the last plotting object. The full syntax is diff --git a/pygmt/src/surface.py b/pygmt/src/surface.py index 0fc0daaa71b..fbee0bd2b32 100644 --- a/pygmt/src/surface.py +++ b/pygmt/src/surface.py @@ -107,8 +107,8 @@ def surface( max_radius : float or str Optional. After solving for the surface, apply a mask so that nodes farther than ``max_radius`` away from a data constraint are set to NaN - [Default is no masking]. Append a distance unit (see - :gmt-docs:`Units `) if needed. One can also + [Default is no masking]. Append a :ref:`distance unit ` if + needed. One can also select the nodes to mask by using the *n_cells*\ **c** form. Here *n_cells* means the number of cells around the node is controlled by a data point. As an example ``"0c"`` means that only the cell diff --git a/pygmt/src/ternary.py b/pygmt/src/ternary.py index 23e75109689..63bb9ed2412 100644 --- a/pygmt/src/ternary.py +++ b/pygmt/src/ternary.py @@ -152,9 +152,9 @@ def ternary( # noqa: PLR0913 Pass in either a file name to an ASCII data table, a Python list, a 2-D $table_classes. width : str - Set the width of the figure by passing a number, followed by - a unit (**i** for inches, **c** for centimeters). Use a negative width - to indicate that positive axes directions be clock-wise + Set the width of the figure by passing a number followed by a + :ref:`dimension unit `. Use a negative width to indicate that + positive axes directions be clock-wise [Default lets the a, b, c axes be positive in a counter-clockwise direction]. region : str or list diff --git a/pygmt/src/text.py b/pygmt/src/text.py index 271d79da1ee..94b19b98cb1 100644 --- a/pygmt/src/text.py +++ b/pygmt/src/text.py @@ -144,10 +144,10 @@ def text( # noqa: PLR0912, PLR0913, PLR0915 [*dx/dy*][**+to**\|\ **O**\|\ **c**\|\ **C**]. Adjust the clearance between the text and the surrounding box [Default is 15% of the font size]. Only used if ``pen`` or ``fill`` - are specified. Append the unit you want (**c** for centimeters, - **i** for inches, or **p** for points; if not given we consult - :gmt-term:`PROJ_LENGTH_UNIT`) or *%* for a percentage of the font - size. Optionally, use modifier **+t** to set the shape of the text + are specified. Append a :ref:`dimension unit `; if not given + we consult :gmt-term:`PROJ_LENGTH_UNIT`. Alternatively, append *%* for a + percentage of the font size. Optionally, use modifier **+t** to set the shape + of the text box when using ``fill`` and/or ``pen``. Append lowercase **o** to get a straight rectangle [Default is **o**]. Append uppercase **O** to get a rounded rectangle. In paragraph mode (*paragraph*) diff --git a/pygmt/src/velo.py b/pygmt/src/velo.py index 957ce8cd58b..b60fa274fef 100644 --- a/pygmt/src/velo.py +++ b/pygmt/src/velo.py @@ -88,7 +88,7 @@ def velo( # noqa : PLR0913 Select the meaning of the columns in the data file and the figure to be plotted. In all cases, the scales are in data units per length unit and sizes are in length units (default length unit is controlled by - :gmt-term:`PROJ_LENGTH_UNIT` unless **c**, **i**, or **p** is + :gmt-term:`PROJ_LENGTH_UNIT` unless a :ref:`dimension unit ` is appended). - **e**\ [*velscale*/]\ *confidence*\ [**+f**\ *font*] diff --git a/pygmt/src/wiggle.py b/pygmt/src/wiggle.py index 290bd9bbed2..288da80ace9 100644 --- a/pygmt/src/wiggle.py +++ b/pygmt/src/wiggle.py @@ -109,10 +109,9 @@ def wiggle( # noqa: PLR0913 Set the alignment of the scale label. Choose from ``"left"`` or ``"right"`` [Default is ``"left"``]. scale : str or float - Give anomaly scale in data-units/distance-unit. Append **c**, **i**, - or **p** to indicate the distance unit (centimeters, inches, or - points); if no unit is given we use the default unit that is - controlled by :gmt-term:`PROJ_LENGTH_UNIT`. + Give anomaly scale in data-units/dimension-unit. Append a + :ref:`dimension unit `; if no unit is given we use the default + unit that is controlled by :gmt-term:`PROJ_LENGTH_UNIT`. positive_fill Set color or pattern for filling positive wiggles [Default is no fill]. negative_fill From ac00ab5214ad7762f28916fcb9a384ec6832c72d Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 25 Jun 2026 17:11:59 +0800 Subject: [PATCH 15/15] Polish more docstrings --- pygmt/src/image.py | 12 ++++++------ pygmt/src/psconvert.py | 3 ++- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/pygmt/src/image.py b/pygmt/src/image.py index 5ed843d0e55..f5302e0883f 100644 --- a/pygmt/src/image.py +++ b/pygmt/src/image.py @@ -87,12 +87,12 @@ def image( # noqa: PLR0913 ``(0, 0)`` with anchor ``"BL"``). width height - Width (and height) of the image in plot coordinates (inches, cm, etc.). If - ``height`` (or ``width``) is set to 0, then the original aspect ratio of the - image is maintained. If ``width`` (or ``height``) is negative, the absolute - value is used to interpolate image to the device resolution using the PostScript - image operator. If neither dimensions nor ``dpi`` are set then revert to the - default dpi [:gmt-term:`GMT_GRAPHICS_DPU`]. + Width (and height) of the image in plot dimension, with an optional + :ref:`dimension unit `. If ``height`` (or ``width``) is set to + 0, then the original aspect ratio of the image is maintained. If ``width`` (or + ``height``) is negative, the absolute value is used to interpolate image to the + device resolution using the PostScript image operator. If neither dimensions nor + ``dpi`` are set then revert to the default dpi [:gmt-term:`GMT_GRAPHICS_DPU`]. dpi Set the dpi of the image in dots per inch, or append **c** to indicate this is dots per cm. diff --git a/pygmt/src/psconvert.py b/pygmt/src/psconvert.py index 6d486d9f277..2112a5fba70 100644 --- a/pygmt/src/psconvert.py +++ b/pygmt/src/psconvert.py @@ -74,7 +74,8 @@ def psconvert( Adjust the BoundingBox and HiResBoundingBox by scaling and/or adding margins. Append **+m** to specify extra margins to extend the bounding box. Give either one (uniform), two (x and y) or four - (individual sides) margins; append unit [Default is set by + (individual sides) margins; append a :ref:`dimension unit ` + [Default is set by :gmt-term:`PROJ_LENGTH_UNIT`]. Append **+s**\ *width* to resize the output image to exactly *width* units. The default unit is set by :gmt-term:`PROJ_LENGTH_UNIT` but you can append a new unit and/or