splatthis 0.2.2__tar.gz → 0.2.4__tar.gz

{splatthis-0.2.2 → splatthis-0.2.4}/CHANGELOG.md

@@ -2,6 +2,83 @@
 
 All notable changes to SplatThis are documented here.
 
+## 0.2.4 - 2026-08-01
+
+### Added
+
+- `splatthis.compositor_fidelity()`, publishing how faithfully a deployed
+  compositor reproduces the *same* splat population the internal reference
+  renderer draws. A consumer that supplies its own splats -- projecting 3D
+  Gaussians through EWA rather than fitting a bitmap -- inherits only this
+  term, not the fitting loss that dominates the headline source-fidelity
+  numbers, and previously had to re-derive it from the corpus.
+
+      compositor SSIM_sRGB   min 0.5965   median 0.7540   max 0.8991   (n=21)
+      r(content gradient)    -0.470
+
+  The correlation is the substantive result. End-to-end fidelity correlates
+  with content gradient at -0.84, which invites the conclusion that a splat
+  view's quality is predictable from what it depicts. It is not: that
+  dependence is almost entirely the fitting stage, and compositor loss is
+  broadly uniform. `is_content_predictable()` returns that judgement so it
+  cannot be re-inferred wrongly.
+
+- `--save-json` on the CLI. `ConversionRequest.save_json` was honoured but
+  unreachable from the command line.
+
+### Changed
+
+- Acceptance no longer gates on wall-clock by default. `max_runtime_sec: 60.0`
+  failed correct runs against presets that train for minutes -- 8 of 70 stored
+  manifests failed on runtime alone, including full-quality runs at SSIM 0.91.
+  Runtime remains measured under `acceptance.measured` and honoured when set
+  explicitly or by `--time-budget`.
+- Run manifests record `artifact_hash_stable` (false under MLX, with a note)
+  and `memory_guard`, so reproducibility and host-memory reductions travel with
+  the data instead of living in prose.
+- Corpus result rows carry `schema_version`, and resume re-scores anything
+  older, so an evidence level can no longer vanish across a resumed run.
+
+### Fixed
+
+- A failing SSIM silently became an inflated one: `except Exception` around the
+  skimage call fell through to a global SSIM reading ~0.10 higher, far above
+  the 0.50 acceptance floor. Only an absent dependency or an input too small to
+  carry a window may fall back now.
+- Colour transforms no longer raise a negative base to a fractional exponent on
+  the discarded branch of `np.where`, which warned during ordinary compositing.
+- The splat-orientation convention is pinned by direct tests, and
+  `mixed_primitives.py` no longer open-codes it.
+
+## 0.2.3 - 2026-08-01
+
+### Changed
+
+- The README showcase renders all four outputs at one size and adds scriptless
+  CSS as a fourth column. The previous table sized each image by its own
+  intrinsic pixels -- 476x502, 364x384 and 728x768 -- so a three-way comparison
+  appeared at three different scales.
+
+  Sized with explicit `width` attributes rather than by resampling the files:
+  PyPI's `readme_renderer` allowlist keeps `width` and `height` on `<img>`, and
+  GitHub does too, so every asset stays at native resolution and stays crisp on
+  high-DPI displays.
+
+  CSS appears as a Chromium capture rather than live. Both platforms sanitize
+  README markup through an allowlist that omits the `<style>` tag and the
+  `style` attribute -- `readme_renderer` runs `nh3.clean()` with no CSS
+  sanitizer configured -- so a build made entirely of CSS radial gradients
+  arrives as 1,615 unstyled `<div>` elements. Each cell is labelled as live
+  vector or as a capture, and captures are noted as lower bounds: they carry
+  screen-capture and rescaling losses on top of the compositor's own.
+
+### Fixed
+
+- The relative-link guard now covers `src="..."` as well as markdown `](...)`.
+  The showcase moved to raw `<img>` tags for sizing, which had made the
+  markdown-only check blind to every image on the page -- the same class of
+  defect that put 18 dead links on the 0.2.0 project page.
+
 ## 0.2.2 - 2026-08-01
 
 ### Changed

{splatthis-0.2.2 → splatthis-0.2.4}/MANIFEST.in

@@ -1,4 +1,5 @@
 include CHANGELOG.md
 include CONTRIBUTING.md
 include src/splatthis/py.typed
+recursive-include src/splatthis/data *.json
 recursive-include src/splatthis/templates *.html *.js *.svg *.xml

{splatthis-0.2.2/src/splatthis.egg-info → splatthis-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splatthis
-Version: 0.2.2
+Version: 0.2.4
 Summary: Fit 2D Gaussian splats to an image and deploy them as SVG, CSS, Canvas, a pixel runtime, or editable PowerPoint shapes
 Author: Bram Alkema
 License-Expression: MIT
@@ -47,6 +47,11 @@ Dynamic: license-file
 
 # SplatThis
 
+[![CI](https://github.com/BramAlkema/SplatThis/actions/workflows/ci.yml/badge.svg)](https://github.com/BramAlkema/SplatThis/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/splatthis)](https://pypi.org/project/splatthis/)
+[![Python](https://img.shields.io/pypi/pyversions/splatthis)](https://pypi.org/project/splatthis/)
+[![License](https://img.shields.io/pypi/l/splatthis)](https://github.com/BramAlkema/SplatThis/blob/main/LICENSE)
+
 Convert a bitmap into Gaussian splats and deploy them as browser-rendered SVG,
 scriptless CSS, browser-native Canvas primitives, an accelerated pixel runtime
 with exact CPU fallbacks, or native editable PowerPoint shapes.
@@ -71,26 +76,28 @@ deployed-fidelity claim.
 ## See it
 
 One 476x502 photograph, fitted to Gaussian splats and emitted to three
-compositors that share no rendering code. The middle image is a real SVG, not a
-raster of one — your browser is drawing 1,615 gradient ellipses.
+compositors that share no rendering code — vector, stylesheet, and DrawingML.
 
-| Source photograph | Native SVG | Native PowerPoint |
-|---|---|---|
-| ![source image](https://bramalkema.github.io/SplatThis/demo/source.png) | ![Browser-rendered SVG](https://bramalkema.github.io/SplatThis/demo/chameleon.svg) | ![PowerPoint slideshow capture](https://bramalkema.github.io/SplatThis/demo/chameleon-pptx.png) |
-| the input | **0.8665** SSIM · vector · 1.5 MB | **0.7885** SSIM · editable shapes · 161 KB |
+| Source | SVG | Scriptless CSS | PowerPoint |
+|:---:|:---:|:---:|:---:|
+| <img src="https://bramalkema.github.io/SplatThis/demo/source.png" alt="Source photograph" width="210"> | <img src="https://bramalkema.github.io/SplatThis/demo/chameleon.svg" alt="Browser-rendered SVG" width="210"> | <img src="https://bramalkema.github.io/SplatThis/demo/chameleon-css.png" alt="Chromium capture of the scriptless CSS build" width="210"> | <img src="https://bramalkema.github.io/SplatThis/demo/chameleon-pptx.png" alt="Microsoft PowerPoint slideshow capture" width="210"> |
+| the input | **0.8665** SSIM<br>vector · 1.5 MB | **0.8748** SSIM<br>DOM + CSS · 0.8 MB | **0.7885** SSIM<br>editable shapes · 161 KB |
+| — | live vector | Chromium capture | PowerPoint capture |
 
-The third image is the only screenshot here, and it has to be: it is Microsoft
-PowerPoint in slideshow, photographed, because there is no other honest way to
-show what PowerPoint actually draws. Its score is measured through that capture
-and is therefore a lower bound.
+The SVG is the real thing: your browser is drawing 1,615 gradient ellipses, not
+displaying a picture of them. The other two are captures because they have to
+be. GitHub and PyPI both sanitize README markup through an allowlist that omits
+the `<style>` tag and the `style` attribute — PyPI's `readme_renderer` runs
+`nh3.clean()` with no CSS sanitizer configured — so a build made entirely of
+CSS radial gradients arrives as 1,615 unstyled `<div>` elements on either site.
+PowerPoint, obviously, does not run in a browser at all.
 
-**[Open the scriptless CSS build →](https://bramalkema.github.io/SplatThis/demo/chameleon-css.html)**
-&nbsp;&nbsp;**0.8748** SSIM · 0.8 MB · no script, no canvas, no SVG, no bitmap
+Both captures are therefore lower bounds: they carry the losses of screen
+capture and rescaling on top of whatever the compositor itself costs.
 
-That one is deliberately a link rather than a picture. It is 1,615 DOM elements
-with CSS radial gradients, and a screenshot of it would be indistinguishable
-from a screenshot of anything else — the point is that your browser is
-compositing it from a stylesheet. View source on it.
+**[Open the scriptless CSS build →](https://bramalkema.github.io/SplatThis/demo/chameleon-css.html)**
+— no script, no canvas, no SVG, no bitmap. View source on it; the capture above
+cannot show that the page is 1,615 DOM elements composited from a stylesheet.
 
 Also available: the
 [editable .pptx](https://bramalkema.github.io/SplatThis/demo/chameleon.pptx),

{splatthis-0.2.2 → splatthis-0.2.4}/README.md

@@ -1,5 +1,10 @@
 # SplatThis
 
+[![CI](https://github.com/BramAlkema/SplatThis/actions/workflows/ci.yml/badge.svg)](https://github.com/BramAlkema/SplatThis/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/splatthis)](https://pypi.org/project/splatthis/)
+[![Python](https://img.shields.io/pypi/pyversions/splatthis)](https://pypi.org/project/splatthis/)
+[![License](https://img.shields.io/pypi/l/splatthis)](https://github.com/BramAlkema/SplatThis/blob/main/LICENSE)
+
 Convert a bitmap into Gaussian splats and deploy them as browser-rendered SVG,
 scriptless CSS, browser-native Canvas primitives, an accelerated pixel runtime
 with exact CPU fallbacks, or native editable PowerPoint shapes.
@@ -24,26 +29,28 @@ deployed-fidelity claim.
 ## See it
 
 One 476x502 photograph, fitted to Gaussian splats and emitted to three
-compositors that share no rendering code. The middle image is a real SVG, not a
-raster of one — your browser is drawing 1,615 gradient ellipses.
+compositors that share no rendering code — vector, stylesheet, and DrawingML.
 
-| Source photograph | Native SVG | Native PowerPoint |
-|---|---|---|
-| ![source image](https://bramalkema.github.io/SplatThis/demo/source.png) | ![Browser-rendered SVG](https://bramalkema.github.io/SplatThis/demo/chameleon.svg) | ![PowerPoint slideshow capture](https://bramalkema.github.io/SplatThis/demo/chameleon-pptx.png) |
-| the input | **0.8665** SSIM · vector · 1.5 MB | **0.7885** SSIM · editable shapes · 161 KB |
+| Source | SVG | Scriptless CSS | PowerPoint |
+|:---:|:---:|:---:|:---:|
+| <img src="https://bramalkema.github.io/SplatThis/demo/source.png" alt="Source photograph" width="210"> | <img src="https://bramalkema.github.io/SplatThis/demo/chameleon.svg" alt="Browser-rendered SVG" width="210"> | <img src="https://bramalkema.github.io/SplatThis/demo/chameleon-css.png" alt="Chromium capture of the scriptless CSS build" width="210"> | <img src="https://bramalkema.github.io/SplatThis/demo/chameleon-pptx.png" alt="Microsoft PowerPoint slideshow capture" width="210"> |
+| the input | **0.8665** SSIM<br>vector · 1.5 MB | **0.8748** SSIM<br>DOM + CSS · 0.8 MB | **0.7885** SSIM<br>editable shapes · 161 KB |
+| — | live vector | Chromium capture | PowerPoint capture |
 
-The third image is the only screenshot here, and it has to be: it is Microsoft
-PowerPoint in slideshow, photographed, because there is no other honest way to
-show what PowerPoint actually draws. Its score is measured through that capture
-and is therefore a lower bound.
+The SVG is the real thing: your browser is drawing 1,615 gradient ellipses, not
+displaying a picture of them. The other two are captures because they have to
+be. GitHub and PyPI both sanitize README markup through an allowlist that omits
+the `<style>` tag and the `style` attribute — PyPI's `readme_renderer` runs
+`nh3.clean()` with no CSS sanitizer configured — so a build made entirely of
+CSS radial gradients arrives as 1,615 unstyled `<div>` elements on either site.
+PowerPoint, obviously, does not run in a browser at all.
 
-**[Open the scriptless CSS build →](https://bramalkema.github.io/SplatThis/demo/chameleon-css.html)**
-&nbsp;&nbsp;**0.8748** SSIM · 0.8 MB · no script, no canvas, no SVG, no bitmap
+Both captures are therefore lower bounds: they carry the losses of screen
+capture and rescaling on top of whatever the compositor itself costs.
 
-That one is deliberately a link rather than a picture. It is 1,615 DOM elements
-with CSS radial gradients, and a screenshot of it would be indistinguishable
-from a screenshot of anything else — the point is that your browser is
-compositing it from a stylesheet. View source on it.
+**[Open the scriptless CSS build →](https://bramalkema.github.io/SplatThis/demo/chameleon-css.html)**
+— no script, no canvas, no SVG, no bitmap. View source on it; the capture above
+cannot show that the page is 1,615 DOM elements composited from a stylesheet.
 
 Also available: the
 [editable .pptx](https://bramalkema.github.io/SplatThis/demo/chameleon.pptx),

{splatthis-0.2.2 → splatthis-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "splatthis"
-version = "0.2.2"
+version = "0.2.4"
 description = "Fit 2D Gaussian splats to an image and deploy them as SVG, CSS, Canvas, a pixel runtime, or editable PowerPoint shapes"
 readme = "README.md"
 license = "MIT"
@@ -87,6 +87,8 @@ splatthis = [
     # PEP 561 marker: without it, type checkers ignore this package's
     # annotations entirely and every consumer sees Any.
     "py.typed",
+    # Published fidelity expectations, read by consumers at runtime.
+    "data/*.json",
     "templates/**/*.html",
     "templates/**/*.js",
     "templates/**/*.svg",

{splatthis-0.2.2 → splatthis-0.2.4}/src/splatthis/__init__.py

@@ -10,6 +10,7 @@ from .browser_export import generate_css_splat_html, generate_native_canvas_html
 from .config import ConversionRequest, ConverterConfig
 from .converter import PNG2SVGConverter
 from .domain import EvidenceLevel, SplatScene
+from .expectations import CompositorFidelity, compositor_fidelity
 from .pixel_runtime import (
     generate_parallax_pixel_runtime_html,
     generate_pixel_runtime_html,
@@ -28,6 +29,8 @@ __all__ = [
     "RawSplat",
     "SplatScene",
     "EvidenceLevel",
+    "CompositorFidelity",
+    "compositor_fidelity",
     "ConversionRequest",
     "ConverterConfig",
     "load_png",

{splatthis-0.2.2 → splatthis-0.2.4}/src/splatthis/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the public package version."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"

{splatthis-0.2.2 → splatthis-0.2.4}/src/splatthis/artifact_backends.py

@@ -6,7 +6,7 @@ from abc import ABC, abstractmethod
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Dict, Mapping
 
-import numpy as np
+import numpy.typing as npt
 
 from .artifact_evaluation import (
     evaluate_css_export_quality,
@@ -56,7 +56,7 @@ class ArtifactBackend(ABC):
         converter: "ConversionEngine",
         request: ConversionRequest,
         scene: SplatScene,
-        target_linear_rgb: np.ndarray,
+        target_linear_rgb: npt.NDArray[Any],
         artifacts_path: Path | None,
     ) -> ArtifactPayload:
         """Emit the primary target exactly once."""
@@ -79,8 +79,8 @@ class ArtifactBackend(ABC):
         *,
         converter: "ConversionEngine",
         request: ConversionRequest,
-        target_linear_rgb: np.ndarray,
-        fallback_linear_rgb: np.ndarray,
+        target_linear_rgb: npt.NDArray[Any],
+        fallback_linear_rgb: npt.NDArray[Any],
         proxy_quality: Mapping[str, Any],
     ) -> ArtifactEvaluation:
         quality = dict(proxy_quality)
@@ -104,8 +104,8 @@ class ArtifactBackend(ABC):
         evaluate: Any,
         success_kind: str,
         unavailable_kind: str,
-        target_linear_rgb: np.ndarray,
-        fallback_linear_rgb: np.ndarray,
+        target_linear_rgb: npt.NDArray[Any],
+        fallback_linear_rgb: npt.NDArray[Any],
     ) -> ArtifactEvaluation:
         quality = dict(proxy_quality)
         if request.output_path is not None:
@@ -159,7 +159,7 @@ class SvgArtifactBackend(ArtifactBackend):
         converter: "ConversionEngine",
         request: ConversionRequest,
         scene: SplatScene,
-        target_linear_rgb: np.ndarray,
+        target_linear_rgb: npt.NDArray[Any],
         artifacts_path: Path | None,
     ) -> ArtifactPayload:
         metadata: Dict[str, Any] = {}
@@ -229,8 +229,8 @@ class SvgArtifactBackend(ArtifactBackend):
         *,
         converter: "ConversionEngine",
         request: ConversionRequest,
-        target_linear_rgb: np.ndarray,
-        fallback_linear_rgb: np.ndarray,
+        target_linear_rgb: npt.NDArray[Any],
+        fallback_linear_rgb: npt.NDArray[Any],
         proxy_quality: Mapping[str, Any],
     ) -> ArtifactEvaluation:
         return self._browser_evaluation(
@@ -258,7 +258,7 @@ class DrawingMLArtifactBackend(ArtifactBackend):
         converter: "ConversionEngine",
         request: ConversionRequest,
         scene: SplatScene,
-        target_linear_rgb: np.ndarray,
+        target_linear_rgb: npt.NDArray[Any],
         artifacts_path: Path | None,
     ) -> ArtifactPayload:
         return ArtifactPayload(
@@ -304,8 +304,8 @@ class PptxArtifactBackend(DrawingMLArtifactBackend):
         *,
         converter: "ConversionEngine",
         request: ConversionRequest,
-        target_linear_rgb: np.ndarray,
-        fallback_linear_rgb: np.ndarray,
+        target_linear_rgb: npt.NDArray[Any],
+        fallback_linear_rgb: npt.NDArray[Any],
         proxy_quality: Mapping[str, Any],
     ) -> ArtifactEvaluation:
         return ArtifactEvaluation(
@@ -335,7 +335,7 @@ class CanvasArtifactBackend(ArtifactBackend):
         converter: "ConversionEngine",
         request: ConversionRequest,
         scene: SplatScene,
-        target_linear_rgb: np.ndarray,
+        target_linear_rgb: npt.NDArray[Any],
         artifacts_path: Path | None,
     ) -> ArtifactPayload:
         parallax_strength = float(
@@ -361,8 +361,8 @@ class CanvasArtifactBackend(ArtifactBackend):
         *,
         converter: "ConversionEngine",
         request: ConversionRequest,
-        target_linear_rgb: np.ndarray,
-        fallback_linear_rgb: np.ndarray,
+        target_linear_rgb: npt.NDArray[Any],
+        fallback_linear_rgb: npt.NDArray[Any],
         proxy_quality: Mapping[str, Any],
     ) -> ArtifactEvaluation:
         return self._browser_evaluation(
@@ -392,7 +392,7 @@ class CssArtifactBackend(ArtifactBackend):
         converter: "ConversionEngine",
         request: ConversionRequest,
         scene: SplatScene,
-        target_linear_rgb: np.ndarray,
+        target_linear_rgb: npt.NDArray[Any],
         artifacts_path: Path | None,
     ) -> ArtifactPayload:
         parallax_strength = float(
@@ -425,8 +425,8 @@ class CssArtifactBackend(ArtifactBackend):
         *,
         converter: "ConversionEngine",
         request: ConversionRequest,
-        target_linear_rgb: np.ndarray,
-        fallback_linear_rgb: np.ndarray,
+        target_linear_rgb: npt.NDArray[Any],
+        fallback_linear_rgb: npt.NDArray[Any],
         proxy_quality: Mapping[str, Any],
     ) -> ArtifactEvaluation:
         return self._browser_evaluation(
@@ -468,7 +468,7 @@ class PixelRuntimeArtifactBackend(ArtifactBackend):
         converter: "ConversionEngine",
         request: ConversionRequest,
         scene: SplatScene,
-        target_linear_rgb: np.ndarray,
+        target_linear_rgb: npt.NDArray[Any],
         artifacts_path: Path | None,
     ) -> ArtifactPayload:
         parallax_strength = self._parallax_strength(converter)
@@ -502,8 +502,8 @@ class PixelRuntimeArtifactBackend(ArtifactBackend):
         *,
         converter: "ConversionEngine",
         request: ConversionRequest,
-        target_linear_rgb: np.ndarray,
-        fallback_linear_rgb: np.ndarray,
+        target_linear_rgb: npt.NDArray[Any],
+        fallback_linear_rgb: npt.NDArray[Any],
         proxy_quality: Mapping[str, Any],
     ) -> ArtifactEvaluation:
         if self.requires_governing_render(converter):

{splatthis-0.2.2 → splatthis-0.2.4}/src/splatthis/artifact_evaluation.py

@@ -6,6 +6,7 @@ import logging
 from typing import Any, Callable, Dict, Optional, Tuple
 
 import numpy as np
+import numpy.typing as npt
 
 from .quality import compute_quality_metrics
 
@@ -13,11 +14,11 @@ logger = logging.getLogger(__name__)
 
 
 def _evaluate_browser_export_quality(
-    target_linear_rgb: np.ndarray,
-    fallback_linear_rgb: Optional[np.ndarray] = None,
+    target_linear_rgb: npt.NDArray[Any],
+    fallback_linear_rgb: Optional[npt.NDArray[Any]] = None,
     *,
     artifact_name: str,
-    capture: Callable[[int, int], Tuple[np.ndarray, str]],
+    capture: Callable[[int, int], Tuple[npt.NDArray[Any], str]],
 ) -> Dict[str, Any]:
     """Grade a browser artifact while keeping proxy evidence diagnostic-only."""
 
@@ -59,9 +60,9 @@ def _evaluate_browser_export_quality(
 
 
 def evaluate_svg_export_quality(
-    target_linear_rgb: np.ndarray,
+    target_linear_rgb: npt.NDArray[Any],
     svg_path: str,
-    fallback_linear_rgb: Optional[np.ndarray] = None,
+    fallback_linear_rgb: Optional[npt.NDArray[Any]] = None,
 ) -> Dict[str, Any]:
     from .browser_capture import render_svg_in_browser_to_linear_rgb
 
@@ -76,9 +77,9 @@ def evaluate_svg_export_quality(
 
 
 def evaluate_css_export_quality(
-    target_linear_rgb: np.ndarray,
+    target_linear_rgb: npt.NDArray[Any],
     html_path: str,
-    fallback_linear_rgb: Optional[np.ndarray] = None,
+    fallback_linear_rgb: Optional[npt.NDArray[Any]] = None,
 ) -> Dict[str, Any]:
     from .browser_capture import render_css_html_in_browser_to_linear_rgb
 
@@ -93,9 +94,9 @@ def evaluate_css_export_quality(
 
 
 def evaluate_native_canvas_export_quality(
-    target_linear_rgb: np.ndarray,
+    target_linear_rgb: npt.NDArray[Any],
     html_path: str,
-    fallback_linear_rgb: Optional[np.ndarray] = None,
+    fallback_linear_rgb: Optional[npt.NDArray[Any]] = None,
 ) -> Dict[str, Any]:
     from .browser_capture import render_canvas_html_in_browser_to_linear_rgb
 
@@ -110,9 +111,9 @@ def evaluate_native_canvas_export_quality(
 
 
 def evaluate_pixel_runtime_export_quality(
-    target_linear_rgb: np.ndarray,
+    target_linear_rgb: npt.NDArray[Any],
     html_path: str,
-    fallback_linear_rgb: Optional[np.ndarray] = None,
+    fallback_linear_rgb: Optional[npt.NDArray[Any]] = None,
 ) -> Dict[str, Any]:
     from .browser_capture import render_pixel_runtime_html_in_browser_to_linear_rgb
 

{splatthis-0.2.2 → splatthis-0.2.4}/src/splatthis/browser_export.py

@@ -7,6 +7,7 @@ from html import escape as escape_html
 from typing import Any, Dict, List, Optional
 
 import numpy as np
+import numpy.typing as npt
 
 from .color import linear_to_srgb
 from .export_common import (
@@ -24,7 +25,7 @@ def generate_css_splat_html(
     splats: List[GaussianSplat],
     width: int,
     height: int,
-    background_linear_rgb: Optional[np.ndarray] = None,
+    background_linear_rgb: Optional[npt.NDArray[Any]] = None,
     title: str = "SplatThis CSS",
     parallax_strength: float = 0.0,
     hover_grid_size: int = 10,
@@ -210,7 +211,7 @@ def generate_native_canvas_html(
     splats: List[GaussianSplat],
     width: int,
     height: int,
-    background_linear_rgb: Optional[np.ndarray] = None,
+    background_linear_rgb: Optional[npt.NDArray[Any]] = None,
     title: str = "SplatThis Canvas",
     parallax_strength: float = 0.0,
     k_sigma: float = 2.5,

{splatthis-0.2.2 → splatthis-0.2.4}/src/splatthis/cli.py

@@ -551,6 +551,14 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="Optional directory for run manifest + iteration dumps",
     )
+    parser.add_argument(
+        "--save-json",
+        action="store_true",
+        help=(
+            "Also write the splat population as canonical raw JSON beside the "
+            "output, for re-scoring or re-emitting without retraining"
+        ),
+    )
     parser.add_argument("-v", "--verbose", action="store_true", help="Verbose logging")
     return parser
 
@@ -696,6 +704,7 @@ def _run_conversion(args: argparse.Namespace) -> int:
         output_format=args.fmt,
         seed=args.seed,
         artifacts_dir=args.artifacts_dir,
+        save_json=args.save_json,
         verbose=args.verbose,
     )
     print(f"Wrote {output}")

{splatthis-0.2.2 → splatthis-0.2.4}/src/splatthis/color.py

@@ -2,33 +2,44 @@
 
 from __future__ import annotations
 
+from typing import Any
+
 import numpy as np
+import numpy.typing as npt
+
+# `np.where` evaluates both branches, so the power term sees every input --
+# including the negatives the linear branch exists to handle. Raising a
+# negative base to a fractional exponent yields NaN and a RuntimeWarning, which
+# `where` then discards. The result is correct but the warning is real, and it
+# fires during ordinary compositing wherever a linear value dips below zero.
+# The float32 variants below already clamped for this reason; these did not.
+_POWER_FLOOR = 1e-12
 
 
-def srgb_to_linear(srgb: np.ndarray) -> np.ndarray:
+def srgb_to_linear(srgb: npt.NDArray[Any]) -> npt.NDArray[Any]:
     """Convert normalized sRGB values to linear RGB."""
 
     values = np.asarray(srgb)
     return np.where(
         values <= 0.04045,
         values / 12.92,
-        np.power((values + 0.055) / 1.055, 2.4),
+        np.power(np.maximum((values + 0.055) / 1.055, _POWER_FLOOR), 2.4),
     )
 
 
-def linear_to_srgb(linear: np.ndarray) -> np.ndarray:
+def linear_to_srgb(linear: npt.NDArray[Any]) -> npt.NDArray[Any]:
     """Convert normalized linear RGB values to clipped sRGB."""
 
     values = np.asarray(linear)
     srgb = np.where(
         values <= 0.0031308,
         12.92 * values,
-        1.055 * np.power(values, 1.0 / 2.4) - 0.055,
+        1.055 * np.power(np.maximum(values, _POWER_FLOOR), 1.0 / 2.4) - 0.055,
     )
     return np.clip(srgb, 0.0, 1.0)
 
 
-def linear_to_srgb_float32(linear: np.ndarray) -> np.ndarray:
+def linear_to_srgb_float32(linear: npt.NDArray[Any]) -> npt.NDArray[Any]:
     """Convert to sRGB with the clipped float32 semantics used by scorers."""
 
     values = np.clip(np.asarray(linear), 0.0, 1.0)
@@ -39,7 +50,7 @@ def linear_to_srgb_float32(linear: np.ndarray) -> np.ndarray:
     ).astype(np.float32)
 
 
-def srgb_to_linear_float32(srgb: np.ndarray) -> np.ndarray:
+def srgb_to_linear_float32(srgb: npt.NDArray[Any]) -> npt.NDArray[Any]:
     """Convert to linear RGB with the clipped float32 scorer semantics."""
 
     values = np.clip(np.asarray(srgb), 0.0, 1.0)