Merge pull request opencv#25608 from sturkmen72:animated_webp_support

Animated WebP Support opencv#25608

related issues opencv#24855 opencv#22569 

### Pull Request Readiness Checklist

See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request

- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [x] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
      Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake

Author: sturkmen72

cmake/OpenCVFindLibsGrfmt.cmake

@@ -196,19 +196,34 @@ if(WITH_WEBP AND NOT WEBP_FOUND
 endif()
 
 if(NOT WEBP_VERSION AND WEBP_INCLUDE_DIR)
-  ocv_clear_vars(ENC_MAJ_VERSION ENC_MIN_VERSION ENC_REV_VERSION)
-  if(EXISTS "${WEBP_INCLUDE_DIR}/enc/vp8enci.h")
-    ocv_parse_header("${WEBP_INCLUDE_DIR}/enc/vp8enci.h" WEBP_VERSION_LINES ENC_MAJ_VERSION ENC_MIN_VERSION ENC_REV_VERSION)
-    set(WEBP_VERSION "${ENC_MAJ_VERSION}.${ENC_MIN_VERSION}.${ENC_REV_VERSION}")
-  elseif(EXISTS "${WEBP_INCLUDE_DIR}/webp/encode.h")
+  if(EXISTS "${WEBP_INCLUDE_DIR}/webp/encode.h")
     file(STRINGS "${WEBP_INCLUDE_DIR}/webp/encode.h" WEBP_ENCODER_ABI_VERSION REGEX "#define[ \t]+WEBP_ENCODER_ABI_VERSION[ \t]+([x0-9a-f]+)" )
     if(WEBP_ENCODER_ABI_VERSION MATCHES "#define[ \t]+WEBP_ENCODER_ABI_VERSION[ \t]+([x0-9a-f]+)")
         set(WEBP_ENCODER_ABI_VERSION "${CMAKE_MATCH_1}")
-        set(WEBP_VERSION "encoder: ${WEBP_ENCODER_ABI_VERSION}")
     else()
       unset(WEBP_ENCODER_ABI_VERSION)
     endif()
   endif()
+
+  if(EXISTS "${WEBP_INCLUDE_DIR}/webp/decode.h")
+    file(STRINGS "${WEBP_INCLUDE_DIR}/webp/decode.h" WEBP_DECODER_ABI_VERSION REGEX "#define[ \t]+WEBP_DECODER_ABI_VERSION[ \t]+([x0-9a-f]+)" )
+    if(WEBP_DECODER_ABI_VERSION MATCHES "#define[ \t]+WEBP_DECODER_ABI_VERSION[ \t]+([x0-9a-f]+)")
+        set(WEBP_DECODER_ABI_VERSION "${CMAKE_MATCH_1}")
+    else()
+      unset(WEBP_DECODER_ABI_VERSION)
+    endif()
+  endif()
+
+  if(EXISTS "${WEBP_INCLUDE_DIR}/webp/demux.h")
+    file(STRINGS "${WEBP_INCLUDE_DIR}/webp/demux.h" WEBP_DEMUX_ABI_VERSION REGEX "#define[ \t]+WEBP_DEMUX_ABI_VERSION[ \t]+([x0-9a-f]+)" )
+    if(WEBP_DEMUX_ABI_VERSION MATCHES "#define[ \t]+WEBP_DEMUX_ABI_VERSION[ \t]+([x0-9a-f]+)")
+        set(WEBP_DEMUX_ABI_VERSION "${CMAKE_MATCH_1}")
+    else()
+      unset(WEBP_DEMUX_ABI_VERSION)
+    endif()
+  endif()
+
+set(WEBP_VERSION "decoder: ${WEBP_DECODER_ABI_VERSION}, encoder: ${WEBP_ENCODER_ABI_VERSION}, demux: ${WEBP_DEMUX_ABI_VERSION}")
 endif()
 
 # --- libopenjp2 (optional, check before libjasper) ---

cmake/OpenCVFindWebP.cmake

@@ -10,8 +10,6 @@
 
 # Look for the header file.
 
-unset(WEBP_FOUND)
-
 FIND_PATH(WEBP_INCLUDE_DIR NAMES webp/decode.h)
 
 if(NOT WEBP_INCLUDE_DIR)
@@ -21,13 +19,14 @@ else()
 
     # Look for the library.
     FIND_LIBRARY(WEBP_LIBRARY NAMES webp)
-    MARK_AS_ADVANCED(WEBP_LIBRARY)
+    FIND_LIBRARY(WEBP_MUX_LIBRARY NAMES webpmux)
+    FIND_LIBRARY(WEBP_DEMUX_LIBRARY NAMES webpdemux)
 
     # handle the QUIETLY and REQUIRED arguments and set WEBP_FOUND to TRUE if
     # all listed variables are TRUE
     INCLUDE(${CMAKE_ROOT}/Modules/FindPackageHandleStandardArgs.cmake)
     FIND_PACKAGE_HANDLE_STANDARD_ARGS(WebP DEFAULT_MSG WEBP_LIBRARY WEBP_INCLUDE_DIR)
 
-    SET(WEBP_LIBRARIES ${WEBP_LIBRARY})
+    SET(WEBP_LIBRARIES ${WEBP_LIBRARY} ${WEBP_MUX_LIBRARY} ${WEBP_DEMUX_LIBRARY})
     SET(WEBP_INCLUDE_DIRS ${WEBP_INCLUDE_DIR})
 endif()

doc/tutorials/app/animations.markdown

@@ -0,0 +1,91 @@
+Handling Animated Image Files {#tutorial_animations}
+===========================
+
+@tableofcontents
+
+|    |    |
+| -: | :- |
+| Original author | Suleyman Turkmen (with help of ChatGPT) |
+| Compatibility | OpenCV >= 4.11 |
+
+Goal
+----
+In this tutorial, you will learn how to:
+
+- Use `cv::imreadanimation` to load frames from animated image files.
+- Understand the structure and parameters of the `cv::Animation` structure.
+- Display individual frames from an animation.
+- Use `cv::imwriteanimation` to write `cv::Animation` to a file.
+
+Source Code
+-----------
+
+@add_toggle_cpp
+-   **Downloadable code**: Click
+    [here](https://github.com/opencv/opencv/tree/4.x/samples/cpp/tutorial_code/imgcodecs/animations.cpp)
+
+-   **Code at a glance:**
+    @include samples/cpp/tutorial_code/imgcodecs/animations.cpp
+@end_toggle
+
+@add_toggle_python
+-   **Downloadable code**: Click
+    [here](https://github.com/opencv/opencv/tree/4.x/samples/python/tutorial_code/imgcodecs/animations.py)
+
+-   **Code at a glance:**
+    @include samples/python/tutorial_code/imgcodecs/animations.py
+@end_toggle
+
+Explanation
+-----------
+
+## Initializing the Animation Structure
+
+   Initialize a `cv::Animation` structure to hold the frames from the animated image file.
+
+@add_toggle_cpp
+@snippet cpp/tutorial_code/imgcodecs/animations.cpp init_animation
+@end_toggle
+
+@add_toggle_python
+@snippet python/tutorial_code/imgcodecs/animations.py init_animation
+@end_toggle
+
+## Loading Frames
+
+   Use `cv::imreadanimation` to load frames from the specified file. Here, we load all frames from an animated WebP image.
+
+@add_toggle_cpp
+@snippet cpp/tutorial_code/imgcodecs/animations.cpp read_animation
+@end_toggle
+
+@add_toggle_python
+@snippet python/tutorial_code/imgcodecs/animations.py read_animation
+@end_toggle
+
+## 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.
+
+@add_toggle_cpp
+@snippet cpp/tutorial_code/imgcodecs/animations.cpp show_animation
+@end_toggle
+
+@add_toggle_python
+@snippet python/tutorial_code/imgcodecs/animations.py show_animation
+@end_toggle
+
+## Saving Animation
+
+@add_toggle_cpp
+@snippet cpp/tutorial_code/imgcodecs/animations.cpp write_animation
+@end_toggle
+
+@add_toggle_python
+@snippet python/tutorial_code/imgcodecs/animations.py write_animation
+@end_toggle
+
+## 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.

doc/tutorials/app/table_of_content_app.markdown

@@ -10,3 +10,4 @@ Application utils (highgui, imgcodecs, videoio modules) {#tutorial_table_of_cont
 -   @subpage tutorial_orbbec_uvc
 -   @subpage tutorial_intelperc
 -   @subpage tutorial_wayland_ubuntu
+-   @subpage tutorial_animations

modules/imgcodecs/include/opencv2/imgcodecs.hpp

@@ -236,6 +236,36 @@ enum ImwriteGIFCompressionFlags {
 
 //! @} imgcodecs_flags
 
+/** @brief Represents an animation with multiple frames.
+The `Animation` struct is designed to store and manage data for animated sequences such as those from animated formats (e.g., GIF, AVIF, APNG, WebP).
+It provides support for looping, background color settings, frame timing, and frame storage.
+*/
+struct CV_EXPORTS_W_SIMPLE Animation
+{
+    //! Number of times the animation should loop. 0 means infinite looping.
+    CV_PROP_RW int loop_count;
+    //! Background color of the animation in BGRA format.
+    CV_PROP_RW Scalar bgcolor;
+    //! Duration for each frame in milliseconds.
+    CV_PROP_RW std::vector<int> durations;
+    //! Vector of frames, where each Mat represents a single frame.
+    CV_PROP_RW std::vector<Mat> frames;
+
+    /** @brief Constructs an Animation object with optional loop count and background color.
+
+    @param loopCount An integer representing the number of times the animation should loop:
+    - `0` (default) indicates infinite looping, meaning the animation will replay continuously.
+    - Positive values denote finite repeat counts, allowing the animation to play a limited number of times.
+    - If a negative value or a value beyond the maximum of `0xffff` (65535) is provided, it is reset to `0`
+    (infinite looping) to maintain valid bounds.
+
+    @param bgColor A `Scalar` object representing the background color in BGRA format:
+    - Defaults to `Scalar()`, indicating an empty color (usually transparent if supported).
+    - This background color provides a solid fill behind frames that have transparency, ensuring a consistent display appearance.
+    */
+    Animation(int loopCount = 0, Scalar bgColor = Scalar());
+};
+
 /** @brief Loads an image from a file.
 
 @anchor imread
@@ -323,6 +353,38 @@ The function imreadmulti loads a specified range from a multi-page image from th
 */
 CV_EXPORTS_W bool imreadmulti(const String& filename, CV_OUT std::vector<Mat>& mats, int start, int count, int flags = IMREAD_ANYCOLOR);
 
+/** @example samples/cpp/tutorial_code/imgcodecs/animations.cpp
+An example to show usage of cv::imreadanimation and cv::imwriteanimation functions.
+Check @ref tutorial_animations "the corresponding tutorial" for more details
+*/
+
+/** @brief Loads frames from an animated image file into an Animation structure.
+
+The function imreadanimation loads frames from an animated image file (e.g., GIF, AVIF, APNG, WEBP) into the provided Animation struct.
+
+@param filename A string containing the path to the file.
+@param animation A reference to an Animation structure where the loaded frames will be stored. It should be initialized before the function is called.
+@param start The index of the first frame to load. This is optional and defaults to 0.
+@param count The number of frames to load. This is optional and defaults to 32767.
+
+@return Returns true if the file was successfully loaded and frames were extracted; returns false otherwise.
+*/
+CV_EXPORTS_W bool imreadanimation(const String& filename, CV_OUT Animation& animation, int start = 0, int count = INT16_MAX);
+
+/** @brief Saves an Animation to a specified file.
+
+The function imwriteanimation saves the provided Animation data to the specified file in an animated format.
+Supported formats depend on the implementation and may include formats like GIF, AVIF, APNG, or WEBP.
+
+@param filename The name of the file where the animation will be saved. The file extension determines the format.
+@param animation A constant reference to an Animation struct containing the frames and metadata to be saved.
+@param params Optional format-specific parameters encoded as pairs (paramId_1, paramValue_1, paramId_2, paramValue_2, ...).
+These parameters are used to specify additional options for the encoding process. Refer to `cv::ImwriteFlags` for details on possible parameters.
+
+@return Returns true if the animation was successfully saved; returns false otherwise.
+*/
+CV_EXPORTS_W bool imwriteanimation(const String& filename, const Animation& animation, const std::vector<int>& params = std::vector<int>());
+
 /** @brief Returns the number of images inside the given file
 
 The function imcount returns the number of pages in a multi-page image (e.g. TIFF), the number of frames in an animation (e.g. AVIF), and 1 otherwise.

modules/imgcodecs/src/grfmt_avif.cpp

@@ -11,6 +11,7 @@
 #include <memory>
 
 #include <opencv2/core/utils/configuration.private.hpp>
+#include <opencv2/core/utils/logger.hpp>
 #include "opencv2/imgproc.hpp"
 #include "grfmt_avif.hpp"
 
@@ -242,6 +243,8 @@ bool AvifDecoder::readData(Mat &img) {
     return false;
   }
 
+  m_animation.durations.push_back(decoder_->imageTiming.durationInTimescales);
+
   if (decoder_->image->exif.size > 0) {
     m_exif.parseExif(decoder_->image->exif.data, decoder_->image->exif.size);
   }
@@ -297,16 +300,26 @@ bool AvifEncoder::isFormatSupported(int depth) const {
 
 bool AvifEncoder::write(const Mat &img, const std::vector<int> &params) {
   std::vector<Mat> img_vec(1, img);
-  return writeToOutput(img_vec, params);
+  return writemulti(img_vec, params);
 }
 
 bool AvifEncoder::writemulti(const std::vector<Mat> &img_vec,
                              const std::vector<int> &params) {
-  return writeToOutput(img_vec, params);
+
+    CV_LOG_INFO(NULL, "Multi page image will be written as animation with 1 second frame duration.");
+
+    Animation animation;
+    animation.frames = img_vec;
+
+    for (size_t i = 0; i < animation.frames.size(); i++)
+    {
+        animation.durations.push_back(1000);
+    }
+    return writeanimation(animation, params);
 }
 
-bool AvifEncoder::writeToOutput(const std::vector<Mat> &img_vec,
-                                const std::vector<int> &params) {
+bool AvifEncoder::writeanimation(const Animation& animation,
+                                 const std::vector<int> &params) {
   int bit_depth = 8;
   int speed = AVIF_SPEED_FASTEST;
   for (size_t i = 0; i < params.size(); i += 2) {
@@ -340,12 +353,12 @@ bool AvifEncoder::writeToOutput(const std::vector<Mat> &img_vec,
 #endif
   encoder_->speed = speed;
 
-  const avifAddImageFlags flag = (img_vec.size() == 1)
+  const avifAddImageFlags flag = (animation.frames.size() == 1)
                                      ? AVIF_ADD_IMAGE_FLAG_SINGLE
                                      : AVIF_ADD_IMAGE_FLAG_NONE;
   std::vector<AvifImageUniquePtr> images;
   std::vector<cv::Mat> imgs_scaled;
-  for (const cv::Mat &img : img_vec) {
+  for (const cv::Mat &img : animation.frames) {
     CV_CheckType(
         img.type(),
         (bit_depth == 8 && img.depth() == CV_8U) ||
@@ -358,13 +371,15 @@ bool AvifEncoder::writeToOutput(const std::vector<Mat> &img_vec,
 
     images.emplace_back(ConvertToAvif(img, do_lossless, bit_depth));
   }
-  for (const AvifImageUniquePtr &image : images) {
+
+  for (size_t i = 0; i < images.size(); i++)
+  {
     OPENCV_AVIF_CHECK_STATUS(
-        avifEncoderAddImage(encoder_, image.get(), /*durationInTimescale=*/1,
-                            flag),
+        avifEncoderAddImage(encoder_, images[i].get(), animation.durations[i], flag),
         encoder_);
   }
 
+  encoder_->timescale = 1000;
   OPENCV_AVIF_CHECK_STATUS(avifEncoderFinish(encoder_, output.get()), encoder_);
 
   if (m_buf) {

modules/imgcodecs/src/grfmt_avif.hpp

@@ -46,12 +46,11 @@ class AvifEncoder CV_FINAL : public BaseImageEncoder {
 
   bool writemulti(const std::vector<Mat>& img_vec,
                   const std::vector<int>& params) CV_OVERRIDE;
+  bool writeanimation(const Animation& animation, const std::vector<int>& params) CV_OVERRIDE;
 
   ImageEncoder newEncoder() const CV_OVERRIDE;
 
  private:
-  bool writeToOutput(const std::vector<Mat>& img_vec,
-                     const std::vector<int>& params);
   avifEncoder* encoder_;
 };
 

modules/imgcodecs/src/grfmt_base.cpp

@@ -144,6 +144,11 @@ bool BaseImageEncoder::writemulti(const std::vector<Mat>&, const std::vector<int
     return false;
 }
 
+bool BaseImageEncoder::writeanimation(const Animation&, const std::vector<int>& )
+{
+    return false;
+}
+
 ImageEncoder BaseImageEncoder::newEncoder() const
 {
     return ImageEncoder();

modules/imgcodecs/src/grfmt_base.hpp

@@ -133,6 +133,8 @@ class BaseImageDecoder {
      */
     virtual bool checkSignature(const String& signature) const;
 
+    const Animation& animation() const { return m_animation; };
+
     /**
      * @brief Create and return a new instance of the derived image decoder.
      * @return A new ImageDecoder object.
@@ -151,6 +153,7 @@ class BaseImageDecoder {
     bool m_use_rgb;       ///< Flag indicating whether to decode the image in RGB order.
     ExifReader m_exif;    ///< Object for reading EXIF metadata from the image.
     size_t m_frame_count; ///< Number of frames in the image (for animations and multi-page images).
+    Animation m_animation;
 };
 
 
@@ -215,6 +218,8 @@ class BaseImageEncoder {
      */
     virtual bool writemulti(const std::vector<Mat>& img_vec, const std::vector<int>& params);
 
+    virtual bool writeanimation(const Animation& animation, const std::vector<int>& params);
+
     /**
      * @brief Get a description of the image encoder (e.g., the format it supports).
      * @return A string describing the encoder.