Implement the Perspective class for specifying viewpoint

[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

This PR introduces a new class-style parameter, pygmt.params.Perspective, to represent GMT’s -p perspective option in a more structured way, and wires it into the public plotting API and documentation.

Changes:

• Added Perspective (pygmt/params/perspective.py) plus unit tests to validate its string serialization and error handling.
• Updated many plotting wrappers’ perspective type annotations/imports to accept a Perspective object.
• Updated parameter documentation and the API docs index to include Perspective.

Reviewed changes

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

Show a summary per file

File	Description
pygmt/tests/test_params_perspective.py	Adds tests for Perspective string formatting and invalid plane handling.
pygmt/src/wiggle.py	Updates perspective type annotation to accept Perspective.
pygmt/src/vlines.py	Updates perspective type annotation to accept Perspective.
pygmt/src/velo.py	Updates perspective type annotation to accept Perspective.
pygmt/src/tilemap.py	Updates perspective type annotation to accept Perspective.
pygmt/src/text.py	Updates perspective type annotation to accept Perspective.
pygmt/src/ternary.py	Updates perspective type annotation to accept Perspective.
pygmt/src/solar.py	Updates perspective type annotation to accept Perspective.
pygmt/src/scalebar.py	Updates perspective type annotation to accept Perspective.
pygmt/src/rose.py	Updates perspective type annotation to accept Perspective.
pygmt/src/plot3d.py	Updates perspective type annotation to accept Perspective.
pygmt/src/plot.py	Updates perspective type annotation to accept Perspective.
pygmt/src/meca.py	Updates perspective type annotation to accept Perspective.
pygmt/src/magnetic_rose.py	Updates perspective type annotation to accept Perspective.
pygmt/src/logo.py	Updates perspective type annotation to accept Perspective.
pygmt/src/legend.py	Updates perspective type annotation to accept Perspective.
pygmt/src/image.py	Updates perspective type annotation to accept Perspective.
pygmt/src/hlines.py	Updates perspective type annotation to accept Perspective.
pygmt/src/histogram.py	Updates perspective type annotation to accept Perspective.
pygmt/src/grdview.py	Updates perspective type annotation to accept Perspective.
pygmt/src/grdimage.py	Updates perspective type annotation to accept Perspective.
pygmt/src/grdcontour.py	Updates perspective type annotation to accept Perspective.
pygmt/src/fill_between.py	Updates perspective type annotation to accept Perspective.
pygmt/src/directional_rose.py	Updates perspective type annotation to accept Perspective.
pygmt/src/contour.py	Updates perspective type annotation to accept Perspective.
pygmt/src/colorbar.py	Updates perspective type annotation to accept Perspective.
pygmt/src/coast.py	Updates perspective type annotation to accept Perspective.
pygmt/src/basemap.py	Updates perspective type annotation to accept Perspective.
pygmt/params/perspective.py	Implements the new Perspective parameter class.
pygmt/params/init.py	Exposes Perspective from pygmt.params.
pygmt/helpers/decorators.py	Updates the shared perspective parameter docstring text.
doc/api/index.rst	Adds Perspective to the “Class-style Parameters” API docs list.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[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).