Present all three projection modes together in the docs

Tidy the documentation for oblique projection:

- README: list oblique alongside orthographic and perspective.
- rendering.rst: present all three projection modes under one Projection
  section (they had drifted into separate Perspective and Oblique
  headings), and add a perovskite oblique example image beside the
  orthographic and perspective ones.
- api.rst: add the Oblique autoclass entry and list it in the Projection
  base note.
- Drop the "cavalier"/"cabinet" terms from the docstrings, examples, and
  docs; the angle and foreshortening parameters are self-describing.
- generate_images.py: render the perovskite oblique example.

Author: bjmorgan

README.md

@@ -22,7 +22,7 @@ hofmann renders crystal and molecular structures as depth-sorted ball-and-stick
 - Coordination polyhedra with configurable shading and slab clipping
 - Unit cell wireframe rendering
 - Interactive viewer with mouse rotation, zoom, and keyboard controls
-- Orthographic and perspective projection
+- Orthographic, perspective, and oblique (axonometric) projection
 
 ## Installation
 

docs/_static/generate_images.py

@@ -7,7 +7,7 @@
 
 from hofmann import (
     AtomLegendItem, AtomStyle, AxesStyle, BondSpec, CellEdgeStyle,
-    Composition, Frame, LegendStyle, PolygonLegendItem,
+    Composition, Frame, LegendStyle, Oblique, PolygonLegendItem,
     PolyhedronLegendItem, PolyhedronSpec, RenderStyle, StructureScene,
     ViewState,
 )
@@ -645,7 +645,7 @@ def generate_docs_images() -> None:
     )
     print(f"  wrote {OUT / 'octahedron_no_half_bonds.svg'}")
 
-    # 5. Perspective: orthographic vs perspective (perovskite)
+    # 5. Projection: orthographic, perspective, oblique (perovskite)
     perov_plain.render_mpl(
         OUT / "perovskite_ortho.svg",
         figsize=(3, 3), dpi=150,
@@ -657,6 +657,12 @@ def generate_docs_images() -> None:
         figsize=(3, 3), dpi=150,
     )
     print(f"  wrote {OUT / 'perovskite_perspective.svg'}")
+    perov_plain.view.projection = Oblique(45.0, 0.5)
+    perov_plain.render_mpl(
+        OUT / "perovskite_oblique.svg",
+        figsize=(3, 3), dpi=150,
+    )
+    print(f"  wrote {OUT / 'perovskite_oblique.svg'}")
     perov_plain.view.set_orthographic()  # Reset
 
     # 6–9. Per-atom colouring examples: ring of atoms.

docs/api.rst

@@ -49,11 +49,14 @@ Data model
 .. autoclass:: Perspective
    :members:
 
+.. autoclass:: Oblique
+   :members:
+
 .. autoclass:: Projection
 
    The abstract base of the projection modes (:class:`Orthographic`,
-   :class:`Perspective`); use it to annotate code that accepts any
-   projection.
+   :class:`Perspective`, :class:`Oblique`); use it to annotate code that
+   accepts any projection.
 
 .. autoclass:: hofmann.model.atom_data.AtomData
    :members: n_atoms, ranges, labels

docs/rendering.rst

@@ -12,7 +12,7 @@ Controlling the view
 --------------------
 
 The :class:`~hofmann.ViewState` controls rotation, zoom, and
-perspective.
+projection.
 
 Rotation
 ~~~~~~~~
@@ -37,16 +37,32 @@ Zoom
 
    scene.view.zoom = 1.5  # Zoom in
 
-Perspective
-~~~~~~~~~~~
+Projection
+~~~~~~~~~~
+
+The projection mode is set on :attr:`~hofmann.ViewState.projection`,
+which takes one of three modes:
+
+- :class:`~hofmann.Orthographic` (the default) — a parallel projection
+  with no foreshortening.
+- :class:`~hofmann.Perspective` — foreshortens with distance from the
+  eye; *strength* sets the amount and *view_distance* the eye distance.
+- :class:`~hofmann.Oblique` — parallel, but draws the third axis receding
+  at an angle (axonometric), so depth reads without the distortion of
+  perspective.  *angle* (degrees, anticlockwise from +x) sets the
+  on-screen direction of the receding axis, and *foreshortening* how far
+  a unit step along it is drawn: ``1.0`` full length, ``0.5`` half,
+  ``0.0`` orthographic.  Atoms, bonds, cell edges, and the axis triad all
+  shear together.
 
 .. code-block:: python
 
-   scene.view.set_perspective(0.3)  # Mild perspective
-   scene.view.set_orthographic()    # Parallel projection (default)
+   scene.view.set_orthographic()                # Parallel (the default)
+   scene.view.set_perspective(0.3)              # Mild perspective
+   scene.view.projection = Oblique(45.0, 0.5)   # Oblique
 
 .. list-table::
-   :widths: 50 50
+   :widths: 33 33 34
 
    * - .. figure:: _static/perovskite_ortho.svg
 
@@ -56,24 +72,9 @@ Perspective
 
           Perspective (``set_perspective(0.5)``)
 
+     - .. figure:: _static/perovskite_oblique.svg
 
-Oblique
-~~~~~~~
-
-An oblique (axonometric) projection is parallel, like orthographic, but
-draws the third axis receding at an angle, so depth reads without the
-distortion of perspective.  Assign an :class:`~hofmann.Oblique`:
-
-.. code-block:: python
-
-   scene.view.projection = Oblique(45.0, 0.5)   # "cabinet"
-   scene.view.projection = Oblique(45.0, 1.0)   # "cavalier"
-
-``angle`` (degrees, anticlockwise from the +x axis) is the on-screen
-direction of the receding axis; ``foreshortening`` is how far a unit
-step along it is drawn — ``1.0`` for cavalier, ``0.5`` for cabinet,
-``0.0`` for orthographic.  Atoms, bonds, cell edges, and the axis triad
-all shear together.
+          Oblique (``Oblique(45, 0.5)``)
 
 
 Render styles

src/hofmann/model/projection.py

@@ -182,8 +182,8 @@ class Oblique(Projection):
 
     A depth-proportional shear draws two axes undistorted and the third
     receding towards *angle* on screen, foreshortened by
-    *foreshortening*.  ``foreshortening = 1.0`` is the classical
-    "cavalier" projection, ``0.5`` "cabinet", ``0.0`` orthographic.
+    *foreshortening*: ``1.0`` draws a unit receding step at full length,
+    ``0.5`` at half length, ``0.0`` recovers the orthographic projection.
 
     Attributes:
         angle: On-screen direction of the receding axis, in degrees

tests/test_rendering/test_projection.py

@@ -65,7 +65,7 @@ def test_perspective_increases_extent(self):
     def test_oblique_extent_grows_by_shear_allowance(self):
         """The shear can enlarge the bounding radius by sqrt(1 + f^2), so
         _scene_extent widens by that factor via max_magnification;
-        cavalier (f = 1) grows by sqrt(2)."""
+        f = 1 grows by sqrt(2)."""
         scene = StructureScene(
             species=["C", "C"],
             frames=[Frame(coords=np.array([