OpenCV
Open Source Computer Vision
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Modules Pages
Handling Animated Image Files

Original author Suleyman Turkmen (with help of ChatGPT)
Compatibility OpenCV >= 4.11

Goal

In this tutorial, you will learn how to:

Source Code

  • Downloadable code: Click here
  • Code at a glance:
    #include <iostream>
    using namespace cv;
    int main( int argc, const char** argv )
    {
    std::string filename = argc > 1 ? argv[1] : "animated_image.webp";
    if (argc == 1)
    {
    Animation animation_to_save;
    Mat image(128, 256, CV_8UC4, Scalar(150, 150, 150, 255));
    int duration = 200;
    for (int i = 0; i < 10; ++i) {
    animation_to_save.frames.push_back(image.clone());
    putText(animation_to_save.frames[i], format("Frame %d", i), Point(30, 80), FONT_HERSHEY_SIMPLEX, 1.5, Scalar(255, 100, 0, 255), 2);
    animation_to_save.durations.push_back(duration);
    }
    imwriteanimation("animated_image.webp", animation_to_save, { IMWRITE_WEBP_QUALITY, 100 });
    }
    Animation animation;
    bool success = imreadanimation(filename, animation);
    if (!success) {
    std::cerr << "Failed to load animation frames\n";
    return -1;
    }
    while (true)
    for (size_t i = 0; i < animation.frames.size(); ++i) {
    imshow("Animation", animation.frames[i]);
    int key_code = waitKey(animation.durations[i]); // Delay between frames
    if (key_code == 27)
    exit(0);
    }
    return 0;
    }
    n-dimensional dense array class
    Definition mat.hpp:829
    #define CV_8UC4
    Definition interface.h:91
    void imshow(const String &winname, InputArray mat)
    Displays an image in the specified window.
    int waitKey(int delay=0)
    Waits for a pressed key.
    int main(int argc, char *argv[])
    Definition highgui_qt.cpp:3
    Definition core.hpp:107
    Represents an animation with multiple frames. The Animation struct is designed to store and manage da...
    Definition imgcodecs.hpp:248
    CV_PROP_RW std::vector< Mat > frames
    Vector of frames, where each Mat represents a single frame.
    Definition imgcodecs.hpp:256
    CV_PROP_RW std::vector< int > durations
    Duration for each frame in milliseconds.
    Definition imgcodecs.hpp:254

Explanation

Initializing the Animation Structure

Initialize a cv::Animation structure to hold the frames from the animated image file.

Animation animation;

Loading Frames

Use cv::imreadanimation to load frames from the specified file. Here, we load all frames from an animated WebP image.

bool success = imreadanimation(filename, animation);
if (!success) {
std::cerr << "Failed to load animation frames\n";
return -1;
}

Displaying Frames

Each frame in the animation.frames vector can be displayed as a standalone image. This loop iterates through each frame, displaying it in a window with a short delay to simulate the animation.

while (true)
for (size_t i = 0; i < animation.frames.size(); ++i) {
imshow("Animation", animation.frames[i]);
int key_code = waitKey(animation.durations[i]); // Delay between frames
if (key_code == 27)
exit(0);
}

Saving Animation

if (argc == 1)
{
Animation animation_to_save;
Mat image(128, 256, CV_8UC4, Scalar(150, 150, 150, 255));
int duration = 200;
for (int i = 0; i < 10; ++i) {
animation_to_save.frames.push_back(image.clone());
putText(animation_to_save.frames[i], format("Frame %d", i), Point(30, 80), FONT_HERSHEY_SIMPLEX, 1.5, Scalar(255, 100, 0, 255), 2);
animation_to_save.durations.push_back(duration);
}
imwriteanimation("animated_image.webp", animation_to_save, { IMWRITE_WEBP_QUALITY, 100 });
}

Summary

The cv::imreadanimation and cv::imwriteanimation functions make it easy to work with animated image files by loading frames into a cv::Animation structure, allowing frame-by-frame processing. With these functions, you can load, process, and save frames from animated image files like GIF, AVIF, APNG, and WebP.