GenericMappingTools · seisman · Jan 18, 2026 · Apr 1, 2026 · Apr 1, 2026 · Apr 1, 2026
diff --git a/doc/techref/index.md b/doc/techref/index.md
@@ -10,6 +10,7 @@ visit the {gmt-docs}`GMT Technical Reference <reference.html>`.
 
 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
@@ -0,0 +1,37 @@
+# Dimension and Distance Units
+
+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**.
+
+(dimension-units)=
+## Dimension Units
+
+Dimension units are used for map dimensions, 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/helpers/decorators.py b/pygmt/helpers/decorators.py
@@ -121,12 +121,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** (inches), **c** (centimeters), or **p** (points).
+            - 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 meanings of the units.
+            - For projected data (**X**\|\ **Y**\|\ **D**), valid units are **c**,
+              **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
@@ -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 <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
@@ -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 <distance-units>`.
         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
@@ -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/grdproject.py b/pygmt/src/grdproject.py
@@ -82,16 +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. 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. 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 ``"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 one of the supported units:
+        **c**, **i**, **p**, **f**, **k**, **M**, **n**, and **u**. See
+        :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

diff --git 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 <grdtrack.html#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 <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
@@ -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 <dimension-units>` 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/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 <dimension-units>`. 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
@@ -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 <dimension-units>`
+        [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

diff --git a/pygmt/src/scalebar.py b/pygmt/src/scalebar.py
@@ -41,8 +41,8 @@ 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.
+        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/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/sphdistance.py b/pygmt/src/sphdistance.py
@@ -85,9 +85,9 @@ 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. 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

diff --git 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 <surface.html#units>`) if needed. One can also
+        [Default is no masking]. Append a :ref:`distance unit <distance-units>` 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
@@ -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 <dimension-units>`. 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
@@ -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 <dimension-units>`; 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
@@ -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 <dimension-units>` is
         appended).
 
         - **e**\ [*velscale*/]\ *confidence*\ [**+f**\ *font*]

diff --git 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 <dimension-units>`; 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