ImageSequence Module

ImageSequence is a module in the Python Pillow library (a fork of PIL), specifically designed for handling multi-frame images (such as GIF, TIFF, and other formats).

The ImageSequence module allows you to access each frame in an image sequence in an iterative manner, making it ideal for processing animated images or image files containing multiple pages.

Main Uses of ImageSequence

  1. Processing animated GIFs: Reading and manipulating GIF animations frame by frame
  2. Processing multi-page TIFFs: Accessing individual pages in a TIFF file
  3. Image sequence processing: Batch processing a single file containing multiple images
  4. Frame extraction and analysis: Extracting specific frames from animated images for analysis or modification

Core Methods of the ImageSequence Module

The following are the most commonly used methods in the ImageSequence module and their descriptions:

Method/Attribute Description Return Value Example
ImageSequence.Iterator(image) Creates an iterator object for iterating over an image sequence Iterator object for frame in ImageSequence.Iterator(img):
ImageSequence.all_frames(image) Returns a list containing all frames List frames = list(ImageSequence.all_frames(img))
seek(frame) Jump to a specific frame (supported by some image formats) None img.seek(5) # Jump to the 6th frame
tell() Returns the index position of the current frame Integer current_frame = img.tell()
n_frames Returns the total number of frames in the image Integer total_frames = img.n_frames

Usage Examples

1. Basic Usage: Iterating Over All Frames of a GIF Animation

Example

from PIL import Image, ImageSequence

# Open GIF file
with Image.open('animation.gif') as img:
    # Iterate over each frame
    for i, frame in enumerate(ImageSequence.Iterator(img)):
        # Process each frame
        frame.save(f'frame_{i}.png')  # Save as individual PNG files

2. Extracting All Pages from a TIFF File

Example

from PIL import Image, ImageSequence

# Open multi-page TIFF file
with Image.open('multipage.tiff') as img:
    # Get all frames
    frames = list(ImageSequence.all_frames(img))
   
    # Process each page
    for i, page in enumerate(frames):
        page.save(f'page_{i}.jpg', quality=95)

3. Modifying and Saving an Animated GIF

Example

from PIL import Image, ImageSequence

# Open source GIF
with Image.open('source.gif') as img:
    # Prepare new frame list
    new_frames = []
   
    # Process each frame
    for frame in ImageSequence.Iterator(img):
        # Modify each frame (e.g., add text)
        modified_frame = frame.copy()
        # ... Add your modification code here ...
       
        new_frames.append(modified_frame)
   
    # Save the modified GIF
    new_frames[0].save('modified.gif',
                      save_all=True,
                      append_images=new_frames[1:],
                      duration=img.info.get('duration', 100),
                      loop=0)

Notes

  1. Memory usage: When processing large multi-frame images, pay attention to memory consumption and consider processing frame by frame rather than loading all frames at once
  2. Format support: Not all image formats support multi-frame operations; common supported formats include GIF, TIFF, WebP, etc.
  3. Frame index: Frame indices start from 0, which may differ from what common image viewers display (viewers usually count from 1)
  4. Modifying the original image: Directly modifying frames may affect the original image; it is recommended to useframe.copy()creating a copy before modification

Summary

The ImageSequence module provides simple yet powerful tools for handling multi-frame images. Through its iterator interface, developers can easily access and manipulate each frame in animated or multi-page images. Whether extracting frames, analyzing content, or creating new animations, this module can greatly simplify the workflow.

Other Extensions