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.

retry_on_io_error([max_retries, ...])

Decorator to retry functions on I/O errors with exponential backoff.

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)[source]

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)[source]

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')[source]

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')[source]

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)[source]

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)[source]

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.retry_on_io_error(max_retries=3, initial_delay=0.5, retry_action=None)[source]

Decorator to retry functions on I/O errors with exponential backoff.

Parameters:

  • max_retries (int) – Maximum number of retry attempts.

  • initial_delay (float) – Initial delay between retries in seconds.

  • retry_action (callable, optional) – Optional function to call before each retry attempt. If decorating a method: retry_action(self, exception, attempt, *args, **kwargs) If decorating a function: retry_action(exception, attempt, *args, **kwargs)

Returns:

Decorated function with retry logic.

Return type:

callable

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

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)[source]

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)[source]

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)[source]

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.