Layout

The simplest way: return the grid

The pipeline function's return statement is the layout. Return a flat tuple for a single row, or a nested list to arrange the outputs in a grid — no extra code:

@interactive_pipeline(gui="qt")
def pipe(img):
    a = exposure(img)
    b = black_and_white(img)
    c = blend(a, b)
    d = compute_histo(c)
    return [[a, b], [c, d]]   # 2x2 grid

• return a, b, c — one row of three.
• return [[a, b], [c, d]] — 2×2 grid.
• return [[a], [b]] — one column of two (stacked).
• return [[a, b], [c, None]] — None leaves a cell empty.

Dynamic layouts: the layout proxy

For layouts that change at runtime — driven by a slider, a dropdown, or the data itself — use the layout proxy from inside any filter. Output names are the variable names used in the pipeline function:

from interactive_pipe import layout

@interactive(layout_mode=["side_by_side", "grid2x2"])
def change_layout(layout_mode: str = "side_by_side"):
    if layout_mode == "side_by_side":
        layout.grid([["input", "result"]])
    if layout_mode == "grid2x2":
        layout.grid([["input", "processed"], ["histogram_graph", "result"]])
    layout.style("result", title="Final Result")

def pipeline(input):
    processed = denoise(input)
    result = change_brightness(processed)
    histogram_graph = compute_histo(processed)
    change_layout()
    return result

Live layout switching (e.g. going from a side-by-side comparison to a 2x2 grid while the app runs) is supported on the Qt backend.

layout methods

Proxy for display and layout operations using contextvars.

This class provides a clean API for controlling output display properties and grid arrangements without polluting function signatures.

Available methods

• style(): Set display properties (title, colormap, etc.)
• grid(): Set the output grid layout
• row(): Convenience for single-row layout

style

style(name: str, *, title: Optional[str] = None, **style_kwargs: Any) -> None

Set display properties for an output.

Parameters:

Name	Type	Description	Default
name	str	Output variable name (must match the variable name in the return statement)	required
title	Optional[str]	Display title for the output	None
**style_kwargs	Any	Additional style properties (colormap, vmin, vmax, etc.)	{}

Example

layout.style("processed", title=f"Brightness: {brightness:.2f}")
layout.style("heatmap", title="Heat Map", colormap="viridis", vmin=0, vmax=1)

Raises:

Type	Description
RuntimeError	If called outside of filter execution context.

grid

grid(arrangement: Union[List[str], List[List[str]]]) -> None

Set the output grid layout.

Parameters:

Name	Type	Description	Default
arrangement	Union[List[str], List[List[str]]]	Either a flat list of output names (treated as a single row) or a 2D list of output names defining the grid arrangement	required

Example

# Single row (flat list)
layout.grid(["img1", "img2", "img3"])

# Single row (nested list - equivalent to above)
layout.grid([["img1", "img2", "img3"]])

# 2x2 grid
layout.grid([
    ["original", "processed"],
    ["histogram", "stats"]
])

Raises:

Type	Description
RuntimeError	If called outside of filter execution context.

row

row(outputs: List[str]) -> None

Convenience method for single-row layout.

This is equivalent to calling grid([outputs]).

Parameters:

Name	Type	Description	Default
outputs	List[str]	List of output names to display in a single row	required

Example

layout.row(["original", "filtered", "result"])

Raises:

Type	Description
RuntimeError	If called outside of filter execution context.