Select the projection mode with a sum type

.gitignore

@@ -42,6 +42,9 @@ htmlcov/
 # Planning docs
 RESTRUCTURE.md
 PLAN-*.md
+OBLIQUE_PROJECTION.md
+.superpowers/
+docs/superpowers/
 
 # OS
 .DS_Store

README.md

@@ -107,7 +107,7 @@ scene.render_mpl("si.pdf")
 ```python
 scene.view.look_along([1, 1, 0])   # View along [110]
 scene.view.zoom = 1.5              # Zoom in
-scene.view.perspective = 0.3       # Mild perspective
+scene.view.set_perspective(0.3)    # Mild perspective
 scene.render_mpl("rotated.svg")
 ```
 

docs/_static/generate_images.py

@@ -411,8 +411,7 @@ def logo_scene() -> StructureScene:
     scene.set_atom_data("gradient", by_index=data)
 
     scene.view.look_along(look_dir)
-    scene.view.perspective = 0.12
-    scene.view.view_distance = 5.0
+    scene.view.set_perspective(0.12, 5.0)
 
     return scene
 
@@ -652,13 +651,13 @@ def generate_docs_images() -> None:
         figsize=(3, 3), dpi=150,
     )
     print(f"  wrote {OUT / 'perovskite_ortho.svg'}")
-    perov_plain.view.perspective = 0.5
+    perov_plain.view.set_perspective(0.5)
     perov_plain.render_mpl(
         OUT / "perovskite_perspective.svg",
         figsize=(3, 3), dpi=150,
     )
     print(f"  wrote {OUT / 'perovskite_perspective.svg'}")
-    perov_plain.view.perspective = 0.0  # Reset
+    perov_plain.view.set_orthographic()  # Reset
 
     # 6–9. Per-atom colouring examples: ring of atoms.
     n = 16

docs/api.rst

@@ -43,6 +43,18 @@ Data model
 .. autoclass:: ViewState
    :members:
 
+.. autoclass:: Orthographic
+   :members:
+
+.. autoclass:: Perspective
+   :members:
+
+.. data:: Projection
+
+   Type alias for the projection modes:
+   ``Orthographic | Perspective``.  Use it to annotate code that
+   accepts any projection.
+
 .. autoclass:: hofmann.model.atom_data.AtomData
    :members: n_atoms, ranges, labels
 

docs/changelog.rst

@@ -1,6 +1,29 @@
 Changelog
 =========
 
+Unreleased
+----------
+
+- **Breaking:** Projection mode is now selected with a single
+  :attr:`~hofmann.ViewState.projection` field taking
+  :class:`~hofmann.Orthographic` (the default) or
+  :class:`~hofmann.Perspective`, set with
+  :meth:`~hofmann.ViewState.set_orthographic` or
+  :meth:`~hofmann.ViewState.set_perspective`.  The ``perspective`` and
+  ``view_distance`` attributes are removed; ``perspective = 0.3``
+  becomes ``set_perspective(0.3)`` and ``perspective = 0.0`` becomes
+  ``set_orthographic()``.  A ``view_distance`` set alongside a
+  perspective strength moves into the same call:
+  ``set_perspective(0.3, 5.0)``.  A perspective strength no longer
+  doubles as an on/off switch, so a viewing distance can no longer be
+  set on a view that ignores it.
+
+- In interactive sessions, the ``d`` and ``D`` viewing-distance keys
+  now act only in perspective mode, where previously they adjusted a
+  distance that had no effect until perspective was switched on.
+  ``P`` returns to an orthographic view at the bottom of the ladder,
+  as before.
+
 0.20.0
 ------
 

docs/interactive.rst

@@ -75,9 +75,10 @@ Pan and perspective
    * - Shift + Arrow keys
      - Pan the view
    * - ``p`` / ``P``
-     - Increase / decrease perspective strength
+     - Increase / decrease perspective strength (``P`` returns to an
+       orthographic view)
    * - ``d`` / ``D``
-     - Increase / decrease viewing distance
+     - Increase / decrease viewing distance (perspective only)
 
 Display toggles
 ^^^^^^^^^^^^^^^

docs/rendering.rst

@@ -42,19 +42,19 @@ Perspective
 
 .. code-block:: python
 
-   scene.view.perspective = 0.3  # Mild perspective
-   scene.view.perspective = 0.0  # Orthographic (default)
+   scene.view.set_perspective(0.3)  # Mild perspective
+   scene.view.set_orthographic()    # Parallel projection (default)
 
 .. list-table::
    :widths: 50 50
 
    * - .. figure:: _static/perovskite_ortho.svg
 
-          Orthographic (``perspective=0.0``)
+          Orthographic (the default)
 
      - .. figure:: _static/perovskite_perspective.svg
 
-          Perspective (``perspective=0.5``)
+          Perspective (``set_perspective(0.5)``)
 
 
 Render styles

src/hofmann/__init__.py

@@ -32,10 +32,13 @@
     Frame,
     LegendItem,
     LegendStyle,
+    Orthographic,
+    Perspective,
     Polyhedron,
     PolygonLegendItem,
     PolyhedronLegendItem,
     PolyhedronSpec,
+    Projection,
     RenderStyle,
     SlabClipMode,
     StructureScene,
@@ -61,10 +64,13 @@
     "Frame",
     "LegendItem",
     "LegendStyle",
+    "Orthographic",
+    "Perspective",
     "Polyhedron",
     "PolygonLegendItem",
     "PolyhedronLegendItem",
     "PolyhedronSpec",
+    "Projection",
     "RenderStyle",
     "SlabClipMode",
     "StructureScene",

src/hofmann/model/__init__.py

@@ -30,7 +30,12 @@
     _DEFAULT_SPACING,
 )
 from hofmann.model.structure_scene import StructureScene
-from hofmann.model.view_state import ViewState
+from hofmann.model.view_state import (
+    Orthographic,
+    Perspective,
+    Projection,
+    ViewState,
+)
 
 __all__ = [
     "AtomLegendItem",
@@ -40,15 +45,18 @@
     "BondSpec",
     "CellEdgeStyle",
     "CmapSpec",
-    "LegendItem",
-    "LegendStyle",
     "Colour",
     "Composition",
     "Frame",
-    "Polyhedron",
+    "LegendItem",
+    "LegendStyle",
+    "Orthographic",
+    "Perspective",
     "PolygonLegendItem",
+    "Polyhedron",
     "PolyhedronLegendItem",
     "PolyhedronSpec",
+    "Projection",
     "RenderStyle",
     "SlabClipMode",
     "StructureScene",