diff --git a/pygmt/src/grdimage.py b/pygmt/src/grdimage.py index 376091976f1..be6d10bc6f4 100644 --- a/pygmt/src/grdimage.py +++ b/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", @@ -34,6 +33,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 @@ -127,9 +128,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``]. @@ -172,7 +173,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, diff --git a/pygmt/src/image.py b/pygmt/src/image.py index f6fdfa71950..e366df96e0a 100644 --- a/pygmt/src/image.py +++ b/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, diff --git a/pygmt/src/tilemap.py b/pygmt/src/tilemap.py index f1b0b549221..95cab7a8c50 100644 --- a/pygmt/src/tilemap.py +++ b/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,