quantui 0.5.2__tar.gz → 0.6.0__tar.gz

{quantui-0.5.2 → quantui-0.6.0}/CHANGELOG.md

@@ -7,6 +7,61 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-08-04
+
+### Added
+
+- **Save orbital isosurfaces as images.** A **Save PNG** button sits under the
+  viewer and captures exactly what you are looking at, camera and all. Options
+  for the filename, the DPI written into the file (72–600; this sets the
+  *print* size, not the pixel count), and a transparent background for dropping
+  a figure onto a slide — the transparency applies only to the saved file, so
+  the viewer on screen is unchanged.
+- **Tunable isosurface resolution** — Coarse/Medium/Fine/Very fine grids,
+  remembered between launches.
+- **Live isosurface controls**: isovalue, opacity and a colour-scheme dropdown
+  (GaussView orange/blue, Avogadro/Jmol red/blue, journal yellow/blue, and
+  more). All three update the existing viewer without recomputing anything, so
+  the orientation you rotated into is preserved.
+- **The isovalue is explained in chemical terms.** Beside the slider, QuantUI
+  reports what fraction of the orbital's density the surface actually encloses
+  — "encloses 98.4% of the density" — because an amplitude threshold is rarely
+  the question anyone has.
+- **A Cancel button** for isosurface generation. The underlying PySCF call
+  cannot be interrupted, so the computation finishes in the background, but its
+  result is discarded and the controls come back immediately.
+- **The molecule is shown before you generate anything**, so the panel is never
+  empty — and you can orient the structure first, since that view carries into
+  the isosurface.
+
+### Changed
+
+- **Orbital isosurfaces are py3Dmol only.** The Plotly renderer is no longer
+  selectable for them: it downsamples the volume by construction, and it cannot
+  carry the new image export. Plotly remains available for the molecule viewers.
+- **Exported animations now match what you saw.** Vibrational modes and
+  optimization trajectories both export from py3Dmol — the renderer that drew
+  them on screen — instead of being rebuilt in Plotly. Exported files are also
+  now complete HTML documents declaring UTF-8, so labels no longer risk
+  mojibake when opened from disk.
+- **For geometry optimizations, the Orbital Isosurface panel opens by default**
+  on the Analysis tab.
+- **Isosurface viewers are framed** like the other 3-D viewers, and generating a
+  new one dims the current one in place rather than collapsing the panel.
+
+### Fixed
+
+- **3-D backgrounds follow the theme.** The isosurface, vibrational and
+  trajectory viewers, and the Analysis-tab molecule viewer, kept their old
+  background when switching Light/Dark until something happened to redraw them.
+- **The page no longer jumps** when generating an isosurface.
+- **Isosurface changes now apply correctly.** Adjusting the isovalue, opacity or
+  colours previously layered a new surface on top of the old one, so raising the
+  isovalue appeared to do nothing, lowering opacity did nothing, and switching
+  palettes made the surface progressively brighter.
+- Very large orbital grids are dramatically lighter in the browser — the cube
+  data was being embedded three times per render.
+
 ## [0.5.2] - 2026-08-03
 
 ### Fixed
@@ -508,7 +563,8 @@ Initial public scaffolding of the QuantUI package: `quantui` package with
 `calculator.py`, basic notebook launcher, Apptainer container definition,
 MIT license, and project metadata.
 
-[Unreleased]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.5.2...HEAD
+[Unreleased]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.5.2...v0.6.0
 [0.5.2]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.4.1...v0.5.0

{quantui-0.5.2/quantui.egg-info → quantui-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantui
-Version: 0.5.2
+Version: 0.6.0
 Summary: An open-source frontend for DFT and post-HF quantum chemistry with PySCF
 Author-email: Jonathan Schultz <nccu-schultz-lab@users.noreply.github.com>
 License: MIT License

{quantui-0.5.2 → quantui-0.6.0}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantui"
-version = "0.5.2"
+version = "0.6.0"
 description = "An open-source frontend for DFT and post-HF quantum chemistry with PySCF"
 readme = "README.md"
 requires-python = ">=3.9"

{quantui-0.5.2 → quantui-0.6.0}/quantui/__init__.py

@@ -7,7 +7,7 @@ Calculations run locally in the Jupyter session — no cluster or SLURM required
 PySCF requires Linux/macOS/WSL. Windows users should use the Apptainer container.
 """
 
-__version__ = "0.5.2"
+__version__ = "0.6.0"
 
 import logging
 from typing import Any

{quantui-0.5.2 → quantui-0.6.0}/quantui/app.py

@@ -147,6 +147,9 @@ from quantui.app_exports import (
 from quantui.app_exports import (
     on_iso_export_cube as _exp_on_iso_export_cube,
 )
+from quantui.app_exports import (
+    on_orb_png_captured as _exp_on_orb_png_captured,
+)
 from quantui.app_formatters import (
     format_freq_result as _fmt_freq_result,
 )
@@ -333,6 +336,12 @@ from quantui.app_visualization import (
 from quantui.app_visualization import (
     on_ir_mode_changed as _viz_on_ir_mode_changed,
 )
+from quantui.app_visualization import (
+    on_iso_appearance_changed as _viz_on_iso_appearance_changed,
+)
+from quantui.app_visualization import (
+    on_iso_cancel as _viz_on_iso_cancel,
+)
 from quantui.app_visualization import (
     on_iso_generate as _viz_on_iso_generate,
 )
@@ -360,6 +369,9 @@ from quantui.app_visualization import (
 from quantui.app_visualization import (
     render_vib_mode as _viz_render_vib_mode,
 )
+from quantui.app_visualization import (
+    rerender_3d_scenes_for_theme as _viz_rerender_3d_scenes_for_theme,
+)
 from quantui.app_visualization import (
     show_ir_spectrum as _viz_show_ir_spectrum,
 )
@@ -1628,9 +1640,31 @@ class QuantUIApp:
             ("Isosurface", "_pop_isosurface", False),
         ],
         "geometry_opt": [
-            ("Trajectory", "_pop_geo_trajectory", True),
+            # ORDER MATTERS: the FIRST entry whose populator returns True and
+            # carries auto_select=True becomes the default panel (see the rules
+            # above). Isosurface therefore leads (requested 2026-08-04); an
+            # earlier attempt put it last, which did nothing because Trajectory
+            # had already claimed the selection.
+            #
+            # Trajectory keeps auto_select=True as the fallback: when a result
+            # has no orbital data, _pop_isosurface returns False, Isosurface
+            # never activates, and Trajectory becomes the default instead.
+            # ORDER IS LOAD-BEARING TWICE OVER.
+            #
+            # 1. Execution: _pop_energies calls show_orbital_diagram, which is
+            #    what populates _last_orb_mo_coeff / _mol_atom / _mol_basis —
+            #    the very state _pop_isosurface checks. Energies MUST run
+            #    first, or Isosurface reports "required data is missing" on a
+            #    result that has it. (Putting Isosurface first did exactly
+            #    that, 2026-08-04.)
+            # 2. Selection: the FIRST entry with auto_select=True that returns
+            #    True becomes the default panel. Energies is False, so
+            #    Isosurface is the first candidate and opens by default —
+            #    which is the request — while Trajectory keeps True as the
+            #    fallback for results with no orbital data.
             ("Energies", "_pop_energies", False),
-            ("Isosurface", "_pop_isosurface", False),
+            ("Isosurface", "_pop_isosurface", True),
+            ("Trajectory", "_pop_geo_trajectory", True),
         ],
         "frequency": [
             ("Vibrational", "_pop_vibrational", True),
@@ -1979,6 +2013,27 @@ class QuantUIApp:
         )
         # Cube + bundle exports
         self._iso_export_cube_btn.on_click(self._on_iso_export_cube)
+        self._iso_cancel_btn.on_click(self._safe_cb(self._on_iso_cancel))
+        # PNG capture arrives from the browser, so there is no button to bind
+        # here — the viewer's own Save-PNG button posts into this Textarea and
+        # ipywidgets syncs it back, firing this observer (ORBX.1).
+        self._orb_png_inbox.observe(
+            self._safe_cb(self._on_orb_png_captured), names="value"
+        )
+        # Persist the grid choice so it survives a relaunch (ORBX.2).
+        self._iso_resolution_dd.observe(
+            self._safe_cb(self._on_iso_resolution_changed), names="value"
+        )
+        # Appearance controls redraw from the cube on disk — no cubegen — so
+        # they can respond directly rather than behind an Apply button.
+        for _w in (
+            self._iso_isovalue_slider,
+            self._iso_opacity_slider,
+            self._iso_colors_dd,
+            # NOT _iso_png_transparent: it is an export-only option, applied at
+            # capture time. Observing it here would change the live viewer.
+        ):
+            _w.observe(self._safe_cb(self._on_iso_appearance_changed), names="value")
         self._export_bundle_btn.on_click(self._on_export_bundle)
 
     # ── Files tab ────────────────────────────────────────────────────────
@@ -2746,8 +2801,18 @@ class QuantUIApp:
         _last_pes = getattr(self, "_last_pes_result", None)
         if _last_pes is not None:
             self._show_pes_scan_result(_last_pes)
-        # Re-render 3D molecule viewer so scene_bgcolor updates immediately.
-        self._refresh_calc_mol_viewer()
+        # Re-render BOTH 3D molecule viewers so scene_bgcolor updates
+        # immediately. This used to call _refresh_calc_mol_viewer directly,
+        # which covered the Calculate tab only — the Analysis-tab viewer kept
+        # its old background until something else happened to redraw it.
+        # _rerender_3d_views already handled both; it just was not reached from
+        # here. Reported 2026-08-04.
+        self._rerender_3d_views()
+        # ...and the isosurface / vibrational viewers, which bake the same
+        # colour into their generated HTML. Without this they keep the old
+        # background until the user regenerates — reported 2026-08-04. Both
+        # re-render from cached inputs; neither re-runs a calculation.
+        _viz_rerender_3d_scenes_for_theme(self)
 
     def _initialize_viz_state_from_preference(self) -> None:
         """Align _viz_backend and the three preference widgets with the
@@ -3313,6 +3378,28 @@ class QuantUIApp:
     def _on_export_pdb(self, btn) -> None:
         _exp_on_export_pdb(self, btn)
 
+    def _on_iso_cancel(self, btn) -> None:
+        _viz_on_iso_cancel(self, btn)
+
+    def _on_iso_appearance_changed(self, change) -> None:
+        _viz_on_iso_appearance_changed(self, change)
+
+    def _on_orb_png_captured(self, change) -> None:
+        _exp_on_orb_png_captured(self, change)
+
+    def _on_iso_resolution_changed(self, change) -> None:
+        """Persist the isosurface grid choice.
+
+        Saved on change rather than at generate time so the preference sticks
+        even if the user picks a grid and then closes the app without running
+        anything.
+        """
+        new_val = (change or {}).get("new")
+        if not new_val or new_val == self._user_settings.viz.iso_resolution:
+            return
+        self._user_settings.viz.iso_resolution = str(new_val)
+        self._user_settings.save()
+
     def _on_iso_export_cube(self, btn) -> None:
         _exp_on_iso_export_cube(self, btn)
 

{quantui-0.5.2 → quantui-0.6.0}/quantui/app_builders.py

@@ -14,6 +14,20 @@ from quantui import molecule_library as _ml
 from quantui import theme as _theme
 from quantui.help_content import HELP_TOPICS
 from quantui.live_log import LiveLog
+from quantui.orbital_visualization import (
+    DEFAULT_ORBITAL_COLORS as _DEFAULT_ORBITAL_COLORS,
+)
+from quantui.orbital_visualization import (
+    ISO_RESOLUTION_OPTIONS as _ISO_RESOLUTION_OPTIONS,
+)
+from quantui.orbital_visualization import (
+    ORBITAL_COLOR_OPTIONS as _ORBITAL_COLOR_OPTIONS,
+)
+
+# Class on the hidden Textarea that receives PNG data URIs from the
+# viewer's Save-PNG button. Shared with the JS that writes into it, so
+# it is defined once here and passed down rather than spelled twice.
+_ORB_PNG_INBOX_CLASS = "quantui-orb-png-inbox"
 
 # Friendlier labels for the library category filter.
 _CATEGORY_LABELS = {
@@ -1541,6 +1555,20 @@ def build_run_section(app: Any, *, layout_fn: Any) -> None:
     )
 
 
+def _persisted_iso_resolution(app: Any) -> str:
+    """The saved isosurface grid preset, or the default if anything is off.
+
+    Read off the app rather than threaded in as a parameter: this builder takes
+    no settings arguments, and adding one for a single control would mean
+    touching every caller. A missing or invalid value must never stop the panel
+    from building — a broken preference should cost the preference, not the UI.
+    """
+    try:
+        return str(app._user_settings.viz.iso_resolution)
+    except Exception:  # noqa: BLE001 — settings must never gate widget creation
+        return "medium"
+
+
 def build_results_section(app: Any, *, layout_fn: Any) -> None:
     """Build results and analysis tab panels/widgets."""
 
@@ -1822,7 +1850,9 @@ def build_results_section(app: Any, *, layout_fn: Any) -> None:
             ),
             app._orb_toggle,
             app._orb_index_input,
-            app._orb_iso_output,
+            # The viewer is NOT here. It sits below the Generate button in
+            # iso_body, so the button stays next to the orbital selector rather
+            # than being pushed ~620px down the page by the rendered viewer.
         ],
         layout=layout_fn(display="none", margin="8px 0 0 0"),
     )
@@ -1853,6 +1883,17 @@ def build_results_section(app: Any, *, layout_fn: Any) -> None:
     # result dir under a friendly name (HOMO.cube / LUMO.cube / etc.).
     # Disabled until the first isosurface generation populates
     # ``app._last_cube_path``.
+    # Cancel abandons an in-flight generation. cubegen itself cannot be
+    # interrupted mid-call, so this bumps the render token — the worker's
+    # result is discarded on arrival and the UI is freed immediately, which is
+    # what "cancel" means to the person waiting.
+    app._iso_cancel_btn = widgets.Button(
+        description="Cancel",
+        icon="times",
+        button_style="warning",
+        tooltip="Abandon this isosurface generation and restore the controls.",
+        layout=layout_fn(width="110px", display="none", margin="8px 0 4px 0"),
+    )
     app._iso_export_cube_btn = widgets.Button(
         description="Export cube",
         icon="download",
@@ -1863,6 +1904,119 @@ def build_results_section(app: Any, *, layout_fn: Any) -> None:
         ),
         layout=layout_fn(width="160px", margin="8px 0 4px 8px"),
     )
+    # Cubegen grid (ORBX.2). Persisted, so someone who works at "fine" does not
+    # re-pick it every launch. The labels carry the cost multiplier because the
+    # jump is steep — 100³ is ~4.6× the grid work of the 60³ default — and the
+    # wait is the thing users are choosing between.
+    _iso_res_opts = list(_ISO_RESOLUTION_OPTIONS)
+    app._iso_resolution_dd = widgets.Dropdown(
+        options=_iso_res_opts,
+        value=_persisted_iso_resolution(app),
+        description="Grid:",
+        style={"description_width": "45px"},
+        tooltip=(
+            "Cube grid density. Higher is smoother but slower to compute; "
+            "cost scales with the cube of this number."
+        ),
+        layout=layout_fn(width="290px", margin="8px 0 4px 0"),
+    )
+
+    # ── Isosurface appearance (ORBX.2 cont.) ────────────────────────────
+    # Both re-render from the cube already on disk — no cubegen — so dragging
+    # either is fast. That is the whole reason they can be sliders rather than
+    # an "apply" button.
+    app._iso_isovalue_slider = widgets.FloatLogSlider(
+        value=0.02,
+        base=10,
+        min=-3.0,  # 0.001
+        max=-0.7,  # ~0.2
+        step=0.02,
+        description="Isovalue:",
+        readout_format=".4f",
+        continuous_update=False,  # re-render on release, not per pixel
+        style={"description_width": "70px"},
+        layout=layout_fn(width="330px"),
+    )
+    # An isovalue is an amplitude threshold, which is not the question people
+    # actually have — "how much of the orbital is inside this surface?" is.
+    # That is the integral of |psi|^2 enclosed, computed from the same cube.
+    app._iso_enclosed_label = widgets.HTML(
+        value="", layout=layout_fn(margin="0 0 0 6px")
+    )
+    app._iso_colors_dd = widgets.Dropdown(
+        options=list(_ORBITAL_COLOR_OPTIONS),
+        value=_DEFAULT_ORBITAL_COLORS,
+        description="Colours:",
+        style={"description_width": "70px"},
+        layout=layout_fn(width="330px"),
+    )
+    app._iso_opacity_slider = widgets.FloatSlider(
+        value=0.85,
+        min=0.1,
+        max=1.0,
+        step=0.05,
+        description="Opacity:",
+        readout_format=".2f",
+        continuous_update=False,
+        style={"description_width": "70px"},
+        layout=layout_fn(width="330px"),
+    )
+
+    # ── PNG export options (ORBX.1 cont.) ───────────────────────────────
+    app._iso_png_name = widgets.Text(
+        value="",
+        placeholder="(defaults to the orbital label, e.g. HOMO)",
+        description="PNG name:",
+        style={"description_width": "70px"},
+        layout=layout_fn(width="330px"),
+    )
+    app._iso_png_transparent = widgets.Checkbox(
+        value=False,
+        description="Transparent background (export only)",
+        indent=False,
+        tooltip=(
+            "The saved PNG has no background, so the figure drops onto a slide "
+            "or a coloured page. The viewer on screen is unchanged — "
+            "transparency is applied at capture, then undone."
+        ),
+        layout=layout_fn(width="330px"),
+    )
+    # Read by the capture JS (see _PNG_CAPTURE_JS), which looks for
+    # "<inbox-class>-transparent input". That keeps the decision on the browser
+    # side at the moment of capture, with no kernel round-trip.
+    app._iso_png_transparent.add_class(f"{_ORB_PNG_INBOX_CLASS}-transparent")
+    # DPI is metadata (the PNG pHYs chunk): it sets the PRINT size, not the
+    # pixel count. 300 dpi is the usual journal floor. Labelled with the
+    # resulting print width so the number means something.
+    app._iso_png_dpi = widgets.Dropdown(
+        options=[
+            ("72 dpi — screen", 72),
+            ("150 dpi — draft print", 150),
+            ("300 dpi — journal standard", 300),
+            ("600 dpi — high-res print", 600),
+        ],
+        value=300,
+        description="PNG dpi:",
+        style={"description_width": "70px"},
+        layout=layout_fn(width="330px"),
+    )
+
+    # Hidden inbox for client-side PNG capture (ORBX.1). The JS in the rendered
+    # isosurface writes a data URI into this Textarea's DOM node and dispatches
+    # an 'input' event; ipywidgets' own view then syncs `value` to the kernel.
+    # It is a real widget (not display:none on the outer box) because the view
+    # must exist in the DOM for that sync to happen at all.
+    app._orb_png_inbox = widgets.Textarea(
+        value="", layout=layout_fn(width="1px", height="1px", visibility="hidden")
+    )
+    app._orb_png_inbox.add_class(_ORB_PNG_INBOX_CLASS)
+
+    # Hidden Output that carries one-shot Javascript to the live viewer
+    # (isovalue / opacity / colours / background). Mirrors _vib_js_bridge.
+    app._iso_js_bridge = widgets.Output(
+        layout=layout_fn(width="0px", height="0px", visibility="hidden")
+    )
+
     app._iso_export_status = widgets.HTML(
         value="", layout=layout_fn(margin="0 0 0 8px")
     )
@@ -1884,12 +2038,31 @@ def build_results_section(app: Any, *, layout_fn: Any) -> None:
             widgets.HBox(
                 [
                     app._iso_generate_btn,
+                    app._iso_cancel_btn,
                     app._iso_spinner,
                     app._iso_export_cube_btn,
                     app._iso_export_status,
                 ],
                 layout=layout_fn(align_items="center", gap="6px"),
             ),
+            app._orb_iso_output,
+            app._iso_resolution_dd,
+            widgets.HBox(
+                [app._iso_isovalue_slider, app._iso_enclosed_label],
+                layout=layout_fn(align_items="center"),
+            ),
+            app._iso_opacity_slider,
+            app._iso_colors_dd,
+            widgets.HTML(
+                '<p style="color:#555;font-size:12px;margin:8px 0 2px">'
+                "<b>PNG export</b> — the Save PNG button under the viewer "
+                "captures the view exactly as you have rotated it.</p>"
+            ),
+            app._iso_png_name,
+            app._iso_png_dpi,
+            app._iso_png_transparent,
+            app._orb_png_inbox,
+            app._iso_js_bridge,
         ],
         layout=layout_fn(padding="8px"),
     )

{quantui-0.5.2 → quantui-0.6.0}/quantui/app_exports.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 from pathlib import Path
 from typing import Any
 
@@ -126,6 +127,129 @@ def export_molecule_and_label(app: Any) -> tuple[Any, str, str]:
     return mol, method, basis
 
 
+# Data URIs from 3Dmol's pngURI(). Anchored and length-bounded: this value
+# arrives from the browser, and while it is the user's own page rather than an
+# untrusted party, decoding whatever lands in a widget traitlet without
+# checking its shape is not a habit worth having.
+logger = logging.getLogger(__name__)
+
+_PNG_URI_PREFIX = "data:image/png;base64,"
+_MAX_PNG_BYTES = 64 * 1024 * 1024
+
+
+def _requested_dpi(app: Any) -> int:
+    try:
+        return int(getattr(app._iso_png_dpi, "value", 300))
+    except Exception:  # noqa: BLE001 — a missing widget must not stop a save
+        return 300
+
+
+def _with_dpi(raw: bytes, dpi: int) -> bytes:
+    """Stamp *dpi* into the PNG's pHYs chunk.
+
+    ⚠️ This sets the PRINT size, not the pixel count. The capture is whatever
+    the canvas holds, and re-encoding cannot invent detail — at 300 dpi a
+    760 px image simply declares itself 2.5 inches wide. That is what makes a
+    figure land at the right physical size in Word or LaTeX instead of being
+    scaled by hand, which is the actual complaint DPI settings answer.
+
+    Pillow is already a dependency (via matplotlib). If anything goes wrong the
+    original bytes are returned: a PNG without the metadata is a mild loss, a
+    failed export is not.
+    """
+    try:
+        import io
+
+        from PIL import Image
+
+        with Image.open(io.BytesIO(raw)) as im:
+            im.load()
+            buf = io.BytesIO()
+            # RGBA is preserved, so a transparent capture stays transparent.
+            im.save(buf, format="PNG", dpi=(dpi, dpi))
+            return buf.getvalue()
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("could not stamp %d dpi into the PNG: %s", dpi, exc)
+        return raw
+
+
+def on_orb_png_captured(app: Any, change: dict) -> None:
+    """Write a PNG captured from the live isosurface viewer (ORBX.1).
+
+    Fires when the viewer's Save-PNG button writes a data URI into the hidden
+    inbox Textarea. The image is whatever the user is actually looking at,
+    camera included — which is the entire reason capture happens client-side
+    rather than by re-rendering server-side.
+
+    The inbox is cleared afterwards so saving the same view twice re-triggers
+    the traitlet (an unchanged value would not fire ``observe``).
+    """
+    import base64
+    import binascii
+
+    uri = (change or {}).get("new") or ""
+    if not uri:
+        return
+
+    def _fail(msg: str) -> None:
+        app._iso_export_status.value = f'<span style="color:#b22">{msg}</span>'
+        # Clear even on failure, or a retry of the identical capture is silent.
+        _clear_inbox(app)
+
+    def _clear_inbox(a: Any) -> None:
+        box = getattr(a, "_orb_png_inbox", None)
+        if box is not None and box.value:
+            box.value = ""
+
+    if not uri.startswith(_PNG_URI_PREFIX):
+        logger.warning("PNG capture: unexpected data URI prefix")
+        _fail("Capture failed (unexpected image format).")
+        return
+    if len(uri) > _MAX_PNG_BYTES:
+        _fail("Capture failed (image too large).")
+        return
+
+    result_dir = getattr(app, "_last_result_dir", None)
+    if result_dir is None or not isinstance(result_dir, Path):
+        _fail("No result folder available.")
+        return
+
+    try:
+        raw = base64.b64decode(uri[len(_PNG_URI_PREFIX) :], validate=True)
+    except (binascii.Error, ValueError) as exc:
+        logger.warning("PNG capture: could not decode payload: %s", exc)
+        _fail("Capture failed (corrupt image data).")
+        return
+
+    # Filename: the user's, falling back to the orbital label. Sanitised
+    # either way — this builds a filesystem path, and a name typed into a text
+    # box is exactly where a stray "../" or "/" arrives.
+    # str() rather than trusting the attribute: this runs against real widgets
+    # in the app but also against partially-built ones, and a non-string here
+    # would turn a successful capture into a traceback on the .strip() below.
+    typed = getattr(getattr(app, "_iso_png_name", None), "value", "")
+    typed = typed.strip() if isinstance(typed, str) else ""
+    label = typed or getattr(app, "_last_cube_orbital", None) or "orbital"
+    label = str(label)
+    if label.lower().endswith(".png"):
+        label = label[:-4]
+    safe = "".join(c if c.isalnum() or c in "-_+ " else "_" for c in str(label))
+    safe = safe.strip() or "orbital"
+    dest = Path(result_dir) / f"{safe}.png"
+
+    raw = _with_dpi(raw, _requested_dpi(app))
+    try:
+        dest.write_bytes(raw)
+    except OSError as exc:
+        logger.warning("PNG capture: could not write %s: %s", dest, exc)
+        _fail("Could not write the image (see log).")
+        return
+
+    logger.info("Saved orbital PNG: %s (%d bytes)", dest, len(raw))
+    app._iso_export_status.value = f'<span style="color:#2a7">Saved: {dest.name}</span>'
+    _clear_inbox(app)
+
+
 def on_iso_export_cube(app: Any, btn: Any) -> None:
     """Copy the last-generated cube file to the result folder.