Command Line Interface
lls-pipeline
Usage:
Options:
process
Usage:
Options:
[INPUT_IMAGE] Path to the image file to read, in a format
readable by AICSImageIO, for example .tiff
or .czi
--skew [X|Y] Axis along which to deskew the image.
Choices: `{"X", "Y"}`. These can be provided
as `str`. \[default: Y]
--angle FLOAT Angle of deskewing, in degrees, as a float.
\[default: 30.0]
--invert-scan-direction / --no-invert-scan-direction
If `True`, reverse the order of planes along
the scan (Z) axis before deskewing. This is
required for oblique plane microscopes whose
stage/galvo scans can be in opposite
directions. Leaving this `False` preserves
the original behaviour compatible with Zeiss
LLS. \[default: no-invert-scan-direction]
--coverslip-rotation / --no-coverslip-rotation
Apply the coverslip rotation (rotate the
deskewed volume by the deskew angle). Effect
is acquisition-geometry dependent: True
(default) uses the standard deskew
(cle.deskew_y/x) and is coverslip-level for
Zeiss LLS7; False skips the rotation and is
coverslip-level for some OPM/SOPi.
\[default: coverslip-rotation]
--physical-pixel-sizes <FLOAT FLOAT FLOAT>...
Pixel size of the microscope, in microns.
This can alternatively be provided as a
`tuple[float]` of `(Z, Y, X)` This takes
three arguments, corresponding to the Z, Y
and X pixel dimensions respectively
\[default: 0.3, 0.1499219272808386,
0.1499219272808386]
--roi-list PATH List of regions of interest, each of which
must be an `N × D` array, where N is the
number of vertices and D the coordinates of
each vertex. This can alternatively be
provided as a `str` or `Path`, or a list of
those, in which case they are interpreted as
paths to ImageJ ROI (.roi/.zip) or napari
shapes (.csv) files that are read from disk.
--roi-units [auto|pixel|micron]
The units the `roi_list` coordinates are in.
'Auto' takes it from the file type: ImageJ
ROIs are pixels, and a napari shapes CSV
saved from the plugin's crop layer is
microns, because that layer is unscaled
while the image layer carries the pixel
size. Set it explicitly for a CSV written by
anything else. \[default: Auto]
--roi-subset TEXT A subset of all the ROIs to process. Each
list item should be an index into the ROI
list indicating an ROI to include. This
allows you to process only a subset of the
regions from a ROI file specified using the
`roi_list` parameter. If `None`, it is
assumed that you want to process all ROIs.
Accepts either repeated flags (--roi-subset
2 --roi-subset 5) or a comma-separated list
(--roi-subset 2,5,7).
--z-range <INTEGER INTEGER>... The range of Z slices to take as a tuple of
the form `(first, last)`. All Z slices
before the first index or after the last
index will be cropped out.
--deconvolution / --disable-deconvolution
\[default: disable-deconvolution]
--decon-processing [cuda_gpu|opencl_gpu|cpu]
Hardware to use to perform the
deconvolution. Choices: `{"cuda_gpu",
"opencl_gpu", "cpu"}`. Can be provided as
`str`. \[default: cpu]
--psf PATH List of Point Spread Functions to use for
deconvolution. Each of which should be a 3D
array. Each PSF can also be provided as a
`str` path, in which case they will be
loaded from disk as images.
--decon-num-iter INTEGER Number of iterations to perform in
deconvolution \[default: 10]
--background TEXT Background value to subtract for
deconvolution. Only used when
`decon_processing` is set to `GPU`. This can
either be a literal number, "auto" which
uses the median of the last slice, or
"second_last" which uses the median of the
last slice. \[default: 0]
--time-range <INTEGER INTEGER>...
The range of times to process. This defaults
to all time points in the image array.
--channel-range <INTEGER INTEGER>...
The range of channels to process. This
defaults to all time points in the image
array.
--save-dir PATH The directory where the output data will be
saved. This can be specified as a `str` or
`Path`.
--save-name TEXT The filename that will be used for output
files. This should not contain a leading
directory or file extension. The final
output files will have additional elements
added to the end of this prefix to indicate
the region of interest, channel, timepoint,
file extension etc.
--save-type [h5|tiff|omezarr] The data type to save the result as. This
will also be used to determine the file
extension of the output files. Choices:
`{"h5", "tiff", "omezarr"}`. Choices can
alternatively be specifed as `str`, for
example `'tiff'`. Note: `tiff` is saved as a
compressed OME-TIFF (`.ome.tif`).
\[default: h5]
--process-parallel INTEGER Number of worker processes for cropping
ROIs. Each worker processes a subset of the
ROI list independently, sharing the GPU. 1
(default) keeps the serial behaviour; higher
values help when a single ROI does not
saturate the GPU. 0 means 'auto': a memory-
safe worker count is derived from the memory
estimate (disabled for
deconvolution/workflow runs, which it cannot
size). Ignored when cropping is disabled.
\[default: 1]
--memory-safety-factor FLOAT Multiplier applied to the estimated per-
worker working set in the memory estimate,
covering OpenCL scratch buffers and
fragmentation. Increase if you hit OOM
crashes with parallel processing; decrease
for more aggressive packing. \[default:
1.5]
--save-mip / --no-save-mip If `True`, save a 2D maximum-intensity
projection (top-down/coverslip view) of the
deskewed data instead of the full volume.
The MIP is computed directly from the raw
data without materialising the deskewed
volume (a CPU/numba gather), so it is
memory-light and fast for very large
acquisitions. One MIP is written per
timepoint and channel, using the chosen
`save_type`. Cropping and deconvolution are
ignored for MIP output. \[default: no-
save-mip]
--mip-interpolation [nearest|linear]
Interpolation used when `save_mip` is
enabled. Choices: `{"nearest", "linear"}`.
`'nearest'` (default) is fastest and blocky;
`'linear'` blends adjacent scan planes for a
smoother MIP. \[default: nearest]
--workflow PATH If defined, this is a workflow to add
lightsheet processing onto
--json-config PATH Path to a JSON file from which parameters
will be read.
--yaml-config PATH Path to a YAML file from which parameters
will be read.
--show-schema / --no-show-schema
If provided, image processing will not be
performed, and instead a JSON document
outlining the JSON/YAML options will be
printed to stdout. This can be used to
assist with writing a config file for use
with the --json-config and --yaml-config
options. \[default: no-show-schema]
--help Show this message and exit.
process
Usage:
Options:
[INPUT_IMAGE] Path to the image file to read, in a format
readable by AICSImageIO, for example .tiff
or .czi
--skew [X|Y] Axis along which to deskew the image.
Choices: `{"X", "Y"}`. These can be provided
as `str`. \[default: Y]
--angle FLOAT Angle of deskewing, in degrees, as a float.
\[default: 30.0]
--invert-scan-direction / --no-invert-scan-direction
If `True`, reverse the order of planes along
the scan (Z) axis before deskewing. This is
required for oblique plane microscopes whose
stage/galvo scans can be in opposite
directions. Leaving this `False` preserves
the original behaviour compatible with Zeiss
LLS. \[default: no-invert-scan-direction]
--coverslip-rotation / --no-coverslip-rotation
Apply the coverslip rotation (rotate the
deskewed volume by the deskew angle). Effect
is acquisition-geometry dependent: True
(default) uses the standard deskew
(cle.deskew_y/x) and is coverslip-level for
Zeiss LLS7; False skips the rotation and is
coverslip-level for some OPM/SOPi.
\[default: coverslip-rotation]
--physical-pixel-sizes <FLOAT FLOAT FLOAT>...
Pixel size of the microscope, in microns.
This can alternatively be provided as a
`tuple[float]` of `(Z, Y, X)` This takes
three arguments, corresponding to the Z, Y
and X pixel dimensions respectively
\[default: 0.3, 0.1499219272808386,
0.1499219272808386]
--roi-list PATH List of regions of interest, each of which
must be an `N × D` array, where N is the
number of vertices and D the coordinates of
each vertex. This can alternatively be
provided as a `str` or `Path`, or a list of
those, in which case they are interpreted as
paths to ImageJ ROI (.roi/.zip) or napari
shapes (.csv) files that are read from disk.
--roi-units [auto|pixel|micron]
The units the `roi_list` coordinates are in.
'Auto' takes it from the file type: ImageJ
ROIs are pixels, and a napari shapes CSV
saved from the plugin's crop layer is
microns, because that layer is unscaled
while the image layer carries the pixel
size. Set it explicitly for a CSV written by
anything else. \[default: Auto]
--roi-subset TEXT A subset of all the ROIs to process. Each
list item should be an index into the ROI
list indicating an ROI to include. This
allows you to process only a subset of the
regions from a ROI file specified using the
`roi_list` parameter. If `None`, it is
assumed that you want to process all ROIs.
Accepts either repeated flags (--roi-subset
2 --roi-subset 5) or a comma-separated list
(--roi-subset 2,5,7).
--z-range <INTEGER INTEGER>... The range of Z slices to take as a tuple of
the form `(first, last)`. All Z slices
before the first index or after the last
index will be cropped out.
--deconvolution / --disable-deconvolution
\[default: disable-deconvolution]
--decon-processing [cuda_gpu|opencl_gpu|cpu]
Hardware to use to perform the
deconvolution. Choices: `{"cuda_gpu",
"opencl_gpu", "cpu"}`. Can be provided as
`str`. \[default: cpu]
--psf PATH List of Point Spread Functions to use for
deconvolution. Each of which should be a 3D
array. Each PSF can also be provided as a
`str` path, in which case they will be
loaded from disk as images.
--decon-num-iter INTEGER Number of iterations to perform in
deconvolution \[default: 10]
--background TEXT Background value to subtract for
deconvolution. Only used when
`decon_processing` is set to `GPU`. This can
either be a literal number, "auto" which
uses the median of the last slice, or
"second_last" which uses the median of the
last slice. \[default: 0]
--time-range <INTEGER INTEGER>...
The range of times to process. This defaults
to all time points in the image array.
--channel-range <INTEGER INTEGER>...
The range of channels to process. This
defaults to all time points in the image
array.
--save-dir PATH The directory where the output data will be
saved. This can be specified as a `str` or
`Path`.
--save-name TEXT The filename that will be used for output
files. This should not contain a leading
directory or file extension. The final
output files will have additional elements
added to the end of this prefix to indicate
the region of interest, channel, timepoint,
file extension etc.
--save-type [h5|tiff|omezarr] The data type to save the result as. This
will also be used to determine the file
extension of the output files. Choices:
`{"h5", "tiff", "omezarr"}`. Choices can
alternatively be specifed as `str`, for
example `'tiff'`. Note: `tiff` is saved as a
compressed OME-TIFF (`.ome.tif`).
\[default: h5]
--process-parallel INTEGER Number of worker processes for cropping
ROIs. Each worker processes a subset of the
ROI list independently, sharing the GPU. 1
(default) keeps the serial behaviour; higher
values help when a single ROI does not
saturate the GPU. 0 means 'auto': a memory-
safe worker count is derived from the memory
estimate (disabled for
deconvolution/workflow runs, which it cannot
size). Ignored when cropping is disabled.
\[default: 1]
--memory-safety-factor FLOAT Multiplier applied to the estimated per-
worker working set in the memory estimate,
covering OpenCL scratch buffers and
fragmentation. Increase if you hit OOM
crashes with parallel processing; decrease
for more aggressive packing. \[default:
1.5]
--save-mip / --no-save-mip If `True`, save a 2D maximum-intensity
projection (top-down/coverslip view) of the
deskewed data instead of the full volume.
The MIP is computed directly from the raw
data without materialising the deskewed
volume (a CPU/numba gather), so it is
memory-light and fast for very large
acquisitions. One MIP is written per
timepoint and channel, using the chosen
`save_type`. Cropping and deconvolution are
ignored for MIP output. \[default: no-
save-mip]
--mip-interpolation [nearest|linear]
Interpolation used when `save_mip` is
enabled. Choices: `{"nearest", "linear"}`.
`'nearest'` (default) is fastest and blocky;
`'linear'` blends adjacent scan planes for a
smoother MIP. \[default: nearest]
--workflow PATH If defined, this is a workflow to add
lightsheet processing onto
--json-config PATH Path to a JSON file from which parameters
will be read.
--yaml-config PATH Path to a YAML file from which parameters
will be read.
--show-schema / --no-show-schema
If provided, image processing will not be
performed, and instead a JSON document
outlining the JSON/YAML options will be
printed to stdout. This can be used to
assist with writing a config file for use
with the --json-config and --yaml-config
options. \[default: no-show-schema]
--help Show this message and exit.
ROI files and units (--roi-list, --roi-units)
--roi-list accepts Fiji ROI Manager files (.roi, .zip) and napari shapes files
(.csv, as written by File -> Save Selected Layers).
Neither format records whether its coordinates are pixels or microns, so
--roi-units declares it. The default, Auto, takes it from the file type — Fiji
files are pixels, a napari .csv saved from the plugin's crop layer is microns:
# Auto: .zip read as pixels, .csv read as microns
lls-pipeline process input.czi --roi-list rois.zip --save-dir out
# Override, for a CSV written by something other than napari
lls-pipeline process input.czi --roi-list rois.csv --roi-units pixels --save-dir out
The value is case-insensitive and accepts either singular or plural (pixel,
pixels, micron, microns).
A wrong unit is not always obvious
The two interpretations differ by the pixel size, so ROIs read in the wrong unit
can still land inside the image and be processed without error. A warning is
logged if any ROI falls outside the deskewed image, but the reliable check is to
leave --roi-units on Auto.
Coverslip-frame deskew (--no-coverslip-rotation)
By default, lls-pipeline performs the standard deskew (cle.deskew_y /
cle.deskew_x) — --coverslip-rotation is on by default. This performs a rotation of the volume based on the skew angle, which is accurate output geometry for Zeiss LLS
data.
Pass --no-coverslip-rotation to skip that rotation and deskew directly into the
shear-only frame that is level for OPM/SOPi (oblique-plane and
single-objective planar illumination) acquisitions. In a single interpolation pass
the data are sheared/deskewed so that the specimen plane is level with the coverslip, rather
than tilted at the light-sheet angle. Within the plugin, you could try "Quick Deskew" to visualize what the output would look like.
Key properties of this mode:
- Both skew directions supported. Works for
--skew Y(default) and--skew Xacquisitions. - MIP path. This mode is also compatible with
--save-mip. - Cropping path. When
--roi-listis provided, each ROI is processed with the selected coverslip rotation mode. - Default unchanged. Omitting
--no-coverslip-rotation(or passing--coverslip-rotation) uses the stock deskew, leaving all behaviour for Zeiss LLS data exactly as before.
Flipping the scan direction (--invert-scan-direction)
Different microscopes scan the sample in different directions. On some oblique-plane systems the stage or galvo scans in the opposite direction to the Zeiss LLS, which produces a deskewed volume that is mirrored along the scan axis.
Pass --invert-scan-direction to reverse the order of the planes along the scan (Z)
axis before deskewing, correcting this handedness:
- Default off. Omitting the flag preserves the original Zeiss LLS behaviour.
- Combine with geometry flags. It works alongside
--skew X/--skew Yand--no-coverslip-rotation, so you can match most OPM acquisition geometries by combining these three options.
Generating MIPs (--save-mip)
At the end of every acquisition, a top-down (coverslip-view) maximum-intensity
projection (MIP) is often all that is needed — for example to define cropping ROIs, or
for a quick overview of a very large dataset. lls-pipeline can produce this deskewed MIP
directly, without ever building the full deskewed volume:
The MIP is computed straight from the raw data by mapping each projected pixel back to the source voxels and accumulating the maximum along the axial direction (a CPU/numba gather). Because the full deskewed volume is never materialised, this path is memory-light and fast, which makes it well suited to terabyte-scale acquisitions.
Key properties:
- One MIP per timepoint and channel, written using the chosen
--save-type(tiff,h5oromezarr). - Smoothness. Use
--mip-interpolation nearest(default — fastest, blocky) or--mip-interpolation linearto blend adjacent scan planes for a smoother MIP. - Geometry aware. Compatible with
--skew X/--skew Yand the coverslip-rotation modes above. - Cropping and deconvolution are ignored when
--save-mipis set — the MIP is a fast whole-frame projection, not a per-ROI product.
MIP output is CLI/API only
Generating MIP files is available through the command line (--save-mip) and the
Python API. It is not currently exposed
as a checkbox in the napari plugin.
For a worked, end-to-end walkthrough — generating a MIP, drawing ROIs on it in Fiji, and feeding them back into a crop run — see the MIP walkthrough.