1 | /*M/////////////////////////////////////////////////////////////////////////////////////// |
2 | // |
3 | // IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING. |
4 | // |
5 | // By downloading, copying, installing or using the software you agree to this license. |
6 | // If you do not agree to this license, do not download, install, |
7 | // copy or use the software. |
8 | // |
9 | // |
10 | // License Agreement |
11 | // For Open Source Computer Vision Library |
12 | // |
13 | // Copyright (C) 2000-2008, Intel Corporation, all rights reserved. |
14 | // Copyright (C) 2009, Willow Garage Inc., all rights reserved. |
15 | // Third party copyrights are property of their respective owners. |
16 | // |
17 | // Redistribution and use in source and binary forms, with or without modification, |
18 | // are permitted provided that the following conditions are met: |
19 | // |
20 | // * Redistribution's of source code must retain the above copyright notice, |
21 | // this list of conditions and the following disclaimer. |
22 | // |
23 | // * Redistribution's in binary form must reproduce the above copyright notice, |
24 | // this list of conditions and the following disclaimer in the documentation |
25 | // and/or other materials provided with the distribution. |
26 | // |
27 | // * The name of the copyright holders may not be used to endorse or promote products |
28 | // derived from this software without specific prior written permission. |
29 | // |
30 | // This software is provided by the copyright holders and contributors "as is" and |
31 | // any express or implied warranties, including, but not limited to, the implied |
32 | // warranties of merchantability and fitness for a particular purpose are disclaimed. |
33 | // In no event shall the Intel Corporation or contributors be liable for any direct, |
34 | // indirect, incidental, special, exemplary, or consequential damages |
35 | // (including, but not limited to, procurement of substitute goods or services; |
36 | // loss of use, data, or profits; or business interruption) however caused |
37 | // and on any theory of liability, whether in contract, strict liability, |
38 | // or tort (including negligence or otherwise) arising in any way out of |
39 | // the use of this software, even if advised of the possibility of such damage. |
40 | // |
41 | //M*/ |
42 | |
43 | #ifndef OPENCV_IMGCODECS_HPP |
44 | #define OPENCV_IMGCODECS_HPP |
45 | |
46 | #include "opencv2/core.hpp" |
47 | |
48 | /** |
49 | @defgroup imgcodecs Image file reading and writing |
50 | @{ |
51 | @defgroup imgcodecs_flags Flags used for image file reading and writing |
52 | @defgroup imgcodecs_ios iOS glue |
53 | @defgroup imgcodecs_macosx MacOS(OSX) glue |
54 | @} |
55 | */ |
56 | |
57 | //////////////////////////////// image codec //////////////////////////////// |
58 | namespace cv |
59 | { |
60 | |
61 | //! @addtogroup imgcodecs |
62 | //! @{ |
63 | |
64 | //! @addtogroup imgcodecs_flags |
65 | //! @{ |
66 | |
67 | //! Imread flags |
68 | enum ImreadModes { |
69 | IMREAD_UNCHANGED = -1, //!< If set, return the loaded image as is (with alpha channel, otherwise it gets cropped). Ignore EXIF orientation. |
70 | IMREAD_GRAYSCALE = 0, //!< If set, always convert image to the single channel grayscale image (codec internal conversion). |
71 | IMREAD_COLOR_BGR = 1, //!< If set, always convert image to the 3 channel BGR color image. |
72 | IMREAD_COLOR = 1, //!< Same as IMREAD_COLOR_BGR. |
73 | IMREAD_ANYDEPTH = 2, //!< If set, return 16-bit/32-bit image when the input has the corresponding depth, otherwise convert it to 8-bit. |
74 | IMREAD_ANYCOLOR = 4, //!< If set, the image is read in any possible color format. |
75 | IMREAD_LOAD_GDAL = 8, //!< If set, use the gdal driver for loading the image. |
76 | IMREAD_REDUCED_GRAYSCALE_2 = 16, //!< If set, always convert image to the single channel grayscale image and the image size reduced 1/2. |
77 | IMREAD_REDUCED_COLOR_2 = 17, //!< If set, always convert image to the 3 channel BGR color image and the image size reduced 1/2. |
78 | IMREAD_REDUCED_GRAYSCALE_4 = 32, //!< If set, always convert image to the single channel grayscale image and the image size reduced 1/4. |
79 | IMREAD_REDUCED_COLOR_4 = 33, //!< If set, always convert image to the 3 channel BGR color image and the image size reduced 1/4. |
80 | IMREAD_REDUCED_GRAYSCALE_8 = 64, //!< If set, always convert image to the single channel grayscale image and the image size reduced 1/8. |
81 | IMREAD_REDUCED_COLOR_8 = 65, //!< If set, always convert image to the 3 channel BGR color image and the image size reduced 1/8. |
82 | IMREAD_IGNORE_ORIENTATION = 128, //!< If set, do not rotate the image according to EXIF's orientation flag. |
83 | IMREAD_COLOR_RGB = 256, //!< If set, always convert image to the 3 channel RGB color image. |
84 | }; |
85 | |
86 | //! Imwrite flags |
87 | enum ImwriteFlags { |
88 | IMWRITE_JPEG_QUALITY = 1, //!< For JPEG, it can be a quality from 0 to 100 (the higher is the better). Default value is 95. |
89 | IMWRITE_JPEG_PROGRESSIVE = 2, //!< Enable JPEG features, 0 or 1, default is False. |
90 | IMWRITE_JPEG_OPTIMIZE = 3, //!< Enable JPEG features, 0 or 1, default is False. |
91 | IMWRITE_JPEG_RST_INTERVAL = 4, //!< JPEG restart interval, 0 - 65535, default is 0 - no restart. |
92 | IMWRITE_JPEG_LUMA_QUALITY = 5, //!< Separate luma quality level, 0 - 100, default is -1 - don't use. If JPEG_LIB_VERSION < 70, Not supported. |
93 | IMWRITE_JPEG_CHROMA_QUALITY = 6, //!< Separate chroma quality level, 0 - 100, default is -1 - don't use. If JPEG_LIB_VERSION < 70, Not supported. |
94 | IMWRITE_JPEG_SAMPLING_FACTOR = 7, //!< For JPEG, set sampling factor. See cv::ImwriteJPEGSamplingFactorParams. |
95 | IMWRITE_PNG_COMPRESSION = 16, //!< For PNG, it can be the compression level from 0 to 9. A higher value means a smaller size and longer compression time. If specified, strategy is changed to IMWRITE_PNG_STRATEGY_DEFAULT (Z_DEFAULT_STRATEGY). Default value is 1 (best speed setting). |
96 | IMWRITE_PNG_STRATEGY = 17, //!< One of cv::ImwritePNGFlags, default is IMWRITE_PNG_STRATEGY_RLE. |
97 | IMWRITE_PNG_BILEVEL = 18, //!< Binary level PNG, 0 or 1, default is 0. |
98 | IMWRITE_PXM_BINARY = 32, //!< For PPM, PGM, or PBM, it can be a binary format flag, 0 or 1. Default value is 1. |
99 | IMWRITE_EXR_TYPE = (3 << 4) + 0 /* 48 */, //!< override EXR storage type (FLOAT (FP32) is default) |
100 | IMWRITE_EXR_COMPRESSION = (3 << 4) + 1 /* 49 */, //!< override EXR compression type (ZIP_COMPRESSION = 3 is default) |
101 | IMWRITE_EXR_DWA_COMPRESSION_LEVEL = (3 << 4) + 2 /* 50 */, //!< override EXR DWA compression level (45 is default) |
102 | IMWRITE_WEBP_QUALITY = 64, //!< For WEBP, it can be a quality from 1 to 100 (the higher is the better). By default (without any parameter) and for quality above 100 the lossless compression is used. |
103 | IMWRITE_HDR_COMPRESSION = (5 << 4) + 0 /* 80 */, //!< specify HDR compression |
104 | IMWRITE_PAM_TUPLETYPE = 128,//!< For PAM, sets the TUPLETYPE field to the corresponding string value that is defined for the format |
105 | IMWRITE_TIFF_RESUNIT = 256,//!< For TIFF, use to specify which DPI resolution unit to set; see libtiff documentation for valid values |
106 | IMWRITE_TIFF_XDPI = 257,//!< For TIFF, use to specify the X direction DPI |
107 | IMWRITE_TIFF_YDPI = 258,//!< For TIFF, use to specify the Y direction DPI |
108 | IMWRITE_TIFF_COMPRESSION = 259,//!< For TIFF, use to specify the image compression scheme. See cv::ImwriteTiffCompressionFlags. Note, for images whose depth is CV_32F, only libtiff's SGILOG compression scheme is used. For other supported depths, the compression scheme can be specified by this flag; LZW compression is the default. |
109 | IMWRITE_TIFF_ROWSPERSTRIP = 278,//!< For TIFF, use to specify the number of rows per strip. |
110 | IMWRITE_TIFF_PREDICTOR = 317,//!< For TIFF, use to specify predictor. See cv::ImwriteTiffPredictorFlags. |
111 | IMWRITE_JPEG2000_COMPRESSION_X1000 = 272,//!< For JPEG2000, use to specify the target compression rate (multiplied by 1000). The value can be from 0 to 1000. Default is 1000. |
112 | IMWRITE_AVIF_QUALITY = 512,//!< For AVIF, it can be a quality between 0 and 100 (the higher the better). Default is 95. |
113 | IMWRITE_AVIF_DEPTH = 513,//!< For AVIF, it can be 8, 10 or 12. If >8, it is stored/read as CV_32F. Default is 8. |
114 | IMWRITE_AVIF_SPEED = 514,//!< For AVIF, it is between 0 (slowest) and (fastest). Default is 9. |
115 | IMWRITE_JPEGXL_QUALITY = 640,//!< For JPEG XL, it can be a quality from 0 to 100 (the higher is the better). Default value is 95. If set, distance parameter is re-calicurated from quality level automatically. This parameter request libjxl v0.10 or later. |
116 | IMWRITE_JPEGXL_EFFORT = 641,//!< For JPEG XL, encoder effort/speed level without affecting decoding speed; it is between 1 (fastest) and 10 (slowest). Default is 7. |
117 | IMWRITE_JPEGXL_DISTANCE = 642,//!< For JPEG XL, distance level for lossy compression: target max butteraugli distance, lower = higher quality, 0 = lossless; range: 0 .. 25. Default is 1. |
118 | IMWRITE_JPEGXL_DECODING_SPEED = 643,//!< For JPEG XL, decoding speed tier for the provided options; minimum is 0 (slowest to decode, best quality/density), and maximum is 4 (fastest to decode, at the cost of some quality/density). Default is 0. |
119 | IMWRITE_GIF_LOOP = 1024,//!< For GIF, it can be a loop flag from 0 to 65535. Default is 0 - loop forever. |
120 | IMWRITE_GIF_SPEED = 1025,//!< For GIF, it is between 1 (slowest) and 100 (fastest). Default is 96. |
121 | IMWRITE_GIF_QUALITY = 1026, //!< For GIF, it can be a quality from 1 to 8. Default is 2. See cv::ImwriteGifCompressionFlags. |
122 | IMWRITE_GIF_DITHER = 1027, //!< For GIF, it can be a quality from -1(most dither) to 3(no dither). Default is 0. |
123 | IMWRITE_GIF_TRANSPARENCY = 1028, //!< For GIF, the alpha channel lower than this will be set to transparent. Default is 1. |
124 | IMWRITE_GIF_COLORTABLE = 1029 //!< For GIF, 0 means global color table is used, 1 means local color table is used. Default is 0. |
125 | }; |
126 | |
127 | enum ImwriteJPEGSamplingFactorParams { |
128 | IMWRITE_JPEG_SAMPLING_FACTOR_411 = 0x411111, //!< 4x1,1x1,1x1 |
129 | IMWRITE_JPEG_SAMPLING_FACTOR_420 = 0x221111, //!< 2x2,1x1,1x1(Default) |
130 | IMWRITE_JPEG_SAMPLING_FACTOR_422 = 0x211111, //!< 2x1,1x1,1x1 |
131 | IMWRITE_JPEG_SAMPLING_FACTOR_440 = 0x121111, //!< 1x2,1x1,1x1 |
132 | IMWRITE_JPEG_SAMPLING_FACTOR_444 = 0x111111 //!< 1x1,1x1,1x1(No subsampling) |
133 | }; |
134 | |
135 | enum ImwriteTiffCompressionFlags { |
136 | IMWRITE_TIFF_COMPRESSION_NONE = 1, //!< dump mode |
137 | IMWRITE_TIFF_COMPRESSION_CCITTRLE = 2, //!< CCITT modified Huffman RLE |
138 | IMWRITE_TIFF_COMPRESSION_CCITTFAX3 = 3, //!< CCITT Group 3 fax encoding |
139 | IMWRITE_TIFF_COMPRESSION_CCITT_T4 = 3, //!< CCITT T.4 (TIFF 6 name) |
140 | IMWRITE_TIFF_COMPRESSION_CCITTFAX4 = 4, //!< CCITT Group 4 fax encoding |
141 | IMWRITE_TIFF_COMPRESSION_CCITT_T6 = 4, //!< CCITT T.6 (TIFF 6 name) |
142 | IMWRITE_TIFF_COMPRESSION_LZW = 5, //!< Lempel-Ziv & Welch |
143 | IMWRITE_TIFF_COMPRESSION_OJPEG = 6, //!< !6.0 JPEG |
144 | IMWRITE_TIFF_COMPRESSION_JPEG = 7, //!< %JPEG DCT compression |
145 | IMWRITE_TIFF_COMPRESSION_T85 = 9, //!< !TIFF/FX T.85 JBIG compression |
146 | IMWRITE_TIFF_COMPRESSION_T43 = 10, //!< !TIFF/FX T.43 colour by layered JBIG compression |
147 | IMWRITE_TIFF_COMPRESSION_NEXT = 32766, //!< NeXT 2-bit RLE |
148 | IMWRITE_TIFF_COMPRESSION_CCITTRLEW = 32771, //!< #1 w/ word alignment |
149 | IMWRITE_TIFF_COMPRESSION_PACKBITS = 32773, //!< Macintosh RLE |
150 | IMWRITE_TIFF_COMPRESSION_THUNDERSCAN = 32809, //!< ThunderScan RLE |
151 | IMWRITE_TIFF_COMPRESSION_IT8CTPAD = 32895, //!< IT8 CT w/padding |
152 | IMWRITE_TIFF_COMPRESSION_IT8LW = 32896, //!< IT8 Linework RLE |
153 | IMWRITE_TIFF_COMPRESSION_IT8MP = 32897, //!< IT8 Monochrome picture |
154 | IMWRITE_TIFF_COMPRESSION_IT8BL = 32898, //!< IT8 Binary line art |
155 | IMWRITE_TIFF_COMPRESSION_PIXARFILM = 32908, //!< Pixar companded 10bit LZW |
156 | IMWRITE_TIFF_COMPRESSION_PIXARLOG = 32909, //!< Pixar companded 11bit ZIP |
157 | IMWRITE_TIFF_COMPRESSION_DEFLATE = 32946, //!< Deflate compression, legacy tag |
158 | IMWRITE_TIFF_COMPRESSION_ADOBE_DEFLATE = 8, //!< Deflate compression, as recognized by Adobe |
159 | IMWRITE_TIFF_COMPRESSION_DCS = 32947, //!< Kodak DCS encoding |
160 | IMWRITE_TIFF_COMPRESSION_JBIG = 34661, //!< ISO JBIG |
161 | IMWRITE_TIFF_COMPRESSION_SGILOG = 34676, //!< SGI Log Luminance RLE |
162 | IMWRITE_TIFF_COMPRESSION_SGILOG24 = 34677, //!< SGI Log 24-bit packed |
163 | IMWRITE_TIFF_COMPRESSION_JP2000 = 34712, //!< Leadtools JPEG2000 |
164 | IMWRITE_TIFF_COMPRESSION_LERC = 34887, //!< ESRI Lerc codec: https://github.com/Esri/lerc |
165 | IMWRITE_TIFF_COMPRESSION_LZMA = 34925, //!< LZMA2 |
166 | IMWRITE_TIFF_COMPRESSION_ZSTD = 50000, //!< ZSTD: WARNING not registered in Adobe-maintained registry |
167 | IMWRITE_TIFF_COMPRESSION_WEBP = 50001, //!< WEBP: WARNING not registered in Adobe-maintained registry |
168 | IMWRITE_TIFF_COMPRESSION_JXL = 50002 //!< JPEGXL: WARNING not registered in Adobe-maintained registry |
169 | }; |
170 | |
171 | enum ImwriteTiffPredictorFlags { |
172 | IMWRITE_TIFF_PREDICTOR_NONE = 1, //!< no prediction scheme used |
173 | IMWRITE_TIFF_PREDICTOR_HORIZONTAL = 2, //!< horizontal differencing |
174 | IMWRITE_TIFF_PREDICTOR_FLOATINGPOINT = 3 //!< floating point predictor |
175 | |
176 | }; |
177 | |
178 | enum ImwriteEXRTypeFlags { |
179 | /*IMWRITE_EXR_TYPE_UNIT = 0, //!< not supported */ |
180 | IMWRITE_EXR_TYPE_HALF = 1, //!< store as HALF (FP16) |
181 | IMWRITE_EXR_TYPE_FLOAT = 2 //!< store as FP32 (default) |
182 | }; |
183 | |
184 | enum ImwriteEXRCompressionFlags { |
185 | IMWRITE_EXR_COMPRESSION_NO = 0, //!< no compression |
186 | IMWRITE_EXR_COMPRESSION_RLE = 1, //!< run length encoding |
187 | IMWRITE_EXR_COMPRESSION_ZIPS = 2, //!< zlib compression, one scan line at a time |
188 | IMWRITE_EXR_COMPRESSION_ZIP = 3, //!< zlib compression, in blocks of 16 scan lines |
189 | IMWRITE_EXR_COMPRESSION_PIZ = 4, //!< piz-based wavelet compression |
190 | IMWRITE_EXR_COMPRESSION_PXR24 = 5, //!< lossy 24-bit float compression |
191 | IMWRITE_EXR_COMPRESSION_B44 = 6, //!< lossy 4-by-4 pixel block compression, fixed compression rate |
192 | IMWRITE_EXR_COMPRESSION_B44A = 7, //!< lossy 4-by-4 pixel block compression, flat fields are compressed more |
193 | IMWRITE_EXR_COMPRESSION_DWAA = 8, //!< lossy DCT based compression, in blocks of 32 scanlines. More efficient for partial buffer access. Supported since OpenEXR 2.2.0. |
194 | IMWRITE_EXR_COMPRESSION_DWAB = 9, //!< lossy DCT based compression, in blocks of 256 scanlines. More efficient space wise and faster to decode full frames than DWAA_COMPRESSION. Supported since OpenEXR 2.2.0. |
195 | }; |
196 | |
197 | //! Imwrite PNG specific flags used to tune the compression algorithm. |
198 | /** These flags will be modify the way of PNG image compression and will be passed to the underlying zlib processing stage. |
199 | |
200 | - The effect of IMWRITE_PNG_STRATEGY_FILTERED is to force more Huffman coding and less string matching; it is somewhat intermediate between IMWRITE_PNG_STRATEGY_DEFAULT and IMWRITE_PNG_STRATEGY_HUFFMAN_ONLY. |
201 | - IMWRITE_PNG_STRATEGY_RLE is designed to be almost as fast as IMWRITE_PNG_STRATEGY_HUFFMAN_ONLY, but give better compression for PNG image data. |
202 | - The strategy parameter only affects the compression ratio but not the correctness of the compressed output even if it is not set appropriately. |
203 | - IMWRITE_PNG_STRATEGY_FIXED prevents the use of dynamic Huffman codes, allowing for a simpler decoder for special applications. |
204 | */ |
205 | enum ImwritePNGFlags { |
206 | IMWRITE_PNG_STRATEGY_DEFAULT = 0, //!< Use this value for normal data. |
207 | IMWRITE_PNG_STRATEGY_FILTERED = 1, //!< Use this value for data produced by a filter (or predictor).Filtered data consists mostly of small values with a somewhat random distribution. In this case, the compression algorithm is tuned to compress them better. |
208 | IMWRITE_PNG_STRATEGY_HUFFMAN_ONLY = 2, //!< Use this value to force Huffman encoding only (no string match). |
209 | IMWRITE_PNG_STRATEGY_RLE = 3, //!< Use this value to limit match distances to one (run-length encoding). |
210 | IMWRITE_PNG_STRATEGY_FIXED = 4 //!< Using this value prevents the use of dynamic Huffman codes, allowing for a simpler decoder for special applications. |
211 | }; |
212 | |
213 | //! Imwrite PAM specific tupletype flags used to define the 'TUPLETYPE' field of a PAM file. |
214 | enum ImwritePAMFlags { |
215 | IMWRITE_PAM_FORMAT_NULL = 0, |
216 | IMWRITE_PAM_FORMAT_BLACKANDWHITE = 1, |
217 | IMWRITE_PAM_FORMAT_GRAYSCALE = 2, |
218 | IMWRITE_PAM_FORMAT_GRAYSCALE_ALPHA = 3, |
219 | IMWRITE_PAM_FORMAT_RGB = 4, |
220 | IMWRITE_PAM_FORMAT_RGB_ALPHA = 5 |
221 | }; |
222 | |
223 | //! Imwrite HDR specific values for IMWRITE_HDR_COMPRESSION parameter key |
224 | enum ImwriteHDRCompressionFlags { |
225 | IMWRITE_HDR_COMPRESSION_NONE = 0, |
226 | IMWRITE_HDR_COMPRESSION_RLE = 1 |
227 | }; |
228 | |
229 | //! Imwrite GIF specific values for IMWRITE_GIF_QUALITY parameter key, if larger than 3, then its related to the size of the color table. |
230 | enum ImwriteGIFCompressionFlags { |
231 | IMWRITE_GIF_FAST_NO_DITHER = 1, |
232 | IMWRITE_GIF_FAST_FLOYD_DITHER = 2, |
233 | IMWRITE_GIF_COLORTABLE_SIZE_8 = 3, |
234 | IMWRITE_GIF_COLORTABLE_SIZE_16 = 4, |
235 | IMWRITE_GIF_COLORTABLE_SIZE_32 = 5, |
236 | IMWRITE_GIF_COLORTABLE_SIZE_64 = 6, |
237 | IMWRITE_GIF_COLORTABLE_SIZE_128 = 7, |
238 | IMWRITE_GIF_COLORTABLE_SIZE_256 = 8 |
239 | }; |
240 | |
241 | //! @} imgcodecs_flags |
242 | |
243 | /** @brief Represents an animation with multiple frames. |
244 | 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). |
245 | It provides support for looping, background color settings, frame timing, and frame storage. |
246 | */ |
247 | struct CV_EXPORTS_W_SIMPLE Animation |
248 | { |
249 | //! Number of times the animation should loop. 0 means infinite looping. |
250 | CV_PROP_RW int loop_count; |
251 | //! Background color of the animation in BGRA format. |
252 | CV_PROP_RW Scalar bgcolor; |
253 | //! Duration for each frame in milliseconds. |
254 | CV_PROP_RW std::vector<int> durations; |
255 | //! Vector of frames, where each Mat represents a single frame. |
256 | CV_PROP_RW std::vector<Mat> frames; |
257 | |
258 | /** @brief Constructs an Animation object with optional loop count and background color. |
259 | |
260 | @param loopCount An integer representing the number of times the animation should loop: |
261 | - `0` (default) indicates infinite looping, meaning the animation will replay continuously. |
262 | - Positive values denote finite repeat counts, allowing the animation to play a limited number of times. |
263 | - If a negative value or a value beyond the maximum of `0xffff` (65535) is provided, it is reset to `0` |
264 | (infinite looping) to maintain valid bounds. |
265 | |
266 | @param bgColor A `Scalar` object representing the background color in BGRA format: |
267 | - Defaults to `Scalar()`, indicating an empty color (usually transparent if supported). |
268 | - This background color provides a solid fill behind frames that have transparency, ensuring a consistent display appearance. |
269 | */ |
270 | Animation(int loopCount = 0, Scalar bgColor = Scalar()); |
271 | }; |
272 | |
273 | /** @brief Loads an image from a file. |
274 | |
275 | @anchor imread |
276 | |
277 | The `imread` function loads an image from the specified file and returns OpenCV matrix. If the image cannot be |
278 | read (because of a missing file, improper permissions, or unsupported/invalid format), the function |
279 | returns an empty matrix. |
280 | |
281 | Currently, the following file formats are supported: |
282 | |
283 | - Windows bitmaps - \*.bmp, \*.dib (always supported) |
284 | - GIF files - \*.gif (always supported) |
285 | - JPEG files - \*.jpeg, \*.jpg, \*.jpe (see the *Note* section) |
286 | - JPEG 2000 files - \*.jp2 (see the *Note* section) |
287 | - Portable Network Graphics - \*.png (see the *Note* section) |
288 | - WebP - \*.webp (see the *Note* section) |
289 | - AVIF - \*.avif (see the *Note* section) |
290 | - Portable image format - \*.pbm, \*.pgm, \*.ppm, \*.pxm, \*.pnm (always supported) |
291 | - PFM files - \*.pfm (see the *Note* section) |
292 | - Sun rasters - \*.sr, \*.ras (always supported) |
293 | - TIFF files - \*.tiff, \*.tif (see the *Note* section) |
294 | - OpenEXR Image files - \*.exr (see the *Note* section) |
295 | - Radiance HDR - \*.hdr, \*.pic (always supported) |
296 | - Raster and Vector geospatial data supported by GDAL (see the *Note* section) |
297 | |
298 | @note |
299 | - The function determines the type of an image by its content, not by the file extension. |
300 | - In the case of color images, the decoded images will have the channels stored in **B G R** order. |
301 | - When using IMREAD_GRAYSCALE, the codec's internal grayscale conversion will be used, if available. |
302 | Results may differ from the output of cvtColor(). |
303 | - On Microsoft Windows\* and Mac OS\*, the codecs shipped with OpenCV (libjpeg, libpng, libtiff, |
304 | and libjasper) are used by default. So, OpenCV can always read JPEGs, PNGs, and TIFFs. On Mac OS, |
305 | there is also an option to use native Mac OS image readers. However, beware that currently these |
306 | native image loaders give images with different pixel values because of the color management embedded |
307 | into Mac OS. |
308 | - On Linux\*, BSD flavors, and other Unix-like open-source operating systems, OpenCV looks for |
309 | codecs supplied with the OS. Ensure the relevant packages are installed (including development |
310 | files, such as "libjpeg-dev" in Debian\* and Ubuntu\*) to get codec support, or turn |
311 | on the OPENCV_BUILD_3RDPARTY_LIBS flag in CMake. |
312 | - If the *WITH_GDAL* flag is set to true in CMake and @ref IMREAD_LOAD_GDAL is used to load the image, |
313 | the [GDAL](http://www.gdal.org) driver will be used to decode the image, supporting |
314 | [Raster](http://www.gdal.org/formats_list.html) and [Vector](http://www.gdal.org/ogr_formats.html) formats. |
315 | - If EXIF information is embedded in the image file, the EXIF orientation will be taken into account, |
316 | and thus the image will be rotated accordingly unless the flags @ref IMREAD_IGNORE_ORIENTATION |
317 | or @ref IMREAD_UNCHANGED are passed. |
318 | - Use the IMREAD_UNCHANGED flag to preserve the floating-point values from PFM images. |
319 | - By default, the number of pixels must be less than 2^30. This limit can be changed by setting |
320 | the environment variable `OPENCV_IO_MAX_IMAGE_PIXELS`. See @ref tutorial_env_reference. |
321 | |
322 | @param filename Name of the file to be loaded. |
323 | @param flags Flag that can take values of `cv::ImreadModes`. |
324 | */ |
325 | CV_EXPORTS_W Mat imread( const String& filename, int flags = IMREAD_COLOR_BGR ); |
326 | |
327 | /** @brief Loads an image from a file. |
328 | |
329 | This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts and the return value. |
330 | @param filename Name of file to be loaded. |
331 | @param dst object in which the image will be loaded. |
332 | @param flags Flag that can take values of cv::ImreadModes |
333 | @note |
334 | The image passing through the img parameter can be pre-allocated. The memory is reused if the shape and the type match with the load image. |
335 | */ |
336 | CV_EXPORTS_W void imread( const String& filename, OutputArray dst, int flags = IMREAD_COLOR_BGR ); |
337 | |
338 | /** @brief Loads a multi-page image from a file. |
339 | |
340 | The function imreadmulti loads a multi-page image from the specified file into a vector of Mat objects. |
341 | @param filename Name of file to be loaded. |
342 | @param mats A vector of Mat objects holding each page. |
343 | @param flags Flag that can take values of cv::ImreadModes, default with cv::IMREAD_ANYCOLOR. |
344 | @sa cv::imread |
345 | */ |
346 | CV_EXPORTS_W bool imreadmulti(const String& filename, CV_OUT std::vector<Mat>& mats, int flags = IMREAD_ANYCOLOR); |
347 | |
348 | /** @brief Loads images of a multi-page image from a file. |
349 | |
350 | The function imreadmulti loads a specified range from a multi-page image from the specified file into a vector of Mat objects. |
351 | @param filename Name of file to be loaded. |
352 | @param mats A vector of Mat objects holding each page. |
353 | @param start Start index of the image to load |
354 | @param count Count number of images to load |
355 | @param flags Flag that can take values of cv::ImreadModes, default with cv::IMREAD_ANYCOLOR. |
356 | @sa cv::imread |
357 | */ |
358 | CV_EXPORTS_W bool imreadmulti(const String& filename, CV_OUT std::vector<Mat>& mats, int start, int count, int flags = IMREAD_ANYCOLOR); |
359 | |
360 | /** @example samples/cpp/tutorial_code/imgcodecs/animations.cpp |
361 | An example to show usage of cv::imreadanimation and cv::imwriteanimation functions. |
362 | Check @ref tutorial_animations "the corresponding tutorial" for more details |
363 | */ |
364 | |
365 | /** @brief Loads frames from an animated image file into an Animation structure. |
366 | |
367 | The function imreadanimation loads frames from an animated image file (e.g., GIF, AVIF, APNG, WEBP) into the provided Animation struct. |
368 | |
369 | @param filename A string containing the path to the file. |
370 | @param animation A reference to an Animation structure where the loaded frames will be stored. It should be initialized before the function is called. |
371 | @param start The index of the first frame to load. This is optional and defaults to 0. |
372 | @param count The number of frames to load. This is optional and defaults to 32767. |
373 | |
374 | @return Returns true if the file was successfully loaded and frames were extracted; returns false otherwise. |
375 | */ |
376 | CV_EXPORTS_W bool imreadanimation(const String& filename, CV_OUT Animation& animation, int start = 0, int count = INT16_MAX); |
377 | |
378 | /** @brief Saves an Animation to a specified file. |
379 | |
380 | The function imwriteanimation saves the provided Animation data to the specified file in an animated format. |
381 | Supported formats depend on the implementation and may include formats like GIF, AVIF, APNG, or WEBP. |
382 | |
383 | @param filename The name of the file where the animation will be saved. The file extension determines the format. |
384 | @param animation A constant reference to an Animation struct containing the frames and metadata to be saved. |
385 | @param params Optional format-specific parameters encoded as pairs (paramId_1, paramValue_1, paramId_2, paramValue_2, ...). |
386 | These parameters are used to specify additional options for the encoding process. Refer to `cv::ImwriteFlags` for details on possible parameters. |
387 | |
388 | @return Returns true if the animation was successfully saved; returns false otherwise. |
389 | */ |
390 | CV_EXPORTS_W bool imwriteanimation(const String& filename, const Animation& animation, const std::vector<int>& params = std::vector<int>()); |
391 | |
392 | /** @brief Returns the number of images inside the given file |
393 | |
394 | 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. |
395 | If the image cannot be decoded, 0 is returned. |
396 | @param filename Name of file to be loaded. |
397 | @param flags Flag that can take values of cv::ImreadModes, default with cv::IMREAD_ANYCOLOR. |
398 | @todo when cv::IMREAD_LOAD_GDAL flag used the return value will be 0 or 1 because OpenCV's GDAL decoder doesn't support multi-page reading yet. |
399 | */ |
400 | CV_EXPORTS_W size_t imcount(const String& filename, int flags = IMREAD_ANYCOLOR); |
401 | |
402 | /** @brief Saves an image to a specified file. |
403 | |
404 | The function imwrite saves the image to the specified file. The image format is chosen based on the |
405 | filename extension (see cv::imread for the list of extensions). In general, only 8-bit unsigned (CV_8U) |
406 | single-channel or 3-channel (with 'BGR' channel order) images |
407 | can be saved using this function, with these exceptions: |
408 | |
409 | - With OpenEXR encoder, only 32-bit float (CV_32F) images can be saved. |
410 | - 8-bit unsigned (CV_8U) images are not supported. |
411 | - With Radiance HDR encoder, non 64-bit float (CV_64F) images can be saved. |
412 | - All images will be converted to 32-bit float (CV_32F). |
413 | - With JPEG 2000 encoder, 8-bit unsigned (CV_8U) and 16-bit unsigned (CV_16U) images can be saved. |
414 | - With JPEG XL encoder, 8-bit unsigned (CV_8U), 16-bit unsigned (CV_16U) and 32-bit float(CV_32F) images can be saved. |
415 | - JPEG XL images with an alpha channel can be saved using this function. |
416 | To do this, create 8-bit (or 16-bit, 32-bit float) 4-channel image BGRA, where the alpha channel goes last. |
417 | Fully transparent pixels should have alpha set to 0, fully opaque pixels should have alpha set to 255/65535/1.0. |
418 | - With PAM encoder, 8-bit unsigned (CV_8U) and 16-bit unsigned (CV_16U) images can be saved. |
419 | - With PNG encoder, 8-bit unsigned (CV_8U) and 16-bit unsigned (CV_16U) images can be saved. |
420 | - PNG images with an alpha channel can be saved using this function. To do this, create |
421 | 8-bit (or 16-bit) 4-channel image BGRA, where the alpha channel goes last. Fully transparent pixels |
422 | should have alpha set to 0, fully opaque pixels should have alpha set to 255/65535 (see the code sample below). |
423 | - With PGM/PPM encoder, 8-bit unsigned (CV_8U) and 16-bit unsigned (CV_16U) images can be saved. |
424 | - With TIFF encoder, 8-bit unsigned (CV_8U), 8-bit signed (CV_8S), |
425 | 16-bit unsigned (CV_16U), 16-bit signed (CV_16S), |
426 | 32-bit signed (CV_32S), |
427 | 32-bit float (CV_32F) and 64-bit float (CV_64F) images can be saved. |
428 | - Multiple images (vector of Mat) can be saved in TIFF format (see the code sample below). |
429 | - 32-bit float 3-channel (CV_32FC3) TIFF images will be saved |
430 | using the LogLuv high dynamic range encoding (4 bytes per pixel) |
431 | |
432 | If the image format is not supported, the image will be converted to 8-bit unsigned (CV_8U) and saved that way. |
433 | |
434 | If the format, depth or channel order is different, use |
435 | Mat::convertTo and cv::cvtColor to convert it before saving. Or, use the universal FileStorage I/O |
436 | functions to save the image to XML or YAML format. |
437 | |
438 | The sample below shows how to create a BGRA image, how to set custom compression parameters and save it to a PNG file. |
439 | It also demonstrates how to save multiple images in a TIFF file: |
440 | @include snippets/imgcodecs_imwrite.cpp |
441 | @param filename Name of the file. |
442 | @param img (Mat or vector of Mat) Image or Images to be saved. |
443 | @param params Format-specific parameters encoded as pairs (paramId_1, paramValue_1, paramId_2, paramValue_2, ... .) see cv::ImwriteFlags |
444 | */ |
445 | CV_EXPORTS_W bool imwrite( const String& filename, InputArray img, |
446 | const std::vector<int>& params = std::vector<int>()); |
447 | |
448 | //! @brief multi-image overload for bindings |
449 | CV_WRAP static inline |
450 | bool imwritemulti(const String& filename, InputArrayOfArrays img, |
451 | const std::vector<int>& params = std::vector<int>()) |
452 | { |
453 | return imwrite(filename, img, params); |
454 | } |
455 | |
456 | /** @brief Reads an image from a buffer in memory. |
457 | |
458 | The function imdecode reads an image from the specified buffer in the memory. If the buffer is too short or |
459 | contains invalid data, the function returns an empty matrix ( Mat::data==NULL ). |
460 | |
461 | See cv::imread for the list of supported formats and flags description. |
462 | |
463 | @note In the case of color images, the decoded images will have the channels stored in **B G R** order. |
464 | @param buf Input array or vector of bytes. |
465 | @param flags The same flags as in cv::imread, see cv::ImreadModes. |
466 | */ |
467 | CV_EXPORTS_W Mat imdecode( InputArray buf, int flags ); |
468 | |
469 | /** @overload |
470 | @param buf Input array or vector of bytes. |
471 | @param flags The same flags as in cv::imread, see cv::ImreadModes. |
472 | @param dst The optional output placeholder for the decoded matrix. It can save the image |
473 | reallocations when the function is called repeatedly for images of the same size. In case of decoder |
474 | failure the function returns empty cv::Mat object, but does not release user-provided dst buffer. |
475 | */ |
476 | CV_EXPORTS Mat imdecode( InputArray buf, int flags, Mat* dst); |
477 | |
478 | /** @brief Reads a multi-page image from a buffer in memory. |
479 | |
480 | The function imdecodemulti reads a multi-page image from the specified buffer in the memory. If the buffer is too short or |
481 | contains invalid data, the function returns false. |
482 | |
483 | See cv::imreadmulti for the list of supported formats and flags description. |
484 | |
485 | @note In the case of color images, the decoded images will have the channels stored in **B G R** order. |
486 | @param buf Input array or vector of bytes. |
487 | @param flags The same flags as in cv::imread, see cv::ImreadModes. |
488 | @param mats A vector of Mat objects holding each page, if more than one. |
489 | @param range A continuous selection of pages. |
490 | */ |
491 | CV_EXPORTS_W bool imdecodemulti(InputArray buf, int flags, CV_OUT std::vector<Mat>& mats, const cv::Range& range = Range::all()); |
492 | |
493 | /** @brief Encodes an image into a memory buffer. |
494 | |
495 | The function imencode compresses the image and stores it in the memory buffer that is resized to fit the |
496 | result. See cv::imwrite for the list of supported formats and flags description. |
497 | |
498 | @param ext File extension that defines the output format. Must include a leading period. |
499 | @param img Image to be compressed. |
500 | @param buf Output buffer resized to fit the compressed image. |
501 | @param params Format-specific parameters. See cv::imwrite and cv::ImwriteFlags. |
502 | */ |
503 | CV_EXPORTS_W bool imencode( const String& ext, InputArray img, |
504 | CV_OUT std::vector<uchar>& buf, |
505 | const std::vector<int>& params = std::vector<int>()); |
506 | |
507 | /** @brief Encodes array of images into a memory buffer. |
508 | |
509 | The function is analog to cv::imencode for in-memory multi-page image compression. |
510 | See cv::imwrite for the list of supported formats and flags description. |
511 | |
512 | @param ext File extension that defines the output format. Must include a leading period. |
513 | @param imgs Vector of images to be written. |
514 | @param buf Output buffer resized to fit the compressed data. |
515 | @param params Format-specific parameters. See cv::imwrite and cv::ImwriteFlags. |
516 | */ |
517 | CV_EXPORTS_W bool imencodemulti( const String& ext, InputArrayOfArrays imgs, |
518 | CV_OUT std::vector<uchar>& buf, |
519 | const std::vector<int>& params = std::vector<int>()); |
520 | |
521 | /** @brief Checks if the specified image file can be decoded by OpenCV. |
522 | |
523 | The function haveImageReader checks if OpenCV is capable of reading the specified file. |
524 | This can be useful for verifying support for a given image format before attempting to load an image. |
525 | |
526 | @param filename The name of the file to be checked. |
527 | @return true if an image reader for the specified file is available and the file can be opened, false otherwise. |
528 | |
529 | @note The function checks the availability of image codecs that are either built into OpenCV or dynamically loaded. |
530 | It does not check for the actual existence of the file but rather the ability to read the specified file type. |
531 | If the file cannot be opened or the format is unsupported, the function will return false. |
532 | |
533 | @sa cv::haveImageWriter, cv::imread, cv::imdecode |
534 | */ |
535 | CV_EXPORTS_W bool haveImageReader( const String& filename ); |
536 | |
537 | /** @brief Checks if the specified image file or specified file extension can be encoded by OpenCV. |
538 | |
539 | The function haveImageWriter checks if OpenCV is capable of writing images with the specified file extension. |
540 | This can be useful for verifying support for a given image format before attempting to save an image. |
541 | |
542 | @param filename The name of the file or the file extension (e.g., ".jpg", ".png"). |
543 | It is recommended to provide the file extension rather than the full file name. |
544 | @return true if an image writer for the specified extension is available, false otherwise. |
545 | |
546 | @note The function checks the availability of image codecs that are either built into OpenCV or dynamically loaded. |
547 | It does not check for the actual existence of the file but rather the ability to write files of the given type. |
548 | |
549 | @sa cv::haveImageReader, cv::imwrite, cv::imencode |
550 | */ |
551 | CV_EXPORTS_W bool haveImageWriter( const String& filename ); |
552 | |
553 | /** @brief To read multi-page images on demand |
554 | |
555 | The ImageCollection class provides iterator API to read multi-page images on demand. Create iterator |
556 | to the collection of the images and iterate over the collection. Decode the necessary page with operator*. |
557 | |
558 | The performance of page decoding is O(1) if collection is increment sequentially. If the user wants to access random page, |
559 | then the time Complexity is O(n) because the collection has to be reinitialized every time in order to go to the correct page. |
560 | However, the intermediate pages are not decoded during the process, so typically it's quite fast. |
561 | This is required because multi-page codecs does not support going backwards. |
562 | After decoding the one page, it is stored inside the collection cache. Hence, trying to get Mat object from already decoded page is O(1). |
563 | If you need memory, you can use .releaseCache() method to release cached index. |
564 | The space complexity is O(n) if all pages are decoded into memory. The user is able to decode and release images on demand. |
565 | */ |
566 | class CV_EXPORTS ImageCollection { |
567 | public: |
568 | struct CV_EXPORTS iterator { |
569 | iterator(ImageCollection* col); |
570 | iterator(ImageCollection* col, int end); |
571 | Mat& operator*(); |
572 | Mat* operator->(); |
573 | iterator& operator++(); |
574 | iterator operator++(int); |
575 | friend bool operator== (const iterator& a, const iterator& b) { return a.m_curr == b.m_curr; } |
576 | friend bool operator!= (const iterator& a, const iterator& b) { return a.m_curr != b.m_curr; } |
577 | |
578 | private: |
579 | ImageCollection* m_pCollection; |
580 | int m_curr; |
581 | }; |
582 | |
583 | ImageCollection(); |
584 | ImageCollection(const String& filename, int flags); |
585 | void init(const String& img, int flags); |
586 | size_t size() const; |
587 | const Mat& at(int index); |
588 | const Mat& operator[](int index); |
589 | void releaseCache(int index); |
590 | iterator begin(); |
591 | iterator end(); |
592 | |
593 | class Impl; |
594 | Ptr<Impl> getImpl(); |
595 | protected: |
596 | Ptr<Impl> pImpl; |
597 | }; |
598 | |
599 | //! @} imgcodecs |
600 | |
601 | } // cv |
602 | |
603 | #endif //OPENCV_IMGCODECS_HPP |
604 | |