imgcodecs.hpp

00001 /*M///////////////////////////////////////////////////////////////////////////////////////
00002 //
00003 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
00004 //
00005 //  By downloading, copying, installing or using the software you agree to this license.
00006 //  If you do not agree to this license, do not download, install,
00007 //  copy or use the software.
00008 //
00009 //
00010 //                          License Agreement
00011 //                For Open Source Computer Vision Library
00012 //
00013 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
00014 // Copyright (C) 2009, Willow Garage Inc., all rights reserved.
00015 // Third party copyrights are property of their respective owners.
00016 //
00017 // Redistribution and use in source and binary forms, with or without modification,
00018 // are permitted provided that the following conditions are met:
00019 //
00020 //   * Redistribution's of source code must retain the above copyright notice,
00021 //     this list of conditions and the following disclaimer.
00022 //
00023 //   * Redistribution's in binary form must reproduce the above copyright notice,
00024 //     this list of conditions and the following disclaimer in the documentation
00025 //     and/or other materials provided with the distribution.
00026 //
00027 //   * The name of the copyright holders may not be used to endorse or promote products
00028 //     derived from this software without specific prior written permission.
00029 //
00030 // This software is provided by the copyright holders and contributors "as is" and
00031 // any express or implied warranties, including, but not limited to, the implied
00032 // warranties of merchantability and fitness for a particular purpose are disclaimed.
00033 // In no event shall the Intel Corporation or contributors be liable for any direct,
00034 // indirect, incidental, special, exemplary, or consequential damages
00035 // (including, but not limited to, procurement of substitute goods or services;
00036 // loss of use, data, or profits; or business interruption) however caused
00037 // and on any theory of liability, whether in contract, strict liability,
00038 // or tort (including negligence or otherwise) arising in any way out of
00039 // the use of this software, even if advised of the possibility of such damage.
00040 //
00041 //M*/
00042 
00043 #ifndef __OPENCV_IMGCODECS_HPP__
00044 #define __OPENCV_IMGCODECS_HPP__
00045 
00046 #include "opencv2/core.hpp"
00047 
00048 /**
00049   @defgroup imgcodecs Image file reading and writing
00050   @{
00051     @defgroup imgcodecs_c C API
00052     @defgroup imgcodecs_ios iOS glue
00053   @}
00054 */
00055 
00056 //////////////////////////////// image codec ////////////////////////////////
00057 namespace cv
00058 {
00059 
00060 //! @addtogroup imgcodecs
00061 //! @{
00062 
00063 //! Imread flags
00064 enum ImreadModes {
00065        IMREAD_UNCHANGED            = -1, //!< If set, return the loaded image as is (with alpha channel, otherwise it gets cropped).
00066        IMREAD_GRAYSCALE            = 0,  //!< If set, always convert image to the single channel grayscale image.
00067        IMREAD_COLOR                = 1,  //!< If set, always convert image to the 3 channel BGR color image.
00068        IMREAD_ANYDEPTH             = 2,  //!< If set, return 16-bit/32-bit image when the input has the corresponding depth, otherwise convert it to 8-bit.
00069        IMREAD_ANYCOLOR             = 4,  //!< If set, the image is read in any possible color format.
00070        IMREAD_LOAD_GDAL            = 8,  //!< If set, use the gdal driver for loading the image.
00071        IMREAD_REDUCED_GRAYSCALE_2  = 16, //!< If set, always convert image to the single channel grayscale image and the image size reduced 1/2.
00072        IMREAD_REDUCED_COLOR_2      = 17, //!< If set, always convert image to the 3 channel BGR color image and the image size reduced 1/2.
00073        IMREAD_REDUCED_GRAYSCALE_4  = 32, //!< If set, always convert image to the single channel grayscale image and the image size reduced 1/4.
00074        IMREAD_REDUCED_COLOR_4      = 33, //!< If set, always convert image to the 3 channel BGR color image and the image size reduced 1/4.
00075        IMREAD_REDUCED_GRAYSCALE_8  = 64, //!< If set, always convert image to the single channel grayscale image and the image size reduced 1/8.
00076        IMREAD_REDUCED_COLOR_8      = 65  //!< If set, always convert image to the 3 channel BGR color image and the image size reduced 1/8.
00077      };
00078 
00079 //! Imwrite flags
00080 enum ImwriteFlags {
00081        IMWRITE_JPEG_QUALITY        = 1,  //!< For JPEG, it can be a quality from 0 to 100 (the higher is the better). Default value is 95.
00082        IMWRITE_JPEG_PROGRESSIVE    = 2,  //!< Enable JPEG features, 0 or 1, default is False.
00083        IMWRITE_JPEG_OPTIMIZE       = 3,  //!< Enable JPEG features, 0 or 1, default is False.
00084        IMWRITE_JPEG_RST_INTERVAL   = 4,  //!< JPEG restart interval, 0 - 65535, default is 0 - no restart.
00085        IMWRITE_JPEG_LUMA_QUALITY   = 5,  //!< Separate luma quality level, 0 - 100, default is 0 - don't use.
00086        IMWRITE_JPEG_CHROMA_QUALITY = 6,  //!< Separate chroma quality level, 0 - 100, default is 0 - don't use.
00087        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.
00088        IMWRITE_PNG_STRATEGY        = 17, //!< One of cv::ImwritePNGFlags, default is IMWRITE_PNG_STRATEGY_DEFAULT.
00089        IMWRITE_PNG_BILEVEL         = 18, //!< Binary level PNG, 0 or 1, default is 0.
00090        IMWRITE_PXM_BINARY          = 32, //!< For PPM, PGM, or PBM, it can be a binary format flag, 0 or 1. Default value is 1.
00091        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.
00092      };
00093 
00094 //! Imwrite PNG specific flags used to tune the compression algorithm.
00095 /** These flags will be modify the way of PNG image compression and will be passed to the underlying zlib processing stage.
00096 
00097 -   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.
00098 -   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.
00099 -   The strategy parameter only affects the compression ratio but not the correctness of the compressed output even if it is not set appropriately.
00100 -   IMWRITE_PNG_STRATEGY_FIXED prevents the use of dynamic Huffman codes, allowing for a simpler decoder for special applications.
00101 */
00102 enum ImwritePNGFlags {
00103        IMWRITE_PNG_STRATEGY_DEFAULT      = 0, //!< Use this value for normal data.
00104        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.
00105        IMWRITE_PNG_STRATEGY_HUFFMAN_ONLY = 2, //!< Use this value to force Huffman encoding only (no string match).
00106        IMWRITE_PNG_STRATEGY_RLE          = 3, //!< Use this value to limit match distances to one (run-length encoding).
00107        IMWRITE_PNG_STRATEGY_FIXED        = 4  //!< Using this value prevents the use of dynamic Huffman codes, allowing for a simpler decoder for special applications.
00108      };
00109 
00110 /** @brief Loads an image from a file.
00111 
00112 @anchor imread
00113 
00114 The function imread loads an image from the specified file and returns it. If the image cannot be
00115 read (because of missing file, improper permissions, unsupported or invalid format), the function
00116 returns an empty matrix ( Mat::data==NULL ).
00117 
00118 Currently, the following file formats are supported:
00119 
00120 -   Windows bitmaps - \*.bmp, \*.dib (always supported)
00121 -   JPEG files - \*.jpeg, \*.jpg, \*.jpe (see the *Notes* section)
00122 -   JPEG 2000 files - \*.jp2 (see the *Notes* section)
00123 -   Portable Network Graphics - \*.png (see the *Notes* section)
00124 -   WebP - \*.webp (see the *Notes* section)
00125 -   Portable image format - \*.pbm, \*.pgm, \*.ppm \*.pxm, \*.pnm (always supported)
00126 -   Sun rasters - \*.sr, \*.ras (always supported)
00127 -   TIFF files - \*.tiff, \*.tif (see the *Notes* section)
00128 -   OpenEXR Image files - \*.exr (see the *Notes* section)
00129 -   Radiance HDR - \*.hdr, \*.pic (always supported)
00130 -   Raster and Vector geospatial data supported by Gdal (see the *Notes* section)
00131 
00132 @note
00133 
00134 -   The function determines the type of an image by the content, not by the file extension.
00135 -   In the case of color images, the decoded images will have the channels stored in **B G R** order.
00136 -   On Microsoft Windows\* OS and MacOSX\*, the codecs shipped with an OpenCV image (libjpeg,
00137     libpng, libtiff, and libjasper) are used by default. So, OpenCV can always read JPEGs, PNGs,
00138     and TIFFs. On MacOSX, there is also an option to use native MacOSX image readers. But beware
00139     that currently these native image loaders give images with different pixel values because of
00140     the color management embedded into MacOSX.
00141 -   On Linux\*, BSD flavors and other Unix-like open-source operating systems, OpenCV looks for
00142     codecs supplied with an OS image. Install the relevant packages (do not forget the development
00143     files, for example, "libjpeg-dev", in Debian\* and Ubuntu\*) to get the codec support or turn
00144     on the OPENCV_BUILD_3RDPARTY_LIBS flag in CMake.
00145 -   In the case you set *WITH_GDAL* flag to true in CMake and @ref IMREAD_LOAD_GDAL to load the image,
00146     then [GDAL](http://www.gdal.org) driver will be used in order to decode the image by supporting
00147     the following formats: [Raster](http://www.gdal.org/formats_list.html),
00148     [Vector](http://www.gdal.org/ogr_formats.html).
00149 @param filename Name of file to be loaded.
00150 @param flags Flag that can take values of cv::ImreadModes
00151 */
00152 CV_EXPORTS_W Mat imread( const String& filename, int flags = IMREAD_COLOR );
00153 
00154 /** @brief Loads a multi-page image from a file.
00155 
00156 The function imreadmulti loads a multi-page image from the specified file into a vector of Mat objects.
00157 @param filename Name of file to be loaded.
00158 @param flags Flag that can take values of cv::ImreadModes, default with cv::IMREAD_ANYCOLOR.
00159 @param mats A vector of Mat objects holding each page, if more than one.
00160 @sa cv::imread
00161 */
00162 CV_EXPORTS_W bool imreadmulti(const String& filename, std::vector<Mat>& mats, int flags = IMREAD_ANYCOLOR);
00163 
00164 /** @brief Saves an image to a specified file.
00165 
00166 The function imwrite saves the image to the specified file. The image format is chosen based on the
00167 filename extension (see cv::imread for the list of extensions). Only 8-bit (or 16-bit unsigned (CV_16U)
00168 in case of PNG, JPEG 2000, and TIFF) single-channel or 3-channel (with 'BGR' channel order) images
00169 can be saved using this function. If the format, depth or channel order is different, use
00170 Mat::convertTo , and cv::cvtColor to convert it before saving. Or, use the universal FileStorage I/O
00171 functions to save the image to XML or YAML format.
00172 
00173 It is possible to store PNG images with an alpha channel using this function. To do this, create
00174 8-bit (or 16-bit) 4-channel image BGRA, where the alpha channel goes last. Fully transparent pixels
00175 should have alpha set to 0, fully opaque pixels should have alpha set to 255/65535.
00176 
00177 The sample below shows how to create such a BGRA image and store to PNG file. It also demonstrates how to set custom
00178 compression parameters :
00179 @code
00180     #include <opencv2/opencv.hpp>
00181 
00182     using namespace cv;
00183     using namespace std;
00184 
00185     void createAlphaMat(Mat &mat)
00186     {
00187         CV_Assert(mat.channels() == 4);
00188         for (int i = 0; i < mat.rows; ++i) {
00189             for (int j = 0; j < mat.cols; ++j) {
00190                 Vec4b& bgra = mat.at<Vec4b>(i, j);
00191                 bgra[0] = UCHAR_MAX; // Blue
00192                 bgra[1] = saturate_cast<uchar>((float (mat.cols - j)) / ((float)mat.cols) * UCHAR_MAX); // Green
00193                 bgra[2] = saturate_cast<uchar>((float (mat.rows - i)) / ((float)mat.rows) * UCHAR_MAX); // Red
00194                 bgra[3] = saturate_cast<uchar>(0.5 * (bgra[1] + bgra[2])); // Alpha
00195             }
00196         }
00197     }
00198 
00199     int main(int argv, char **argc)
00200     {
00201         // Create mat with alpha channel
00202         Mat mat(480, 640, CV_8UC4);
00203         createAlphaMat(mat);
00204 
00205         vector<int> compression_params;
00206         compression_params.push_back(IMWRITE_PNG_COMPRESSION);
00207         compression_params.push_back(9);
00208 
00209         try {
00210             imwrite("alpha.png", mat, compression_params);
00211         }
00212         catch (cv::Exception& ex) {
00213             fprintf(stderr, "Exception converting image to PNG format: %s\n", ex.what());
00214             return 1;
00215         }
00216 
00217         fprintf(stdout, "Saved PNG file with alpha data.\n");
00218         return 0;
00219     }
00220 @endcode
00221 @param filename Name of the file.
00222 @param img Image to be saved.
00223 @param params Format-specific parameters encoded as pairs (paramId_1, paramValue_1, paramId_2, paramValue_2, ... .) see cv::ImwriteFlags
00224 */
00225 CV_EXPORTS_W bool imwrite( const String& filename, InputArray img,
00226               const std::vector<int>& params = std::vector<int>());
00227 
00228 /** @brief Reads an image from a buffer in memory.
00229 
00230 The function imdecode reads an image from the specified buffer in the memory. If the buffer is too short or
00231 contains invalid data, the function returns an empty matrix ( Mat::data==NULL ).
00232 
00233 See cv::imread for the list of supported formats and flags description.
00234 
00235 @note In the case of color images, the decoded images will have the channels stored in **B G R** order.
00236 @param buf Input array or vector of bytes.
00237 @param flags The same flags as in cv::imread, see cv::ImreadModes.
00238 */
00239 CV_EXPORTS_W Mat imdecode( InputArray buf, int flags );
00240 
00241 /** @overload
00242 @param buf
00243 @param flags
00244 @param dst The optional output placeholder for the decoded matrix. It can save the image
00245 reallocations when the function is called repeatedly for images of the same size.
00246 */
00247 CV_EXPORTS Mat imdecode( InputArray buf, int flags, Mat* dst);
00248 
00249 /** @brief Encodes an image into a memory buffer.
00250 
00251 The function imencode compresses the image and stores it in the memory buffer that is resized to fit the
00252 result. See cv::imwrite for the list of supported formats and flags description.
00253 
00254 @param ext File extension that defines the output format.
00255 @param img Image to be written.
00256 @param buf Output buffer resized to fit the compressed image.
00257 @param params Format-specific parameters. See cv::imwrite and cv::ImwriteFlags.
00258 */
00259 CV_EXPORTS_W bool imencode( const String& ext, InputArray img,
00260                             CV_OUT std::vector<uchar>& buf,
00261                             const std::vector<int>& params = std::vector<int>());
00262 
00263 //! @} imgcodecs
00264 
00265 } // cv
00266 
00267 #endif //__OPENCV_IMGCODECS_HPP__
00268