Skip to content

Image Pipeline Playground

feat(backend/nodes): template paths for multi-image Save node

Mohammad Rajaeie159fce183e3
diff --git a/backend/app/engine/executor.py b/backend/app/engine/executor.py
index fb6a3cd..faf8827 100644
--- a/backend/app/engine/executor.py
+++ b/backend/app/engine/executor.py
@@ -15,6 +15,7 @@ import numpy as np
from app.engine.cache import CacheManager
from app.engine.registry import NodeRegistry, registry
+from app.engine.run_context import current_sample_index
from app.models.graph import (
Edge,
ExecuteRequest,
@@ -274,85 +275,93 @@ class DagExecutor:
for sample_index in range(sample_count):
cancel.check()
sample_seed = request.seed + sample_index
+ sample_token = current_sample_index.set(sample_index)
outputs: dict[str, dict[str, np.ndarray | list[np.ndarray]]] = {}
sample_previews: dict[str, Any] = {}
- for index, node_id in enumerate(order):
- cancel.check()
- instance = nodes[node_id]
- node_impl = self.registry.get(instance.type)
- params = node_impl.validate_params(instance.params)
- inputs = _collect_inputs(
- node_id,
- request.graph.edges,
- outputs,
- sample_index=sample_index,
- )
- input_hash_map = _input_hashes(inputs, self.cache)
- cache_key = self.cache.make_key(instance.type, params, input_hash_map, sample_seed)
-
- emit(
- ExecutionEvent(
- type=ExecutionEventType.PROGRESS,
- node_id=node_id,
- progress=(index + 1) / len(order),
+ try:
+ for index, node_id in enumerate(order):
+ cancel.check()
+ instance = nodes[node_id]
+ node_impl = self.registry.get(instance.type)
+ params = node_impl.validate_params(instance.params)
+ node_impl.prepare_run(params)
+ inputs = _collect_inputs(
+ node_id,
+ request.graph.edges,
+ outputs,
sample_index=sample_index,
- message=f"Executing {instance.type}",
)
- )
+ input_hash_map = _input_hashes(inputs, self.cache)
+ cache_key = self.cache.make_key(
+ instance.type, params, input_hash_map, sample_seed
+ )
+
+ emit(
+ ExecutionEvent(
+ type=ExecutionEventType.PROGRESS,
+ node_id=node_id,
+ progress=(index + 1) / len(order),
+ sample_index=sample_index,
+ message=f"Executing {instance.type}",
+ )
+ )
- cache_hit = False
- produced: dict[str, np.ndarray | list[np.ndarray]]
- started = time.perf_counter()
- if request.cache and self.cache.has_outputs(cache_key):
- cached = self.cache.get_outputs(cache_key)
- if cached is not None:
- produced = cached
+ cache_hit = False
+ produced: dict[str, np.ndarray | list[np.ndarray]]
+ started = time.perf_counter()
+ use_cache = request.cache and node_impl.cacheable
+ if use_cache and self.cache.has_outputs(cache_key):
+ cached = self.cache.get_outputs(cache_key)
+ if cached is not None:
+ produced = cached
+ outputs[node_id] = produced
+ cache_hit = True
+
+ if not cache_hit:
+ produced = node_impl.execute(inputs, params, seed=sample_seed)
outputs[node_id] = produced
- cache_hit = True
-
- if not cache_hit:
- produced = node_impl.execute(inputs, params, seed=sample_seed)
- outputs[node_id] = produced
- if request.cache:
- self.cache.put_outputs(
- cache_key,
- produced,
- meta={"node_id": node_id, "type": instance.type},
+ if use_cache:
+ self.cache.put_outputs(
+ cache_key,
+ produced,
+ meta={"node_id": node_id, "type": instance.type},
+ )
+
+ duration_ms = (time.perf_counter() - started) * 1000.0
+ emit(
+ ExecutionEvent(
+ type=ExecutionEventType.PROGRESS,
+ node_id=node_id,
+ progress=(index + 1) / len(order),
+ sample_index=sample_index,
+ cache_hit=cache_hit,
+ duration_ms=duration_ms,
+ message=(
+ f"Finished {instance.type} in {duration_ms:.1f}ms"
+ + (" (cache)" if cache_hit else "")
+ ),
)
+ )
- duration_ms = (time.perf_counter() - started) * 1000.0
- emit(
- ExecutionEvent(
- type=ExecutionEventType.PROGRESS,
+ _emit_port_previews(
+ emit=emit,
node_id=node_id,
- progress=(index + 1) / len(order),
+ produced=produced,
sample_index=sample_index,
cache_hit=cache_hit,
- duration_ms=duration_ms,
- message=(
- f"Finished {instance.type} in {duration_ms:.1f}ms"
- + (" (cache)" if cache_hit else "")
- ),
+ sample_previews=sample_previews,
)
- )
- _emit_port_previews(
- emit=emit,
- node_id=node_id,
- produced=produced,
- sample_index=sample_index,
- cache_hit=cache_hit,
- sample_previews=sample_previews,
+ results["samples"].append(
+ {
+ "sample_index": sample_index,
+ "seed": sample_seed,
+ "previews": sample_previews,
+ }
)
-
- results["samples"].append(
- {
- "sample_index": sample_index,
- "seed": sample_seed,
- "previews": sample_previews,
- }
- )
+ finally:
+ current_sample_index.reset(sample_token)
emit(ExecutionEvent(type=ExecutionEventType.DONE, message="Execution complete"))
return results
diff --git a/backend/app/engine/registry.py b/backend/app/engine/registry.py
index 517eb65..379c0f9 100644
--- a/backend/app/engine/registry.py
+++ b/backend/app/engine/registry.py
@@ -20,6 +20,7 @@ class BaseNode(ABC):
ports: list[PortSpec] = []
params: list[ParamField] = []
stochastic: bool = False
+ cacheable: bool = True
def metadata(self) -> NodeMetadata:
return NodeMetadata(
@@ -51,6 +52,9 @@ class BaseNode(ABC):
raise ValueError(f"Parameter '{field.name}' must be one of {field.options}")
return merged
+ def prepare_run(self, params: dict[str, Any]) -> None:
+ """Hook called before execute/cache lookup (e.g. publish source filenames)."""
+
@abstractmethod
def execute(
self,
diff --git a/backend/app/engine/run_context.py b/backend/app/engine/run_context.py
new file mode 100644
index 0000000..25b8c5d
--- /dev/null
+++ b/backend/app/engine/run_context.py
@@ -0,0 +1,18 @@
+"""Per-execution context for sample index and source filenames."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+
+current_sample_index: ContextVar[int] = ContextVar("current_sample_index", default=0)
+current_source_stems: ContextVar[list[str]] = ContextVar(
+ "current_source_stems",
+ default=[],
+)
+
+
+def source_stem_for_sample(sample_index: int) -> str:
+ stems = current_source_stems.get()
+ if not stems:
+ return "image"
+ return stems[sample_index % len(stems)]
diff --git a/backend/app/nodes/io.py b/backend/app/nodes/io.py
index 9616112..d7f02ec 100644
--- a/backend/app/nodes/io.py
+++ b/backend/app/nodes/io.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+from datetime import datetime
from pathlib import Path
from typing import Any
@@ -9,6 +10,11 @@ import cv2
import numpy as np
from app.engine.registry import BaseNode
+from app.engine.run_context import (
+ current_sample_index,
+ current_source_stems,
+ source_stem_for_sample,
+)
from app.nodes.common import (
IMAGE_EXTENSIONS,
file_param,
@@ -67,6 +73,17 @@ class LoadImageNode(BaseNode):
)
]
+ def prepare_run(self, params: dict[str, Any]) -> None:
+ path_value = str(params.get("path", ""))
+ if not path_value:
+ current_source_stems.set([])
+ return
+ try:
+ files = list_image_files(Path(path_value))
+ current_source_stems.set([file_path.stem for file_path in files])
+ except (OSError, ValueError, FileNotFoundError):
+ current_source_stems.set([])
+
def execute(
self,
inputs: dict[str, np.ndarray | list[np.ndarray] | None],
@@ -78,6 +95,7 @@ class LoadImageNode(BaseNode):
raise ValueError("Load Images requires a file or folder selection")
path = Path(path_value)
files = list_image_files(path)
+ current_source_stems.set([file_path.stem for file_path in files])
images = [read_image(file_path) for file_path in files]
return {"image": images}
@@ -112,9 +130,24 @@ class SaveImageNode(BaseNode):
type = "save_image"
label = "Save Image"
category = "io"
- description = "Write an image to disk."
+ description = (
+ "Write image(s) to disk. Path supports templates: "
+ "{filename}, {time}, {index}."
+ )
+ cacheable = False
ports = [image_in(), image_out()]
- params = [string_param("path", "Path", "output.png")]
+ params = [
+ string_param(
+ "path",
+ "Path",
+ "output/{filename}_{index}.png",
+ description=(
+ "Output path template. Placeholders: "
+ "{filename} source stem, {time} YYYYmmdd_HHMMSS, {index} sample index. "
+ "If {index} is omitted, it is appended for sample index > 0."
+ ),
+ )
+ ]
def execute(
self,
@@ -123,7 +156,13 @@ class SaveImageNode(BaseNode):
seed: int = 0,
) -> dict[str, np.ndarray | list[np.ndarray]]:
image = require_image(inputs)
- path = Path(str(params["path"]))
+ sample_index = current_sample_index.get()
+ path = resolve_save_path(
+ str(params["path"]),
+ index=sample_index,
+ filename=source_stem_for_sample(sample_index),
+ when=datetime.now(),
+ )
path.parent.mkdir(parents=True, exist_ok=True)
if not cv2.imwrite(str(path), image):
raise RuntimeError(f"Failed to write image to '{path}'")
@@ -136,12 +175,56 @@ class SaveImageNode(BaseNode):
input_vars: dict[str, str],
output_vars: dict[str, str],
) -> list[str]:
+ template = str(params["path"])
+ src = input_vars["image"]
+ dst = output_vars["image"]
return [
- f"cv2.imwrite({params['path']!r}, {input_vars['image']})",
- f"{output_vars['image']} = {input_vars['image']}",
+ "from datetime import datetime",
+ f"_template = {template!r}",
+ "_index = 0 # set per sample when batching",
+ "_filename = 'image'",
+ "_time = datetime.now().strftime('%Y%m%d_%H%M%S')",
+ (
+ "_path = Path(_template.replace('{filename}', _filename)"
+ ".replace('{time}', _time).replace('{index}', str(_index)))"
+ ),
+ (
+ "if _index > 0 and '{index}' not in _template "
+ "and '{time}' not in _template and '{filename}' not in _template:"
+ ),
+ " _path = _path.with_name(f'{_path.stem}_{_index}{_path.suffix}')",
+ "_path.parent.mkdir(parents=True, exist_ok=True)",
+ f"cv2.imwrite(str(_path), {src})",
+ f"{dst} = {src}",
]
+def resolve_save_path(
+ template: str,
+ *,
+ index: int,
+ filename: str,
+ when: datetime,
+) -> Path:
+ """Expand {filename}, {time}, {index} in a save path template."""
+ safe_name = Path(filename).stem or "image"
+ # Strip path separators from injected filename so templates stay under the intended folder.
+ safe_name = safe_name.replace("/", "_").replace("\\", "_")
+ time_token = when.strftime("%Y%m%d_%H%M%S")
+ expanded = (
+ template.replace("{filename}", safe_name)
+ .replace("{time}", time_token)
+ .replace("{index}", str(index))
+ )
+ path = Path(expanded)
+ has_unique_token = any(
+ token in template for token in ("{index}", "{time}", "{filename}")
+ )
+ if index > 0 and not has_unique_token:
+ path = path.with_name(f"{path.stem}_{index}{path.suffix}")
+ return path
+
+
class PreviewNode(BaseNode):
type = "preview"
label = "Preview"
diff --git a/backend/tests/test_io_save_image.py b/backend/tests/test_io_save_image.py
new file mode 100644
index 0000000..20bd28f
--- /dev/null
+++ b/backend/tests/test_io_save_image.py
@@ -0,0 +1,105 @@
+"""Tests for Save Image path templates and multi-sample writes."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+from app.engine.executor import DagExecutor
+from app.engine.registry import registry
+from app.engine.run_context import current_sample_index, current_source_stems
+from app.models.graph import Edge, ExecuteRequest, Graph, NodeInstance
+from app.nodes import register_builtin_nodes
+from app.nodes.io import resolve_save_path
+
+
+def test_resolve_save_path_templates() -> None:
+ when = datetime(2026, 7, 30, 22, 55, 1)
+ path = resolve_save_path(
+ "out/{filename}_{index}_{time}.png",
+ index=2,
+ filename="lena",
+ when=when,
+ )
+ assert path == Path("out/lena_2_20260730_225501.png")
+
+
+def test_resolve_save_path_auto_index_when_missing() -> None:
+ path = resolve_save_path(
+ "output.png",
+ index=3,
+ filename="x",
+ when=datetime(2026, 1, 1, 0, 0, 0),
+ )
+ assert path.name == "output_3.png"
+
+
+def test_save_image_uses_templates(tmp_path) -> None:
+ register_builtin_nodes()
+ image = np.zeros((4, 4, 3), dtype=np.uint8)
+ image[:, :] = (10, 20, 30)
+ token_i = current_sample_index.set(1)
+ token_s = current_source_stems.set(["photo"])
+ try:
+ out = registry.get("save_image").execute(
+ {"image": image},
+ {"path": str(tmp_path / "{filename}_{index}.png")},
+ seed=0,
+ )["image"]
+ finally:
+ current_sample_index.reset(token_i)
+ current_source_stems.reset(token_s)
+
+ assert out.shape == image.shape
+ saved = tmp_path / "photo_1.png"
+ assert saved.is_file()
+ loaded = cv2.imread(str(saved))
+ assert loaded is not None
+ assert tuple(loaded[0, 0]) == (10, 20, 30)
+
+
+def test_save_image_batch_writes_unique_files(tmp_path) -> None:
+ register_builtin_nodes()
+ a = np.full((2, 2, 3), 1, dtype=np.uint8)
+ b = np.full((2, 2, 3), 2, dtype=np.uint8)
+ path_a = tmp_path / "a.png"
+ path_b = tmp_path / "b.png"
+ cv2.imwrite(str(path_a), a)
+ cv2.imwrite(str(path_b), b)
+
+ request = ExecuteRequest(
+ graph=Graph(
+ nodes=[
+ NodeInstance(
+ id="load",
+ type="load_image",
+ params={"path": str(tmp_path)},
+ ),
+ NodeInstance(
+ id="save",
+ type="save_image",
+ params={"path": str(tmp_path / "out" / "{filename}_{index}.png")},
+ ),
+ ],
+ edges=[
+ Edge(
+ id="e1",
+ source="load",
+ source_port="image",
+ target="save",
+ target_port="image",
+ )
+ ],
+ ),
+ seed=0,
+ sample_count=2,
+ cache=True,
+ )
+ executor = DagExecutor(tmp_path / "cache", node_registry=registry)
+ executor.execute(request)
+
+ assert (tmp_path / "out" / "a_0.png").is_file()
+ assert (tmp_path / "out" / "b_1.png").is_file()