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_c C API 52 @defgroup imgcodecs_ios iOS glue 53 @} 54 */ 55 56 //////////////////////////////// image codec //////////////////////////////// 57 namespace cv 58 { 59 60 //! @addtogroup imgcodecs 61 //! @{ 62 63 //! Imread flags 64 enum ImreadModes { 65 IMREAD_UNCHANGED = -1, //!< If set, return the loaded image as is (with alpha channel, otherwise it gets cropped). 66 IMREAD_GRAYSCALE = 0, //!< If set, always convert image to the single channel grayscale image. 67 IMREAD_COLOR = 1, //!< If set, always convert image to the 3 channel BGR color image. 68 IMREAD_ANYDEPTH = 2, //!< If set, return 16-bit/32-bit image when the input has the corresponding depth, otherwise convert it to 8-bit. 69 IMREAD_ANYCOLOR = 4, //!< If set, the image is read in any possible color format. 70 IMREAD_LOAD_GDAL = 8 //!< If set, use the gdal driver for loading the image. 71 }; 72 73 //! Imwrite flags 74 enum ImwriteFlags { 75 IMWRITE_JPEG_QUALITY = 1, //!< For JPEG, it can be a quality from 0 to 100 (the higher is the better). Default value is 95. 76 IMWRITE_JPEG_PROGRESSIVE = 2, //!< Enable JPEG features, 0 or 1, default is False. 77 IMWRITE_JPEG_OPTIMIZE = 3, //!< Enable JPEG features, 0 or 1, default is False. 78 IMWRITE_JPEG_RST_INTERVAL = 4, //!< JPEG restart interval, 0 - 65535, default is 0 - no restart. 79 IMWRITE_JPEG_LUMA_QUALITY = 5, //!< Separate luma quality level, 0 - 100, default is 0 - don't use. 80 IMWRITE_JPEG_CHROMA_QUALITY = 6, //!< Separate chroma quality level, 0 - 100, default is 0 - don't use. 81 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. Default value is 3. 82 IMWRITE_PNG_STRATEGY = 17, //!< One of cv::ImwritePNGFlags, default is IMWRITE_PNG_STRATEGY_DEFAULT. 83 IMWRITE_PNG_BILEVEL = 18, //!< Binary level PNG, 0 or 1, default is 0. 84 IMWRITE_PXM_BINARY = 32, //!< For PPM, PGM, or PBM, it can be a binary format flag, 0 or 1. Default value is 1. 85 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. 86 }; 87 88 //! Imwrite PNG specific flags 89 enum ImwritePNGFlags { 90 IMWRITE_PNG_STRATEGY_DEFAULT = 0, 91 IMWRITE_PNG_STRATEGY_FILTERED = 1, 92 IMWRITE_PNG_STRATEGY_HUFFMAN_ONLY = 2, 93 IMWRITE_PNG_STRATEGY_RLE = 3, 94 IMWRITE_PNG_STRATEGY_FIXED = 4 95 }; 96 97 /** @brief Loads an image from a file. 98 99 @anchor imread 100 101 @param filename Name of file to be loaded. 102 @param flags Flag that can take values of @ref cv::ImreadModes 103 104 The function imread loads an image from the specified file and returns it. If the image cannot be 105 read (because of missing file, improper permissions, unsupported or invalid format), the function 106 returns an empty matrix ( Mat::data==NULL ). Currently, the following file formats are supported: 107 108 - Windows bitmaps - \*.bmp, \*.dib (always supported) 109 - JPEG files - \*.jpeg, \*.jpg, \*.jpe (see the *Notes* section) 110 - JPEG 2000 files - \*.jp2 (see the *Notes* section) 111 - Portable Network Graphics - \*.png (see the *Notes* section) 112 - WebP - \*.webp (see the *Notes* section) 113 - Portable image format - \*.pbm, \*.pgm, \*.ppm (always supported) 114 - Sun rasters - \*.sr, \*.ras (always supported) 115 - TIFF files - \*.tiff, \*.tif (see the *Notes* section) 116 117 @note 118 119 - The function determines the type of an image by the content, not by the file extension. 120 - On Microsoft Windows\* OS and MacOSX\*, the codecs shipped with an OpenCV image (libjpeg, 121 libpng, libtiff, and libjasper) are used by default. So, OpenCV can always read JPEGs, PNGs, 122 and TIFFs. On MacOSX, there is also an option to use native MacOSX image readers. But beware 123 that currently these native image loaders give images with different pixel values because of 124 the color management embedded into MacOSX. 125 - On Linux\*, BSD flavors and other Unix-like open-source operating systems, OpenCV looks for 126 codecs supplied with an OS image. Install the relevant packages (do not forget the development 127 files, for example, "libjpeg-dev", in Debian\* and Ubuntu\*) to get the codec support or turn 128 on the OPENCV_BUILD_3RDPARTY_LIBS flag in CMake. 129 130 @note In the case of color images, the decoded images will have the channels stored in B G R order. 131 */ 132 CV_EXPORTS_W Mat imread( const String& filename, int flags = IMREAD_COLOR ); 133 134 /** @brief Loads a multi-page image from a file. (see imread for details.) 135 136 @param filename Name of file to be loaded. 137 @param flags Flag that can take values of @ref cv::ImreadModes, default with IMREAD_ANYCOLOR. 138 @param mats A vector of Mat objects holding each page, if more than one. 139 140 */ 141 CV_EXPORTS_W bool imreadmulti(const String& filename, std::vector<Mat>& mats, int flags = IMREAD_ANYCOLOR); 142 143 /** @brief Saves an image to a specified file. 144 145 @param filename Name of the file. 146 @param img Image to be saved. 147 @param params Format-specific save parameters encoded as pairs, see @ref cv::ImwriteFlags 148 paramId_1, paramValue_1, paramId_2, paramValue_2, ... . 149 150 The function imwrite saves the image to the specified file. The image format is chosen based on the 151 filename extension (see imread for the list of extensions). Only 8-bit (or 16-bit unsigned (CV_16U) 152 in case of PNG, JPEG 2000, and TIFF) single-channel or 3-channel (with 'BGR' channel order) images 153 can be saved using this function. If the format, depth or channel order is different, use 154 Mat::convertTo , and cvtColor to convert it before saving. Or, use the universal FileStorage I/O 155 functions to save the image to XML or YAML format. 156 157 It is possible to store PNG images with an alpha channel using this function. To do this, create 158 8-bit (or 16-bit) 4-channel image BGRA, where the alpha channel goes last. Fully transparent pixels 159 should have alpha set to 0, fully opaque pixels should have alpha set to 255/65535. The sample below 160 shows how to create such a BGRA image and store to PNG file. It also demonstrates how to set custom 161 compression parameters : 162 @code 163 #include <vector> 164 #include <stdio.h> 165 #include <opencv2/opencv.hpp> 166 167 using namespace cv; 168 using namespace std; 169 170 void createAlphaMat(Mat &mat) 171 { 172 CV_Assert(mat.channels() == 4); 173 for (int i = 0; i < mat.rows; ++i) { 174 for (int j = 0; j < mat.cols; ++j) { 175 Vec4b& bgra = mat.at<Vec4b>(i, j); 176 bgra[0] = UCHAR_MAX; // Blue 177 bgra[1] = saturate_cast<uchar>((float (mat.cols - j)) / ((float)mat.cols) * UCHAR_MAX); // Green 178 bgra[2] = saturate_cast<uchar>((float (mat.rows - i)) / ((float)mat.rows) * UCHAR_MAX); // Red 179 bgra[3] = saturate_cast<uchar>(0.5 * (bgra[1] + bgra[2])); // Alpha 180 } 181 } 182 } 183 184 int main(int argv, char **argc) 185 { 186 // Create mat with alpha channel 187 Mat mat(480, 640, CV_8UC4); 188 createAlphaMat(mat); 189 190 vector<int> compression_params; 191 compression_params.push_back(IMWRITE_PNG_COMPRESSION); 192 compression_params.push_back(9); 193 194 try { 195 imwrite("alpha.png", mat, compression_params); 196 } 197 catch (runtime_error& ex) { 198 fprintf(stderr, "Exception converting image to PNG format: %s\n", ex.what()); 199 return 1; 200 } 201 202 fprintf(stdout, "Saved PNG file with alpha data.\n"); 203 return 0; 204 } 205 @endcode 206 */ 207 CV_EXPORTS_W bool imwrite( const String& filename, InputArray img, 208 const std::vector<int>& params = std::vector<int>()); 209 210 /** @overload */ 211 CV_EXPORTS_W Mat imdecode( InputArray buf, int flags ); 212 213 /** @brief Reads an image from a buffer in memory. 214 215 @param buf Input array or vector of bytes. 216 @param flags The same flags as in imread, see @ref cv::ImreadModes. 217 @param dst The optional output placeholder for the decoded matrix. It can save the image 218 reallocations when the function is called repeatedly for images of the same size. 219 220 The function reads an image from the specified buffer in the memory. If the buffer is too short or 221 contains invalid data, the empty matrix/image is returned. 222 223 See imread for the list of supported formats and flags description. 224 225 @note In the case of color images, the decoded images will have the channels stored in B G R order. 226 */ 227 CV_EXPORTS Mat imdecode( InputArray buf, int flags, Mat* dst); 228 229 /** @brief Encodes an image into a memory buffer. 230 231 @param ext File extension that defines the output format. 232 @param img Image to be written. 233 @param buf Output buffer resized to fit the compressed image. 234 @param params Format-specific parameters. See imwrite and @ref cv::ImwriteFlags. 235 236 The function compresses the image and stores it in the memory buffer that is resized to fit the 237 result. See imwrite for the list of supported formats and flags description. 238 239 @note cvEncodeImage returns single-row matrix of type CV_8UC1 that contains encoded image as array 240 of bytes. 241 */ 242 CV_EXPORTS_W bool imencode( const String& ext, InputArray img, 243 CV_OUT std::vector<uchar>& buf, 244 const std::vector<int>& params = std::vector<int>()); 245 246 //! @} imgcodecs 247 248 } // cv 249 250 #endif //__OPENCV_IMGCODECS_HPP__ 251