Versions and compatibility

This manual has two publication tracks and release-numbered snapshots.

Selector	Meaning	Use it for
stable	Alias intended for the current supported software release manual	Routine analysis after confirming the displayed version
nightly	Documentation built from this repository's main branch	Previewing unreleased docs and interfaces
0.x.y…	Immutable snapshot published for a particular release	Reopening old workflows or reporting exact methods

This manual covers VIPP 0.16.0a7. Use the canonical GitHub release for the exact manual-install wheel, unsigned Windows installer, separate unsigned Apple Silicon and Intel macOS packages, checksums and qualification evidence. Use the PyPI 0.16.0a7 page for an exact package pin. The nightly manual may describe later unreleased work.

0.16.0a7 retains workflow, batch-config and manifest schema 6 from 0.15.0a3, including verified resume. Earlier manifests cannot supply the new recovery evidence. New operations and reproduction references still require a compatible runtime; unchanged schema numbers do not promise backward compatibility.

Application publication and manual deployment are separate operations. Always confirm the version shown by the manual selector; do not assume that the stable alias moved merely because a new package was published.

The main/nightly manual can describe behavior newer than the latest tag. Use the version selector when you need the manual for an installed release.

Match software and manual

The VIPP interface displays its package version. Compare it with the version selector in the site header. If they differ:

• switch the manual to the installed release; or
• install the release described by the manual in a separate environment.

Do not assume a workflow saved by one alpha release is compatible with another. VIPP 0.16.0a7 writes workflow schema version 6, batch configuration version 6, and manifest schema version 6; workflow versions 1 and 2 are rejected. Valid schema-3 workflows load with explicit CPU intent, schema-4 workflows retain authored compute intent, and schema-5 workflows retain canonical SourceItem evidence. Supported earlier batch configurations remain loadable and acquire their newer fields only after review and save. Workflow JSON contains no source pixels or cached scientific results. Recalculate and compare graph structure, parameters, selected items, reader/backend, axes, channels, physical grids, dynamic ports, compute request, node behavior, actual backend, and results on known sample data. See the workflow contract.

Move from 0.16.0a6 to 0.16.0a7

Opening a workflow now loads its bound sources, and recovery recalculates automatic results instead of leaving the processing cards blank. These are new calculations, not recovered caches. Manual steps remain paused even with saved Auto Recalculate enabled; file writers and dependent steps wait too. Review sources and output destinations before Calculate all releases that restriction. Original files and existing workflow tabs are not overwritten.

Settings → Workflow paths chooses relative (default) or absolute paths for later workflow saves. If only the JSON will move, open it while its relative paths still resolve, choose Absolute file locations, and save before the move. The setting cannot discover an unknown old base after relocation. Neither mode copies data; separate Python export and Batch Save config behavior is unchanged. See save and recover workflows.

Schemas, scientific algorithms and dependencies are unchanged. Keep originals, regenerate Python exports with the installed version, and recheck representative results. See the 0.16.0a7 release notes.

Move from 0.16.0a5 to 0.16.0a6

This update changes startup and Windows setup reliability. Scientific algorithms, image interpretation, compute policy and schema numbers are unchanged. Preserve original workflows and data, regenerate Python exports using the installed version, and recheck representative results. Reader libraries prepare after the interface opens; selecting a file immediately can still require a wait. See the 0.16.0a6 release notes.

Move from 0.16.0a4 to 0.16.0a5

Keep the original workflow, data, environment and decisive outputs. Schemas and scientific algorithms are unchanged, but regenerate Python exports using the installed version and recheck representative results.

When moving a project, copy its workflow, batch config, exported program and data together with their folder structure. Relative paths use their owning document's folder. Review individual batch Skip/Overwrite choices after a move. No-overwrite image writes now refuse racing destinations; choose another path rather than expecting an existing result to be replaced.

Workflow recovery copies are separate graph working copies, not a replacement for Save or a backup of calculated results/source data. Recovered tabs are unsaved copies and never run automatically. Save Batch configuration separately; recovery does not reconstruct the Batch workspace. In-app GPU setup opens a reviewed separate environment; save/reopen workflows there explicitly. See the 0.16.0a5 release notes for safety and platform limits.

Move from 0.16.0a3 to 0.16.0a4

Preserve original workflows, source data, environments and decisive outputs. Workflow, batch-config and manifest schemas remain 6, but Review Images and ImageJ Gaussian Blur require 0.16.0a4. An unchanged schema does not make a new operation executable in an older runtime. Review display recipes are workflow presentation metadata, not scientific parameters or output images.

Recalculate representative workflows and regenerate Python exports with the installed version. Verify reader calibration and reopen important exports; the OME reader/writer compatibility fixes do not validate an acquisition's metadata or guarantee compatibility with every receiving application. Review the Batch plan after changing any destination or filename. See the 0.16.0a4 release notes for the bounded Gaussian, linked-view and native-window qualification limits.

Move from 0.16.0a2 to 0.16.0a3

Preserve original workflows, inputs, environments and decisive results before resaving. The workflow, batch-config and manifest schemas stay at 6, but the new detection and tracking operations require 0.16.0a3. Previous frame registration stores a strategy and cumulative-quality policy; do not reproduce it as a fixed-reference series in an older runtime.

The released tracking names and IDs are Detect Spots per Frame (detect_spots_per_frame) and Build Tracks (build_tracks). Earlier unreleased development identifiers are not compatibility aliases. Generated Python remains pinned to its creator version: regenerate it with the installed release and recalculate representative data.

Keep detection/tracking batch manifests with the exact tables. A detached CSV does not establish one calibrated observation series; multiple collected source items must not be treated as one coordinate frame. Review capped frames, crossing ambiguity, missing observations and valid coverage before interpreting counts or trajectories. See the 0.16.0a3 release notes.

Move from 0.16.0a1 to 0.16.0a2

Preserve original workflows, inputs, environments and decisive results before resaving. The workflow, batch-config and manifest schemas stay at 6, but the new registration, transform and per-label skeleton operations require 0.16.0a2.

Registration estimates motion without changing pixels; Apply Transform creates resampled data on the reference grid. Check axes, physical calibration, the estimation channel and reference, then inspect the Valid coverage output before using border regions in measurements. Keep transform JSON with its workflow and source data; there is no GUI transform-import control.

Use the label-preserving skeleton route to join measurements to the original objects. Skeleton component IDs from the older mask-first route are different identities and must not be matched to original labels by number alone.

CPU median acceleration retains the existing plane-wise result contract; it does not silently replace Gaussian, background subtraction or deconvolution. Recalculate representative data and regenerate Python exports with the installed version. See the 0.16.0a2 release notes.

Move from 0.15.0a5 to 0.16.0a1

Preserve original workflows and environments before resaving. Results Workspace, Plot Results, collected measurement datasets and the CellProfiler compartment nodes require a runtime that contains those features, even though the workflow, batch-config and manifest schemas remain 6.

Existing Summarize Measurements nodes retain their version-1 calculations until explicit upgrade. New Statistics nodes use version 2 with explicit observation levels, weighting, exclusions and counts; singleton sample SD is undefined. Review representative outputs before upgrading an existing recipe. The decimal controls change only table display, never stored measurement precision.

Regenerate Python exports with the installed version, retain source datasets beside their workflows, and review the 0.16.0a1 release notes. Descriptive statistics and reference-implementation comparisons do not establish independent biological replication or biological validity.

Move from 0.15.0a4 to 0.15.0a5

Use the single installed VIPP launcher and choose compute modes inside the app. Automatic update checks now run on every startup unless disabled; guided Windows updates still require reviewing setup.

Reopen bundled examples to see the new layouts and separate RACC/overlap-count workflows. Saved copies keep their authored settings. Colocalization Mask requires 0.15.0a5 or newer even though schemas remain 6. Its counts are connected overlap regions, not necessarily whole organelles. Preserve original analyses, regenerate Python exports and recheck important results. See 0.15.0a5 release notes.

Move from 0.15.0a3 to 0.15.0a4

This is a presentation-fix update: clearer graph-wire routing and detailed multichannel histogram outlines, including PNG/TIFF exports. Scientific calculations, histogram values and schema versions are unchanged. Preserve original analyses and environments, regenerate exported Python for the new runtime, and recheck consequential results. See 0.15.0a4 release notes.

Move from 0.15.0a2 to 0.15.0a3

1. Preserve original workflows, inputs, outputs, environments and batch manifests. Open a duplicate for review; regenerate Python exports using the exact installed VIPP version.
2. Check new label-boundary QC and filter counts against the connected labels. These controls do not make or validate a new segmentation for you.
3. Review any RL/RL-TV numerical-difference advisory when choosing GPU execution beyond the earlier CPU-comparison region. Execution permission is not a guarantee of CPU equivalence or restoration quality.
4. Keep original schema-6 manifests and item sidecars for verified resume. Earlier manifests lack the required recovery evidence. A reproducibility package is a portable recipe/report, not a resume receipt or an environment.
5. When reopening a recorded package, choose original-run reproduction or new input data explicitly. Original-input checks and version acknowledgement do not establish matching scientific outputs; compare decisive results.

See 0.15.0a3 release notes.

Move from 0.15.0a1 to 0.15.0a2

The workflow, batch-config and manifest schema numbers remain 6, 6 and 5. New node types and parameters nevertheless require 0.15.0a2; a shared schema number is not a promise that an older runtime understands new operations.

Legacy threshold and rescaling defaults retain equivalent batch-workflow identity after restore. Explicit non-default choices still affect that identity. Range-threshold history records both bounds and the endpoint rule; retain earlier manifests as the original execution record rather than rewriting their history.

1. Preserve original data, environments, workflows, batch configurations and decisive outputs. Open a duplicate for review and recalculate representative data.
2. Review Binary Threshold foreground choices. Above and Below are strict; In range includes both endpoints and Outside range excludes them. Existing nodes retain Above unless authored otherwise; saved range limits matter only in a range mode.
3. Use Rescale Intensity → Invert intensity for reversed mapping with ordered output bounds. Old reversed bounds are retained but must be corrected explicitly before calculation. Merely opening a workflow does not swap them.
4. Check reader/backend, selected series, axes, channels and calibration after moving to included native readers. Reader support checks installation health, not acquisition interpretation.
5. Review source Channel display and Display settings independently of scientific parameters. These presentation changes do not resample data or change processing.
6. Recalculate mesh measurements after smoothing or simplification; compare the changed geometry with the original branch. Inspect open-surface status and confirm units before 3MF export.
7. Regenerate Python exports using the exact installed VIPP version, and check batch plans and outputs before a large run.

See the 0.15.0a2 release notes for the full change summary and limits.

Move from 0.14.0a3 to 0.15.0a1

This is a substantial alpha update: the toolbar, inspector, batch window, measurement views, and several scientific controls have changed. Supported older documents still receive explicit migrations, but alpha status is not a promise that every old workflow or generated program behaves identically.

1. Keep original workflows, configurations, prior manifests, and decisive outputs. Open a duplicate in the new release rather than overwriting the only record of an earlier analysis.
2. Review the source, axes, calibrated measurements, and results on known data. Clip is now called Clamp Intensity; the bound calculation is unchanged.
3. Review ImageJ Default Threshold (8-bit). New nodes use the fixed Default method. An older saved ImageJ Triangle choice is retained as legacy behavior, not silently converted to Default.
4. Use the four Batch workflow tabs. Check before running; per-item keep/overwrite choices are saved in configuration version 6. Older configurations do not acquire invented item choices. Workflow version 6 and manifest version 5 are unchanged from 0.14.0a3.
5. Regenerate exported Python using 0.15.0a1. Exported programs require the exact VIPP runtime version; a successful import is not an end-to-end result check.
6. Recheck actual compute decisions if enabling the new mesh/skeleton GPU candidates. A hybrid GPU implementation can still perform substantial CPU work; validate important measurements against the reference.

Legacy scatter-raster nodes remain executable but are hidden from the palette. For new interactive plots, open the scatter window from a metrics node.

Move from 0.14.0a2 to 0.14.0a3

0.14.0a3 adds responsive volumetric cropping, exact bounded source reads for a strict direct local OME-Zarr Crop Stack path, safe node bypass and batch execution profiles, workflow-editing improvements, and napari 0.9 qualification.

1. Preserve the exact 0.14.0a2 environment, original workflows, batch evidence, generated programs, and decisive outputs for provenance.
2. Install the exact qualified 0.14.0a3 asset for the platform, or use an exact package pin in a fresh environment. Do not replace the preserved a2 environment in place.
3. Open a duplicate schema-5 workflow and review sources, graph structure, parameters, compute intent, and every node's Run/Bypass state. A workflow without saved bypass intent continues to run its nodes; saving the reviewed duplicate writes workflow schema 6.
4. Review the effective node behavior after loading any schema-4 batch configuration. Older configurations contain no whole-batch override and therefore use the workflow's authored behavior. Saving after review writes batch configuration schema 5, and new runs write manifest schema 5.
5. Recalculate known sample data and compare decisive intermediates and final results. Give focused attention to Crop Stack bounds, source identity, requested versus actual backends, bypass provenance, and batch outputs.

Move from 0.14.0a1 to 0.14.0a2

0.14.0a2 is a focused desktop-compatibility and packaging alpha. It does not change the SourceItem, reader, workflow-schema-5, batch-schema-4, per-sample, OME-Zarr preview, or scientific CPU/GPU contracts introduced in 0.14.0a1.

1. Keep the original 0.14.0a1 environment, workflow, batch evidence, and decisive outputs for provenance.
2. Choose the checksum-verified Windows installer, the architecture-matched checksum-verified macOS package, or the wheel attached to the GitHub release. The macOS packages are CPU-only, require macOS 13 or newer, and install a current-user environment under ~/Library/vipp with ~/Applications/VIPP.app.
3. Do not treat pip install napari-vipp==0.14.0a2 as the resize-fixed build. PyPI's immutable a2 files predate that fix. Record the installation surface as well as the nominal version when reproducing an a2 environment.
4. Open a duplicate workflow and confirm sources, graph structure, parameters, compute intent, and decisive outputs. Schema migration is not expected, but an alpha update still warrants a focused comparison.
5. If VIPP is detached from napari, confirm that the floating window can be resized in width and height or maximized. Reattaching it should restore napari's dock constraints.

Move from 0.13.0a9 to 0.14.0a1

0.14 introduces SourceItem identity, workflow schema 5, and batch config/manifest schema 4. Treat the upgrade as a source and scientific review.

1. Preserve the 0.13 environment, workflow, input identities, outputs, execution reports, and batch artifacts.
2. Install 0.14.0a1 separately from the official checksum-verified installer or an exact package pin. Do not substitute an untagged build.
3. Open a duplicate workflow. Resolve every Image Source and verify the selected item, reader/backend, axes, shape, calibration, channels, and decisive results before saving schema 5.
4. For attached batch workspaces, let metadata-only discovery complete. Review every restored SourceItem and per-sample value; changed or missing sources must remain quarantined rather than being reassigned by order or filename.
5. Confirm that an OME-Zarr lower-level preview is labelled presentation-only and that analysis/output still use level 0.
6. Run CPU reference checks before relying on accelerator results, then inspect actual implementation badges and provenance for the intended compute mode.
7. Regenerate and revalidate exported Python and saved batch runners under a1.

Move from 0.12.0a3 to 0.13.0a1

0.13 introduces durable compute intent and guarded source-axis declarations, and can also change calculated colocalization values. Treat the upgrade as a scientific review, not only a file-format conversion.

1. Keep the original schema-3 workflow, 0.12.0a3 environment, generated Python, batch config, manifests, sidecars, and validated outputs unchanged.
2. Open a duplicate in 0.13.0a1. Confirm that its migrated compute mode is CPU. Inspect graph structure, parameters, dynamic ports, source bindings, axes/channels, physical grids, Batch Output declarations, and optional Batch workspace attachment.
3. Recalculate on CPU and compare decisive intermediates and final results. Cached arrays/tables were never embedded in the workflow. Give particular attention to colocalization thresholds, native-unit intensity sums, Pearson population fields, Manders fields, cropped masks, and ND2 axis order.
4. Save the reviewed duplicate as schema 4. The saved execution.compute object records cpu, auto, prefer_gpu, or custom mode and any authored per-node preferences; it does not record a promise about which implementation will actually be available on another machine.
5. If acceleration is wanted after the CPU comparison, use Prefer GPU to place every reviewed eligible operation on GPU regardless of speed, or use Custom to choose providers per node/apply Find fastest pipeline…. Auto uses reviewed safe GPU defaults without compatible history; accelerated-only history schedules one same-surface CPU measurement before later matching runs apply the 1.20x/20-ms gate. Review CPU/CuPy/cuCIM/fallback badges and retain the actual-run execution provenance. Do not add an unplanned Convert Dtype merely to make a GPU benchmark faster.
6. Load or recreate Batch workspace. Version-1 batch configs migrate to an explicit CPU request; version-2 configs retain their saved compute request. Neither older version contains a source-axis declaration. Review the source-specific Image stack choice, configured/effective requests, memory and fallback policy, bindings, paths, collision policy, and fresh preflight, then save the reviewed configuration as version 3.
7. Regenerate and revalidate exported Python and the saved batch runner. A generated 0.12 program refuses a 0.13 runtime by design.
8. For a consequential batch, test progress, cancellation, and OOM/fallback on non-critical data, then inspect the version-3 manifest's raw/effective source axes, applied declarations, execution documents, digests, output links, cleanup evidence, and partial/skipped/cancelled/failed records.

The colocalization and ImageJ-threshold revisions have frozen automated fixtures but still require independent upstream-method review. Treat them as experimental and perform an external reference comparison before relying on the revised values.

Move from 0.12.0a2 to 0.12.0a3

1. Keep the original workflow, 0.12.0a2 environment, standalone batch config, manifests, item sidecars, and validated outputs for provenance.
2. Open a duplicate workflow in 0.12.0a3 and confirm that graph structure, parameters, dynamic ports, sources, and Batch Output declarations are as expected.
3. Recalculate the workflow and compare decisive intermediates and final measurements. Cached scientific results are not serialized in workflow JSON.
4. If using Batch workspace, review the suggested or restored destination, source bindings, patterns, formats, collision policy, and fresh preflight. Preview remains optional; Run does not implicitly calculate a representative.
5. Regenerate and revalidate Python exports. An export refuses a VIPP runtime version different from the one that generated it.
6. Inspect the finalized manifest and item sidecars after a batch, including partial, skipped, and failed items.

A 0.12.0a3 workflow can optionally carry a top-level batch_config. VIPP 0.12.0a2 can still reconstruct the schema-3 scientific graph because it ignores that unknown top-level attachment, but it does not restore it and will omit it if the workflow is saved again. Preserve the original 0.12.0a3 file when moving between releases.

Move from 0.12.0a1 to 0.12.0a2

1. Keep the original workflow and 0.12.0a1 environment for provenance.
2. Open a duplicate workflow in 0.12.0a2 and confirm that graph structure, parameters, dynamic ports, and sources are as expected.
3. Recalculate the workflow. Cached results are not serialized in workflow JSON, so structural loading is not evidence that old outputs were restored.
4. Review the clearer bright-amber actionable and dark-amber waiting states, especially around manual nodes and isolated tuning, before calculating.
5. Compare decisive intermediates and final measurements with the validated 0.12.0a1 results or other reference data.
6. Regenerate and revalidate Python exports. An export refuses a VIPP runtime version different from the one that generated it.

Upgrade to 0.12.0a1

Schema 3 exists because silently supplying new scientific defaults could change results. In particular, 0.12 requires explicit channel-axis and RGB/intensity mapping choices for affected operations and strengthens source/grid behavior.

1. Keep the exact older VIPP environment and original workflow read-only.
2. Record the old graph, parameters, dynamic output ports, input series, axes, channel mapping, scale, units, and representative outputs.
3. Recreate the workflow in 0.12.0a1. Do not edit only the JSON version.
4. Resolve each new required scientific choice explicitly. Do not infer channel_axis from a trailing length-three/four dimension unless the data really are declared RGB/RGBA.
5. Verify every multi-input grid. Equal shape alone no longer establishes compatible axes, sampling, units, or origin.
6. Compare decisive intermediates and final measurements against known data or reference annotations before batch use.
7. Regenerate Python exports; generated programs require the exact VIPP runtime version that created them.
8. Create and preview a new vipp_batch_config.json; archive the workflow, config, manifest, sidecars, environment, and validation evidence together.

If the old environment is unavailable, use the JSON and methods notes as a reference for manual reconstruction, but do not claim numerical equivalence without testing it.

Install a release

To ask pip to choose the latest unpinned alpha, use:

python -m pip install "napari[pyqt6]"
python -m pip install --pre napari-vipp

To reproduce a specific alpha exactly, use a fresh environment and record the distribution surface as well as the version. An exact prerelease does not need --pre. For 0.16.0a7, use the exact package pin:

python -m pip install "napari[pyqt6]>=0.6" "napari-vipp==0.16.0a7"

On macOS use napari[pyside6] instead of napari[pyqt6]; macOS remains CPU-only.

For the optional CUDA 13 extra, use a separate 64-bit CPython 3.12 environment:

python -m pip install "napari[pyqt6]>=0.6" "napari-vipp[gpu-cuda13]==0.16.0a7"
vipp-compute-doctor --track cuda13

The extra installs a reproducible CUDA/CuPy track; it does not make an unqualified GPU, driver, OS, or scientific stack scientifically admitted. Never install both CUDA-major extras into one environment. See installation and the 64-bit Windows CUDA guide.

Nightly policy

Nightly documentation may describe work not yet available from PyPI and can change without migration support. If unreleased behavior contributes to an analysis, record the application commit, documentation commit, Python version, and environment—not only a nominal package version.