utils

Collection of helper functions.

fastddm.utils.chunkify(seq: ndarray, chunksize: int, overlap: int = 0) → List[ndarray]

Chunkify a sequence into smaller portions.

Takes a sequence seq and chunks it into smaller portions of size chunksize, with a given overlap with the previous chunk.

The sequence could be e.g. image indices, or an image sequence itself. However, be aware that in the latter case, depending on the chunksize and overlap settings the needed amount of memory could be very high! (It is recommended to use image sequence indices, see example below.)

The last chunk may not be of the right size. The chunking will happen along the first axis.

Parameters:

  • seq (numpy.ndarray) – A numpy array of to be chunked content.

  • chunksize (int) – The size of the output chunks.

  • overlap (int, optional) – Give a number > 0 by how much the chunks should overlap, i.e. overlap=2 would result in [[1 2 3], [2 3 4], [3 4 5], ...], by default 0.

Returns:

The list of chunks.

Return type:

List[numpy.ndarray]

Examples

>>> chunkify(np.arange(10), chunksize=5, overlap=2)
[array([0, 1, 2, 3, 4]), array([3, 4, 5, 6, 7]), array([6, 7, 8, 9])]
fastddm.utils.images2numpy(fnames: Sequence[str], color_seq: Sequence[int] | None = None) → ndarray

Read a sequence of image files and return it as a numpy array.

Parameters:

  • fnames (Sequence[str]) – A sequence of file names.

  • color_seq (Sequence[int] | None, optional) – A sequence, e.g. range(2), to describe a specific color sequence to be selected, by default None.

Returns:

The image sequence as a numpy array. Coordinate convention is (z,y,x). If color images are imported, convention is (c,z,y,x).

Return type:

numpy.ndarray

fastddm.utils.read_images(src: str | List[str], seq: Sequence[int] | None = None, color_seq: Sequence[int] | None = None, input_order: str | None = None) → ndarray

Read a single image file or a list of image files.

The single image file can itself be a sequence of images, like multipage tiff or nd2. If seq is given, e.g. with seq=range(10) or seq=(10, 11, 12) it will only be applied to single image files, again, like e.g. multipage tiff or nd2.

Parameters:

  • src (Union[str, List[str]]) – File path to a single image file or a list of file paths.

  • seq (Sequence[int] | None, optional) – A subset of a multi-image file, can be set e.g. via a range object, by default None.

  • color_seq (Sequence[int] | None, optional) – A sequence, e.g. range(2), to describe a specific color sequence to be selected, by default None.

  • input_order (str | None, optional) – The order of input dimensions. Currently only supports up to 4 dimensions "CTYX", only used for TIFF files, be default None.

Returns:

The images in array form.

Return type:

numpy.ndarray

Raises:

RuntimeError – If the src type is not supported (e.g. generator expressions).

fastddm.utils.read_metadata(src: str) → Dict[str, Any]

Read an images metadata and return it as a dictionary.

Currently only supports .nd2 files and raw metadata for tiff files.

Parameters:

src (str) – Path to file location.

Returns:

A dictionary of all available metadata (no content checking is performed).

Return type:

Metadata

Raises:
fastddm.utils.tiff2numpy(src: str, seq: Sequence[int] | None = None, color_seq: Sequence[int] | None = None, input_order: str | None = None) → ndarray

Read a TIFF file (or a sequence inside a multipage TIFF) and return it as a numpy array.

The tiff file is assumed to be of the shape (T,Y,X). If color_seq is given, the order (C,T,Y,X) is assumed, otherwise the option input_order needs to be specified. If input_order is given, the full tiff file is read into memory, the axes ordered accordingly, and then seq and color_seq applied (if specified).

If a non-tiff file is given, it is opened with skimage.io.imread() using only default parameters.

It will be reshaped into (T,Y,X) (or (C,T,Y,X) if color channels are present) before it is returned.

Parameters:

  • src (str) – The path to the TIFF file.

  • seq (Sequence[int] | None, optional) – A sequence, e.g. range(5, 10), to describe a specific range within a multipage TIFF, by default None.

  • color_seq (Sequence[int] | None, optional) – A sequence, e.g. range(2), to describe a specific color sequence to be selected, by default None.

  • input_order (str | None, optional) – The order of input dimensions. Currently only supports up to 4 dimensions, "CTYX", by default None.

Returns:

The array containing the image information. Coordinate convention is (T,Y,X) (or (C,T,Y,X)).

Return type:

numpy.ndarray