Merge pull request #27499 from vpisarev:image_io_with_metadata

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

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.