Figure.image: Add the parameter 'invert' for option -I (#4089)

Author: seisman

pygmt/src/image.py

@@ -14,18 +14,19 @@
 
 @fmt_docstring
 @use_alias(D="position", G="bitcolor")
-def image(
+def image(  # noqa: PLR0913
     self,
     imagefile: PathLike,
-    projection: str | None = None,
-    region: Sequence[float | str] | str | None = None,
     box: Box | bool = False,
     monochrome: bool = False,
+    invert: bool = False,
+    projection: str | None = None,
+    region: Sequence[float | str] | str | None = None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | Sequence[int] | bool = False,
-    transparency: float | None = None,
     perspective: float | Sequence[float] | str | bool = False,
+    transparency: float | None = None,
     **kwargs,
 ):
     r"""
@@ -48,6 +49,7 @@ def image(
 
     $aliases
        - F = box
+       - I = invert
        - J = projection
        - M = monochrome
        - R = region
@@ -62,8 +64,6 @@ def image(
         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
         [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\ **+r**\ *dpi*\
         **+w**\ [**-**]\ *width*\ [/*height*]\ [**+j**\ *justify*]\
@@ -85,6 +85,15 @@ def image(
     monochrome
         Convert color image to monochrome grayshades using the (television)
         YIQ-transformation.
+    invert
+        Invert 1-bit image before plotting, i.e., black pixels (on) become white (off)
+        and vice versa. Ignored if used with color images.
+
+        **Note**: There was an upstream GMT bug, so this feature may not work correctly
+        for some 1-bit images for GMT<=6.6.0.
+        See `PR #8837 <https://github.com/GenericMappingTools/gmt/pull/8837>`__.
+    $projection
+    $region
     $verbose
     $panel
     $perspective
@@ -95,6 +104,7 @@ def image(
     aliasdict = AliasSystem(
         F=Alias(box, name="box"),
         M=Alias(monochrome, name="monochrome"),
+        I=Alias(invert, name="invert"),
     ).add_common(
         J=projection,
         R=region,