Command-line scripts

linumpy ships a large collection of linum_* command-line tools. The authoritative inventory lives in Scripts Reference, which groups scripts by purpose (preprocessing, mosaic creation, stitching, stacking, diagnostics, conversion, GPU benchmarks, …).

Each script uses argparse and prints its full options list with --help. A handful of high-traffic entry points are documented here inline using sphinx-argparse; the rest can be browsed in the reference page above or queried directly on the command line.

Mosaic acquisition & preprocessing

Convert 3D OCT tiles to a 3D mosaic grid.

GPU acceleration is used when available (–use_gpu, default on) for volume resampling/resizing (5-12x speedup). Falls back to CPU if no GPU is detected or –no-use_gpu is passed.

usage: linum_create_mosaic_grid_3d [-h] [--data_type {OCT,PSOCT}]
                                   (--from_root_directory FROM_ROOT_DIRECTORY | --from_tiles_list FROM_TILES_LIST [FROM_TILES_LIST ...])
                                   [-r RESOLUTION]
                                   [--axial_resolution AXIAL_RESOLUTION]
                                   [-z SLICE] [--keep_galvo_return]
                                   [--zarr_root ZARR_ROOT]
                                   [--fix_galvo_shift | --no-fix_galvo_shift]
                                   [--fix_camera_shift | --no-fix_camera_shift]
                                   [--preprocess | --no-preprocess]
                                   [--galvo_threshold GALVO_THRESHOLD]
                                   [--sharding_factor SHARDING_FACTOR]
                                   [--use_gpu | --no-use_gpu] [--verbose]
                                   [--n_processes N_PROCESSES]
                                   [--polarization {0,1}]
                                   [--number_of_angles NUMBER_OF_ANGLES]
                                   [--angle_index ANGLE_INDEX]
                                   [--return_complex RETURN_COMPLEX]
                                   [--crop_first_index CROP_FIRST_INDEX]
                                   [--crop_second_index CROP_SECOND_INDEX]
                                   output_zarr

Positional Arguments

output_zarr

Full path to the output zarr file

Named Arguments

--data_type

Possible choices: OCT, PSOCT

Type of the data to process [‘OCT’]

Default: 'OCT'

input

--from_root_directory

Full path to a directory containing the tiles to process.

--from_tiles_list

List of tiles to assemble (argument –slice is ignored).

other options

-r, --resolution

Output isotropic resolution in micron per pixel. [10.0]

Default: 10.0

--axial_resolution

Axial resolution of the raw data in microns. [3.5]

Default: 3.5

-z, --slice

Slice to process.

--keep_galvo_return

Keep the galvo return signal [False]

Default: False

--zarr_root

Path to parent directory under which the zarr temporary directory will be created [/tmp/].

--fix_galvo_shift, --no-fix_galvo_shift

Fix the galvo shift. [True]

Default: True

--fix_camera_shift, --no-fix_camera_shift

Fix the camera shift. [False]

Default: False

--preprocess, --no-preprocess

Apply preprocessing (rotate/flip) for legacy data. [True]

Default: True

--galvo_threshold

Galvo detection confidence threshold. [0.6]

Default: 0.6

--sharding_factor

A sharding factor of N will result in N^2 tiles per shard. [1]

Default: 1

--use_gpu, --no-use_gpu

Use GPU acceleration if available. [True]

Default: True

--verbose, -v

Print GPU information.

Default: False

--n_processes

Number of processes to use. -1 to use all cores [1].

Default: 1

PS-OCT options

--polarization

Possible choices: 0, 1

Polarization index to process

Default: 1

--number_of_angles

Angle index to process

Default: 1

--angle_index

Angle index to process

Default: 0

--return_complex

Return Complex64 or Float32 data type

Default: False

--crop_first_index

First index for cropping on the z axis [320]

Default: 320

--crop_second_index

Second index for cropping on the z axis [750]

Default: 750

usage: linum_compensate_psf_from_model [-h] [--out_psf OUT_PSF] [--nz NZ]
                                       [--n_profiles N_PROFILES]
                                       [--n_iterations N_ITERATIONS]
                                       [--smooth SMOOTH]
                                       in_zarr out_zarr

Positional Arguments

in_zarr

Input stitched 3D slice (OME-zarr).

out_zarr

Output volume corrected for beam PSF (OME-zarr).

Named Arguments

--out_psf

Optional output PSF filename.

--nz

The “nz” first voxels belonging to background [25].

Default: 25

--n_profiles

Number of intensity profiles to use [10].

Default: 10

--n_iterations

Number of iterations [15].

Default: 15

--smooth

Smoothing factor as a fraction of volume depth [0.01].

Default: 0.01

Compensate the tissue attenuation using a precomputed attenuation.

bias field.

usage: linum_compensate_attenuation [-h] input bias output

Positional Arguments

input

Input volume (.ome.zarr)

bias

Attenuation bias field (.ome.zarr)

output

Compensated volume (.ome.zarr)

Stitching, stacking & alignment

Simplified pairwise registration for motor-position-based reconstruction.

This script performs two tasks.

1. Z-MATCHING: find the optimal Z-overlap between consecutive slices.

2. REFINEMENT: compute small rotation and sub-pixel corrections.

The XY alignment is handled by motor positions (shifts_xy.csv), so this script only computes small corrections, not large translations.

Outputs.

• transform.tfm – SimpleITK transform file (rotation + small translation).

• offsets.txt – Z-index correspondence [fixed_z, moving_z].

• metrics.json – registration quality metrics.

usage: linum_register_pairwise [-h]
                               [--slicing_interval_mm SLICING_INTERVAL_MM]
                               [--search_range_mm SEARCH_RANGE_MM]
                               [--moving_z_index MOVING_Z_INDEX]
                               [--enable_rotation | --no-enable_rotation]
                               [--max_rotation_deg MAX_ROTATION_DEG]
                               [--max_translation_px MAX_TRANSLATION_PX]
                               [--initial_alignment {none,com,gradient,both}]
                               [--out_transform OUT_TRANSFORM]
                               [--out_offsets OUT_OFFSETS]
                               [--screenshot SCREENSHOT] [-f]
                               in_fixed in_moving out_directory

Positional Arguments

in_fixed

Fixed volume (.ome.zarr) - bottom slice

in_moving

Moving volume (.ome.zarr) - top slice

out_directory

Output directory

Named Arguments

--out_transform

Default: 'transform.tfm'

--out_offsets

Default: 'offsets.txt'

--screenshot

Save debug screenshot

-f

Force overwriting of the output files.

Default: False

Z-matching

--slicing_interval_mm

Physical slice thickness in mm [0.2]

Default: 0.2

--search_range_mm

Search range around expected Z in mm [0.1]

Default: 0.1

--moving_z_index

Z-index in moving volume to align [0]

Default: 0

Refinement

--enable_rotation, --no-enable_rotation

Enable rotation correction. Use –no-enable_rotation to disable. [True]

Default: True

--max_rotation_deg

Maximum rotation correction in degrees [5.0]

Default: 5.0

--max_translation_px

Maximum translation refinement in pixels [20.0]

Default: 20.0

--initial_alignment

Possible choices: none, com, gradient, both

Initial alignment method before refinement:

none - no initial alignment com - centre of mass alignment gradient - gradient magnitude phase correlation both - try gradient first, fall back to com [‘both’]

Default: 'both'

Stack 3D mosaics on top of each other in a single 3D volume using pairwise registration transforms.

Expects all 3D mosaics to be in the same space (same dimensions for last two axes).

DEPRECATED: This script is superseded by linum_stack_slices_motor.py, which provides the same functionality plus confidence-based transform degradation, translation filtering/accumulation, rotation smoothing, auto-exclude, and richer diagnostics. Use linum_stack_slices_motor.py with –no_xy_shift for equivalent behavior on common-space slices.

usage: linum_stack_slices_3d [-h] [--normalize] [--blend] [--overlap OVERLAP]
                             [--no_accumulate_transforms]
                             [--max_pairwise_translation MAX_PAIRWISE_TRANSLATION]
                             [--pyramid_resolutions PYRAMID_RESOLUTIONS [PYRAMID_RESOLUTIONS ...]]
                             [--n_levels N_LEVELS] [--make_isotropic]
                             [--no-make_isotropic]
                             in_mosaics_dir in_transforms_dir out_stack

Positional Arguments

in_mosaics_dir

Input mosaics directory in .ome.zarr format.

in_transforms_dir

Input transforms directory. Each subdirectory should have the same name as the corresponding mosaic file (without the .ome.zarr extension) and contain a .mat transform file and .txt offsets file.

out_stack

Output stack in .ome.zarr format.

Named Arguments

--normalize

Normalize slices during reconstruction.

Default: False

--blend

Use diffusion method for blending consecutive slices.

Default: False

--overlap

Number of overlapping voxels to keep from bottom of previous mosaic. By default keeps all.

--no_accumulate_transforms

Apply each transform independently instead of accumulating. Use when slices are already in common space (XY aligned).

Default: False

--max_pairwise_translation

Maximum allowed pairwise translation magnitude in pixels. Transforms whose translation exceeds this value have their translation zeroed out (rotation is preserved) before accumulation. 0 = keep all translations (default). Recommended: 50. Prevents registration failures (clamped translations) from compounding during accumulation.

Default: 0

--pyramid_resolutions

Target resolutions for pyramid levels in microns. Default: 10 25 50 100 (for analysis at 10, 25, 50, 100 µm).

Default: [10, 25, 50, 100]

--n_levels

Number of pyramid levels (overrides –pyramid_resolutions). Uses power-of-2 downsampling if specified.

--make_isotropic

Resample anisotropic data to isotropic voxels (default).

Default: True

--no-make_isotropic

Preserve aspect ratio (anisotropic output).

Default: True

Align a 3D brain volume to RAS orientation using rigid registration to the Allen atlas.

This script computes a rigid transform from the input brain volume to a RAS-aligned version by registering it to the Allen Brain Atlas. The transform can be applied directly to the zarr file (resampling) or stored in OME-Zarr metadata.

usage: linum_align_to_ras [-h] [--allen-resolution {10,25,50,100}]
                          [--metric {MI,MSE,CC,AntsCC}]
                          [--max-iterations MAX_ITERATIONS]
                          [--store-transform-only] [--level LEVEL]
                          [--chunks CHUNKS CHUNKS CHUNKS]
                          [--n-levels N_LEVELS]
                          [--pyramid_resolutions PYRAMID_RESOLUTIONS [PYRAMID_RESOLUTIONS ...]]
                          [--make_isotropic] [--no_isotropic] [--verbose]
                          [--preview PREVIEW]
                          [--input-orientation INPUT_ORIENTATION]
                          [--initial-rotation RX RY RZ] [--preview-only]
                          [--orientation-preview PATH]
                          [--orientation-preview-only]
                          input_zarr output_zarr

Positional Arguments

input_zarr

Input OME-Zarr file from 3D reconstruction pipeline

output_zarr

Output OME-Zarr file (RAS-aligned)

Named Arguments

--allen-resolution

Possible choices: 10, 25, 50, 100

Allen atlas resolution in micron [100]

Default: 100

--metric

Possible choices: MI, MSE, CC, AntsCC

Registration metric [‘MI’]

Default: 'MI'

--max-iterations

Maximum registration iterations [1000]

Default: 1000

--store-transform-only

Store transform in metadata only (don’t resample volume)

Default: False

--level

Pyramid level for registration (0 = full resolution) [0]

Default: 0

--chunks

Chunk size for output zarr. Uses input chunks when None.

--n-levels

Number of pyramid levels for output. Uses Allen atlas levels when None.

--pyramid_resolutions

Target pyramid resolution levels in µm (e.g. 10 25 50 100). If omitted, inherits levels from input zarr metadata or uses Allen resolutions.

--make_isotropic

Resample to isotropic voxels at each pyramid level.

Default: True

--no_isotropic

Default: True

--verbose

Print registration progress

Default: False

--preview

Generate preview image showing alignment comparison

--input-orientation

Input volume orientation code (3 letters: R/L, A/P, S/I) Examples: ‘RAS’ (Allen), ‘LPI’, ‘PIR’

--initial-rotation

Initial rotation angles in degrees (Rx, Ry, Rz). Use to provide initial orientation hint for registration.

Default: [0.0, 0.0, 0.0]

--preview-only

Only generate preview of input volume (no registration)

Default: False

--orientation-preview

Save a 3-panel preview of the volume after –input-orientation and –initial-rotation are applied. Use to verify these parameters before committing to a full registration run.

--orientation-preview-only

Generate –orientation-preview and exit without running registration.

Default: False

Slice quality & interpolation

Assess slice quality for 3D mosaic grids and optionally update slice configuration.

This script analyzes mosaic grid slices to detect quality issues that might affect reconstruction. It uses multiple metrics to identify problematic slices:

• SSIM (Structural Similarity): compares each slice to its neighbors.

• Edge Preservation: detects if edge structures are preserved compared to neighbors.

• Variance Consistency: checks for unusual signal variance (data loss/corruption).

• First Slice Detection: automatically identifies calibration slices (thicker/different).

GPU acceleration is used when available (–use_gpu, default on) for SSIM and edge-detection computations. Falls back to CPU automatically if no GPU is detected.

The output can be:

• A new slice_config.csv with quality scores and recommendations.

• An update to an existing slice_config.csv with quality assessments.

• A quality report for review.

Example usage:

# Assess quality and create/update slice config
linum_assess_slice_quality.py /path/to/mosaics slice_config.csv

# Assess and exclude low-quality slices automatically
linum_assess_slice_quality.py /path/to/mosaics slice_config.csv --min_quality 0.3

# Exclude first N calibration slices
linum_assess_slice_quality.py /path/to/mosaics slice_config.csv --exclude_first 1

# Update existing config with quality info
linum_assess_slice_quality.py /path/to/mosaics slice_config.csv --update_existing

# Force CPU fallback
linum_assess_slice_quality.py /path/to/mosaics slice_config.csv --no-use_gpu

usage: linum_assess_slice_quality [-h] [--use_gpu | --no-use_gpu]
                                  [--gpu_id GPU_ID]
                                  [--min_quality MIN_QUALITY]
                                  [--sample_depth SAMPLE_DEPTH]
                                  [--pyramid_level PYRAMID_LEVEL]
                                  [--roi_size ROI_SIZE]
                                  [--processes PROCESSES]
                                  [--exclude_first EXCLUDE_FIRST]
                                  [--detect_calibration]
                                  [--calibration_thickness_ratio CALIBRATION_THICKNESS_RATIO]
                                  [--update_existing]
                                  [--existing_config EXISTING_CONFIG]
                                  [--report_only] [-v] [-f]
                                  input output_file

Positional Arguments

input

Input directory containing mosaic grids (*.ome.zarr)

output_file

Output slice configuration CSV file

Named Arguments

-f

Force overwriting of the output files.

Default: False

GPU Options

--use_gpu, --no-use_gpu

Use GPU acceleration if available. [True]

Default: True

--gpu_id

GPU device ID to use. [0]

Default: 0

Quality Assessment

--min_quality

Minimum quality score to include slice (0-1). Default: 0.0 (include all, just report)

Default: 0.0

--sample_depth

Number of z-planes to sample per slice for faster assessment. Default: 5 (0=all)

Default: 5

--pyramid_level

Pyramid level to use for assessment (0=full res). Higher levels are faster but less accurate. Default: 0

Default: 0

--roi_size

Side length of center crop in XY (pixels) used for all quality metrics. 0 = full plane (slow for large single-resolution mosaics). Recommended: 1024.

Default: 0

--processes

Number of parallel workers for slice assessment (CPU mode only). Each worker reads its own zarr planes concurrently. Default: 1 (sequential). Set to params.processes.

Default: 1

Calibration Slice Handling

--exclude_first

Exclude first N slices as calibration slices. Default: 1 (first slice is usually calibration)

Default: 1

--detect_calibration

Automatically detect calibration slices by their different thickness/structure

Default: False

--calibration_thickness_ratio

Slices with thickness ratio > this are flagged as calibration. Default: 1.5

Default: 1.5

Update Existing Config

--update_existing

Update an existing slice_config.csv with quality info

Default: False

--existing_config

Path to existing slice config to update

Output Options

--report_only

Only print report, don’t write config file

Default: False

-v, --verbose

Print detailed quality metrics per slice

Default: False

Interpolate a missing slice using information from adjacent slices.

Uses z-aware morphing (zmorph): an affine transform T between the boundary planes of the two neighbours is computed, then for each output plane at fractional depth alpha the before-boundary is warped by T^alpha and the after-boundary by T^(alpha - 1) and the two are cross-faded.

Hard skip on gate failure: when zmorph’s 2D boundary registration fails any quality gate, no interpolated zarr is produced: the slot is left as a genuine gap rather than filled with a blended (and therefore fabricated) volume. A manifest fragment and diagnostics JSON are still emitted so the failure is visible in slice_config_final.csv and the final report. The average / weighted methods remain available as explicit, user-requested baselines.

Only a SINGLE missing slice can be reconstructed – two or more consecutive gaps carry insufficient information.

See docs/SLICE_INTERPOLATION_FEATURE.md for the physical model and parameter-tuning guidance.

Example usage:

linum_interpolate_missing_slice.py slice_z00.ome.zarr slice_z02.ome.zarr \\
    slice_z01_interpolated.ome.zarr

# Finalise mode: merge per-slice manifest fragments into slice_config.csv
linum_interpolate_missing_slice.py --finalise \\
    --slice_config_in  slice_config.csv \\
    --slice_config_out slice_config_final.csv \\
    --fragments        interpolate_missing_slice/

usage: linum_interpolate_missing_slice [-h]
                                       [--method {zmorph,average,weighted}]
                                       [--blend_method {linear,gaussian}]
                                       [--registration_metric {MSE,CC,MI}]
                                       [--max_iterations MAX_ITERATIONS]
                                       [--overlap_search_window OVERLAP_SEARCH_WINDOW]
                                       [--min_overlap_correlation MIN_OVERLAP_CORRELATION]
                                       [--reference_slab_size REFERENCE_SLAB_SIZE]
                                       [--min_foreground_fraction MIN_FOREGROUND_FRACTION]
                                       [--min_ncc_improvement MIN_NCC_IMPROVEMENT]
                                       [--diagnostics DIAGNOSTICS]
                                       [--manifest_entry MANIFEST_ENTRY]
                                       [--slice_id SLICE_ID] [--finalise]
                                       [--slice_config_in SLICE_CONFIG_IN]
                                       [--slice_config_out SLICE_CONFIG_OUT]
                                       [--fragments FRAGMENTS]
                                       [--preview PREVIEW]
                                       [--preview_slice PREVIEW_SLICE]
                                       [--preview_dpi PREVIEW_DPI] [-f]
                                       [slice_before] [slice_after] [output]

Positional Arguments

slice_before

Path to the slice BEFORE the missing slice (*.ome.zarr)

slice_after

Path to the slice AFTER the missing slice (*.ome.zarr)

output

Output path for the interpolated slice (*.ome.zarr)

Named Arguments

--method

Possible choices: zmorph, average, weighted

Interpolation method:

zmorph - z-aware morphing (respects serial-section geometry; recommended) average - Simple average of adjacent slices weighted - Weighted average with distance falloff

[default: ‘zmorph’]

Default: 'zmorph'

--blend_method

Possible choices: linear, gaussian

Blending method for combining warped slices:

linear - Equal 50/50 blend (may show edges) gaussian - Feathered blend using distance transform (recommended)

[default: ‘gaussian’]

Default: 'gaussian'

--registration_metric

Possible choices: MSE, CC, MI

Metric for registration [default: ‘MSE’]

Default: 'MSE'

--max_iterations

Maximum iterations for registration [default: 1000]

Default: 1000

--overlap_search_window

Number of z-planes to search at each volume boundary when selecting the registration reference pair automatically. [default: 5]

Default: 5

--min_overlap_correlation

Minimum normalized cross-correlation required between the boundary planes to proceed with registration. Below this threshold zmorph emits no output (hard skip). [default: 0.3]

Default: 0.3

--reference_slab_size

Number of z-planes averaged around the boundary reference plane when running the 2D registration. Larger slabs are more robust to per-plane noise. [default: 3]

Default: 3

--min_foreground_fraction

Minimum fraction of foreground pixels required for a candidate boundary plane to be considered. [default: 0.1]

Default: 0.1

--min_ncc_improvement

Minimum improvement in boundary NCC required after 2D registration to accept the transform. Below this zmorph emits no output (hard skip). [default: 0.05]

Default: 0.05

--diagnostics

Path to write a JSON diagnostics file (plane selection, pre/post NCC, half-transform verification, fallback reason).

--manifest_entry

Path to write a single-line CSV manifest entry for this interpolated slice (aggregated downstream).

--slice_id

Slice id string (e.g. ‘02’) to record in the manifest entry.

-f

Force overwriting of the output files.

Default: False

Finalise Mode

Merge per-slice interpolation manifest fragments into slice_config.csv. When –finalise is set, the positional slice arguments are ignored and the script instead consumes –slice_config_in + –fragments and writes –slice_config_out.

--finalise

Run in finalise mode: merge fragments into slice_config.csv.

Default: False

--slice_config_in

Input slice_config.csv (finalise mode).

--slice_config_out

Output slice_config.csv (finalise mode).

--fragments

Directory containing per-slice manifest fragment CSVs (finalise mode). Fragments are discovered by glob; empty dir results in slice_config copied unchanged.

Preview Options

Generate visual previews for quality checking

--preview

Path to save a preview image (PNG) showing slice before, slice after, and the interpolated result. Useful for verifying interpolation quality.

--preview_slice

Z-index to use for preview. Default: middle slice.

--preview_dpi

DPI for preview image [default: 150]

Default: 150

GPU & diagnostics

Print GPU availability and configuration information for linumpy.

This script checks if GPU acceleration is available and prints diagnostic information useful for troubleshooting.

Example usage:

# Show basic GPU info
linum_gpu_info.py

# Show detailed status of all GPUs with memory usage
linum_gpu_info.py --status

# List all available GPUs
linum_gpu_info.py --list

# Select GPU with most free memory (for multi-GPU systems)
linum_gpu_info.py --select-best

# Select specific GPU by ID
linum_gpu_info.py --select 1

# Run quick performance test
linum_gpu_info.py --test

# Output as JSON (useful for scripting)
linum_gpu_info.py --json

usage: linum_gpu_info [-h] [--json] [--test] [--status] [--list]
                      [--select-best] [--select ID]

Named Arguments

--json

Output as JSON

Default: False

--test

Run a quick GPU test

Default: False

--status

Show detailed status of all GPUs

Default: False

--list

List all available GPUs

Default: False

--select-best

Select GPU with most free memory

Default: False

--select

Select specific GPU by ID

Apply N4 bias field correction to an OME-Zarr OCT volume.

Three correction modes are supported.

• per_section – independently correct each serial tissue section (removes depth-dependent attenuation per section).

• global – correct the whole stack as one volume (removes slow large-scale intensity gradients).

• two_pass – run per_section first, then global (default).

The --strength parameter (0-1) blends between the original and the fully-corrected result: output = strength * corrected + (1 - strength) * input.

usage: linum_correct_bias_field [-h] [--mode {per_section,global,two_pass}]
                                [--strength STRENGTH]
                                [--n_serial_slices N_SERIAL_SLICES]
                                [--n_processes N_PROCESSES]
                                [--shrink_factor SHRINK_FACTOR]
                                [--n_iterations N_ITERATIONS [N_ITERATIONS ...]]
                                [--spline_distance_mm SPLINE_DISTANCE_MM]
                                [--mask_smoothing_sigma MASK_SMOOTHING_SIGMA]
                                [--histogram_match | --no-histogram_match]
                                [--histogram_n_bins HISTOGRAM_N_BINS]
                                [--histogram_match_per_zplane | --no-histogram_match_per_zplane]
                                [--tissue_threshold TISSUE_THRESHOLD]
                                [--zprofile_smooth_sigma ZPROFILE_SMOOTH_SIGMA]
                                [--zero_outside_mask | --no-zero_outside_mask]
                                [--save_bias_field PATH]
                                [--pyramid_resolutions PYRAMID_RESOLUTIONS [PYRAMID_RESOLUTIONS ...]]
                                [--make_isotropic] [--no_isotropic]
                                [--n_levels N_LEVELS] [--verbose]
                                [--backend {cpu,gpu,auto}]
                                in_image out_image

Positional Arguments

in_image

Input OME-Zarr image.

out_image

Output OME-Zarr image.

Named Arguments

--mode

Possible choices: per_section, global, two_pass

Correction mode. [‘two_pass’]

Default: 'two_pass'

--strength

Mixing weight between corrected and original (0 = no correction, 1 = full). [1.0]

Default: 1.0

--n_serial_slices

Number of serial tissue sections stacked along Z (for per_section / two_pass). [1]

Default: 1

--n_processes

Number of processes to use. -1 to use all cores [1].

Default: 1

--shrink_factor

Spatial downsampling factor for the N4 fit. [4]

Default: 4

--n_iterations

Max N4 iterations per fitting level. Length of list = number of fitting levels. Defaults to the backend’s own choice ([50, 50, 50, 50] for cpu, [25, 25, 25] for gpu).

--spline_distance_mm

Approximate B-spline knot spacing in mm. Defaults to 2.0 for per_section, 10.0 for global.

--mask_smoothing_sigma

Gaussian smoothing sigma for tissue mask estimation. [2.0]

Default: 2.0

--histogram_match, --no-histogram_match

Apply per-section histogram matching to a global reference distribution before N4 correction. Equalises section-to-section intensity drift while preserving relative contrast within each section. [True]

Default: True

--histogram_n_bins

Number of histogram bins for matching. [512]

Default: 512

--histogram_match_per_zplane, --no-histogram_match_per_zplane

Match each Z-plane independently to the global tissue distribution (strongest reduction of inter-slice intensity steps). When False, the volume is split into –n_serial_slices chunks (legacy behaviour). [False]

Default: False

--tissue_threshold

Voxels at or below this intensity are background and left unchanged by histogram matching. Use a small positive value (e.g. 0.005) to exclude near-zero noise. [0.0]

Default: 0.0

--zprofile_smooth_sigma

After histogram matching, remove residual per-Z-plane jitter with a smoothed scalar gain (Gaussian sigma in Z-plane units). 0 = disabled. Typical: 2.0-4.0. Eliminates the ~1-2% inter-slice steps HM cannot remove while preserving the smooth depth attenuation profile. [0.0]

Default: 0.0

--zero_outside_mask, --no-zero_outside_mask

Zero out voxels outside the tissue mask in the final output (removes agarose halo). [True]

Default: True

--save_bias_field

Save recovered bias field to this path.

--pyramid_resolutions

Target resolutions for pyramid levels in microns. [[10, 25, 50, 100]]

Default: [10, 25, 50, 100]

--make_isotropic

Resample to isotropic voxels. [True]

Default: True

--no_isotropic

Default: True

--n_levels

Use fixed pyramid levels instead of pyramid_resolutions.

--verbose

Enable INFO-level logging.

Default: False

--backend

Possible choices: cpu, gpu, auto

N4 backend. ‘cpu’ uses SimpleITK; ‘gpu’ uses the CuPy/NumPy port in linumpy.gpu.n4; ‘auto’ picks gpu when CUDA is available. [‘cpu’]

Default: 'cpu'

Note

To document additional scripts here, add an .. argparse:: block with the script’s module path and the name of the function that returns its argparse.ArgumentParser (most linumpy scripts expose _build_arg_parser — verify with grep -n _build_arg_parser scripts/<script>.py).