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        IMREAD_IGNORE_ORIENTATION   = 128 //!< If set, do not rotate the image according to EXIF's orientation flag.
00078      };
00079 
00080 //! Imwrite flags
00081 enum ImwriteFlags {
00082        IMWRITE_JPEG_QUALITY        = 1,  //!< For JPEG, it can be a quality from 0 to 100 (the higher is the better). Default value is 95.
00083        IMWRITE_JPEG_PROGRESSIVE    = 2,  //!< Enable JPEG features, 0 or 1, default is False.
00084        IMWRITE_JPEG_OPTIMIZE       = 3,  //!< Enable JPEG features, 0 or 1, default is False.
00085        IMWRITE_JPEG_RST_INTERVAL   = 4,  //!< JPEG restart interval, 0 - 65535, default is 0 - no restart.
00086        IMWRITE_JPEG_LUMA_QUALITY   = 5,  //!< Separate luma quality level, 0 - 100, default is 0 - don't use.
00087        IMWRITE_JPEG_CHROMA_QUALITY = 6,  //!< Separate chroma quality level, 0 - 100, default is 0 - don't use.
00088        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. Also strategy is changed to IMWRITE_PNG_STRATEGY_DEFAULT (Z_DEFAULT_STRATEGY).
00089        IMWRITE_PNG_STRATEGY        = 17, //!< One of cv::ImwritePNGFlags, default is IMWRITE_PNG_STRATEGY_DEFAULT.
00090        IMWRITE_PNG_BILEVEL         = 18, //!< Binary level PNG, 0 or 1, default is 0.
00091        IMWRITE_PXM_BINARY          = 32, //!< For PPM, PGM, or PBM, it can be a binary format flag, 0 or 1. Default value is 1.
00092        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.
00093        IMWRITE_PAM_TUPLETYPE       = 128,//!< For PAM, sets the TUPLETYPE field to the corresponding string value that is defined for the format
00094      };
00095 
00096 //! Imwrite PNG specific flags used to tune the compression algorithm.
00097 /** These flags will be modify the way of PNG image compression and will be passed to the underlying zlib processing stage.
00098 
00099 -   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.
00100 -   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.
00101 -   The strategy parameter only affects the compression ratio but not the correctness of the compressed output even if it is not set appropriately.
00102 -   IMWRITE_PNG_STRATEGY_FIXED prevents the use of dynamic Huffman codes, allowing for a simpler decoder for special applications.
00103 */
00104 enum ImwritePNGFlags {
00105        IMWRITE_PNG_STRATEGY_DEFAULT      = 0, //!< Use this value for normal data.
00106        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.
00107        IMWRITE_PNG_STRATEGY_HUFFMAN_ONLY = 2, //!< Use this value to force Huffman encoding only (no string match).
00108        IMWRITE_PNG_STRATEGY_RLE          = 3, //!< Use this value to limit match distances to one (run-length encoding).
00109        IMWRITE_PNG_STRATEGY_FIXED        = 4  //!< Using this value prevents the use of dynamic Huffman codes, allowing for a simpler decoder for special applications.
00110      };
00111 
00112 //! Imwrite PAM specific tupletype flags used to define the 'TUPETYPE' field of a PAM file.
00113 enum ImwritePAMFlags {
00114        IMWRITE_PAM_FORMAT_NULL = 0,
00115        IMWRITE_PAM_FORMAT_BLACKANDWHITE = 1,
00116        IMWRITE_PAM_FORMAT_GRAYSCALE = 2,
00117        IMWRITE_PAM_FORMAT_GRAYSCALE_ALPHA = 3,
00118        IMWRITE_PAM_FORMAT_RGB = 4,
00119        IMWRITE_PAM_FORMAT_RGB_ALPHA = 5,
00120      };
00121 
00122 /** @brief Loads an image from a file.
00123 
00124 @anchor imread
00125 
00126 The function imread loads an image from the specified file and returns it. If the image cannot be
00127 read (because of missing file, improper permissions, unsupported or invalid format), the function
00128 returns an empty matrix ( Mat::data==NULL ).
00129 
00130 Currently, the following file formats are supported:
00131 
00132 -   Windows bitmaps - \*.bmp, \*.dib (always supported)
00133 -   JPEG files - \*.jpeg, \*.jpg, \*.jpe (see the *Notes* section)
00134 -   JPEG 2000 files - \*.jp2 (see the *Notes* section)
00135 -   Portable Network Graphics - \*.png (see the *Notes* section)
00136 -   WebP - \*.webp (see the *Notes* section)
00137 -   Portable image format - \*.pbm, \*.pgm, \*.ppm \*.pxm, \*.pnm (always supported)
00138 -   Sun rasters - \*.sr, \*.ras (always supported)
00139 -   TIFF files - \*.tiff, \*.tif (see the *Notes* section)
00140 -   OpenEXR Image files - \*.exr (see the *Notes* section)
00141 -   Radiance HDR - \*.hdr, \*.pic (always supported)
00142 -   Raster and Vector geospatial data supported by Gdal (see the *Notes* section)
00143 
00144 @note
00145 
00146 -   The function determines the type of an image by the content, not by the file extension.
00147 -   In the case of color images, the decoded images will have the channels stored in **B G R** order.
00148 -   On Microsoft Windows\* OS and MacOSX\*, the codecs shipped with an OpenCV image (libjpeg,
00149     libpng, libtiff, and libjasper) are used by default. So, OpenCV can always read JPEGs, PNGs,
00150     and TIFFs. On MacOSX, there is also an option to use native MacOSX image readers. But beware
00151     that currently these native image loaders give images with different pixel values because of
00152     the color management embedded into MacOSX.
00153 -   On Linux\*, BSD flavors and other Unix-like open-source operating systems, OpenCV looks for
00154     codecs supplied with an OS image. Install the relevant packages (do not forget the development
00155     files, for example, "libjpeg-dev", in Debian\* and Ubuntu\*) to get the codec support or turn
00156     on the OPENCV_BUILD_3RDPARTY_LIBS flag in CMake.
00157 -   In the case you set *WITH_GDAL* flag to true in CMake and @ref IMREAD_LOAD_GDAL to load the image,
00158     then [GDAL](http://www.gdal.org) driver will be used in order to decode the image by supporting
00159     the following formats: [Raster](http://www.gdal.org/formats_list.html),
00160     [Vector](http://www.gdal.org/ogr_formats.html).
00161 -   If EXIF information are embedded in the image file, the EXIF orientation will be taken into account
00162     and thus the image will be rotated accordingly except if the flag @ref IMREAD_IGNORE_ORIENTATION is passed.
00163 @param filename Name of file to be loaded.
00164 @param flags Flag that can take values of cv::ImreadModes
00165 */
00166 CV_EXPORTS_W Mat imread( const String& filename, int flags = IMREAD_COLOR );
00167 
00168 /** @brief Loads a multi-page image from a file.
00169 
00170 The function imreadmulti loads a multi-page image from the specified file into a vector of Mat objects.
00171 @param filename Name of file to be loaded.
00172 @param flags Flag that can take values of cv::ImreadModes, default with cv::IMREAD_ANYCOLOR.
00173 @param mats A vector of Mat objects holding each page, if more than one.
00174 @sa cv::imread
00175 */
00176 CV_EXPORTS_W bool imreadmulti(const String& filename, std::vector<Mat>& mats, int flags = IMREAD_ANYCOLOR);
00177 
00178 /** @brief Saves an image to a specified file.
00179 
00180 The function imwrite saves the image to the specified file. The image format is chosen based on the
00181 filename extension (see cv::imread for the list of extensions). Only 8-bit (or 16-bit unsigned (CV_16U)
00182 in case of PNG, JPEG 2000, and TIFF) single-channel or 3-channel (with 'BGR' channel order) images
00183 can be saved using this function. If the format, depth or channel order is different, use
00184 Mat::convertTo , and cv::cvtColor to convert it before saving. Or, use the universal FileStorage I/O
00185 functions to save the image to XML or YAML format.
00186 
00187 It is possible to store PNG images with an alpha channel using this function. To do this, create
00188 8-bit (or 16-bit) 4-channel image BGRA, where the alpha channel goes last. Fully transparent pixels
00189 should have alpha set to 0, fully opaque pixels should have alpha set to 255/65535.
00190 
00191 The sample below shows how to create such a BGRA image and store to PNG file. It also demonstrates how to set custom
00192 compression parameters :
00193 @code
00194     #include <opencv2/opencv.hpp>
00195 
00196     using namespace cv;
00197     using namespace std;
00198 
00199     void createAlphaMat(Mat &mat)
00200     {
00201         CV_Assert(mat.channels() == 4);
00202         for (int i = 0; i < mat.rows; ++i) {
00203             for (int j = 0; j < mat.cols; ++j) {
00204                 Vec4b& bgra = mat.at<Vec4b>(i, j);
00205                 bgra[0] = UCHAR_MAX; // Blue
00206                 bgra[1] = saturate_cast<uchar>((float (mat.cols - j)) / ((float)mat.cols) * UCHAR_MAX); // Green
00207                 bgra[2] = saturate_cast<uchar>((float (mat.rows - i)) / ((float)mat.rows) * UCHAR_MAX); // Red
00208                 bgra[3] = saturate_cast<uchar>(0.5 * (bgra[1] + bgra[2])); // Alpha
00209             }
00210         }
00211     }
00212 
00213     int main(int argv, char **argc)
00214     {
00215         // Create mat with alpha channel
00216         Mat mat(480, 640, CV_8UC4);
00217         createAlphaMat(mat);
00218 
00219         vector<int> compression_params;
00220         compression_params.push_back(IMWRITE_PNG_COMPRESSION);
00221         compression_params.push_back(9);
00222 
00223         try {
00224             imwrite("alpha.png", mat, compression_params);
00225         }
00226         catch (cv::Exception& ex) {
00227             fprintf(stderr, "Exception converting image to PNG format: %s\n", ex.what());
00228             return 1;
00229         }
00230 
00231         fprintf(stdout, "Saved PNG file with alpha data.\n");
00232         return 0;
00233     }
00234 @endcode
00235 @param filename Name of the file.
00236 @param img Image to be saved.
00237 @param params Format-specific parameters encoded as pairs (paramId_1, paramValue_1, paramId_2, paramValue_2, ... .) see cv::ImwriteFlags
00238 */
00239 CV_EXPORTS_W bool imwrite( const String& filename, InputArray img,
00240               const std::vector<int>& params = std::vector<int>());
00241 
00242 /** @brief Reads an image from a buffer in memory.
00243 
00244 The function imdecode reads an image from the specified buffer in the memory. If the buffer is too short or
00245 contains invalid data, the function returns an empty matrix ( Mat::data==NULL ).
00246 
00247 See cv::imread for the list of supported formats and flags description.
00248 
00249 @note In the case of color images, the decoded images will have the channels stored in **B G R** order.
00250 @param buf Input array or vector of bytes.
00251 @param flags The same flags as in cv::imread, see cv::ImreadModes.
00252 */
00253 CV_EXPORTS_W Mat imdecode( InputArray buf, int flags );
00254 
00255 /** @overload
00256 @param buf
00257 @param flags
00258 @param dst The optional output placeholder for the decoded matrix. It can save the image
00259 reallocations when the function is called repeatedly for images of the same size.
00260 */
00261 CV_EXPORTS Mat imdecode( InputArray buf, int flags, Mat* dst);
00262 
00263 /** @brief Encodes an image into a memory buffer.
00264 
00265 The function imencode compresses the image and stores it in the memory buffer that is resized to fit the
00266 result. See cv::imwrite for the list of supported formats and flags description.
00267 
00268 @param ext File extension that defines the output format.
00269 @param img Image to be written.
00270 @param buf Output buffer resized to fit the compressed image.
00271 @param params Format-specific parameters. See cv::imwrite and cv::ImwriteFlags.
00272 */
00273 CV_EXPORTS_W bool imencode( const String& ext, InputArray img,
00274                             CV_OUT std::vector<uchar>& buf,
00275                             const std::vector<int>& params = std::vector<int>());
00276 
00277 //! @} imgcodecs
00278 
00279 } // cv
00280 
00281 #endif //OPENCV_IMGCODECS_HPP