Figure.timestamp: Plot GMT timestamp logo

[seisman]

The Figure.timestamp method is a high-level wrapper for GMT's common option -U. With this method, we should disallow -U option in all plotting method.

The syntax of -U

The full syntax of the -U option is:

-U[<label>][+c][+t<text>][+j<just>][+o<dx>[/<dy>]]

• label: The label after the GMT timestamp logo [Add Figure.timestamp to plot the GMT timestamp logo #2208]
• +c: used to append the raw GMT command (e.g., gmt coast -R... -J...) after the timestamp logo. It's not implemented because (1) It's rarely used. A figure is usually produced by multiple commands, so it makes no sense to show the command string of a single command; (2) It makes little sense to show the raw GMT command string for a figure produced by a Python script; (3) It's also impossible to implement it in the Figure.timestamp() function. [Unimplemented]
• +j<just>: The justification of the timestamp logo [Add Figure.timestamp to plot the GMT timestamp logo #2208]
• +o<dx>/<dy>: timestamp offset [Add Figure.timestamp to plot the GMT timestamp logo #2208]
• +t<text>: The text string in the GMT logo, added in GMT 6.5.0 [Add Figure.timestamp to plot the GMT timestamp logo #2208]

There are four GMT defaults that can affect the timestamp logo.

• MAP_LOGO: controls if a timestamp logo should be plotted [Not implmented since it makes no sense here]
• MAP_LOGO_POS: defaults to BL/-54p/-54p. It's equivalent to setting the +j and +o modifiers. [Already implmented]
• FONT_LOGO can control the font ID of the text strings. It's implemented by passing --FONT_LOGO=xxx to the GMT C API. [Add Figure.timestamp to plot the GMT timestamp logo #2208]
• FORMAT_TIME_STAMP can control the format of the timestamp. It's implemented by passing --FORMAT_TIME_STAMP to the GMT C API. [Add Figure.timestamp to plot the GMT timestamp logo #2208]

Function signature

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

Implementation notes

1. The method is implemented by calling gmt plot -T -U...
2. An upstream bug of the +o modifier for GMT <=6.4.0 (-U doesn't work with a single offset value gmt#7107).
3. For GMT<=6.4.0, FONT_LOGO can only change the font ID, but since GMT 6.5.0, it can also change both the font ID and color (but not the font size). See Allow FONT_LOGO to change font color gmt#7125
4. In GMT 6.5.0, a new modifier +t will be added. See Allow FONT_LOGO to change font color gmt#7125.

Issues to track

• Initial feature implementation PR Add Figure.timestamp to plot the GMT timestamp logo #2208
• All functionality are implemented Add Figure.timestamp to plot the GMT timestamp logo #2208
• Add a tutorial/gallery Figure.timestamp: Improve documentation and gallery example #2434
• Docstrings are complete and easy to read Figure.timestamp: Improve documentation and gallery example #2434
• Full type hints Figure.timestamp: Improve documentation and gallery example #2434

[seisman]

Sorry, incorrectly clicked a button. Closing.