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 not implemented yet, but they're mainly for animations so not frequently used.

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.