framerudiments 0.4.2__tar.gz → 0.4.4__tar.gz

{framerudiments-0.4.2 → framerudiments-0.4.4}/AGENTS.md

@@ -22,3 +22,11 @@ and immutable assets. New publication destinations still require user authority.
 ## Full ecosystem and release preflight
 
 Before every new workflow run, check the latest stable official release and observe the actual runtime used by the job. Follow [the shared preflight](https://github.com/kieransimkin/DanceFlow/blob/main/docs/workflows/release-preflight.md) and this project's [people-and-agent guide](docs/ECOSYSTEM.md). Review the complete relevant capability inventory rather than only a familiar command. Consider every DanceFlow component against the actual task; use and compose all applicable supported capabilities, and improve a concrete reusable gap in its canonical repository. Record why existing capabilities suffice when no change is justified. No catalogue checklist expands the task, authorises model downloads/training, or proves integration. Preserve exact source/package identity, clocks, model-local storage, privacy, costs, immutable releases and separate deployment gates.
+
+## Preflight temporary-directory access
+
+Before any long, costly, model-backed, media-rendering, build, test, packaging or release command that creates private or atomic temporary directories, run a disposable preflight with the exact runtime, user or sandbox, and intended output parent. The probe must create a unique directory, write and read a file, atomically rename it, then remove the file and directory.
+
+Keep temporary data and caches under the owning project on `Z:`; model weights and model-specific caches remain under that project's ignored `models/`. If the probe returns `WinError 5`, access denied, a rename failure or a cleanup failure, stop before the expensive command. Preserve the exact error and use the documented narrowly approved unrestricted recovery from the outset only when the task requires it. Use a fresh output directory and do not repeat the already-failing full job in the restricted shell.
+
+After any unrestricted recovery, verify that the final output is readable and writable from the normal managed environment. If it is not, copy the completed bytes into a pre-created project-local directory that passed the probe, verify hashes, and retain the original failure and recovery evidence. Do not edit global ACLs, switch caches to `C:`, terminate unrelated processes or claim the underlying permission problem is fixed. Repositories that own temporary-directory creation should provide and test a reusable preflight helper rather than relying only on this instruction.

{framerudiments-0.4.2/src/framerudiments.egg-info → framerudiments-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framerudiments
-Version: 0.4.2
+Version: 0.4.4
 Summary: Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence.
 Author: Kieran Simkin
 License-Expression: MIT
@@ -33,9 +33,10 @@ Dynamic: license-file
 
 ## Five fire methods and ice
 
-Version 0.4.2 adds filmed flame, animated flame sprites, a bounded 2D fluid
-solver, GPU volumetric rays, Blender/Mantaflow bake playback, scorched artwork burn-away,
-fractured ice and frost. Use ordinary material layers or the reusable
+Version 0.4.3 adds evidence-recorded three-stop fire palettes, an optional
+vertical tip bias applied after burn-front placement, and less repetitive
+deterministic layouts for filmed and Mantaflow sources. The five fire methods,
+scorched artwork burn-away, fractured ice and frost remain available through ordinary material layers or the reusable
 `FireRenderer` and `NaturalMaterial` APIs. Source clocks, clean text, transparent edges and
 seek-safe rendering remain explicit. See [natural materials](docs/natural-materials.md).
 
@@ -151,7 +152,7 @@ its own tone, sprite, LRC, CUE and four-dimensional recording.
   stills, a poster, phone preview, input/output hashes, commands and logs.
 
 The [spectrum guide](docs/spectrum.md) covers saved StemLab Fourier calibration,
-frequency labels, peak controls and per-frame JSONL effect signals. Run
+frequency labels, independent fixed-grid visibility, peak controls and per-frame JSONL effect signals. Run
 `framerudiments renderers` for the current built-in names. The optional
 `demo --spectrum` generator uses StemLab 1.6+; rendering its saved recording
 keeps the core package lightweight.

{framerudiments-0.4.2 → framerudiments-0.4.4}/README.md

@@ -2,9 +2,10 @@
 
 ## Five fire methods and ice
 
-Version 0.4.2 adds filmed flame, animated flame sprites, a bounded 2D fluid
-solver, GPU volumetric rays, Blender/Mantaflow bake playback, scorched artwork burn-away,
-fractured ice and frost. Use ordinary material layers or the reusable
+Version 0.4.3 adds evidence-recorded three-stop fire palettes, an optional
+vertical tip bias applied after burn-front placement, and less repetitive
+deterministic layouts for filmed and Mantaflow sources. The five fire methods,
+scorched artwork burn-away, fractured ice and frost remain available through ordinary material layers or the reusable
 `FireRenderer` and `NaturalMaterial` APIs. Source clocks, clean text, transparent edges and
 seek-safe rendering remain explicit. See [natural materials](docs/natural-materials.md).
 
@@ -120,7 +121,7 @@ its own tone, sprite, LRC, CUE and four-dimensional recording.
   stills, a poster, phone preview, input/output hashes, commands and logs.
 
 The [spectrum guide](docs/spectrum.md) covers saved StemLab Fourier calibration,
-frequency labels, peak controls and per-frame JSONL effect signals. Run
+frequency labels, independent fixed-grid visibility, peak controls and per-frame JSONL effect signals. Run
 `framerudiments renderers` for the current built-in names. The optional
 `demo --spectrum` generator uses StemLab 1.6+; rendering its saved recording
 keeps the core package lightweight.

{framerudiments-0.4.2 → framerudiments-0.4.4}/RELEASE_NOTES.md

@@ -1,3 +1,22 @@
+# FrameRudiments 0.4.4
+
+- Spectrum views accept a validated `style.grid` boolean. Set it to `false` to remove the three fixed dB guide lines while retaining calibrated bars and moving peak holds; label visibility remains independent.
+- The existing default remains `true` for backward compatibility. Documentation and focused regression coverage include the no-grid, no-label presentation used by clean campaign visualisers.
+
+# FrameRudiments 0.4.3
+
+- Atlas fire accepts an evidence-recorded three-stop CSS palette ordered as
+  shadow, body and core. An optional bounded `palette_vertical` bias can carry
+  the shadow colour into visible flame tongues after burn-front placement while
+  preserving the source alpha silhouette.
+- Filmed and Mantaflow layouts vary deterministic jet scale, playback rate,
+  phase, mirroring, angle and placement across wide surfaces, reducing obvious
+  repeated strips without introducing a new source clock.
+- Invalid palette shapes, colours and bounds fail closed. The focused fire
+  suite, configured full suite, package checks and clean-wheel palette smoke
+  test cover the reusable contract.
+- [Actual synthetic still/video, API, settings and limitations](docs/natural-materials.md).
+
 # FrameRudiments 0.4.2
 
 - Five selectable fire routes: hash-pinned CC0 filmed flame, animated flame

{framerudiments-0.4.2 → framerudiments-0.4.4}/docs/natural-materials.md

@@ -1,6 +1,6 @@
 # Five fire methods and ice
 
-FrameRudiments 0.4.2 offers five distinct fire routes through one RGBA and
+FrameRudiments 0.4.3 offers five distinct fire routes through one RGBA and
 artwork-burn API. Recorded flame preserves photographed detail; sprite
 particles rearrange that detail; a 2D fluid solver, a GPU volume renderer and
 a Blender/Mantaflow bake offer different degrees of simulation and control.
@@ -49,7 +49,9 @@ assets fail clearly; methods never silently substitute another backend.
 from framerudiments import FireRenderer, NaturalMaterial
 
 fire = FireRenderer(ticket.size, method="sprites", seed=21,
-                    resolution=0.75, warmth=1.0, glow=0.1)
+                    resolution=0.75, warmth=1.0, glow=0.1,
+                    palette=["#531178", "#ef5b16", "#ffd25c"],
+                    palette_vertical=0.7)
 ice = NaturalMaterial(ticket.size, "ice", seed=21, resolution=0.75)
 try:
     burning = fire.burn(ticket, source_seconds, progress=0.5)
@@ -87,12 +89,18 @@ source-to-asset time mapping in the scene if a bake represents another interval.
 
 Shared controls are `seed`, `speed`, `glow` and `opacity`. `resolution` declares
 the synthetic working tile scale (0.1–1). Atlas detail remains bounded by its
-actual cell resolution. `flame_height` controls the tiled footage/bake layout;
+actual cell resolution. The footage route deterministically varies jet scale, playback rate, phase, mirroring, angle and placement so wide surfaces do not expose an evenly repeated source silhouette. `flame_height` controls the overlapping footage/bake layout;
 sprite shape and simulation shape are owned by their respective backends.
 The legacy noise `scale`/`turbulence` controls apply to `stylized`, and to the
 shared scorched burn mask, rather than altering recorded motion. `warmth`
 (0–1) grades only atlas-based methods, preserves alpha and is a creative colour
-grade, never a new source or temperature observation.
+grade, never a new source or temperature observation. It can blend the original
+emission towards the default hot grade or an explicit
+three-stop CSS `palette` ordered shadow, body and core. The selected colours
+are retained in renderer evidence; the palette changes RGB only and preserves
+the source alpha silhouette. `palette_vertical` (0–1) optionally biases the
+shadow colour into higher flame tongues while retaining the energy-led body and
+core grade; it is useful when art direction calls for coloured flame tips.
 
 Simulation controls are explicit `backend_settings`: `fluid_2d` accepts
 `simulation_hz`, `resolution` and `warmup`; `volume` accepts `steps`. Atlas

{framerudiments-0.4.2 → framerudiments-0.4.4}/docs/spectrum.md

@@ -26,7 +26,8 @@ the ordinary FrameRudiments dependencies.
     "min_peak_db": -60,
     "min_peak_contrast_db": 3,
     "min_peak_distance": 2,
-    "labels": true
+    "labels": true,
+    "grid": true
   }
 }
 ```
@@ -112,6 +113,7 @@ In addition to the common `colours`, `padding` and `background`, spectrum accept
 | `gap` | 1 pixel, nonnegative |
 | `peak_colour`, `label_colour` | CSS colours |
 | `labels`, `font_size` | true; responsive default font size, explicit range 6..128 pixels |
+| `grid` | true; set false to omit the three horizontal dB reference lines while retaining bars and peak holds |
 
 Every render/preflight streams active spectrum reports into
 `rudiment-analysis.jsonl`, binding the sidecar hash in the final manifest.

{framerudiments-0.4.2 → framerudiments-0.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "framerudiments"
-version = "0.4.2"
+version = "0.4.4"
 description = "Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence."
 requires-python = ">=3.11"
 readme = "README.md"

{framerudiments-0.4.2 → framerudiments-0.4.4}/src/framerudiments/__init__.py

@@ -1,6 +1,6 @@
 """Offline frame composition on a traceable musical clock."""
 
-__version__ = "0.4.2"
+__version__ = "0.4.4"
 
 from .project import Project
 from .render import render, preflight

{framerudiments-0.4.2 → framerudiments-0.4.4}/src/framerudiments/fire_renderer.py

@@ -4,7 +4,7 @@ from pathlib import Path
 import math
 from types import SimpleNamespace
 
-from PIL import Image, ImageFilter
+from PIL import Image, ImageColor, ImageFilter
 
 from .natural_materials import NaturalMaterial
 from .io import file_ref, number, sha256
@@ -24,7 +24,17 @@ def builtin_asset(name="marburg"):
 
 class FireRenderer(NaturalMaterial):
     def __init__(
-        self, size, method="footage", *, asset=None, repeat=True, warmth=0, backend_settings=None, **settings
+        self,
+        size,
+        method="footage",
+        *,
+        asset=None,
+        repeat=True,
+        warmth=0,
+        palette=None,
+        palette_vertical=0,
+        backend_settings=None,
+        **settings,
     ):
         if method not in METHODS:
             raise ValueError(f"Unknown fire method; choose {METHODS}")
@@ -34,6 +44,20 @@ class FireRenderer(NaturalMaterial):
         self.method = method
         self.closed = False
         self.warmth = number(warmth, "fire warmth grade", minimum=0, maximum=1)
+        if palette is not None:
+            if not isinstance(palette, (list, tuple)) or len(palette) != 3:
+                raise ValueError("Fire palette must contain exactly three CSS colours")
+            try:
+                self.palette = tuple(ImageColor.getcolor(value, "RGB") for value in palette)
+            except (TypeError, ValueError) as exc:
+                raise ValueError("Fire palette must contain exactly three CSS colours") from exc
+            self.palette_source = list(palette)
+        else:
+            self.palette = None
+            self.palette_source = None
+        self.palette_vertical = number(
+            palette_vertical, "fire vertical palette bias", minimum=0, maximum=1
+        )
         self.repeat = repeat
         self.atlas = None
         self.backend = None
@@ -71,6 +95,8 @@ class FireRenderer(NaturalMaterial):
         self.evidence.update(
             method=method,
             warmth_grade=self.warmth,
+            palette=self.palette_source,
+            palette_vertical=self.palette_vertical,
             repeat=repeat,
             asset=self.atlas.evidence if self.atlas else None,
             backend="opengl"
@@ -168,16 +194,30 @@ class FireRenderer(NaturalMaterial):
 
     def _footage(self, seconds):
         image = Image.new("RGBA", self.size)
-        h = max(8, round(self.size[1] * self.flame_height))
+        base_h = max(8, round(self.size[1] * self.flame_height))
         cw, ch = self.atlas.cell_size
-        w = max(4, round(h * cw / ch))
-        count = math.ceil(self.size[0] / max(1, w * 0.72)) + 1
+        base_w = max(4, round(base_h * cw / ch))
+        step = max(2, round(base_w * 0.42))
+        count = math.ceil(self.size[0] / step) + 3
         for i in range(count):
-            t = seconds + ((i * 73 + self.seed * 17) % 233) / 100
+            # Vary every jet deterministically so a real source does not become
+            # an artificial picket-fence pattern when it spans a wide surface.
+            code = (i * 1103515245 + self.seed * 12345) & 0x7FFFFFFF
+            scale = 0.72 + ((code >> 4) % 67) / 100
+            speed = 0.82 + ((code >> 11) % 39) / 100
+            h = max(8, round(base_h * scale))
+            w = max(4, round(h * cw / ch))
+            t = seconds * speed + ((code >> 17) % 997) / 137
             tile = self.atlas.frame_at(t, repeat=self.repeat)
             tile = tile.convert("RGBa").resize((w, h), Image.Resampling.LANCZOS).convert("RGBA")
-            x = round(i * w * 0.72 - w * 0.2)
-            y = self.size[1] - h
+            if code & 1:
+                tile = tile.transpose(Image.Transpose.FLIP_LEFT_RIGHT)
+            angle = ((code >> 23) % 7) - 3
+            if angle:
+                tile = tile.rotate(angle, Image.Resampling.BICUBIC, expand=True)
+            jitter_x = ((code >> 7) % max(2, step)) - step / 2
+            x = round((i - 1) * step + jitter_x - tile.width * 0.18)
+            y = round(self.size[1] - tile.height + (((code >> 14) % 13) - 6) * base_h / 100)
             image.alpha_composite(tile, (x, y))
         return image
 
@@ -211,19 +251,45 @@ class FireRenderer(NaturalMaterial):
             # photographed/simulated silhouette so blue-screen fringes cannot
             # leak into a warm fire treatment.
             energy = np.max(a[:, :, :3], axis=2)
-            warm = np.dstack(
-                (
-                    np.ones_like(energy),
-                    np.clip(0.04 + energy * 0.58, 0, 1),
-                    np.clip((energy - 0.84) * 4.5, 0, 1),
+            if self.palette:
+                low, middle, high = (np.asarray(colour, dtype=np.float32) / 255 for colour in self.palette)
+                split = 0.58
+                lower_t = np.clip(energy / split, 0, 1)[:, :, None]
+                upper_t = np.clip((energy - split) / (1 - split), 0, 1)[:, :, None]
+                lower = low + (middle - low) * lower_t
+                upper = middle + (high - middle) * upper_t
+                warm = np.where((energy < split)[:, :, None], lower, upper)
+                # Keep low-energy tongues dark while allowing the hot core to
+                # reach the selected highlight. Alpha continues to own shape.
+                warm *= (0.28 + 0.72 * energy)[:, :, None]
+            else:
+                warm = np.dstack(
+                    (
+                        np.ones_like(energy),
+                        np.clip(0.12 + energy * 0.82, 0, 1),
+                        np.clip((energy - 0.93) * 8, 0, 1),
+                    )
                 )
-            )
             a[:, :, :3] = a[:, :, :3] * (1 - self.warmth) + warm * self.warmth
             tile = Image.fromarray(np.rint(a * 255).astype(np.uint8))
         if front != 1:
             shifted = Image.new("RGBA", self.size)
             shifted.alpha_composite(tile, (0, round((front - 1) * self.size[1])))
             tile = shifted
+        if self.palette and self.palette_vertical:
+            # Apply the tip bias after front placement. Otherwise a moving burn
+            # front can translate all cooler graded pixels off-canvas and leave
+            # only the body/core colours visible at the consumption edge.
+            np = self.np
+            a = np.asarray(tile, dtype=np.float32) / 255
+            energy = np.max(a[:, :, :3], axis=2)
+            low = np.asarray(self.palette[0], dtype=np.float32) / 255
+            y = np.linspace(0, 1, a.shape[0], dtype=np.float32)[:, None]
+            tip = np.clip((front - y) / max(0.05, self.flame_height), 0, 1)
+            tip *= self.palette_vertical
+            cool = low[None, None, :] * (0.38 + 0.62 * energy)[:, :, None]
+            a[:, :, :3] = a[:, :, :3] * (1 - tip[:, :, None]) + cool * tip[:, :, None]
+            tile = Image.fromarray(np.rint(a * 255).astype(np.uint8))
         factor = amount * self.opacity
         tile.putalpha(tile.getchannel("A").point(lambda a: round(a * factor)))
         if self.glow:

{framerudiments-0.4.2 → framerudiments-0.4.4}/src/framerudiments/rudiment_renderers.py

@@ -280,6 +280,7 @@ class SpectrumRenderer(_Viewport):
                 "label_colour",
                 "font_size",
                 "labels",
+                "grid",
             },
         )
         self.floor = number(style.get("floor_db", -72), "spectrum floor", minimum=-240, maximum=0)
@@ -306,6 +307,9 @@ class SpectrumRenderer(_Viewport):
         self.labels = style.get("labels", True)
         if not isinstance(self.labels, bool):
             raise ValueError("Spectrum labels must be boolean")
+        self.grid = style.get("grid", True)
+        if not isinstance(self.grid, bool):
+            raise ValueError("Spectrum grid must be boolean")
         self.font_size = integer(
             style.get("font_size", max(6, min(14, size[0] // 30))), "spectrum font", minimum=6, maximum=128
         )
@@ -346,7 +350,8 @@ class SpectrumRenderer(_Viewport):
             return bottom - max(0, min(1, (db - self.floor) / (self.ceiling - self.floor))) * (bottom - top)
 
         for db in (self.floor, (self.floor + self.ceiling) / 2, self.ceiling):
-            draw.line((left, y(db), right, y(db)), fill="#40516a")
+            if self.grid:
+                draw.line((left, y(db), right, y(db)), fill="#40516a")
             if self.labels:
                 draw.text(
                     (self.padding, y(db) - self.font_size / 2),

{framerudiments-0.4.2 → framerudiments-0.4.4/src/framerudiments.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framerudiments
-Version: 0.4.2
+Version: 0.4.4
 Summary: Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence.
 Author: Kieran Simkin
 License-Expression: MIT
@@ -33,9 +33,10 @@ Dynamic: license-file
 
 ## Five fire methods and ice
 
-Version 0.4.2 adds filmed flame, animated flame sprites, a bounded 2D fluid
-solver, GPU volumetric rays, Blender/Mantaflow bake playback, scorched artwork burn-away,
-fractured ice and frost. Use ordinary material layers or the reusable
+Version 0.4.3 adds evidence-recorded three-stop fire palettes, an optional
+vertical tip bias applied after burn-front placement, and less repetitive
+deterministic layouts for filmed and Mantaflow sources. The five fire methods,
+scorched artwork burn-away, fractured ice and frost remain available through ordinary material layers or the reusable
 `FireRenderer` and `NaturalMaterial` APIs. Source clocks, clean text, transparent edges and
 seek-safe rendering remain explicit. See [natural materials](docs/natural-materials.md).
 
@@ -151,7 +152,7 @@ its own tone, sprite, LRC, CUE and four-dimensional recording.
   stills, a poster, phone preview, input/output hashes, commands and logs.
 
 The [spectrum guide](docs/spectrum.md) covers saved StemLab Fourier calibration,
-frequency labels, peak controls and per-frame JSONL effect signals. Run
+frequency labels, independent fixed-grid visibility, peak controls and per-frame JSONL effect signals. Run
 `framerudiments renderers` for the current built-in names. The optional
 `demo --spectrum` generator uses StemLab 1.6+; rendering its saved recording
 keeps the core package lightweight.

{framerudiments-0.4.2 → framerudiments-0.4.4}/tests/test_fire_methods.py

@@ -98,6 +98,23 @@ def test_grade_keeps_alpha_at_unshifted_front(atlas):
         b.close()
 
 
+def test_three_stop_palette_grades_fire_without_changing_alpha(atlas):
+    palette = ["#531178", "#ef5b16", "#ffd25c"]
+    plain = FireRenderer((64, 64), "footage", asset=atlas, warmth=0, glow=0)
+    graded = FireRenderer(
+        (64, 64), "footage", asset=atlas, warmth=1, palette=palette, palette_vertical=0.7, glow=0
+    )
+    try:
+        a, b = plain.render(0.1, front=1), graded.render(0.1, front=1)
+        assert a.getchannel("A").tobytes() == b.getchannel("A").tobytes()
+        assert a.tobytes() != b.tobytes()
+        assert graded.evidence["palette"] == palette
+        assert graded.evidence["palette_vertical"] == 0.7
+    finally:
+        plain.close()
+        graded.close()
+
+
 def test_native_sprite_particle_age_selects_frame_and_long_source_is_bounded(atlas):
     f = FireRenderer((64, 64), "sprites", asset=atlas)
     try:
@@ -153,6 +170,9 @@ def test_bundled_assets_have_reviewed_provenance_and_no_private_paths():
         {"backend_settings": []},
         {"method": "missing"},
         {"asset": {}, "method": "fluid_2d"},
+        {"palette": ["#fff", "#000"]},
+        {"palette": ["#fff", "not-a-colour", "#000"]},
+        {"palette_vertical": 2},
     ),
 )
 def test_invalid_fire_options_do_not_fallback(settings):

{framerudiments-0.4.2 → framerudiments-0.4.4}/tests/test_spectrum.py

@@ -4,6 +4,7 @@ import os
 
 from dancerudiments_authoring.recording import Recording, RecordingClock, write_recording
 import pytest
+from PIL import ImageColor
 
 from framerudiments import Project, render
 from framerudiments.compositor import Compositor
@@ -93,6 +94,17 @@ def test_peak_hold_decays_deterministically_without_hidden_state(spectrum_projec
     assert comp.frame(30)[0].tobytes() == first
 
 
+def test_spectrum_grid_can_be_omitted_without_removing_bars_or_peak_holds(spectrum_project):
+    project, _, _ = spectrum_project
+    project.data["layers"][0]["style"] = {"grid": False, "labels": False}
+    comp = Compositor(Project(project.data, project.base))
+    view = comp.layers[0]
+    assert view.renderer.grid is False
+    image = view.renderer.render(view.data(comp.context(0)))
+    assert ImageColor.getcolor("#40516a", "RGBA") not in set(image.get_flattened_data())
+    assert image.getbbox() is not None
+
+
 def test_local_peak_plateaus_threshold_contrast_and_minimum_distance():
     assert peak_indices(
         [-60, -10, -10, -60, -20, -60], floor=-72, threshold=-50, contrast=3, distance=2, count=3