genewildish/Mainline
1
0
Fork 1
Code Issues Pull Requests 4 Packages Projects Releases Wiki Activity

feat: Complete pipeline hot-rebuild implementation with acceptance tests

Browse Source 
- Implements pipeline hot-rebuild with state preservation (issue #43)
- Adds auto-injection of MVP stages for missing capabilities
- Adds radial camera mode for polar coordinate scanning
- Adds afterimage and motionblur effects using framebuffer history
- Adds comprehensive acceptance tests for camera modes and pipeline rebuild
- Updates presets.toml with new effect configurations

Related to: #35 (Pipeline Mutation API epic)
Closes: #43, #44, #45
This commit is contained in:
David Gwilliam
2026-03-19 03:34:06 -07:00
parent 0eb5f1d5ff
commit 238bac1bb2
30 changed files with 3438 additions and 378 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
engine/pipeline/adapters/__init__.py
View File

@@ -4,7 +4,7 @@ This module provides adapters that wrap existing components
(EffectPlugin, Display, DataSource, Camera) as Stage implementations.
"""
from .camera import CameraStage
from .camera import CameraClockStage, CameraStage
from .data_source import DataSourceStage, PassthroughStage, SourceItemsToBufferStage
from .display import DisplayStage
from .effect_plugin import EffectPluginStage
@@ -30,6 +30,7 @@ __all__ = [
"PassthroughStage",
"SourceItemsToBufferStage",
"CameraStage",
"CameraClockStage",
"ViewportFilterStage",
"FontStage",
"ImageToTextStage",

123
engine/pipeline/adapters/camera.py
View File

@@ -6,8 +6,83 @@ from typing import Any
from engine.pipeline.core import DataType, PipelineContext, Stage
class CameraClockStage(Stage):
"""Per-frame clock stage that updates camera state.
This stage runs once per frame and updates the camera's internal state
(position, time). It makes camera_y/camera_x available to subsequent
stages via the pipeline context.
Unlike other stages, this is a pure clock stage and doesn't process
data - it just updates camera state and passes data through unchanged.
"""
def __init__(self, camera, name: str = "camera-clock"):
self._camera = camera
self.name = name
self.category = "camera"
self.optional = False
self._last_frame_time: float | None = None
@property
def stage_type(self) -> str:
return "camera"
@property
def capabilities(self) -> set[str]:
# Provides camera state info only
# NOTE: Do NOT provide "source" as it conflicts with viewport_filter's "source.filtered"
return {"camera.state"}
@property
def dependencies(self) -> set[str]:
# Clock stage - no dependencies (updates every frame regardless of data flow)
return set()
@property
def inlet_types(self) -> set:
# Accept any data type - this is a pass-through stage
return {DataType.ANY}
@property
def outlet_types(self) -> set:
# Pass through whatever was received
return {DataType.ANY}
def process(self, data: Any, ctx: PipelineContext) -> Any:
"""Update camera state and pass data through.
This stage updates the camera's internal state (position, time) and
makes the updated camera_y/camera_x available to subsequent stages
via the pipeline context.
The data is passed through unchanged - this stage only updates
camera state, it doesn't transform the data.
"""
if data is None:
return data
current_time = time.perf_counter()
dt = 0.0
if self._last_frame_time is not None:
dt = current_time - self._last_frame_time
self._camera.update(dt)
self._last_frame_time = current_time
# Update context with current camera position
ctx.set_state("camera_y", self._camera.y)
ctx.set_state("camera_x", self._camera.x)
# Pass data through unchanged
return data
class CameraStage(Stage):
"""Adapter wrapping Camera as a Stage."""
"""Adapter wrapping Camera as a Stage.
This stage applies camera viewport transformation to the rendered buffer.
Camera state updates are handled by CameraClockStage.
"""
def __init__(self, camera, name: str = "vertical"):
self._camera = camera
@@ -22,7 +97,7 @@ class CameraStage(Stage):
Returns:
Dictionary containing camera state that can be restored
"""
return {
state = {
"x": self._camera.x,
"y": self._camera.y,
"mode": self._camera.mode.value
@@ -36,6 +111,14 @@ class CameraStage(Stage):
"_y_float": getattr(self._camera, "_y_float", 0.0),
"_time": getattr(self._camera, "_time", 0.0),
}
# Save radial camera state if present
if hasattr(self._camera, "_r_float"):
state["_r_float"] = self._camera._r_float
if hasattr(self._camera, "_theta_float"):
state["_theta_float"] = self._camera._theta_float
if hasattr(self._camera, "_radial_input"):
state["_radial_input"] = self._camera._radial_input
return state
def restore_state(self, state: dict[str, Any]) -> None:
"""Restore camera state from saved state.
@@ -68,6 +151,14 @@ class CameraStage(Stage):
if hasattr(self._camera, "_time"):
self._camera._time = state.get("_time", 0.0)
# Restore radial camera state if present
if hasattr(self._camera, "_r_float"):
self._camera._r_float = state.get("_r_float", 0.0)
if hasattr(self._camera, "_theta_float"):
self._camera._theta_float = state.get("_theta_float", 0.0)
if hasattr(self._camera, "_radial_input"):
self._camera._radial_input = state.get("_radial_input", 0.0)
@property
def stage_type(self) -> str:
return "camera"
@@ -93,18 +184,26 @@ class CameraStage(Stage):
if data is None:
return data
current_time = time.perf_counter()
dt = 0.0
if self._last_frame_time is not None:
dt = current_time - self._last_frame_time
self._camera.update(dt)
self._last_frame_time = current_time
ctx.set_state("camera_y", self._camera.y)
ctx.set_state("camera_x", self._camera.x)
# Camera state is updated by CameraClockStage
# We only apply the viewport transformation here
if hasattr(self._camera, "apply"):
viewport_width = ctx.params.viewport_width if ctx.params else 80
viewport_height = ctx.params.viewport_height if ctx.params else 24
return self._camera.apply(data, viewport_width, viewport_height)
# Use filtered camera position if available (from ViewportFilterStage)
# This handles the case where the buffer has been filtered and starts at row 0
filtered_camera_y = ctx.get("camera_y", self._camera.y)
# Temporarily adjust camera position for filtering
original_y = self._camera.y
self._camera.y = filtered_camera_y
try:
result = self._camera.apply(data, viewport_width, viewport_height)
finally:
# Restore original camera position
self._camera.y = original_y
return result
return data

15
engine/pipeline/adapters/effect_plugin.py
View File

@@ -6,13 +6,22 @@ from engine.pipeline.core import PipelineContext, Stage
class EffectPluginStage(Stage):
"""Adapter wrapping EffectPlugin as a Stage."""
"""Adapter wrapping EffectPlugin as a Stage.
def __init__(self, effect_plugin, name: str = "effect"):
Supports capability-based dependencies through the dependencies parameter.
"""
def __init__(
self,
effect_plugin,
name: str = "effect",
dependencies: set[str] | None = None,
):
self._effect = effect_plugin
self.name = name
self.category = "effect"
self.optional = False
self._dependencies = dependencies or set()
@property
def stage_type(self) -> str:
@@ -49,7 +58,7 @@ class EffectPluginStage(Stage):
@property
def dependencies(self) -> set[str]:
return set()
return self._dependencies
@property
def inlet_types(self) -> set:

32
engine/pipeline/adapters/transform.py
View File

@@ -49,7 +49,9 @@ class ViewportFilterStage(Stage):
@property
def dependencies(self) -> set[str]:
return {"source"}
# Always requires camera.state for viewport filtering
# CameraUpdateStage provides this (auto-injected if missing)
return {"source", "camera.state"}
@property
def inlet_types(self) -> set:
@@ -95,9 +97,13 @@ class ViewportFilterStage(Stage):
# Find start index (first item that intersects with visible range)
start_idx = 0
start_item_y = 0 # Y position where the first visible item starts
for i, total_h in enumerate(cumulative_heights):
if total_h > start_y:
start_idx = i
# Calculate the Y position of the start of this item
if i > 0:
start_item_y = cumulative_heights[i - 1]
break
# Find end index (first item that extends beyond visible range)
@@ -107,6 +113,16 @@ class ViewportFilterStage(Stage):
end_idx = i + 1
break
# Adjust camera_y for the filtered buffer
# The filtered buffer starts at row 0, but the camera position
# needs to be relative to where the first visible item starts
filtered_camera_y = camera_y - start_item_y
# Update context with the filtered camera position
# This ensures CameraStage can correctly slice the filtered buffer
ctx.set_state("camera_y", filtered_camera_y)
ctx.set_state("camera_x", ctx.get("camera_x", 0)) # Keep camera_x unchanged
# Return visible items
return data[start_idx:end_idx]
@@ -127,9 +143,16 @@ class FontStage(Stage):
def capabilities(self) -> set[str]:
return {"render.output"}
@property
def stage_dependencies(self) -> set[str]:
# Must connect to viewport_filter stage to get filtered source
return {"viewport_filter"}
@property
def dependencies(self) -> set[str]:
return {"source"}
# Depend on source.filtered (provided by viewport_filter)
# This ensures we get the filtered/processed source, not raw source
return {"source.filtered"}
@property
def inlet_types(self) -> set:
@@ -147,6 +170,11 @@ class FontStage(Stage):
if not isinstance(data, list):
return [str(data)]
import os
if os.environ.get("DEBUG_CAMERA"):
print(f"FontStage: input items={len(data)}")
viewport_width = ctx.params.viewport_width if ctx.params else 80
result = []

147
engine/pipeline/controller.py
View File

@@ -68,6 +68,15 @@ class Pipeline:
self._metrics_enabled = self.config.enable_metrics
self._frame_metrics: list[FrameMetrics] = []
self._max_metrics_frames = 60
# Minimum capabilities required for pipeline to function
# NOTE: Research later - allow presets to override these defaults
self._minimum_capabilities: set[str] = {
"source",
"render.output",
"display.output",
"camera.state", # Always required for viewport filtering
}
self._current_frame_number = 0
def add_stage(self, name: str, stage: Stage, initialize: bool = True) -> "Pipeline":
@@ -214,15 +223,22 @@ class Pipeline:
pass
def _rebuild(self) -> None:
"""Rebuild execution order after mutation without full reinitialization."""
"""Rebuild execution order after mutation or auto-injection."""
was_initialized = self._initialized
self._initialized = False
self._capability_map = self._build_capability_map()
self._execution_order = self._resolve_dependencies()
try:
self._validate_dependencies()
self._validate_types()
except StageError:
pass
# Restore initialized state
self._initialized = was_initialized
def get_stage(self, name: str) -> Stage | None:
"""Get a stage by name."""
return self._stages.get(name)
@@ -297,10 +313,123 @@ class Pipeline:
"stage_count": len(self._stages),
}
def build(self) -> "Pipeline":
"""Build execution order based on dependencies."""
@property
def minimum_capabilities(self) -> set[str]:
"""Get minimum capabilities required for pipeline to function."""
return self._minimum_capabilities
@minimum_capabilities.setter
def minimum_capabilities(self, value: set[str]):
"""Set minimum required capabilities.
NOTE: Research later - allow presets to override these defaults
"""
self._minimum_capabilities = value
def validate_minimum_capabilities(self) -> tuple[bool, list[str]]:
"""Validate that all minimum capabilities are provided.
Returns:
Tuple of (is_valid, missing_capabilities)
"""
missing = []
for cap in self._minimum_capabilities:
if not self._find_stage_with_capability(cap):
missing.append(cap)
return len(missing) == 0, missing
def ensure_minimum_capabilities(self) -> list[str]:
"""Automatically inject MVP stages if minimum capabilities are missing.
Auto-injection is always on, but defaults are trivial to override.
Returns:
List of stages that were injected
"""
from engine.camera import Camera
from engine.data_sources.sources import EmptyDataSource
from engine.display import DisplayRegistry
from engine.pipeline.adapters import (
CameraClockStage,
CameraStage,
DataSourceStage,
DisplayStage,
SourceItemsToBufferStage,
)
injected = []
# Check for source capability
if (
not self._find_stage_with_capability("source")
and "source" not in self._stages
):
empty_source = EmptyDataSource(width=80, height=24)
self.add_stage("source", DataSourceStage(empty_source, name="empty"))
injected.append("source")
# Check for camera.state capability (must be BEFORE render to accept SOURCE_ITEMS)
camera = None
if not self._find_stage_with_capability("camera.state"):
# Inject static camera (trivial, no movement)
camera = Camera.scroll(speed=0.0)
camera.set_canvas_size(200, 200)
if "camera_update" not in self._stages:
self.add_stage(
"camera_update", CameraClockStage(camera, name="camera-clock")
)
injected.append("camera_update")
# Check for render capability
if (
not self._find_stage_with_capability("render.output")
and "render" not in self._stages
):
self.add_stage("render", SourceItemsToBufferStage(name="items-to-buffer"))
injected.append("render")
# Check for camera stage (must be AFTER render to accept TEXT_BUFFER)
if camera and "camera" not in self._stages:
self.add_stage("camera", CameraStage(camera, name="static"))
injected.append("camera")
# Check for display capability
if (
not self._find_stage_with_capability("display.output")
and "display" not in self._stages
):
display = DisplayRegistry.create("terminal")
if display:
self.add_stage("display", DisplayStage(display, name="terminal"))
injected.append("display")
# Rebuild pipeline if stages were injected
if injected:
self._rebuild()
return injected
def build(self, auto_inject: bool = True) -> "Pipeline":
"""Build execution order based on dependencies.
Args:
auto_inject: If True, automatically inject MVP stages for missing capabilities
"""
self._capability_map = self._build_capability_map()
self._execution_order = self._resolve_dependencies()
# Validate minimum capabilities and auto-inject if needed
if auto_inject:
is_valid, missing = self.validate_minimum_capabilities()
if not is_valid:
injected = self.ensure_minimum_capabilities()
if injected:
print(
f" \033[38;5;226mAuto-injected stages for missing capabilities: {injected}\033[0m"
)
# Rebuild after auto-injection
self._capability_map = self._build_capability_map()
self._execution_order = self._resolve_dependencies()
self._validate_dependencies()
self._validate_types()
self._initialized = True
@@ -367,12 +496,24 @@ class Pipeline:
temp_mark.add(name)
stage = self._stages.get(name)
if stage:
# Handle capability-based dependencies
for dep in stage.dependencies:
# Find a stage that provides this capability
dep_stage_name = self._find_stage_with_capability(dep)
if dep_stage_name:
visit(dep_stage_name)
# Handle direct stage dependencies
for stage_dep in stage.stage_dependencies:
if stage_dep in self._stages:
visit(stage_dep)
else:
# Stage dependency not found - this is an error
raise StageError(
name,
f"Missing stage dependency: '{stage_dep}' not found in pipeline",
)
temp_mark.remove(name)
visited.add(name)
ordered.append(name)

15
engine/pipeline/core.py
View File

@@ -155,6 +155,21 @@ class Stage(ABC):
"""
return set()
@property
def stage_dependencies(self) -> set[str]:
"""Return set of stage names this stage must connect to directly.
This allows explicit stage-to-stage dependencies, useful for enforcing
pipeline structure when capability matching alone is insufficient.
Examples:
- {"viewport_filter"} # Must connect to viewport_filter stage
- {"camera_update"} # Must connect to camera_update stage
NOTE: These are stage names (as added to pipeline), not capabilities.
"""
return set()
def init(self, ctx: "PipelineContext") -> bool:
"""Initialize stage with pipeline context.

11
engine/pipeline/presets.py
View File

@@ -50,6 +50,11 @@ class PipelinePreset:
border: bool | BorderMode = (
False # Border mode: False=off, True=simple, BorderMode.UI for panel
)
# Extended fields for fine-tuning
camera_speed: float = 1.0 # Camera movement speed
viewport_width: int = 80 # Viewport width in columns
viewport_height: int = 24 # Viewport height in rows
source_items: list[dict[str, Any]] | None = None # For ListDataSource
def to_params(self) -> PipelineParams:
"""Convert to PipelineParams."""
@@ -67,6 +72,8 @@ class PipelinePreset:
)
params.camera_mode = self.camera
params.effect_order = self.effects.copy()
# Note: camera_speed, viewport_width/height are not stored in PipelineParams
# They are used directly from the preset object in pipeline_runner.py
return params
@classmethod
@@ -80,6 +87,10 @@ class PipelinePreset:
camera=data.get("camera", "vertical"),
effects=data.get("effects", []),
border=data.get("border", False),
camera_speed=data.get("camera_speed", 1.0),
viewport_width=data.get("viewport_width", 80),
viewport_height=data.get("viewport_height", 24),
source_items=data.get("source_items"),
)

52
engine/pipeline/stages/framebuffer.py
View File

@@ -1,12 +1,12 @@
"""
Frame buffer stage - stores previous frames for temporal effects.
Provides:
- frame_history: list of previous buffers (most recent first)
- intensity_history: list of corresponding intensity maps
- current_intensity: intensity map for current frame
Provides (per-instance, using instance name):
- framebuffer.{name}.history: list of previous buffers (most recent first)
- framebuffer.{name}.intensity_history: list of corresponding intensity maps
- framebuffer.{name}.current_intensity: intensity map for current frame
Capability: "framebuffer.history"
Capability: "framebuffer.history.{name}"
"""
import threading
@@ -22,21 +22,32 @@ class FrameBufferConfig:
"""Configuration for FrameBufferStage."""
history_depth: int = 2 # Number of previous frames to keep
name: str = "default" # Unique instance name for capability and context keys
class FrameBufferStage(Stage):
"""Stores frame history and computes intensity maps."""
"""Stores frame history and computes intensity maps.
Supports multiple instances with unique capabilities and context keys.
"""
name = "framebuffer"
category = "effect" # It's an effect that enriches context with frame history
def __init__(self, config: FrameBufferConfig | None = None, history_depth: int = 2):
self.config = config or FrameBufferConfig(history_depth=history_depth)
def __init__(
self,
config: FrameBufferConfig | None = None,
history_depth: int = 2,
name: str = "default",
):
self.config = config or FrameBufferConfig(
history_depth=history_depth, name=name
)
self._lock = threading.Lock()
@property
def capabilities(self) -> set[str]:
return {"framebuffer.history"}
return {f"framebuffer.history.{self.config.name}"}
@property
def dependencies(self) -> set[str]:
@@ -53,8 +64,9 @@ class FrameBufferStage(Stage):
def init(self, ctx: PipelineContext) -> bool:
"""Initialize framebuffer state in context."""
ctx.set("frame_history", [])
ctx.set("intensity_history", [])
prefix = f"framebuffer.{self.config.name}"
ctx.set(f"{prefix}.history", [])
ctx.set(f"{prefix}.intensity_history", [])
return True
def process(self, data: Any, ctx: PipelineContext) -> Any:
@@ -70,16 +82,18 @@ class FrameBufferStage(Stage):
if not isinstance(data, list):
return data
prefix = f"framebuffer.{self.config.name}"
# Compute intensity map for current buffer (per-row, length = buffer rows)
intensity_map = self._compute_buffer_intensity(data, len(data))
# Store in context
ctx.set("current_intensity", intensity_map)
ctx.set(f"{prefix}.current_intensity", intensity_map)
with self._lock:
# Get existing histories
history = ctx.get("frame_history", [])
intensity_hist = ctx.get("intensity_history", [])
history = ctx.get(f"{prefix}.history", [])
intensity_hist = ctx.get(f"{prefix}.intensity_history", [])
# Prepend current frame to history
history.insert(0, data.copy())
@@ -87,8 +101,8 @@ class FrameBufferStage(Stage):
# Trim to configured depth
max_depth = self.config.history_depth
ctx.set("frame_history", history[:max_depth])
ctx.set("intensity_history", intensity_hist[:max_depth])
ctx.set(f"{prefix}.history", history[:max_depth])
ctx.set(f"{prefix}.intensity_history", intensity_hist[:max_depth])
return data
@@ -137,7 +151,8 @@ class FrameBufferStage(Stage):
"""Get frame from history by index (0 = current, 1 = previous, etc)."""
if ctx is None:
return None
history = ctx.get("frame_history", [])
prefix = f"framebuffer.{self.config.name}"
history = ctx.get(f"{prefix}.history", [])
if 0 <= index < len(history):
return history[index]
return None
@@ -148,7 +163,8 @@ class FrameBufferStage(Stage):
"""Get intensity map from history by index."""
if ctx is None:
return None
intensity_hist = ctx.get("intensity_history", [])
prefix = f"framebuffer.{self.config.name}"
intensity_hist = ctx.get(f"{prefix}.intensity_history", [])
if 0 <= index < len(intensity_hist):
return intensity_hist[index]
return None

4
engine/pipeline/validation.py
View File

@@ -22,6 +22,8 @@ VALID_CAMERAS = [
"omni",
"floating",
"bounce",
"radial",
"static",
"none",
"",
]
@@ -43,7 +45,7 @@ class ValidationResult:
MVP_DEFAULTS = {
"source": "fixture",
"display": "terminal",
"camera": "", # Empty = no camera stage (static viewport)
"camera": "static", # Static camera provides camera_y=0 for viewport filtering
"effects": [],
"border": False,
}