Merge branch 'main' into no_clip

Author: seisman

pygmt/src/grdimage.py

@@ -21,7 +21,6 @@
     E="dpi",
     G="bitcolor",
     I="shading",
-    M="monochrome",
     Q="nan_transparent",
     R="region",
     n="interpolation",
@@ -32,6 +31,7 @@
 def grdimage(
     self,
     grid: PathLike | xr.DataArray,
+    monochrome: bool = False,
     no_clip: bool = False,
     projection=None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
@@ -76,6 +76,7 @@ def grdimage(
 
     {aliases}
        - J = projection
+       - M = monochrome
        - N = no_clip
        - V = verbose
        - c = panel
@@ -129,9 +130,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
         Do **not** clip the image at the frame boundaries (only relevant for
         non-rectangular maps) [Default is ``False``].
@@ -175,6 +176,7 @@ def grdimage(
         raise NotImplementedError(msg)
 
     aliasdict = AliasSystem(
+        M=Alias(monochrome, name="monochrome"),
         N=Alias(no_clip, name="no_clip"),
     ).add_common(
         J=projection,

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/solar.py

@@ -32,15 +32,15 @@ def solar(
     r"""
     Plot day-night terminators and other sunlight parameters.
 
-    This function plots the day-night terminator. Alternatively, it can plot the
+    This method plots the day-night terminator. Alternatively, it can plot the
     terminators for civil twilight, nautical twilight, or astronomical twilight.
 
     Full GMT docs at :gmt-docs:`solar.html`.
 
     {aliases}
        - G = fill
        - J = projection
-       - T = terminator, **+d**: terminator_datetime
+       - T = terminator, **+d**/**+z**: terminator_datetime
        - V = verbose
        - W = pen
        - c = panel
@@ -49,8 +49,7 @@ def solar(
     Parameters
     ----------
     terminator
-        Set the type of terminator displayed, which can be set with either the full name
-        or the first letter of the name. Available options are:
+        Set the type of terminator. Choose one of the following:
 
         - ``"astronomical"``: Astronomical twilight
         - ``"civil"``: Civil twilight
@@ -60,8 +59,12 @@ def solar(
         Refer to https://en.wikipedia.org/wiki/Twilight for the definitions of different
         types of twilight.
     terminator_datetime : str or datetime object
-        Set the UTC date and time of the displayed terminator [Default is the current
-        UTC date and time]. It can be passed as a string or Python datetime object.
+        Set the date and time for the terminator calculation. It can be provided as a
+        string or any datetime-like object recognized by :func:`pandas.to_datetime`. The
+        time can be specified in UTC or using a UTC offset. The offset must be an
+        integer number of hours (e.g., -8 or +5); fractional hours are truncated
+        towards zero (e.g., -8.5 becomes -8 and +5.5 becomes +5). [Default is the
+        current UTC date and time].
     {region}
     {projection}
     {frame}
@@ -102,12 +105,16 @@ def solar(
     """
     self._activate_figure()
 
-    datetime_string = None
+    datetime_string, datetime_timezone = None, None
     if terminator_datetime:
         try:
-            datetime_string = pd.to_datetime(terminator_datetime).strftime(
-                "%Y-%m-%dT%H:%M:%S.%f"
-            )
+            _datetime = pd.to_datetime(terminator_datetime)
+            datetime_string = _datetime.strftime("%Y-%m-%dT%H:%M:%S.%f")
+            # GMT's solar module uses the C 'atoi' function to parse the timezone
+            # offset. Ensure the offset is an integer number of hours (e.g., -8 or +5).
+            # Fractional hours (e.g., -8.5 or +5.5) are truncated towards zero.
+            if utcoffset := _datetime.utcoffset():
+                datetime_timezone = int(utcoffset.total_seconds() / 3600)
         except ValueError as verr:
             raise GMTValueError(terminator_datetime, description="datetime") from verr
 
@@ -125,6 +132,7 @@ def solar(
                 },
             ),
             Alias(datetime_string, name="terminator_datetime", prefix="+d"),
+            Alias(datetime_timezone, name="terminator_timezone", prefix="+z"),
         ],
         W=Alias(pen, name="pen"),
     ).add_common(

pygmt/src/tilemap.py

@@ -21,7 +21,6 @@
     B="frame",
     E="dpi",
     I="shading",
-    M="monochrome",
     Q="nan_transparent",
     # R="region",
     p="perspective",
@@ -36,6 +35,7 @@ def tilemap(  # noqa: PLR0913
     wait: int = 0,
     max_retries: int = 2,
     zoom_adjust: int | None = None,
+    monochrome: bool = False,  
     no_clip: bool = False,
     projection=None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
@@ -59,6 +59,7 @@ def tilemap(  # noqa: PLR0913
 
     {aliases}
        - J = projection
+       - M = monochrome
        - N = no_clip
        - V = verbose
        - c = panel
@@ -133,6 +134,7 @@ def tilemap(  # noqa: PLR0913
         kwargs["R"] = "/".join(str(coordinate) for coordinate in region)
 
     aliasdict = AliasSystem(
+        M=Alias(monochrome, name="monochrome"),
         N=Alias(no_clip, name="no_clip"),
     ).add_common(
         J=projection,

pygmt/tests/baseline/test_solar_terminator_datetime_timezone.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 10c5d3cadeb50764177bf49cbefeecb1
+  size: 48753
+  hash: md5
+  path: test_solar_terminator_datetime_timezone.png

pygmt/tests/test_solar.py

@@ -119,3 +119,29 @@ def test_solar_default_terminator():
         terminator_datetime="1990-02-17 04:25:00",
     )
     return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_solar_terminator_datetime_timezone():
+    """
+    Test passing the terminator_datetime argument with a time string that includes a
+    timezone.
+    """
+    fig = Figure()
+    fig.basemap(region="d", projection="W0/15c", frame=True)
+    fig.solar(terminator_datetime="2020-01-01T01:02:03", pen="1p,black")
+    fig.solar(terminator_datetime="2020-01-01T01:02:03+01:00", pen="1p,red")
+    fig.solar(terminator_datetime="2020-01-01T01:02:03-01:00", pen="1p,blue")
+    fig.solar(
+        terminator_datetime=datetime.datetime(
+            2020, 1, 1, 1, 2, 3, tzinfo=datetime.timezone(datetime.timedelta(hours=2))
+        ),
+        pen="1p,lightred",
+    )
+    fig.solar(
+        terminator_datetime=datetime.datetime(
+            2020, 1, 1, 1, 2, 3, tzinfo=datetime.timezone(datetime.timedelta(hours=-2))
+        ),
+        pen="1p,lightblue",
+    )
+    return fig