Merge pull request #27499 from vpisarev:image_io_with_metadata

vpisarev · web-flow · commit 66e5fce9282f · 2025-07-01T18:38:22.000+03:00
Extend image I/O API with metadata support #27499 Covered with the PR: * AVIF encoder can write exif, xmp, icc * AVIF decoder can read exif * JPEG encoder can write exif * JPEG decoder can read exif * PNG encoder can write exif * PNG decoder can read exif This PR is a sort of preamble for #27488. I suggest to merge this one first to OpenCV 4.x, then promote this change to OpenCV 5.x and then provide extra API to read and write metadata in 5.x (or maybe 4.x) in a style similar to #27488. Maybe in that PR exif packing/unpacking should be done using a separate external API. That is, metadata reading and writing can/should be done in 2 steps: * [1] pack and then [2] embed exif into image at the encoding stage. * [1] extract and then [2] unpack exif at the decoding stage. ### 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 - [x] 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
diff --git a/modules/imgcodecs/include/opencv2/imgcodecs.hpp b/modules/imgcodecs/include/opencv2/imgcodecs.hpp
@@ -251,6 +251,15 @@ enum ImwriteGIFCompressionFlags {
     IMWRITE_GIF_COLORTABLE_SIZE_256  = 8
 };
 
+enum ImageMetadataType
+{
+    IMAGE_METADATA_UNKNOWN = -1,
+    IMAGE_METADATA_EXIF = 0,
+    IMAGE_METADATA_XMP = 1,
+    IMAGE_METADATA_ICCP = 2,
+    IMAGE_METADATA_MAX = 2
+};
+
 //! @} imgcodecs_flags
 
 /** @brief Represents an animation with multiple frames.
@@ -360,6 +369,17 @@ The image passing through the img parameter can be pre-allocated. The memory is
  */
 CV_EXPORTS_W void imread( const String& filename, OutputArray dst, int flags = IMREAD_COLOR_BGR );
 
+/** @brief Reads an image from a file together with associated metadata.
+
+The function imreadWithMetadata reads image from the specified file. It does the same thing as imread, but additionally reads metadata if the corresponding file contains any.
+@param filename Name of the file to be loaded.
+@param metadataTypes Output vector with types of metadata chucks returned in metadata, see ImageMetadataType.
+@param metadata Output vector of vectors or vector of matrices to store the retrieved metadata
+@param flags Flag that can take values of cv::ImreadModes
+*/
+CV_EXPORTS_W Mat imreadWithMetadata( const String& filename, CV_OUT std::vector<int>& metadataTypes,
+                                     OutputArrayOfArrays metadata, int flags = IMREAD_ANYCOLOR);
+
 /** @brief Loads a multi-page image from a file.
 
 The function imreadmulti loads a multi-page image from the specified file into a vector of Mat objects.
@@ -508,6 +528,20 @@ It also demonstrates how to save multiple images in a TIFF file:
 CV_EXPORTS_W bool imwrite( const String& filename, InputArray img,
               const std::vector<int>& params = std::vector<int>());
 
+/** @brief Saves an image to a specified file with metadata
+
+The function imwriteWithMetadata saves the image to the specified file. It does the same thing as imwrite, but additionally writes metadata if the corresponding format supports it.
+@param filename Name of the file. As with imwrite, image format is determined by the file extension.
+@param img (Mat or vector of Mat) Image or Images to be saved.
+@param metadataTypes Vector with types of metadata chucks stored in metadata to write, see ImageMetadataType.
+@param metadata Vector of vectors or vector of matrices with chunks of metadata to store into the file
+@param params Format-specific parameters encoded as pairs (paramId_1, paramValue_1, paramId_2, paramValue_2, ... .) see cv::ImwriteFlags
+*/
+CV_EXPORTS_W bool imwriteWithMetadata( const String& filename, InputArray img,
+                                       const std::vector<int>& metadataTypes,
+                                       InputArrayOfArrays& metadata,
+                                       const std::vector<int>& params = std::vector<int>());
+
 //! @brief multi-image overload for bindings
 CV_WRAP static inline
 bool imwritemulti(const String& filename, InputArrayOfArrays img,
@@ -529,6 +563,22 @@ See cv::imread for the list of supported formats and flags description.
 */
 CV_EXPORTS_W Mat imdecode( InputArray buf, int flags );
 
+/** @brief Reads an image from a buffer in memory together with associated metadata.
+
+The function imdecode reads an image from the specified buffer in the memory. If the buffer is too short or
+contains invalid data, the function returns an empty matrix ( Mat::data==NULL ).
+
+See cv::imread for the list of supported formats and flags description.
+
+@note In the case of color images, the decoded images will have the channels stored in **B G R** order.
+@param buf Input array or vector of bytes.
+@param metadataTypes Output vector with types of metadata chucks returned in metadata, see ImageMetadataType.
+@param metadata Output vector of vectors or vector of matrices to store the retrieved metadata
+@param flags The same flags as in cv::imread, see cv::ImreadModes.
+*/
+CV_EXPORTS_W Mat imdecodeWithMetadata( InputArray buf, CV_OUT std::vector<int>& metadataTypes,
+                                       OutputArrayOfArrays metadata, int flags = IMREAD_ANYCOLOR );
+
 /** @overload
 @param buf Input array or vector of bytes.
 @param flags The same flags as in cv::imread, see cv::ImreadModes.
@@ -567,6 +617,24 @@ CV_EXPORTS_W bool imencode( const String& ext, InputArray img,
                             CV_OUT std::vector<uchar>& buf,
                             const std::vector<int>& params = std::vector<int>());
 
+/** @brief Encodes an image into a memory buffer.
+
+The function imencode compresses the image and stores it in the memory buffer that is resized to fit the
+result. See cv::imwrite for the list of supported formats and flags description.
+
+@param ext File extension that defines the output format. Must include a leading period.
+@param img Image to be compressed.
+@param metadataTypes Vector with types of metadata chucks stored in metadata to write, see ImageMetadataType.
+@param metadata Vector of vectors or vector of matrices with chunks of metadata to store into the file
+@param buf Output buffer resized to fit the compressed image.
+@param params Format-specific parameters. See cv::imwrite and cv::ImwriteFlags.
+*/
+CV_EXPORTS_W bool imencodeWithMetadata( const String& ext, InputArray img,
+                                        const std::vector<int>& metadataTypes,
+                                        InputArrayOfArrays metadata,
+                                        CV_OUT std::vector<uchar>& buf,
+                                        const std::vector<int>& params = std::vector<int>());
+
 /** @brief Encodes array of images into a memory buffer.
 
 The function is analog to cv::imencode for in-memory multi-page image compression.
diff --git a/modules/imgcodecs/src/exif.cpp b/modules/imgcodecs/src/exif.cpp
@@ -94,6 +94,10 @@ ExifEntry_t ExifReader::getTag(const ExifTagName tag) const
     return entry;
 }
 
+const std::vector<unsigned char>& ExifReader::getData() const
+{
+    return m_data;
+}
 
 /**
  * @brief Parsing the exif data buffer and prepare (internal) exif directory
diff --git a/modules/imgcodecs/src/exif.hpp b/modules/imgcodecs/src/exif.hpp
@@ -175,6 +175,10 @@ class ExifReader
      */
     ExifEntry_t getTag( const ExifTagName tag ) const;
 
+    /**
+     * @brief Get the whole exif buffer
+     */
+    const std::vector<unsigned char>& getData() const;
 
 private:
     std::vector<unsigned char> m_data;
diff --git a/modules/imgcodecs/src/grfmt_avif.cpp b/modules/imgcodecs/src/grfmt_avif.cpp
@@ -68,8 +68,8 @@ avifResult CopyToMat(const avifImage *image, int channels, bool useRGB , Mat *ma
   return avifImageYUVToRGB(image, &rgba);
 }
 
-AvifImageUniquePtr ConvertToAvif(const cv::Mat &img, bool lossless,
-                                 int bit_depth) {
+AvifImageUniquePtr ConvertToAvif(const cv::Mat &img, bool lossless, int bit_depth,
+                                 const std::vector<std::vector<uchar> >& metadata) {
   CV_Assert(img.depth() == CV_8U || img.depth() == CV_16U);
 
   const int width = img.cols;
@@ -112,6 +112,18 @@ AvifImageUniquePtr ConvertToAvif(const cv::Mat &img, bool lossless,
     result->yuvRange = AVIF_RANGE_FULL;
   }
 
+  if (!metadata.empty()) {
+    const std::vector<uchar>& metadata_exif = metadata[IMAGE_METADATA_EXIF];
+    const std::vector<uchar>& metadata_xmp = metadata[IMAGE_METADATA_XMP];
+    const std::vector<uchar>& metadata_iccp = metadata[IMAGE_METADATA_ICCP];
+    if (!metadata_exif.empty())
+      avifImageSetMetadataExif(result, (const uint8_t*)metadata_exif.data(), metadata_exif.size());
+    if (!metadata_exif.empty())
+      avifImageSetMetadataXMP(result, (const uint8_t*)metadata_xmp.data(), metadata_xmp.size());
+    if (!metadata_iccp.empty())
+      avifImageSetProfileICC(result, (const uint8_t*)metadata_iccp.data(), metadata_iccp.size());
+  }
+
   avifRGBImage rgba;
   avifRGBImageSetDefaults(&rgba, result);
   if (img.channels() == 3) {
@@ -120,7 +132,7 @@ AvifImageUniquePtr ConvertToAvif(const cv::Mat &img, bool lossless,
     CV_Assert(img.channels() == 4);
     rgba.format = AVIF_RGB_FORMAT_BGRA;
   }
-  rgba.rowBytes = img.step[0];
+  rgba.rowBytes = (uint32_t)img.step[0];
   rgba.depth = bit_depth;
   rgba.pixels =
       const_cast<uint8_t *>(reinterpret_cast<const uint8_t *>(img.data));
@@ -287,6 +299,10 @@ bool AvifDecoder::nextPage() {
 AvifEncoder::AvifEncoder() {
   m_description = "AVIF files (*.avif)";
   m_buf_supported = true;
+  m_support_metadata.assign((size_t)IMAGE_METADATA_MAX + 1, false);
+  m_support_metadata[(size_t)IMAGE_METADATA_EXIF] = true;
+  m_support_metadata[(size_t)IMAGE_METADATA_XMP] = true;
+  m_support_metadata[(size_t)IMAGE_METADATA_ICCP] = true;
   encoder_ = avifEncoderCreate();
 }
 
@@ -349,7 +365,7 @@ bool AvifEncoder::writeanimation(const Animation& animation,
              img.channels() == 1 || img.channels() == 3 || img.channels() == 4,
              "AVIF only supports 1, 3, 4 channels");
 
-    images.emplace_back(ConvertToAvif(img, do_lossless, bit_depth));
+    images.emplace_back(ConvertToAvif(img, do_lossless, bit_depth, m_metadata));
   }
 
   for (size_t i = 0; i < images.size(); i++)
diff --git a/modules/imgcodecs/src/grfmt_base.cpp b/modules/imgcodecs/src/grfmt_base.cpp
@@ -58,11 +58,30 @@ BaseImageDecoder::BaseImageDecoder()
     m_frame_count = 1;
 }
 
+bool BaseImageDecoder::haveMetadata(ImageMetadataType type) const
+{
+    if (type == IMAGE_METADATA_EXIF)
+        return !m_exif.getData().empty();
+    return false;
+}
+
+Mat BaseImageDecoder::getMetadata(ImageMetadataType type) const
+{
+    if (type == IMAGE_METADATA_EXIF) {
+        const std::vector<unsigned char>& exif = m_exif.getData();
+        if (!exif.empty()) {
+            Mat exifmat(1, (int)exif.size(), CV_8U, (void*)exif.data());
+            return exifmat;
+        }
+    }
+    return Mat();
+}
 
 ExifEntry_t BaseImageDecoder::getExifTag(const ExifTagName tag) const
 {
     return m_exif.getTag(tag);
 }
+
 bool BaseImageDecoder::setSource( const String& filename )
 {
     m_filename = filename;
@@ -140,6 +159,23 @@ bool BaseImageEncoder::setDestination( std::vector<uchar>& buf )
     return true;
 }
 
+bool BaseImageEncoder::addMetadata(ImageMetadataType type, const Mat& metadata)
+{
+    CV_Assert_N(type >= IMAGE_METADATA_EXIF, type <= IMAGE_METADATA_MAX);
+    if (metadata.empty())
+        return true;
+    size_t itype = (size_t)type;
+    if (itype >= m_support_metadata.size() || !m_support_metadata[itype])
+        return false;
+    if (m_metadata.empty())
+        m_metadata.resize((size_t)IMAGE_METADATA_MAX+1);
+    CV_Assert(metadata.elemSize() == 1);
+    CV_Assert(metadata.isContinuous());
+    const unsigned char* data = metadata.ptr<unsigned char>();
+    m_metadata[itype].assign(data, data + metadata.total());
+    return true;
+}
+
 bool BaseImageEncoder::write(const Mat &img, const std::vector<int> &params) {
     std::vector<Mat> img_vec(1, img);
     return writemulti(img_vec, params);
diff --git a/modules/imgcodecs/src/grfmt_base.hpp b/modules/imgcodecs/src/grfmt_base.hpp
@@ -69,6 +69,20 @@ class BaseImageDecoder {
      */
     virtual int type() const { return m_type; }
 
+    /**
+     * @brief Checks whether file contains metadata of the certain type.
+     * @param type The type of metadata to look for
+     */
+    virtual bool haveMetadata(ImageMetadataType type) const;
+
+    /**
+     * @brief Retrieves metadata (if any) of the certain kind.
+     * If there is no such metadata, the method returns empty array.
+     *
+     * @param type The type of metadata to look for
+     */
+    virtual Mat getMetadata(ImageMetadataType type) const;
+
     /**
      * @brief Fetch a specific EXIF tag from the image's metadata.
      * @param tag The EXIF tag to retrieve.
@@ -205,6 +219,13 @@ class BaseImageEncoder {
      */
     virtual bool setDestination(std::vector<uchar>& buf);
 
+    /**
+     * @brief Sets the metadata to write together with the image data
+     * @param type The type of metadata to add
+     * @param metadata The packed metadata (Exif, XMP, ...)
+     */
+    virtual bool addMetadata(ImageMetadataType type, const Mat& metadata);
+
     /**
      * @brief Encode and write the image data.
      * @param img The Mat object containing the image data to be encoded.
@@ -243,6 +264,8 @@ class BaseImageEncoder {
     virtual void throwOnError() const;
 
 protected:
+    std::vector<std::vector<unsigned char> > m_metadata; // see IMAGE_METADATA_...
+    std::vector<bool> m_support_metadata;
     String m_description;    ///< Description of the encoder (e.g., format name, capabilities).
     String m_filename;       ///< Destination file name for encoded data.
     std::vector<uchar>* m_buf; ///< Pointer to the buffer for encoded data if using memory-based destination.
diff --git a/modules/imgcodecs/src/grfmt_jpeg.cpp b/modules/imgcodecs/src/grfmt_jpeg.cpp
@@ -600,6 +600,8 @@ JpegEncoder::JpegEncoder()
 {
     m_description = "JPEG files (*.jpeg;*.jpg;*.jpe)";
     m_buf_supported = true;
+    m_support_metadata.assign((size_t)IMAGE_METADATA_MAX + 1, false);
+    m_support_metadata[(size_t)IMAGE_METADATA_EXIF] = true;
 }
 
 
@@ -815,6 +817,22 @@ bool JpegEncoder::write( const Mat& img, const std::vector<int>& params )
 
         jpeg_start_compress( &cinfo, TRUE );
 
+        if (!m_metadata.empty()) {
+            const std::vector<uchar>& metadata_exif = m_metadata[IMAGE_METADATA_EXIF];
+            size_t exif_size = metadata_exif.size();
+            if (exif_size > 0u) {
+                const char app1_exif_prefix[] = {'E', 'x', 'i', 'f', '\0', '\0'};
+                size_t app1_exif_prefix_size = sizeof(app1_exif_prefix);
+                size_t data_size = exif_size + app1_exif_prefix_size;
+
+                std::vector<uchar> metadata_app1(data_size);
+                uchar* data = metadata_app1.data();
+                memcpy(data, app1_exif_prefix, app1_exif_prefix_size);
+                memcpy(data + app1_exif_prefix_size, metadata_exif.data(), exif_size);
+                jpeg_write_marker(&cinfo, JPEG_APP0 + 1, data, (unsigned)data_size);
+            }
+        }
+
         if( doDirectWrite )
         {
             for( int y = 0; y < height; y++ )
diff --git a/modules/imgcodecs/src/grfmt_png.cpp b/modules/imgcodecs/src/grfmt_png.cpp
@@ -858,6 +858,8 @@ PngEncoder::PngEncoder()
 {
     m_description = "Portable Network Graphics files (*.png;*.apng)";
     m_buf_supported = true;
+    m_support_metadata.assign((size_t)IMAGE_METADATA_MAX+1, false);
+    m_support_metadata[IMAGE_METADATA_EXIF] = true;
     op_zstream1.zalloc = NULL;
     op_zstream2.zalloc = NULL;
     next_seq_num = 0;
@@ -989,6 +991,16 @@ bool  PngEncoder::write( const Mat& img, const std::vector<int>& params )
                     for( y = 0; y < height; y++ )
                         buffer[y] = img.data + y*img.step;
 
+                    if (!m_metadata.empty()) {
+                        std::vector<uchar>& exif = m_metadata[IMAGE_METADATA_EXIF];
+                        if (!exif.empty()) {
+                            writeChunk(f, "eXIf", exif.data(), (uint32_t)exif.size());
+                        }
+                        // [TODO] add xmp and icc. They need special handling,
+                        // see https://dev.exiv2.org/projects/exiv2/wiki/The_Metadata_in_PNG_files and
+                        // https://www.libpng.org/pub/png/spec/1.2/PNG-Chunks.html.
+                    }
+
                     png_write_image( png_ptr, buffer.data() );
                     png_write_end( png_ptr, info_ptr );
 
diff --git a/modules/imgcodecs/src/loadsave.cpp b/modules/imgcodecs/src/loadsave.cpp
diff --git a/modules/imgcodecs/test/test_exif.cpp b/modules/imgcodecs/test/test_exif.cpp
diff --git a/modules/python/test/test_imread.py b/modules/python/test/test_imread.py

Original file line number	Diff line number	Diff line change
`@@ -94,6 +94,10 @@ ExifEntry_t ExifReader::getTag(const ExifTagName tag) const`
`94`	`94`	`return entry;`
`95`	`95`	`}`
`96`	`96`
	`97`	`+const std::vector<unsigned char>& ExifReader::getData() const`
	`98`	`+{`
	`99`	`+ return m_data;`
	`100`	`+}`
`97`	`101`
`98`	`102`	`/**`
`99`	`103`	`* @brief Parsing the exif data buffer and prepare (internal) exif directory`