Chapter 3. The NovoDeblur command line interface

Index Previous Next

3.1 The NovoDeblur command prompt
3.2 Shared command-line conventions
3.3 The bfdeconv tool
3.4 The cfdeconv tool
3.5 The lsdeconv tool
3.6 The psfdeconv tool
3.7 The sfdeconv tool
3.8 The checkgpu tool
3.9 The histogram3d tool
3.10 The imageextractor tool
3.11 The PSFextractor tool

3.1 The NovoDeblur command prompt

The NovoDeblur Toolkit command prompt can be started from the Windows Start Menu shortcut. You can also run all tools from any shell (PowerShell, cmd, terminal) if the toolkit folder is in your system PATH.

Current command-line tools in the Python toolkit:

• bfdeconv - brightfield deconvolution with computed PSF.

• cfdeconv - confocal deconvolution with computed PSF.

• lsdeconv - light-sheet deconvolution with computed PSF.

• psfdeconv - deconvolution with measured PSF.

• sfdeconv - spinning-disk deconvolution with computed PSF.

• checkgpu - checks GPU compatibility for NovoDeblur.

• histogram3d - computes histograms from 3D data.

• imageextractor - OME-TIFF metadata export and slice extraction.

• PSFextractor - extracts a measured PSF from bead stacks.

To show help for any tool, run:

For long command lines, every tool supports argument files using the @file.txt syntax (one argument per line).

3.2 Shared command-line conventions

All deconvolution tools (bfdeconv, cfdeconv, lsdeconv, psfdeconv, sfdeconv) use named flags (for example --source, --dxy, --iter) instead of positional parameters.

Common source syntax: --source accepts either a TIFF folder or an OME-TIFF file. For OME-TIFF you can append @S@C@T (1-based), for example:
--source sample.ome.tif@1@2@1

Common deconvolution flags (defaults and validated ranges):

• --dest output folder (default * for automatic naming).

• --blocks block layout (default auto; or e.g. 2x2x2).

• --dxy --dz voxel size in µm (default: no default, required; valid range: [0.01, 100]).

• --iter max iterations (default: 50, valid range: [0, 1000]); --stopcrit early stop threshold (default: 0.001, valid range: [0, 1]).

• --regul regularization (default: 0.0, valid range: [0, 0.5]); --clip histogram clipping (default: 0.005, valid range: [0, 1]).

• --backsub background mode (default: A; accepted forms: A, B:spec, C:value with value >= 0).

• --useGPU 1 (GPU) or 0 (CPU), default 1.

• --roi none (default) or x1-y1-z1-x2-y2-z2.

• --scaling 0 (full 16-bit) or 1 (source range), default 0.

• --ome 0 (TIFF folder) or 1 (single OME-TIFF), default 0.

Objective model (--objpar) range hints: mode in {0,1}, M in [0.1,150], NA in [0.01,1.4], ng/ni in [1,2], tg in [0,1000] µm, wd in [0,50000] µm.

3.3 The bfdeconv tool

Performs iterative deconvolution of brightfield microscopy stacks using a computed PSF.

Usage:

Tool-specific flags:

• --objpar objective model string (required).

• --focaldepth imaging depth in µm (optional, default 0, valid range: [0, 10000]).

• --em illumination wavelength in µm (required, valid range: [0.1, 1]).

• --rf sample refractive index (required, valid range: [1, 2]).

3.4 The cfdeconv tool

Performs iterative deconvolution of confocal microscopy stacks using a computed PSF.

Usage:

Tool-specific flags:

• --objpar objective model string (required).

• --focaldepth imaging depth in µm (optional, default 0, valid range: [0, 10000]).

• --ex excitation wavelength in µm (required, valid range: [0.1, 1]).

• --em emission wavelength in µm (required, valid range: [0.1, 1]).

• --rf sample refractive index (required, valid range: [1, 2]).

• --pinhole confocal pinhole size in Airy units (required, valid range: [0.1, 5]).

3.5 The lsdeconv tool

Performs iterative deconvolution of light-sheet microscopy stacks using a computed PSF.

Usage:

Tool-specific flags:

• --objpar objective model string (required).

• --ex excitation wavelength in µm (required, valid range: [0.1, 1]).

• --em emission wavelength in µm (required, valid range: [0.1, 1]).

• --rf sample refractive index (required, valid range: [1, 2]).

• --NA_illumination illumination numerical aperture (required, valid range: [0.001, 0.5]).

3.6 The psfdeconv tool

Performs iterative deconvolution using a measured PSF stack.

Usage:

Tool-specific flags:

• --psfpath folder with measured PSF TIFF slices (required).

• --dxy_psf --dz_psf PSF voxel size in µm (required, valid range: [0.01, 100]).

The PSF stack must have odd dimensions and square XY planes. If PSF voxel size differs from source voxel size, the PSF is automatically resampled.

3.7 The sfdeconv tool

Performs iterative deconvolution of spinning-disk confocal stacks using a computed PSF.

Usage:

Tool-specific flags:

• --objpar objective model string (required).

• --focaldepth imaging depth in µm (optional, default 0, valid range: [0, 10000]).

• --ex excitation wavelength in µm (required, valid range: [0.1, 1]).

• --em emission wavelength in µm (required, valid range: [0.1, 1]).

• --rf sample refractive index (required, valid range: [1, 2]).

• --pinhole pinhole size in Airy units (required, valid range: [0.1, 5]).

3.8 The checkgpu tool

Checks whether the selected NVIDIA GPU can be used by NovoDeblur.

Usage:

Notes:

• --GPUno is optional and 0-based.

• The tool reports architecture, compute capability, memory, and driver compatibility.

• Compatibility thresholds: architecture code >= 7, minimum GPU memory 2000 MB, minimum NVIDIA driver version 590.44.01.

• Return codes indicate the reason for pass/fail (compatible, no GPU, insufficient memory, unsupported architecture, unsupported driver).

3.9 The histogram3d tool

Calculates a 3D intensity histogram from TIFF-folder or OME-TIFF input.

Usage:

Arguments:

• --source TIFF folder or OME-TIFF (optional @S@C@T suffix).

• --bins number of bins (required, valid range: [10, 1000]).

• --roi none (default) or rectangular ROI in pixels.

• --outfile optional output text file.

3.10 The imageextractor tool

Extracts slices from OME-TIFF data and can also print OME metadata.

Usage:

Arguments:

• --info metadata mode.

• --extract extraction mode.

• --S --C --T required in extract mode; all are 1-based positive integers.

• --format output type (uint8, uint16, or float32); default is uint16.

3.11 The PSFextractor tool

Extracts an empirical PSF from fluorescent bead image stacks.

Usage (confocal):

Usage (lightsheet):

Important arguments:

• --source TIFF folder or OME-TIFF (supports @S@C@T on OME input).

• --dest output folder, or single output OME-TIFF filename.

• --microscope must be confocal or lightsheet.

• --NA_illumination is required in lightsheet mode.

• --options optional advanced parameter string (p1-p2-p3-p4-p5-p6-p7-p8-p9).

Advanced option defaults: 0.13-0-21-41-1-1-0.5-0-1.5.

Advanced option ranges: p1 [0.01,0.99], p2 0 (auto) or [0.01,0.99], p3/p4 odd integers in [21,91], p5 [0.1,10], p6 [0.1,5], p7 [0,5], p8 in {0,1}, p9 [1,3].

Advanced parameters description (--options p1-p2-p3-p4-p5-p6-p7-p8-p9):

• p1: BEAD_VOLUME_INTENSITY_CUTOFF (default 0.13, range [0.01, 0.99])
  Normalized intensity threshold (0–1) used to distinguish bead voxels from background. Lower values include more voxels in the bead volume calculation; higher values are more stringent.

• p2: BLOB_DETECTION_SENSITIVITY (default 0 = auto-tuning, or range [0.01, 0.99])
  Threshold for 3D blob (bead) detection. Set to 0 to automatically tune sensitivity based on the first data block (recommended). Non-zero values bypass auto-tuning; lower values detect fainter beads, higher values are more selective.

• p3: ACCUMULATOR_SIZE_XY (default 21, must be odd, range [21, 91])
  Size of the 3D window (in pixels) used to extract individual bead volumes in the XY plane. Must be an odd number to ensure a well-defined center. Larger windows capture bigger beads; smaller windows suit smaller beads.

• p4: ACCUMULATOR_SIZE_Z (default 41, must be odd, range [21, 91])
  Size of the 3D extraction window in the Z-direction (in pixels). Must be odd. Controls axial extent of bead extraction.

• p5: MAX_SIGMA_ECC (default 1.0, range [0.1, 10])
  Maximum number of standard deviations the eccentricity (center-of-mass displacement from geometric center) of a bead can deviate from the mean of all beads. Beads exceeding this threshold are rejected as outliers.

• p6: MAX_SIGMA_VOL (default 1.0, range [0.1, 5])
  Maximum number of standard deviations the bead volume can deviate from the mean. Rejects beads with unusual sizes (too large or too small), improving PSF quality.

• p7: SIGMA_GAUSSIAN_SMOOTHING (default 0.5, range [0, 5])
  Standard deviation (in pixels) of the Gaussian filter applied to the image before bead detection. Smoothing reduces noise and can help with faint beads; 0 disables smoothing.

• p8: SYMMETRIC_PSF (default 0, values {0, 1})
  Flag to enforce radial symmetry on the extracted PSF. Set to 0 to use the PSF as-is (asymmetric); set to 1 to compute a radially symmetric version by circular averaging. Useful if beads are known to be spherically symmetric.

• p9: PSF_IMAGE_SIZE_FACTOR (default 1.5, range [1, 3])
  Scaling factor applied to the PSF dimensions relative to its Full Width at Half Maximum (FWHM). Larger factors produce larger PSF kernels, which may capture fine structure but increase memory; smaller factors yield compact PSFs.

Index Previous Next