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_image(image, filename)

Saves a single image to an image file.

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.save_image(image, filename)[source]

Saves a single image to an image file.

Supported file types: jpg, png.

Parameters:

  • image (ndarray) – A single image of shape (height, width), (height, width, channels) with 1 (grayscale), 3 (RGB) or 4 (RGBA) channels. Image should be uint8. JPEG has no alpha channel, so an RGBA image is written as RGB; PNG keeps the alpha channel.

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

Returns:

The path the image was written to.

Return type:

Path

Raises:

ValueError – If the file extension is not supported.

zea.io_lib.save_to_gif(images, filename, fps=20, shared_color_palette=True, transparent=False, loop=0)[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.

  • loop (int, optional) – Number of times to repeat after the first play. Defaults to 0, which loops forever. Pass None to write no loop extension at all, so the GIF plays once and stops on the last frame.

  • transparent (bool, optional) – If True, keeps the alpha channel of RGBA images as GIF transparency. GIF only supports binary transparency, so pixels with alpha < 128 become fully transparent and all others fully opaque. One palette entry is reserved for the transparent color. Requires RGBA input. Defaults to False.

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). For GIF files, transparent=True keeps the alpha channel of RGBA images.

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[str] | None) – List of file extensions to match. If None, all files 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.