diff --git a/doc/conf.py b/doc/conf.py
index 6b61ac02008..0202fad58c6 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -37,10 +37,8 @@
# configure links to GMT docs
extlinks = {
- "gmt-docs": (
- "https://docs.generic-mapping-tools.org/latest/%s",
- "https://docs.generic-mapping-tools.org/latest/",
- )
+ "gmt-docs": ("https://docs.generic-mapping-tools.org/latest/%s", None),
+ "gmt-term": ("https://docs.generic-mapping-tools.org/latest/gmt.conf#term-%s", ""),
}
# intersphinx configuration
diff --git a/pygmt/mathops.py b/pygmt/mathops.py
index a4a61c13d42..e74deb82c3a 100644
--- a/pygmt/mathops.py
+++ b/pygmt/mathops.py
@@ -8,18 +8,55 @@
@fmt_docstring
@use_alias(
+ A="transparency",
C="cmap",
- T="series",
+ D="background",
+ F="color_model",
G="truncate",
H="output",
I="reverse",
+ M="overrule_bg",
+ N="no_bg",
+ Q="log",
+ T="series",
V="verbose",
+ W="categorical",
+ Ww="cyclic",
Z="continuous",
)
@kwargs_to_strings(T="sequence", G="sequence")
def makecpt(**kwargs):
"""
- Creates a static color palette table (CPT).
+ Make GMT color palette tables.
+
+ This is a module that will help you make static color palette tables
+ (CPTs). By default, the CPT will simply be saved to the current session,
+ but you can use *output* to save it to a file. You define an equidistant
+ set of contour intervals or pass your own z-table or list, and create a new
+ CPT based on an existing master (dynamic) CPT. The resulting CPT can be
+ reversed relative to the master cpt, and can be made continuous or
+ discrete. For color tables beyond the standard GMT offerings, visit
+ `cpt-city `_ and
+ `Scientific Colour-Maps `_.
+
+ The CPT includes three additional colors beyond the range of z-values.
+ These are the background color (B) assigned to values lower than the lowest
+ *z*-value, the foreground color (F) assigned to values higher than the
+ highest *z*-value, and the NaN color (N) painted wherever values are
+ undefined.
+
+ If the master CPT includes B, F, and N entries, these will be copied into
+ the new master file. If not, the parameters :gmt-term:`COLOR_BACKGROUND`,
+ :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` from the
+ :gmt-docs:`gmt.conf ` file or the command line will be used. This
+ default behavior can be overruled using the options *background*,
+ *overrule_bg* or *no_bg*.
+
+ The color model (RGB, HSV or CMYK) of the palette created by **makecpt**
+ will be the same as specified in the header of the master CPT. When there
+ is no :gmt-term:`COLOR_MODEL` entry in the master CPT, the
+ :gmt-term:`COLOR_MODEL` specified in the :gmt-docs:`gmt.conf `
+ file or on the command line will be used.
Full option list at :gmt-docs:`makecpt.html`
@@ -27,21 +64,49 @@ def makecpt(**kwargs):
Parameters
----------
+ transparency : str
+ Sets a constant level of transparency (0-100) for all color slices.
+ Append **+a** to also affect the fore-, back-, and nan-colors
+ [Default is no transparency, i.e., 0 (opaque)].
cmap : str
Selects the master color palette table (CPT) to use in the
interpolation. Full list of built-in color palette tables can be found
at :gmt-docs:`cookbook/cpts.html#built-in-color-palette-tables-cpt`.
+ background : bool or str
+ Select the back- and foreground colors to match the colors for lowest
+ and highest *z*-values in the output CPT [Default (``background=True``
+ or ``background='o'``) uses the colors specified in the master file, or
+ those defined by the parameters :gmt-term:`COLOR_BACKGROUND`,
+ :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN`]. Use
+ ``background='i'`` to match the colors for the lowest and highest
+ values in the input (instead of the output) CPT.
+ color_model :
+ ``[R|r|h|c][+c[label]]``.
+ Force output CPT to be written with r/g/b codes, gray-scale values or
+ color name (**R**, default) or r/g/b codes only (**r**), or h-s-v codes
+ (**h**), or c/m/y/k codes (**c**). Optionally or alternatively, append
+ **+c** to write discrete palettes in categorical format. If *label* is
+ appended then we create labels for each category to be used when the
+ CPT is plotted. The *label* may be a comma-separated list of category
+ names (you can skip a category by not giving a name), or give
+ *start*[-], where we automatically build monotonically increasing
+ labels from *start* (a single letter or an integer). Append - to build
+ ranges *start*-*start+1* instead.
series : list or str
- ``[min/max/inc[+b|l|n]|file|list]``. Defines the range of the new CPT
- by giving the lowest and highest z-value (and optionally an interval).
- If this is not given, the existing range in the master CPT will be used
- intact.
+ ``[min/max/inc[+b|l|n]|file|list]``.
+ Defines the range of the new CPT by giving the lowest and highest
+ z-value (and optionally an interval). If this is not given, the
+ existing range in the master CPT will be used intact. The values
+ produced defines the color slice boundaries. If **+n** is used it
+ refers to the number of such boundaries and not the number of slices.
+ For details on array creation, see
+ :gmt-docs:`makecpt.html#generate-1d-array`.
truncate : list or str
- ``zlo/zhi``. Truncate the incoming CPT so that the lowest and highest
- z-levels are to zlo and zhi. If one of these equal NaN then we leave
- that end of the CPT alone. The truncation takes place before any
- resampling. See also
- :gmt-docs:`cookbook/features.html#manipulating-cpts`.
+ ``zlo/zhi``.
+ Truncate the incoming CPT so that the lowest and highest z-levels are
+ to *zlo* and *zhi*. If one of these equal NaN then we leave that end of
+ the CPT alone. The truncation takes place before any resampling. See
+ also :gmt-docs:`cookbook/features.html#manipulating-cpts`.
output : str
Optional. The file name with extension .cpt to store the generated CPT
file. If not given or False (default), saves the CPT as the session
@@ -51,19 +116,38 @@ def makecpt(**kwargs):
progression in the master CPT. Set this to z to reverse the sign of
z-values in the color table. Note that this change of z-direction
happens before *truncate* and *series* values are used so the latter
- must be compatible with the changed z-range. See also
+ must be compatible with the changed *z*-range. See also
:gmt-docs:`cookbook/features.html#manipulating-cpts`.
+ overrule_bg :
+ Overrule background, foreground, and NaN colors specified in the master
+ CPT with the values of the parameters :gmt-term:`COLOR_BACKGROUND`,
+ :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` specified in
+ the :gmt-docs:`gmt.conf ` file or on the command line. When
+ combined with **background**, only :gmt-term:`COLOR_NAN` is considered.
+ no_bg : bool
+ Do not write out the background, foreground, and NaN-color fields
+ [Default will write them, i.e. ``no_bg=False``].
+ log : bool
+ For logarithmic interpolation scheme with input given as logarithms.
+ Expects input z-values provided via **series** to be log10(*z*),
+ assigns colors, and writes out *z*.
continuous : bool
- Creates a continuous CPT [Default is discontinuous, i.e., constant
- colors for each interval]. This option has no effect when no *series*
- is used, or when using *series=[z_min, z_max]*; in the first case the
- input CPT remains untouched, in the second case it is only scaled to
- match the range z_min/z_max.
-
+ Force a continuous CPT when building from a list of colors and a list
+ of z-values [Default is None, i.e. discrete values].
{V}
-
+ categorical : bool
+ Do not interpolate the input color table but pick the output colors
+ starting at the beginning of the color table, until colors for all
+ intervals are assigned. This is particularly useful in combination with
+ a categorical color table, like ``cmap='categorical'``.
+ cyclic : bool
+ Produce a wrapped (cyclic) color table that endlessly repeats its
+ range. Note that ``cyclic=True`` cannot be set together with
+ ``categorical=True``.
"""
with Session() as lib:
+ if "W" in kwargs and "Ww" in kwargs:
+ raise GMTInvalidInput("Set only categorical or cyclic to True, not both.")
if "H" not in kwargs.keys(): # if no output is set
arg_str = build_arg_string(kwargs)
elif "H" in kwargs.keys(): # if output is set
diff --git a/pygmt/tests/test_makecpt.py b/pygmt/tests/test_makecpt.py
index 3c1716a1f8d..70443ee1b14 100644
--- a/pygmt/tests/test_makecpt.py
+++ b/pygmt/tests/test_makecpt.py
@@ -182,3 +182,41 @@ def test_makecpt_continuous(grid):
makecpt(cmap="blue,white", continuous=True, series="-4500,4500")
fig.grdimage(grid, projection="W0/6i")
return fig
+
+
+@check_figures_equal()
+def test_makecpt_categorical(region):
+ """
+ Use static color palette table that is categorical.
+ """
+ fig_ref = Figure()
+ makecpt(C="categorical", W="")
+ fig_ref.colorbar(cmap=True, region=region, frame=True, position="JBC")
+
+ fig_test = Figure()
+ makecpt(cmap="categorical", categorical=True)
+ fig_test.colorbar(cmap=True, region=region, frame=True, position="JBC")
+ return fig_ref, fig_test
+
+
+@check_figures_equal()
+def test_makecpt_cyclic(region):
+ """
+ Use static color palette table that is cyclic.
+ """
+ fig_ref = Figure()
+ makecpt(C="cork", W="w")
+ fig_ref.colorbar(cmap=True, region=region, frame=True, position="JBC")
+
+ fig_test = Figure()
+ makecpt(cmap="cork", cyclic=True)
+ fig_test.colorbar(cmap=True, region=region, frame=True, position="JBC")
+ return fig_ref, fig_test
+
+
+def test_makecpt_categorical_and_cyclic():
+ """
+ Use incorrect setting by setting both categorical and cyclic to True.
+ """
+ with pytest.raises(GMTInvalidInput):
+ makecpt(cmap="batlow", categorical=True, cyclic=True)