[seisman]

Implement the Perspective class for the -p option. See #4176 for related discussions.

Notes:

• level is used rather than zlevel, because strictly speaking it can set the level for x-, y-, or z-planes.
• +w/+v are implemented as refpoint + cstype

Preview:

• https://pygmt-dev--4201.org.readthedocs.build/en/4201/api/generated/pygmt.params.Perspective.html
• https://pygmt-dev--4201.org.readthedocs.build/en/4201/api/generated/pygmt.Figure.basemap.html

[Copilot]

Pull request overview

Copilot reviewed 32 out of 32 changed files in this pull request and generated no new comments.

Suppressed comments (2)

pygmt/src/plot.py:63

• The updated type annotation for perspective drops str, but perspective is still accepted as a raw GMT -p string by the alias system (AliasSystem.add_common uses Alias(value, sep="/", size={2, 3}), which treats strings as scalars). Dropping str makes the public typing inconsistent with runtime behavior and removes the only typed way to pass advanced -p modifiers not covered by Perspective yet (e.g., +w/+v).

    panel: int | Sequence[int] | bool = False,
    incols: int | str | Sequence[int | str] | None = None,
    perspective: Perspective | float | Sequence[float] | bool = False,
    transparency: float | Sequence[float] | bool | None = None,

pygmt/helpers/decorators.py:283

• The perspective docstring no longer mentions that callers can still pass a raw string with the full GMT -p syntax (including +w/+v modifiers). Since the alias system still accepts strings for p (see pygmt/alias.py:374-375), this makes the documentation misleading and removes the only documented path for features not yet covered by Perspective.

            Accepts a :class:`pygmt.params.Perspective` object, a single value
            *azimuth*, a sequence of two values (*azimuth*, *elevation*), a sequence of
            three values (*azimuth*, *elevation*, *level*).

            - *azimuth*: Azimuth angle of the viewpoint in degrees [Default is 180,

[yvonnefroehlich]

+w/+v are not implemented yet, but they're mainly for animations so not frequently used.

I personally like +w quite much for rotations around the z-axis (i.e., within the paper plane).

(I) Rotate around the center of the plot, as we do it for the PyGMT logo:

pygmt/pygmt/src/pygmtlogo.py

Line 44 in 6f49e84

perspective = "30+w0/0"

(II) Rotate plotting symbols

https://github.com/yvonnefroehlich/gmt-pygmt-plotting/blob/e206f040ef9d99d3ff779e2b5e952b127e32410e/003_taup/taup_path_curve.py#L454

perspective_receiver = f"{angle_receiver}+w{x_receiver}/{y_receiver}"

[seisman]

+w/+v are not implemented yet, but they're mainly for animations so not frequently used.

I personally like +w quite much for rotations around the z-axis (i.e., within the paper plane).

(I) Rotate around the center of the plot, as we do it for the PyGMT logo:

pygmt/pygmt/src/pygmtlogo.py

Line 44 in 6f49e84

perspective = "30+w0/0"

(II) Rotate plotting symbols

https://github.com/yvonnefroehlich/gmt-pygmt-plotting/blob/e206f040ef9d99d3ff779e2b5e952b127e32410e/003_taup/taup_path_curve.py#L454

perspective_receiver = f"{angle_receiver}+w{x_receiver}/{y_receiver}"

That's a good use case. Please see my comments at #4176 (comment).