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..db5eda1f843 --- /dev/null +++ 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 index 53c7e1f1d29..b6e41057bb6 100644 --- 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 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/grdproject.py b/pygmt/src/grdproject.py index 55c8cb83e5a..27a94ca629c 100644 --- 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 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/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 diff --git a/pygmt/src/scalebar.py b/pygmt/src/scalebar.py index 918d10bbcd5..9d7dffb490b 100644 --- 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 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/sphdistance.py b/pygmt/src/sphdistance.py index 74d1e72ae89..336df63055c 100644 --- 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 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 ca2bf13ef9e..66870b438e4 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