Convert image sequence to ND2 format¶

Functions for converting image sequences are not part of the base limnd2 namespace, but are instead accessible through the limnd2.tools namespace.

In order to use functions and classes described on this page, import them like this:

from limnd2.tools import convert_sequence_to_nd2,\
    convert_sequence_to_nd2_args, convert_sequence_to_nd2_cli

Summary¶

convert_sequence_to_nd2: Convert a sequence of images to ND2 format.
convert_sequence_to_nd2_cli: Convert a sequence of images to ND2 format with CLI arguments (for CLI usage).
convert_sequence_to_nd2_args: Convert a sequence of images to ND2 format with CLI arguments (for usage in Python scripts).

Examples¶

Since converting image sequences is pretty advanced task and requires correct order of images, and correctly set attributes and metadata, we prepared a few examples that showcase how to use the convert_sequence_to_nd2 function to create one dimensional, multi-dimensional and even multi-channel ND2 files.

To see the examples, please check out the convert_to_nd2_examples folder in the limnd2 repository on GitHub.

Function documentation¶

convert_sequence_to_nd2 ¶

convert_sequence_to_nd2(input_data: list[list[LimImageSource]] | list[tuple[LimImageSource]] | list[list[str | Path]] | list[tuple[str | Path]] | list[LimImageSource] | list[str | Path], output_path: Path | str, attributes: ImageAttributes | None = None, experiment: ExperimentLevel | str | None = None, metadata: PictureMetadata | None = None) -> bool

Convert a sequence of images to ND2 format. This function takes a sequence of images (either as file paths or LimImageSource objects) and converts them to ND2 file. User can also provide custom attributes, experiment, and metadata for the ND2 file, if they are not provided, default values will be used.

PARAMETER	DESCRIPTION
`input_data`	1D or 2D list of file paths or `LimImageSource` objects representing the images to be converted. If the input list is one dimensional, each image will be treated as a separate frame, if the input list is two dimensional, each sublist is treated as several channels in the same frame. TYPE: `str \| Path \| LimImageSource`
`output_path`	Path where the resulting ND2 file will be saved. TYPE: `str \| Path`
`attributes`	ND2 file atributes Warning ND2 attributes must be correctly set, or the data may be shown incorrectly when viewing the ND2 file. If you are unsure about the attributes, omit the argument and they will be calculated automatically based on the input data. TYPE: `ImageAttributes` DEFAULT: `None`
`experiment`	Experiment level for the ND2 file or a string describing what type of experiment to create `["timeloop", "zstack", "multipoint"]`. Warning ND2 experiment must also be correctly set (to match dimensions of the input data), if the experiment is omitted, the function will creare multipoint experiment with the number of points equal to the number of frames in the input data. It is also important that the files are ordered correctly with respect to the set experiment. In ideal case, files will be ordered by timeloop first, then multipoint, then zstack. TYPE: `ExperimentLevel \| str` DEFAULT: `None`
`metadata`	Metadata for the ND2 file. If not provided, default metadata will be used (those are calulated based on number of channels). Warning ND2 metadata must also be correctly set, number of channels in the metadata must match the number of channels in the input data. TYPE: `PictureMetadata` DEFAULT: `None`

RETURNS	DESCRIPTION
`Path`	Path to the written ND2 file.

convert_sequence_to_nd2_cli ¶

convert_sequence_to_nd2_cli(args: list[str] | None = None) -> int

Converts a sequence of images to ND2 file using command line arguments for usage in CLI (returns exit code).

Command line arguments should be provided as a list of strings. The specific arguments and their usage are described in the CLI script that uses this function: CLI Convert image tool

PARAMETER	DESCRIPTION
`args`	List of command line arguments. If None, uses sys.argv. TYPE: `list[str] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`None`	Exits the program with exit code 0 if successful, or 1 if an error occurred.

convert_sequence_to_nd2_args ¶

convert_sequence_to_nd2_args(args: list[str] | None = None) -> Path

Converts a sequence of images to ND2 file using command line arguments for usage in Python scripts (returns path to the file).

Command line arguments should be provided as a list of strings. The specific arguments and their usage are described in the CLI script that uses this function: CLI Convert image tool

PARAMETER	DESCRIPTION
`args`	List of command line arguments. If None, uses sys.argv. TYPE: `list[str] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Path`	Path to the written ND2 file.