feat: implement visual pipeline debugger

Author: Your Name

imagelab-backend/app/models/pipeline.py

@@ -4,12 +4,14 @@
 class PipelineStep(BaseModel):
     type: str
     params: dict = {}
+    id: str | None = None
 
 
 class PipelineRequest(BaseModel):
     image: str
     image_format: str = "png"
     pipeline: list[PipelineStep]
+    debug: bool = False
 
 
 class StepTiming(BaseModel):
@@ -23,10 +25,21 @@ class PipelineTimings(BaseModel):
     steps: list[StepTiming]
 
 
+class DebugStepState(BaseModel):
+    """Snapshot of the image after a single operator executes."""
+
+    step: int
+    block_id: str | None = None
+    operator_type: str
+    image: str
+    duration_ms: float
+
+
 class PipelineResponse(BaseModel):
     success: bool
     image: str | None = None
     image_format: str | None = None
     error: str | None = None
     step: int | None = None
     timings: PipelineTimings | None = None
+    debug_states: list[DebugStepState] | None = None

imagelab-backend/app/services/pipeline_executor.py

@@ -1,11 +1,46 @@
 import time
 
-from app.models.pipeline import PipelineRequest, PipelineResponse, PipelineTimings, StepTiming
+import cv2
+import numpy as np
+
+from app.models.pipeline import (
+    DebugStepState,
+    PipelineRequest,
+    PipelineResponse,
+    PipelineTimings,
+    StepTiming,
+)
 from app.operators.registry import get_operator
 from app.utils.image import decode_base64_image, encode_image_base64
 
 NOOP_TYPES = {"basic_readimage", "basic_writeimage", "border_for_all", "border_each_side"}
 
+DEBUG_ENCODE_FORMAT = "jpeg"
+DEBUG_JPEG_QUALITY = 70
+MAX_DEBUG_DIM = 512
+MAX_DEBUG_STEPS = 25
+
+
+def _thumbnail_for_debug(image: np.ndarray) -> np.ndarray:
+    """Resize image to fit within MAX_DEBUG_DIM for compact debug snapshots."""
+    h, w = image.shape[:2]
+    if max(h, w) <= MAX_DEBUG_DIM:
+        return image
+    scale = MAX_DEBUG_DIM / max(h, w)
+    new_w, new_h = int(w * scale), int(h * scale)
+    return cv2.resize(image, (new_w, new_h), interpolation=cv2.INTER_AREA)
+
+
+def _encode_debug_image(image: np.ndarray) -> str:
+    """Encode an intermediate image as a compressed JPEG thumbnail."""
+    thumb = _thumbnail_for_debug(image)
+    # Ensure the image has 3 channels for JPEG encoding
+    if len(thumb.shape) == 2:
+        thumb = cv2.cvtColor(thumb, cv2.COLOR_GRAY2BGR)
+    elif thumb.shape[2] == 4:
+        thumb = cv2.cvtColor(thumb, cv2.COLOR_BGRA2BGR)
+    return encode_image_base64(thumb, DEBUG_ENCODE_FORMAT, quality=DEBUG_JPEG_QUALITY)
+
 
 # Thread-safety: this function is safe to call concurrently from FastAPI's
 # threadpool. All processing state (image array, operator instances, encoded
@@ -22,6 +57,7 @@ def execute_pipeline(request: PipelineRequest) -> PipelineResponse:
     """
     t_start_total = time.perf_counter()
     step_timings: list[StepTiming] = []
+    debug_states: list[DebugStepState] = []
 
     try:
         image = decode_base64_image(request.image)
@@ -34,6 +70,18 @@ def execute_pipeline(request: PipelineRequest) -> PipelineResponse:
             timings=PipelineTimings(total_ms=(t_fail - t_start_total) * 1000, steps=step_timings),
         )
 
+    # Step 0: capture the original decoded image as the "before anything" state
+    if request.debug:
+        debug_states.append(
+            DebugStepState(
+                step=0,
+                block_id=None,
+                operator_type="original",
+                image=_encode_debug_image(image),
+                duration_ms=0.0,
+            )
+        )
+
     for i, step in enumerate(request.pipeline):
         if step.type in NOOP_TYPES:
             continue
@@ -46,23 +94,36 @@ def execute_pipeline(request: PipelineRequest) -> PipelineResponse:
                 error=f"Unknown operator '{step.type}' at step {i + 1}",
                 step=i + 1,
                 timings=PipelineTimings(total_ms=(t_fail - t_start_total) * 1000, steps=step_timings),
+                debug_states=debug_states if request.debug else None,
             )
 
         try:
             t_step_start = time.perf_counter()
             operator = operator_cls(step.params)
             image = operator.compute(image)
             t_step_end = time.perf_counter()
-            step_timings.append(
-                StepTiming(step=i + 1, operator_type=step.type, duration_ms=(t_step_end - t_step_start) * 1000)
-            )
+            step_ms = (t_step_end - t_step_start) * 1000
+            step_timings.append(StepTiming(step=i + 1, operator_type=step.type, duration_ms=step_ms))
+
+            # Debug injection: capture this step's output
+            if request.debug and len(debug_states) < MAX_DEBUG_STEPS:
+                debug_states.append(
+                    DebugStepState(
+                        step=i + 1,
+                        block_id=step.id,
+                        operator_type=step.type,
+                        image=_encode_debug_image(image),
+                        duration_ms=step_ms,
+                    )
+                )
         except Exception as e:
             t_fail = time.perf_counter()
             return PipelineResponse(
                 success=False,
                 error=f"Error in step {i + 1} ({step.type}): {type(e).__name__}: {e}",
                 step=i + 1,
                 timings=PipelineTimings(total_ms=(t_fail - t_start_total) * 1000, steps=step_timings),
+                debug_states=debug_states if request.debug else None,
             )
 
     try:
@@ -75,6 +136,7 @@ def execute_pipeline(request: PipelineRequest) -> PipelineResponse:
             error=error_msg,
             step=len(request.pipeline),
             timings=PipelineTimings(total_ms=(t_fail - t_start_total) * 1000, steps=step_timings),
+            debug_states=debug_states if request.debug else None,
         )
 
     t_end_total = time.perf_counter()
@@ -84,4 +146,5 @@ def execute_pipeline(request: PipelineRequest) -> PipelineResponse:
         image=encoded,
         image_format=request.image_format,
         timings=PipelineTimings(total_ms=(t_end_total - t_start_total) * 1000, steps=step_timings),
+        debug_states=debug_states if request.debug else None,
     )

imagelab-backend/app/utils/color.py

@@ -1,6 +1,5 @@
 import re
 
-
 HEX_COLOR_RE = re.compile(r"^[0-9a-fA-F]{6}$")
 
 
@@ -19,17 +18,13 @@ def hex_to_bgr(hex_color: str) -> tuple[int, int, int]:
         ValueError: If hex_color is not a valid 6-digit hex color string.
     """
     if not isinstance(hex_color, str):
-        raise TypeError(
-            f"hex_to_bgr expects a str, got {type(hex_color).__name__!r}"
-        )
+        raise TypeError(f"hex_to_bgr expects a str, got {type(hex_color).__name__!r}")
 
     original = hex_color
     normalized = hex_color.removeprefix("#")
 
     if not HEX_COLOR_RE.fullmatch(normalized):
-        raise ValueError(
-            f"Invalid hex color: {original!r}. Expected format '#rrggbb' or 'rrggbb'."
-        )
+        raise ValueError(f"Invalid hex color: {original!r}. Expected format '#rrggbb' or 'rrggbb'.")
 
     r = int(normalized[0:2], 16)
     g = int(normalized[2:4], 16)

imagelab-backend/app/utils/image.py

@@ -13,8 +13,15 @@ def decode_base64_image(b64: str) -> np.ndarray:
     return image
 
 
-def encode_image_base64(image: np.ndarray, fmt: str = "png") -> str:
-    success, buf = cv2.imencode(f".{fmt}", image)
+def encode_image_base64(image: np.ndarray, fmt: str = "png", quality: int | None = None) -> str:
+    params = []
+    if quality is not None:
+        if fmt.lower() in ("jpg", "jpeg"):
+            params = [cv2.IMWRITE_JPEG_QUALITY, quality]
+        elif fmt.lower() == "webp":
+            params = [cv2.IMWRITE_WEBP_QUALITY, quality]
+
+    success, buf = cv2.imencode(f".{fmt}", image, params)
     if not success:
         raise ValueError(f"Could not encode image as {fmt}")
     return base64.b64encode(buf).decode("utf-8")

imagelab-backend/tests/test_filtering_operators.py

@@ -80,9 +80,7 @@ def test_asymmetric_kernel_uses_width_height_convention(self):
         image = np.arange(75, dtype=np.uint8).reshape(5, 5, 3)
         width, height = 1, 5
 
-        result = BoxFilter({"width": width, "height": height, "depth": -1}).compute(
-            image
-        )
+        result = BoxFilter({"width": width, "height": height, "depth": -1}).compute(image)
         expected = cv2.boxFilter(
             image,
             -1,

imagelab-frontend/src/components/Layout.tsx

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useState, useEffect } from "react";
 import { useBlocklyWorkspace } from "../hooks/useBlocklyWorkspace";
 import { usePipelineStore } from "../store/pipelineStore";
 import Navbar from "./Navbar";
@@ -10,9 +10,40 @@ import { ErrorBoundary } from "./ErrorBoundary";
 
 export default function Layout() {
   const { containerRef, workspace } = useBlocklyWorkspace();
-  const { reset } = usePipelineStore();
+  const { reset, isDebugActive, debugStates, debugCursor } = usePipelineStore();
   const [resetKey, setResetKey] = useState(0);
 
+  // Apply visual highlighting to blocks during debug mode
+  useEffect(() => {
+    if (!workspace) return;
+
+    // First, remove highlight from all blocks
+    const allBlocks = workspace.getAllBlocks(false);
+    allBlocks.forEach((block) => {
+      const svgRoot = block.getSvgRoot();
+      if (svgRoot) {
+        svgRoot.classList.remove("debug-highlighted-block");
+      }
+    });
+
+    // Then, if debug is active and we have a valid block, highlight it
+    if (isDebugActive && debugStates && debugStates.length > 0) {
+      const currentState = debugStates[debugCursor];
+      if (currentState && currentState.block_id) {
+        const activeBlock = workspace.getBlockById(currentState.block_id);
+        if (activeBlock) {
+          const svgRoot = activeBlock.getSvgRoot();
+          if (svgRoot) {
+            svgRoot.classList.add("debug-highlighted-block");
+
+            // Optional: Scroll to the block
+            // workspace.centerOnBlock(currentState.block_id);
+          }
+        }
+      }
+    }
+  }, [workspace, isDebugActive, debugStates, debugCursor]);
+
   const handleEditorReset = () => {
     setResetKey((prev) => prev + 1);
     reset();

imagelab-frontend/src/components/Preview/DebugScrubber.tsx

@@ -0,0 +1,92 @@
+import { usePipelineStore } from "../../store/pipelineStore";
+import { ChevronLeft, ChevronRight, X, Play } from "lucide-react";
+
+export default function DebugScrubber() {
+  const { debugStates, debugCursor, stepForward, stepBackward, exitDebug } = usePipelineStore();
+
+  if (!debugStates || debugStates.length === 0) return null;
+
+  const currentState = debugStates[debugCursor];
+
+  return (
+    <div className="flex flex-col h-full bg-gray-50 bg-[radial-gradient(#e5e7eb_1px,transparent_1px)] [background-size:16px_16px]">
+      {/* Header */}
+      <div className="flex items-center justify-between px-3 py-2 bg-white border-b border-amber-200">
+        <div className="flex items-center gap-2">
+          <span className="flex items-center justify-center w-5 h-5 rounded bg-amber-100 text-amber-700 text-xs font-bold font-mono">
+            {debugCursor}
+          </span>
+          <span className="text-sm font-semibold text-gray-700 font-mono">
+            {currentState.operator_type}
+          </span>
+        </div>
+        <button
+          onClick={exitDebug}
+          className="p-1 hover:bg-gray-100 rounded text-gray-400 hover:text-gray-600 transition-colors"
+          title="Exit Debug Mode (Esc)"
+        >
+          <X size={16} />
+        </button>
+      </div>
+
+      {/* Image Display */}
+      <div className="flex-1 flex items-center justify-center p-4 min-h-0 overflow-auto">
+        <img
+          src={`data:image/jpeg;base64,${currentState.image}`}
+          alt={`Debug step ${debugCursor}`}
+          className="max-w-full max-h-full object-contain shadow-sm border border-gray-200 rounded"
+        />
+      </div>
+
+      {/* Footer / Scrubber Controls */}
+      <div className="p-3 bg-white border-t border-gray-200 shadow-[0_-4px_6px_-1px_rgba(0,0,0,0.05)]">
+        <div className="flex items-center gap-3">
+          <button
+            onClick={stepBackward}
+            disabled={debugCursor === 0}
+            className="p-1.5 rounded hover:bg-gray-100 disabled:opacity-30 disabled:hover:bg-transparent text-gray-600 transition-colors"
+            title="Previous Step (Left Arrow)"
+          >
+            <ChevronLeft size={20} />
+          </button>
+
+          <div className="flex-1 relative flex items-center group cursor-pointer h-6">
+            {/* Scrubber track */}
+            <div className="absolute left-0 right-0 h-1.5 bg-gray-100 rounded-full overflow-hidden">
+              <div
+                className="h-full bg-amber-400 rounded-full transition-all duration-200"
+                style={{
+                  width: `${(debugCursor / Math.max(1, debugStates.length - 1)) * 100}%`,
+                }}
+              />
+            </div>
+            {/* Interactive ticks */}
+            <div className="absolute inset-x-0 inset-y-0 flex justify-between items-center px-1">
+              {debugStates.map((_, i) => (
+                <div
+                  key={i}
+                  className={`w-1.5 h-1.5 rounded-full z-10 transition-colors duration-200 ${
+                    i <= debugCursor ? "bg-amber-600" : "bg-gray-300"
+                  } ${i === debugCursor ? "ring-4 ring-amber-100 scale-150" : ""}`}
+                />
+              ))}
+            </div>
+          </div>
+
+          <button
+            onClick={stepForward}
+            disabled={debugCursor === debugStates.length - 1}
+            className="p-1.5 rounded hover:bg-gray-100 disabled:opacity-30 disabled:hover:bg-transparent text-gray-600 transition-colors"
+            title="Next Step (Right Arrow)"
+          >
+            {debugCursor === debugStates.length - 1 ? (
+              <Play size={20} />
+            ) : (
+              <ChevronRight size={20} />
+            )}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}