Add Figure.timestamp to plot the GMT timestamp logo #2208

seisman · 2023-02-13T05:15:22Z

I'm still unsure what's the best way to document features that require new GMT versions.

Hm. Is there a similar situation for the Julia wrapper, which can serve as an orientation?

weiji14 · 2023-03-02T04:07:37Z

The output of the justification image doesn't look correct?

All of the timestamps are on the bottom left (BL). Shouldn't they be at the four different corners?

Unlike other embellishments (e.g., inset, legend or direction rose), the timestamp logo is always located at the lower left corner of the map. I believe this is GMT's design.

See https://docs.generic-mapping-tools.org/dev/gmt.conf.html#term-MAP_LOGO_POS

Sets the justification and the position of the logo/timestamp box relative to the current plot’s lower left corner (i.e., map origin)

Interesting design choice 😅 Actually, I just realized I was thinking of position rather than justification. Maybe we should document the default offset="-54p/-54p" under the offset docstring?

The default values are clear from the function definition:

Figure.timestamp((text=None, label=None, justification='BL', offset=('-54p', '-54p'), font='Helvetica,black', timefmt='%Y %b %d %H:%M:%S')

I'm hesitate to document the defaults in the docstring.

Ah ok, was thinking of adding [Default is ('-54p', '-54p')], but it's not really needed I guess.

-Original file line number
+Diff line change
@@ Expand Up / @@ -34,6 +34,7 @@ Plotting map elements @@
         Figure.logo
         Figure.solar
         Figure.text
+        Figure.timestamp
     Plotting tabular data
     ~~~~~~~~~~~~~~~~~~~~~
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up / @@ -518,6 +518,7 @@ def _repr_html_(self): @@
             subplot,
             ternary,
             text,
+            timestamp,
             velo,
             wiggle,
         )
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up / @@ -51,6 +51,7 @@ @@
     from pygmt.src.surface import surface
     from pygmt.src.ternary import ternary
     from pygmt.src.text import text_ as text  # "text" is an argument within "text_"
+    from pygmt.src.timestamp import timestamp
     from pygmt.src.triangulate import triangulate
     from pygmt.src.velo import velo
     from pygmt.src.which import which
@@ Expand Down @@

-Original file line number
+Diff line change
@@ -0,0 +1,102 @@
+    """
+    timestamp - Plot the GMT timestamp logo.
+    """
+    from packaging.version import Version
+    from pygmt import __gmt_version__
+    from pygmt.clib import Session
+    from pygmt.exceptions import GMTInvalidInput
+    from pygmt.helpers import build_arg_string, is_nonstr_iter
+    __doctest_skip__ = ["timestamp"]
+    def timestamp(
+        self,
+        text=None,
+        label=None,
+        justification="BL",
+        offset=("-54p", "-54p"),
+        font="Helvetica,black",
+        timefmt="%Y %b %d %H:%M:%S",
+    ):
+        r"""
+        Plot the GMT timestamp logo.
+        Parameters
+        ----------
+        text : None or str
+            If ``None``, the current UNIX timestamp is shown in the GMT timestamp
+            logo. Set this parameter to replace the UNIX timestamp with a
+            custom text string instead. The text must be less than 64 characters.
+            *Requires GMT>=6.5.0*.
+        label : None or str
+            The text string shown after the GMT timestamp logo.
+        justification : str
+            Justification of the timestamp. The *justification* is a two-character
+            code that is a combination of a horizontal (**L**\ (eft),
+            **C**\ (enter), or **R**\ (ight)) and a vertical (**T**\ (op),
+            **M**\ (iddle), or **B**\ (ottom)) code.
+        offset : str or tuple
+            *offset* or (*offset_x*, *offset_y*).
+            Offset the anchor point of the timestamp by *offset_x* and *offset_y*.
+            If a single value *offset* is given, *offset_y* = *offset_x* =
+            *offset*.
+        font : str
+            Font of the timestamp and the optional label. The parameter can't
+            change the font color for GMT<=6.4.0, only the font ID.
+        timefmt : str
+            Format string for the UNIX timestamp. The format string is parsed by
+            the C function ``strftime``, so that virtually any text can be used
+            (even not containing any time information).
+        Examples
+        --------
+        >>> # Plot the GMT timestamp logo.
+        >>> import pygmt
+        >>> fig = pygmt.Figure()
+        >>> fig.timestamp()
+        >>> fig.show()
+        <IPython.core.display.Image object>
+        >>> # Plot the GMT timestamp logo with a custom label.
+        >>> fig = pygmt.Figure()
+        >>> fig.timestamp(label="Powered by PyGMT")
+        >>> fig.show()
+        <IPython.core.display.Image object>
+        """
+        self._preprocess()  # pylint: disable=protected-access
+        # Build the options passed to the "plot" module
+        kwdict = {"T": True, "U": ""}
+        if label is not None:
+            kwdict["U"] += f"{label}"
+        kwdict["U"] += f"+j{justification}"
+        if is_nonstr_iter(offset):  # given a tuple
+            kwdict["U"] += "+o" + "/".join(f"{item}" for item in offset)
+        else:  # given a single value
+            if "/" not in offset and Version(__gmt_version__) <= Version("6.4.0"):
+                # Giving a single offset doesn't work in GMT <= 6.4.0.
+                # See https://github.com/GenericMappingTools/gmt/issues/7107.
+                kwdict["U"] += f"+o{offset}/{offset}"
+            else:
+                kwdict["U"] += f"+o{offset}"
+        # The +t modifier was added in GMT 6.5.0.
+        # See https://github.com/GenericMappingTools/gmt/pull/7127.
+        if text is not None:
+            if Version(__gmt_version__) < Version("6.5.0"):
+                raise GMTInvalidInput("The parameter 'text' requires GMT>=6.5.0.")
+            if len(str(text)) > 64:
+                raise GMTInvalidInput(
+                    "The parameter 'text' must be less than 64 characters."
+                )
+            kwdict["U"] += f"+t{text}"
+        with Session() as lib:
+            lib.call_module(
+                module="plot",
+                args=build_arg_string(
+                    kwdict, confdict={"FONT_LOGO": font, "FORMAT_TIME_STAMP": timefmt}
+                ),
+            )

-Original file line number
+Diff line change
@@ -0,0 +1,4 @@
+    outs:
+    - md5: b4ca6cb54d80463606bb3d28eb077227
+      size: 1668
+      path: test_timestamp.png

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Figure.timestamp to plot the GMT timestamp logo #2208

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

seisman Feb 13, 2023

Uh oh!

yvonnefroehlich Feb 14, 2023

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

weiji14 Mar 2, 2023

Uh oh!

seisman Mar 2, 2023 •

edited

Loading

Uh oh!

weiji14 Mar 2, 2023

Uh oh!

seisman Mar 2, 2023

Uh oh!

weiji14 Mar 2, 2023

Uh oh!

-Original file line number
+Diff line change
@@ -0,0 +1,88 @@
+    """
+    Tests for Figure.timestamp.
+    """
+    import pytest
+    from packaging.version import Version
+    from pygmt import Figure, __gmt_version__
+    @pytest.fixture(scope="module", name="faketime")
+    def fixture_faketime():
+        """
+        Fake datetime that will be passed to the "timefmt" parameter, so that the
+        timestamp string always has a fixed value.
+        """
+        return "9999-99-99T99:99:99"
+    @pytest.mark.mpl_image_compare
+    def test_timestamp(faketime):
+        """
+        Test that the simplest timestamp() call works.
+        """
+        fig = Figure()
+        fig.timestamp(timefmt=faketime)
+        return fig
+    @pytest.mark.mpl_image_compare
+    def test_timestamp_label(faketime):
+        """
+        Check if the "label" parameter works.
+        """
+        fig = Figure()
+        fig.timestamp(label="Powered by PyGMT", timefmt=faketime)
+        return fig
+    @pytest.mark.mpl_image_compare
+    def test_timestamp_justification():
+        """
+        Check if the "justification" parameter works.
+        Only a subset of justification codes are tested to avoid overlapping
+        timestamps.
+        """
+        fig = Figure()
+        fig.basemap(projection="X10c/5c", region=[0, 10, 0, 5], frame=0)
+        for just in ["BL", "BR", "TL", "TR"]:
+            fig.timestamp(justification=just, timefmt=just)
+        return fig
+    @pytest.mark.mpl_image_compare
+    def test_timestamp_offset():
+        """
+        Check if the "offset" parameter works.
+        """
+        fig = Figure()
+        fig.basemap(projection="X10c/5c", region=[0, 10, 0, 5], frame="g1")
+        for offset in ["1c", "1c/2c", ("1c", "3c")]:
+            fig.timestamp(offset=offset, timefmt=f"offset={offset}")
+        return fig
+    @pytest.mark.mpl_image_compare
+    def test_timestamp_font(faketime):
+        """
+        Test if the "font" parameter works.
+        """
+        fig = Figure()
+        fig.timestamp(font="Times-Roman", label="Powered by GMT", timefmt=faketime)
+        return fig
+    @pytest.mark.skipif(
+        Version(__gmt_version__) < Version("6.5.0"),
+        reason="The 'text' parameter requires GMT>=6.5.0",
+    )
+    @pytest.mark.mpl_image_compare(filename="test_timestamp.png")
+    def test_timestamp_text(faketime):
+        """
+        Test if the "text" parameter works.
+        Requires GMT>=6.5.0.
+        """
+        fig = Figure()
+        fig.timestamp(text=faketime)
+        return fig

Add Figure.timestamp to plot the GMT timestamp logo #2208

Uh oh!

Add Figure.timestamp to plot the GMT timestamp logo #2208

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

seisman Feb 13, 2023

Choose a reason for hiding this comment

Uh oh!

yvonnefroehlich Feb 14, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

weiji14 Mar 2, 2023

Choose a reason for hiding this comment

Uh oh!

seisman Mar 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weiji14 Mar 2, 2023

Choose a reason for hiding this comment

Uh oh!

seisman Mar 2, 2023

Choose a reason for hiding this comment

Uh oh!

weiji14 Mar 2, 2023

Choose a reason for hiding this comment

Uh oh!

seisman Mar 2, 2023 •

edited

Loading