VIPP 0.12.0a1¶

Release date: 14 July 2026

Maturity: Alpha pre-release

VIPP 0.12.0a1 is a major architectural and scientific-contract overhaul. It makes source identity, axis/channel meaning, physical-grid compatibility, workflow execution, Python export, and batch provenance explicit. It also adds a retained batch workspace for reviewing representatives and completed runs.

This release deliberately rejects several ambiguous behaviors instead of guessing. An error that appears after upgrading can therefore be a new safety check rather than a regression.

Workflow compatibility break

0.12.0a1 writes workflow schema version 3. Schema versions 1 and 2 are rejected; there is no automatic migration. Keep the VIPP environment that created an older workflow, preserve the original JSON, and recreate and validate the graph in 0.12. Do not change only the version field.

Highlights¶

Stable, revision-checked file/store and napari-layer sources.
Explicit axes, channel choices, RGB meaning, and physical-grid validation.
One validated headless executor shared by the GUI and generated Python.
Versioned batch configuration, deterministic preview/execution planning, manifests, archives, item sidecars, and collision policies.
A retained Batch workspace... with full-plan representative navigation, item progress, final status, validation, and manifest paths.
Exact, chunk-bounded diagnostic calculations with stale-result protection.
More usable Richardson-Lucy TV controls and consistent draggable histogram thresholds.
A smaller composition root and enforced Qt-free scientific service layer.

Before upgrading¶

Record the exact older VIPP version and preserve its environment if an existing workflow must remain executable.
Make read-only copies of workflow JSON, generated Python, inputs, outputs, methods notes, and validation evidence.
Recreate schema-1/2 graphs in 0.12.0a1. Compare every node, connection, dynamic port, parameter, source series, axis, channel, scale, unit, and result on known data.
Select every new required channel-axis mode, Composite-to-RGB mapping, threshold scope/bin choice, and intensity cutoff deliberately.
Regenerate exported Python. A 0.12 export records its generating VIPP version and refuses a different runtime.
Preview a batch again and save a new batch config. Do not treat an older ad-hoc runner or file list as equivalent to the 0.12 batch contract.

See the complete upgrade procedure and workflow contract.

Scientific behavior and compatibility¶

Explicit axes and channels¶

Operations whose result depends on channel placement now persist a channel_axis choice. -1 means scalar/no-channel data; it no longer means “guess from a trailing axis of length three or four.” Generic C axes remain scientific channels unless metadata explicitly declares rgb or rgba.

This affects crop, blur and denoising, background correction, edge filters, automatic/manual/adaptive thresholds, and other channel-sensitive operations. Axis metadata carries confidence: an explicit reader/user declaration is not treated as interchangeable with shape inference. Automatic spatial, projection, channel, and PSF choices fail when only ambiguous inferred meaning is available.

Composite to RGB preserves native numeric values by default. Independent per-channel 1st-to-99th-percentile normalization is available only as an explicit lossy mapping. Wide integers, floating overflow, non-finite, complex, object, duplicated-axis, invalid manual index, and ambiguous automatic-axis cases are validated rather than silently coerced. Manual axis mode deliberately permits any valid chosen axis—including Z when metadata declares a separate C axis.

Composite configuration now exposes two persisted decisions:

Channel axis mode — Auto resolves the explicit carried channel axis and shows it in a disabled selector; Manual enables any valid explicit axis choice, including a deliberate spatial-axis mapping.
RGB mapping mode — Auto shows a disabled resolved mapping; Manual enables one assignment for every detected source channel.

Manual choices are Unassigned, Red, Green, Blue, Magenta, Cyan, and Yellow. Unassigned channels contribute nothing; composite colours and repeated assignments mix additively. The dynamic form supports arbitrary source-channel counts, not only three RGB selectors. Auto mapping preserves declared encoded RGB/RGBA order (alpha ignored) or blends all fluorescence channels using their carried pseudo-colours and the repeating Blue/Green/Red/Magenta/Yellow/ Cyan fallback. Legacy numeric axis and RGB-plane fields remain hidden only for workflow compatibility.

Changing these controls invalidates Composite → RGB and its downstream dependants only. Every calculated upstream manual result—including a deconvolution several hops away—remains cached in Keep-all, Smart, and Low-memory modes. Automatic upstream nodes are not invalidated by the edit, but their arrays remain eligible for normal Smart/Low-memory pruning and are recomputed if needed.

Stable sources and physical grids¶

Local files and directory stores receive an identity derived from their path revision and bytes. VIPP checks that identity around inspection and materialization, owns a read-only snapshot, and pins it until Refresh. A source changed during calculation is rejected. Live NumPy-backed napari layers are likewise copied and revision-tokened; supported data, metadata, RGB, axes, scale, translation, unit, rotation, shear, and affine events invalidate stale work.

Multi-image operations no longer use equal array shape as proof of alignment. They validate axis meaning, sample counts, scale, compatible units, and origin. Image/mask broadcasting is semantic rather than based on coincident sizes, and image/PSF operations require compatible spatial sampling. VIPP does not insert hidden registration, resampling, axis reinterpretation, or origin repair.

Operation contracts fail visibly¶

Parameter validation was tightened across crop, projection, split/range grammar, Canny, hysteresis, difference-of-Gaussians, image arithmetic, gamma, linear scaling, dtype conversion, and PSF generation. Invalid values fail instead of being clamped, reordered, rounded, or replaced. Kernels accept read-only inputs and must not mutate source/cache buffers.

Workflow persistence, execution, and export¶

Schema 3 persists the choices required by the stricter scientific contracts, including channel semantics and Composite-to-RGB mapping. Workflow files are decoded into detached, validated GraphSnapshot and WorkflowSnapshot values. Port/type/cycle/tunnel validation completes before live editor state is replaced.

JSON and generated text are written through flushed, fsynced, same-directory temporary files and atomically replaced. Non-finite JSON is rejected; a failed write leaves the prior artifact intact. Related files remain separate artifacts—not one multi-file transaction.

Background execution crosses a typed, detached request/result boundary. Qt workers adapt signals and do not own scientific calculation. Late results are discarded after graph/source revisions change or the widget shuts down.

Export Python... now embeds immutable, validated workflow JSON and invokes the same executor as VIPP. Each call constructs a fresh pipeline, preserves ImageState through supported load/save paths, and supports explicit multi-source bindings. Missing, duplicate, or unknown sources fail. Generated programs are locked to the exact VIPP version that created them.

Deterministic batch configuration and provenance¶

The collection batch system now uses a single deterministic planner for both preview and execution. Each bound source collection is sorted and paired by position; all collections must contain the same number of items. Planning resolves selected outputs and detects duplicate, existing-path, input-overlap, and within-plan collisions before graph execution.

Batch Output nodes are authoritative. A warned compatibility fallback may save terminal nodes only when each terminal has one unambiguous output port. Workflows with enabled Save Image side effects are rejected for batch use.

A versioned vipp_batch_config.json records:

source-node bindings, folders, patterns, and deterministic pairing;
output folder, names, formats, and Error/Skip/Overwrite policy;
resolved output declarations;
the required workflow companion and optional runner;
the canonical scientific workflow hash.

Every run writes a latest vipp_batch_manifest.json, a run-id archive, and per-item sidecar checkpoints. These record workflow/config hashes, software versions, source identities and metadata, planned output paths/policies, errors, and item/output states. Successful outputs survive later item failures; final summaries distinguish completed, partial, skipped, and failed items.

For each item, outputs are staged privately, every source identity is reverified, and only then are outputs promoted one at a time. A source revision change publishes none of that item's outputs. A later promotion failure is recorded as partial. Sidecars provide an interruption-recovery trail but are not a cross-file transaction log.

The generated vipp_batch_pipeline.py is now a thin launcher that defaults to its sibling config and delegates to the same headless batch core as the GUI.

Run batch... has been replaced by Batch workspace.... The modeless, retained workspace keeps configuration, the reviewed plan, run progress, final statuses, validation, and the manifest path available while the graph is visible. Its body scrolls on small displays while Run and Close remain fixed.

After preview, Previous/Next buttons, a slider, and preview-table activation can select any item in the complete plan. VIPP atomically swaps all collection-bound Image Sources and calculates only that representative through the live graph. It does not save outputs, change serialized source parameters, or alter the workflow hash. Requested and successfully committed representative positions are tracked separately so a failed or stale asynchronous load is never labelled as displayed.

Editing the scientific graph or batch setup marks the reviewed plan stale. Run performs a fresh preflight and stops for review if files, destinations, collision states, sources, or the graph differ. Historical run status remains visible until a new preview.

Open batch demo... creates a safe working copy of a deterministic two-source, three-item bundle. Navigate all three paired fields, then Run demo batch to produce nine NPY/TIFF/TSV outputs and validate exact arrays/rows, identities, hashes, manifests, archives, and three finalized item sidecars.

Diagnostics, histograms, and presentation¶

The new Qt-free diagnostics core provides exact finite statistics, extrema, percentiles, histograms, contrast limits, and label-volume summaries. Bounded chunks control temporary memory; they never imply hidden sampling. Large work runs through typed, stale-safe workers.

Generated inspect/pin layers receive detached arrays. Provisional contrast is display-only and later replaced by exact finite limits; presentation cannot feed back into source selection, graph caches, or scientific outputs.

Input-histogram guides now behave consistently:

Binary and Hysteresis thresholds and explicit Rescale/Clip guides are draggable and queue interactive recalculation.
Both Rescale Intensity guides can be dragged. Moving a percentile-derived guide switches the node to explicit values and preserves the other exact cutoff.
Clicking a guide without moving it does not edit a parameter.
Unchanged input counts are reused while a manual guide moves; the output histogram refreshes when the output population changes.

Richardson-Lucy TV controls¶

Every Richardson-Lucy TV parameter now has an effect-oriented tooltip on its label and interactive controls. Practical slider windows are independent of the spinner's accepted values:

Parameter	Slider	Effect
Iterations	Linear, 1–100	More iterations can recover detail but increase time and amplify noise, ringing, or PSF mismatch.
TV regularization	Geometric, 1e-6–0.1	Larger values suppress noise more strongly but can flatten fine structures; enter `0` in the spinner to disable.
TV epsilon	Geometric, 1e-12–1e-2	Stabilizes the TV gradient norm near zero.
Filter epsilon	Geometric, 1e-15–1e-3	Stabilizes very small predicted-blur denominators; enter `0` to disable.
Denominator floor	Geometric, 1e-3–1	Limits extreme TV correction; larger values increase stability but can weaken correction.

The spinner remains the exact-entry control and can accept valid values outside the slider window. Slider ranges are exploration aids, not scientific validity limits. The ordinary Richardson-Lucy and Richardson-Lucy TV inspector forms also wrap long rows and let spatial-mode and slider controls shrink, so their labels and native size hints no longer force the inspector panel wide.

Runtime, cache, and platform behavior¶

Adaptive execution moves known-expensive work and inputs of at least 4,000,000 elements or 32 MiB away from the UI thread. Run all in BG remains a force-all override. Exact diagnostics share this policy and remain complete-population calculations.

Cache status now dispatches by operating system instead of assuming os.sysconf exists everywhere:

Windows reads available/total physical memory with GlobalMemoryStatusEx and never calls sysconf;
macOS reads VM statistics with host_statistics64, using guarded sysconf calls for page size and physical-page count;
other POSIX systems use guarded sysconf page counters.

If a required API is absent or fails, the display reports memory as unavailable instead of crashing or fabricating a value. Cache values remain operational estimates, not a full process or Python-heap profile.

The batch representative strip now starts in its compact arrangement and uses wrapping labels whose platform-specific size hints cannot force the dock wider. Its minimum-size hint stays at or below 420 px on Windows, macOS, and Linux; at that width, header controls, source details, progress, and workspace action stack instead of being clipped.

Architecture and contributor impact¶

_widget.py is now primarily the composition root and was reduced by roughly 4,500 net lines. Reusable controls, dialogs, plots, examples, sources, workers, history, lifecycle, view-dimension, and batch responsibilities moved into focused ui/ modules. Qt-free core/ services own grids, diagnostics, snapshots, execution, atomic I/O, source identity, file snapshots, and batch setup/execution. Architecture tests enforce dependency direction.

See architecture and scientific boundaries for the module map, ownership rules, and contributor verification ladder.

Validation status and limitations¶

0.12.0a1 includes expanded operation-contract, golden, example, workflow, export, batch, source, grid, diagnostic, architecture, and Qt integration tests. The deterministic batch bundle provides exact end-to-end checks for its small defined case.

These tests do not establish broad biological validity, cross-tool equivalence, microscope-format coverage, whole-slide/HCS scalability, or restoration quality on a particular assay. Batch remains local-file and position-pairing oriented; semantic-axis iteration and plate/well/field HCS traversal are outside this release. Many scientific operations remain eager. GPU acceleration, blind/spatially varying deconvolution, and broad real-data benchmark packs remain future work.

Read validation status, validate each transferred workflow on representative and held-out data, and report remaining limitations beside any scientific claim.