zea.io_lib

Input / output functions for reading and writing files.

Use to quickly read and write files or interact with file system.

Functions

compute_global_palette_by_histogram(pillow_imgs)	Computes a global color palette for a sequence of images using histogram analysis.
grayscale_to_rgb(image)	Converts a grayscale image to an RGB image.
load_image(filename[, mode])	Load an image file and return a numpy array.
load_video(filename[, mode])	Load a video file and return a numpy array of frames.
matplotlib_figure_to_numpy(fig, **kwargs)	Convert matplotlib figure to numpy array.
preprocess_for_saving(images)	Preprocesses images for saving to GIF or MP4.
save_to_gif(images, filename[, fps, ...])	Saves a sequence of images to a GIF file.
save_to_mp4(images, filename[, fps, ...])	Saves a sequence of images to an MP4 file.
save_video(images, filename[, fps])	Saves a sequence of images to a video file.
search_file_tree(directory[, filetypes, ...])	Traverse a directory tree and yield file paths matching specified file types.

zea.io_lib.compute_global_palette_by_histogram(pillow_imgs, bits_per_channel=5, palette_size=256)

Computes a global color palette for a sequence of images using histogram analysis.

Parameters:

• pillow_imgs (list) – List of pillow images. All images should be in RGB mode.

• bits_per_channel (int, optional) – Number of bits to use per color channel for histogram binning. Can take values between 1 and 7. Defaults to 5.

• palette_size (int, optional) – Number of colors in the resulting palette. Defaults to 256.

Returns:

A PIL ‘P’ mode image containing the computed color palette.

Return type:

PIL.Image

Raises:

ValueError – If bits_per_channel or palette_size is outside of range.

zea.io_lib.grayscale_to_rgb(image)

Converts a grayscale image to an RGB image.

Parameters:

image (ndarray) – Grayscale image. Must have shape (height, width).

Returns:

RGB image.

Return type:

ndarray

zea.io_lib.load_image(filename, mode='L')

Load an image file and return a numpy array.

Supported file types: jpg, png.

Parameters:

• filename (str) – The path to the image file.

• mode (str, optional) – Color mode: “L” (grayscale) or “RGB”. Defaults to “L”.

Returns:

A numpy array of the image.

Return type:

numpy.ndarray

Raises:

ValueError – If the file extension or mode is not supported.

zea.io_lib.load_video(filename, mode='L')

Load a video file and return a numpy array of frames.

Supported file types: mp4, gif.

Parameters:

• filename (str) – The path to the video file.

• mode (str, optional) – Color mode: “L” (grayscale) or “RGB”. Defaults to “L”.

Returns:

Array of frames (num_frames, H, W) or (num_frames, H, W, C)

Return type:

numpy.ndarray

Raises:

ValueError – If the file extension or mode is not supported.

zea.io_lib.matplotlib_figure_to_numpy(fig, **kwargs)

Convert matplotlib figure to numpy array.

Parameters:

fig (matplotlib.figure.Figure) – figure to convert.

Returns:

numpy array of figure.

Return type:

np.ndarray

zea.io_lib.preprocess_for_saving(images)

Preprocesses images for saving to GIF or MP4.

Parameters:

images (ndarray, list[ndarray]) – Images. Must have shape (n_frames, height, width, channels) or (n_frames, height, width).

zea.io_lib.save_to_gif(images, filename, fps=20, shared_color_palette=True)

Saves a sequence of images to a GIF file.

Note

It’s recommended to use save_video() for a more general interface that supports multiple formats.

Parameters:

• images (list or np.ndarray) – List or array of images. Must have shape (n_frames, height, width, channels) or (n_frames, height, width). If channel axis is not present, or is 1, grayscale image is assumed, which is then converted to RGB. Images should be uint8.

• filename (str or Path) – Filename to which data should be written.

• fps (int) – Frames per second of rendered format.

• shared_color_palette (bool, optional) – If True, creates a global color palette across all frames, ensuring consistent colors throughout the GIF. Defaults to True, which is default behavior of PIL.Image.save. Note: True increases speed and shrinks file size for longer sequences.

zea.io_lib.save_to_mp4(images, filename, fps=20, shared_color_palette=False)

Saves a sequence of images to an MP4 file.

Note

It’s recommended to use save_video() for a more general interface that supports multiple formats.

Parameters:

• images (list or np.ndarray) – List or array of images. Must have shape (n_frames, height, width, channels) or (n_frames, height, width). If channel axis is not present, or is 1, grayscale image is assumed, which is then converted to RGB. Images should be uint8.

• filename (str or Path) – Filename to which data should be written.

• fps (int) – Frames per second of rendered format.

• shared_color_palette (bool, optional) – If True, creates a global color palette across all frames, ensuring consistent colors throughout the MP4. Note: True can cause slow saving for longer sequences.

Raises:

ImportError – If imageio-ffmpeg is not installed.

Returns:

Success message.

Return type:

str

zea.io_lib.save_video(images, filename, fps=20, **kwargs)

Saves a sequence of images to a video file.

Supported file types: mp4, gif.

Parameters:

• images (list or np.ndarray) – List or array of images. Must have shape (n_frames, height, width, channels) or (n_frames, height, width). If channel axis is not present, or is 1, grayscale image is assumed, which is then converted to RGB. Images should be uint8.

• filename (str or Path) – Filename to which data should be written.

• fps (int) – Frames per second of rendered format.

• **kwargs – Additional keyword arguments passed to the specific save function. For GIF and mp4 files, this includes shared_color_palette (bool).

Raises:

ValueError – If the file extension is not supported.

zea.io_lib.search_file_tree(directory, filetypes=None, verbose=True, relative=False)

Traverse a directory tree and yield file paths matching specified file types.

Parameters:

• directory (str or Path) – The root directory to start the search.

• filetypes (list of str, optional) – List of file extensions to match. If None, file types supported by zea are matched. Defaults to None.

• verbose (bool, optional) – If True, logs the search process. Defaults to True.

• relative (bool, optional) – If True, yields file paths relative to the root directory. Defaults to False.

Yields:

Path – Paths of files matching the specified file types.