Figure.image/grdimage/tilemap: Migrate the monochrome parameter to the new alias system

pygmt/src/grdimage.py

@@ -6,7 +6,7 @@
 
 import xarray as xr
 from pygmt._typing import PathLike
-from pygmt.alias import AliasSystem
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
 
@@ -21,7 +21,6 @@
     E="dpi",
     G="bitcolor",
     I="shading",
-    M="monochrome",
     N="no_clip",
     Q="nan_transparent",
     R="region",
@@ -33,6 +32,7 @@
 def grdimage(
     self,
     grid: PathLike | xr.DataArray,
+    monochrome: bool = False,
     projection=None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
@@ -76,6 +76,7 @@ def grdimage(
 
     {aliases}
        - J = projection
+       - M = monochrome
        - V = verbose
        - c = panel
        - t = transparency
@@ -128,9 +129,9 @@ def grdimage(
         input data represent an *image* then an *intensfile* or constant
         *intensity* must be provided.
     {projection}
-    monochrome : bool
-        Force conversion to monochrome image using the (television) YIQ
-        transformation. Cannot be used with ``nan_transparent``.
+    monochrome
+        Force conversion to monochrome image using the (television) YIQ transformation.
+        Cannot be used with ``nan_transparent``.
     no_clip : bool
         Do **not** clip the image at the frame boundaries (only relevant
         for non-rectangular maps) [Default is ``False``].
@@ -173,7 +174,9 @@ def grdimage(
         )
         raise NotImplementedError(msg)
 
-    aliasdict = AliasSystem().add_common(
+    aliasdict = AliasSystem(
+        M=Alias(monochrome, name="monochrome"),
+    ).add_common(
         J=projection,
         V=verbose,
         c=panel,

pygmt/src/image.py

@@ -12,13 +12,14 @@
 
 
 @fmt_docstring
-@use_alias(D="position", G="bitcolor", M="monochrome", R="region", p="perspective")
+@use_alias(D="position", G="bitcolor", R="region", p="perspective")
 @kwargs_to_strings(R="sequence", p="sequence")
 def image(
     self,
     imagefile: PathLike,
     projection=None,
     box: Box | bool = False,
+    monochrome: bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | tuple[int, int] | bool = False,
@@ -28,26 +29,35 @@ def image(
     r"""
     Plot raster or EPS images.
 
-    Reads an Encapsulated PostScript file or a raster image file and plots
-    it on a map.
+    Reads Encapsulated PostScript (EPS) or raster image files and plots them. The
+    image can be scaled arbitrarily, and 1-bit raster images can be:
+
+    - inverted, i.e., black pixels (on) becomes white (off) and vice versa.
+    - colorized, by assigning different foreground and background colors.
+    - made transparent where either the back- or foreground is painted.
+
+    As an option, the user may choose to convert colored raster images to grayscale
+    using TV's YIQ-transformation. For raster files, the user can select which color is
+    made transparent. The user may also choose to replicate the image which, when
+    preceded by appropriate clip paths, may allow larger custom-designed fill patterns
+    to be implemented.
 
     Full GMT docs at :gmt-docs:`image.html`.
 
     {aliases}
        - F = box
        - J = projection
+       - M = monochrome
        - V = verbose
        - c = panel
        - t = transparency
 
     Parameters
     ----------
-    imagefile : str
-        This must be an Encapsulated PostScript (EPS) file or a raster
-        image. An EPS file must contain an appropriate BoundingBox. A
-        raster file can have a depth of 1, 8, 24, or 32 bits and is read
-        via GDAL. **Note**: If GDAL was not configured during GMT installation
-        then only EPS files are supported.
+    imagefile
+        An Encapsulated PostScript (EPS) file or a raster image file. An EPS file must
+        contain an appropriate BoundingBox. A raster file can have a depth of 1, 8, 24,
+        or 32 bits and is read via GDAL.
     {projection}
     {region}
     position : str
@@ -68,7 +78,7 @@ def image(
         to make those pixels transparent. Can be repeated with different
         settings. Alternatively, for color images you can select a single
         *color* that should be made transparent instead (**+t**).
-    monochrome : bool
+    monochrome
         Convert color image to monochrome grayshades using the (television)
         YIQ-transformation.
     {verbose}
@@ -80,6 +90,7 @@ def image(
 
     aliasdict = AliasSystem(
         F=Alias(box, name="box"),
+        M=Alias(monochrome, name="monochrome"),
     ).add_common(
         J=projection,
         V=verbose,

pygmt/src/tilemap.py

@@ -4,7 +4,7 @@
 
 from typing import Literal
 
-from pygmt.alias import AliasSystem
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.datasets.tile_map import load_tile_map
 from pygmt.enums import GridType
@@ -21,7 +21,6 @@
     B="frame",
     E="dpi",
     I="shading",
-    M="monochrome",
     N="no_clip",
     Q="nan_transparent",
     # R="region",
@@ -37,6 +36,7 @@ def tilemap(  # noqa: PLR0913
     wait: int = 0,
     max_retries: int = 2,
     zoom_adjust: int | None = None,
+    monochrome: bool = False,
     projection=None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
@@ -59,6 +59,7 @@ def tilemap(  # noqa: PLR0913
 
     {aliases}
        - J = projection
+       - M = monochrome
        - V = verbose
        - c = panel
        - t = transparency
@@ -131,7 +132,9 @@ def tilemap(  # noqa: PLR0913
     if kwargs.get("N") in {None, False}:
         kwargs["R"] = "/".join(str(coordinate) for coordinate in region)
 
-    aliasdict = AliasSystem().add_common(
+    aliasdict = AliasSystem(
+        M=Alias(monochrome, name="monochrome"),
+    ).add_common(
         J=projection,
         V=verbose,
         c=panel,