Imageio Usage Examples ====================== Some of these examples use Visvis to visualize the image data, but one can also use Matplotlib to show the images. Imageio provides a range of :doc:`example images `, which can be used by using a URI like ``'imageio:chelsea.png'``. The images are automatically downloaded if not already present on your system. Therefore most examples below should just work. Read an image of a cat ---------------------- Probably the most important thing you'll ever need. .. code-block:: python import imageio.v3 as iio im = iio.imread('imageio:chelsea.png') print(im.shape) # (300, 451, 3) If the image is a GIF: .. code-block:: python import imageio.v3 as iio # index=None means: read all images in the file and stack along first axis frames = iio.imread("imageio:newtonscradle.gif", index=None) # ndarray with (num_frames, height, width, channel) print(frames.shape) # (36, 150, 200, 3) Read from fancy sources ----------------------- Imageio can read from filenames, file objects. .. code-block:: python import imageio.v3 as iio import io # from HTTPS web_image = "https://upload.wikimedia.org/wikipedia/commons/d/d3/Newtons_cradle_animation_book_2.gif" frames = iio.imread(web_image, index=None) # from bytes bytes_image = iio.imwrite("", frames, extension=".gif") frames = iio.imread(bytes_image, index=None) # from byte streams byte_stream = io.BytesIO(bytes_image) frames = iio.imread(byte_stream, index=None) # from file objects class MyFileObject: def read(size:int=-1): return bytes_image def close(): return # nothing to do frames = iio.imread(MyFileObject()) Read all Images in a Folder --------------------------- .. code-block:: python import imageio.v3 as iio from pathlib import Path images = list() for file in Path("path/to/folder").iterdir(): if not file.is_file(): continue images.append(iio.imread(file)) Note, however, that ``Path().iterdir()`` does not guarantees the order in which files are read. Grab screenshot or image from the clipboard ------------------------------------------- (Screenshots are supported on Windows and OS X, clipboard on Windows only.) .. code-block:: python import imageio.v3 as iio im_screen = iio.imread('') im_clipboard = iio.imread('') Grab frames from your webcam ---------------------------- .. note:: For this to work, you need to install the ffmpeg backend:: pip install imageio[ffmpeg] .. code-block:: python import imageio.v3 as iio import numpy as np for idx, frame in enumerate(iio.imiter("")): print(f"Frame {idx}: avg. color {np.sum(frame, axis=-1)}") Note: You can replace the zero with another index in case you have multiple devices attached. Convert a short movie to grayscale ---------------------------------- .. note:: For this to work, you need to install the ffmpeg backend:: pip install imageio[ffmpeg] .. code-block:: python import imageio as iio import numpy as np # read the video (it fits into memory) # Note: this will open the image twice. Check the docs (advanced usage) if # this is an issue for your use-case metadata = iio.immeta("imageio:cockatoo.mp4", exclude_applied=False) frames = iio.imread("imageio:cockatoo.mp4", index=None) # manually convert the video gray_frames = np.dot(frames, [0.2989, 0.5870, 0.1140]) gray_frames = np.round(gray_frames).astype(np.uint8) gray_frames_as_rgb = np.stack([gray_frames] * 3, axis=-1) # write the video iio.imwrite("cockatoo_gray.mp4", gray_frames_as_rgb, fps=metadata["fps"]) Read or iterate frames in a video --------------------------------- .. note:: For this to work, you need to install the pyav backend:: pip install av .. code-block:: python import imageio.v3 as iio # read a single frame frame = iio.imread( "imageio:cockatoo.mp4", index=42, plugin="pyav", ) # bulk read all frames # Warning: large videos will consume a lot of memory (RAM) frames = iio.imread("imageio:cockatoo.mp4", plugin="pyav") # iterate over large videos for frame in iio.imiter("imageio:cockatoo.mp4", plugin="pyav"): print(frame.shape, frame.dtype) Re-encode a (large) video ------------------------- .. note:: For this to work, you need to install the pyav backend:: pip install av .. code-block:: python import imageio.v3 as iio # assume this is too large to keep all frames in memory source = "imageio:cockatoo.mp4" dest = "reencoded_cockatoo.mkv" fps = iio.immeta(source, plugin="pyav")["fps"] with iio.imopen(dest, "w", plugin="pyav") as out_file: out_file.init_video_stream("vp9", fps=fps) for frame in iio.imiter(source, plugin="pyav"): out_file.write_frame(frame) Read medical data (DICOM) ------------------------- .. code-block:: python import imageio.v3 as iio dirname = 'path/to/dicom/files' # Read multiple images of different shape ims = [img for img in iio.imiter(dirname, plugin='DICOM')] # Read as volume vol = iio.imread(dirname, plugin='DICOM') # Read multiple volumes of different shape vols = [img for img in iio.imiter(dirname, plugin='DICOM')] Volume data ----------- .. code-block:: python import imageio.v3 as iio import visvis as vv vol = iio.imread('imageio:stent.npz') vv.volshow(vol) Writing videos with FFMPEG and vaapi ------------------------------------ Using vaapi can help free up CPU time on your device while you are encoding videos. One notable difference between vaapi and x264 is that vaapi doesn't support the color format yuv420p. Note, you will need ffmpeg compiled with vaapi for this to work. .. code-block:: python import imageio.v2 as iio import numpy as np # All images must be of the same size image1 = np.stack([iio.imread('imageio:camera.png')] * 3, 2) image2 = iio.imread('imageio:astronaut.png') image3 = iio.imread('imageio:immunohistochemistry.png') w = iio.get_writer('my_video.mp4', format='FFMPEG', mode='I', fps=1, codec='h264_vaapi', output_params=['-vaapi_device', '/dev/dri/renderD128', '-vf', 'format=gray|nv12,hwupload'], pixelformat='vaapi_vld') w.append_data(image1) w.append_data(image2) w.append_data(image3) w.close() A little bit of explanation: * ``output_params`` * ``vaapi_device`` specifies the encoding device that will be used. * ``vf`` and ``format`` tell ffmpeg that it must upload to the dedicated hardware. Since vaapi only supports a subset of color formats, we ensure that the video is in either gray or nv12 before uploading it. The ``or`` operation is achieved with ``|``. * ``pixelformat``: set to ``'vaapi_vld'`` to avoid a warning in ffmpeg. * ``codec``: the code you wish to use to encode the video. Make sure your hardware supports the chosen codec. If your hardware supports h265, you may be able to encode using ``'hevc_vaapi'`` Writing to Bytes (Encoding) --------------------------- You can convert ndimages into byte strings. For this, you have to hint the desired extension (using ``extension=``), as a byte string doesn't specify any information about the format or color space to use. Note that, if the backend supports writing to file-like objects, the entire process will happen without touching your file-system. .. code-block:: python import imageio.v3 as iio # load an example image img = iio.imread('imageio:astronaut.png') # png-encoded bytes string png_encoded = iio.imwrite("", img, extension=".png") # jpg-encoded bytes string jpg_encoded = iio.imwrite("", img, extension=".jpeg") # RGBA bytes string img = iio.imread('imageio:astronaut.png', mode="RGBA") png_encoded = iio.imwrite("", img, extension=".png") Writing to BytesIO ------------------ Similar to writing to byte strings, you can also write to BytesIO directly. .. code-block:: python import imageio.v3 as iio import io # load an example image img = iio.imread('imageio:astronaut.png') # write as PNG output = io.BytesIO() iio.imwrite(output, img, plugin="pillow", extension=".png") # write as JPG output = io.BytesIO() iio.imwrite(output, img, plugin="pillow", extension=".jpeg") Optimizing a GIF using pygifsicle ------------------------------------ When creating a `GIF `_ using `imageio `_ the resulting images can get quite heavy, as the created GIF is not optimized. This can be useful when the elaboration process for the GIF is not finished yet (for instance if some elaboration on specific frames stills need to happen), but it can be an issue when the process is finished and the GIF is unexpectedly big. GIF files can be compressed in several ways, the most common one method (the one used here) is saving just the differences between the following frames. In this example, we apply the described method to a given GIF `my_gif` using `pygifsicle `_, a porting of the general-purpose GIF editing command-line library `gifsicle `_. To install pygifsicle and gifsicle, `read the setup on the project page `_: it boils down to installing the package using pip and following the console instructions: .. code-block:: shell pip install pygifsicle Now, let's start by creating a gif using imageio: .. code-block:: python import imageio.v3 as iio import matplotlib.pyplot as plt import numpy as np n = 100 gif_path = "test.gif" n = 100 plt.figure(figsize=(4, 4)) for x in range(n): plt.scatter(x / n, x / n) plt.xlim(0, 1) plt.ylim(0, 1) plt.savefig(f"{x}.jpg") frames = np.stack([iio.imread(f"{x}.jpg") for x in range(n)], axis=0) iio.imwrite(gif_path, frames) This way we obtain a 2.5MB gif. We now want to compress the created GIF. We can either overwrite the initial one or create a new optimized one: We start by importing the library method: .. code-block:: python from pygifsicle import optimize optimize(gif_path, "optimized.gif") # For creating a new one optimize(gif_path) # For overwriting the original one The new optimized GIF now weights 870KB, almost 3 times less. Putting everything together: .. code-block:: python import imageio.v3 as iio import matplotlib.pyplot as plt import numpy as np from pygifsicle import optimize n = 100 gif_path = "test.gif" n = 100 plt.figure(figsize=(4, 4)) for x in range(n): plt.scatter(x / n, x / n) plt.xlim(0, 1) plt.ylim(0, 1) plt.savefig(f"{x}.jpg") frames = np.stack([iio.imread(f"{x}.jpg") for x in range(n)], axis=0) iio.imwrite(gif_path, frames) optimize(gif_path) Reading Images from ZIP archives -------------------------------- .. note:: In the future, this syntax will change to better match the URI standard by using fragments. The updated syntax will be ``"Path/to/file.zip#path/inside/zip/to/image.png"``. .. code-block:: python import imageio.v3 as iio image = iio.imread("Path/to/file.zip/path/inside/zip/to/image.png") Reading Multiple Files from a ZIP archive ----------------------------------------- Assuming there are only image files in the ZIP archive you can iterate over them with a simple script like the one below. .. code-block:: python import os from zipfile import ZipFile import imageio.v3 as iio images = list() with ZipFile("imageio.zip") as zf: for name in zf.namelist(): im = iio.imread(name) images.append(im) Reading Metadata ---------------- ImageIO differentiates between two types of metadata: format-specific metadata and standardized metadata. Format-specific metadata comes in the form of a python dict and aims to expose all the metadata contained in the image using the containers/plugins key and format:: import imageio.v3 as iio metadata = iio.immeta("imageio:chelsea.png") print(metadata["mode"]) # "RGB" Standardized metadata, on the other hand, comes in the form of the :class:`ImageProperties ` dataclass and aims to expose a curated set of metadata using a standardized name and format independent of the underlying container or plugin:: import imageio.v3 as iio props = iio.improps("imageio:chelsea.png") print(props.shape) # (300, 451, 3) print(props.dtype) # dtype('uint8')