2012-04-30 22:33:52 +08:00
/*M///////////////////////////////////////////////////////////////////////////////////////
//
// IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
//
// By downloading, copying, installing or using the software you agree to this license.
// If you do not agree to this license, do not download, install,
// copy or use the software.
//
//
// License Agreement
// For Open Source Computer Vision Library
//
// Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
// Copyright (C) 2009, Willow Garage Inc., all rights reserved.
// Third party copyrights are property of their respective owners.
//
// Redistribution and use in source and binary forms, with or without modification,
// are permitted provided that the following conditions are met:
//
// * Redistribution's of source code must retain the above copyright notice,
// this list of conditions and the following disclaimer.
//
// * Redistribution's in binary form must reproduce the above copyright notice,
// this list of conditions and the following disclaimer in the documentation
// and/or other materials provided with the distribution.
//
// * The name of the copyright holders may not be used to endorse or promote products
// derived from this software without specific prior written permission.
//
// This software is provided by the copyright holders and contributors "as is" and
// any express or implied warranties, including, but not limited to, the implied
// warranties of merchantability and fitness for a particular purpose are disclaimed.
// In no event shall the Intel Corporation or contributors be liable for any direct,
// indirect, incidental, special, exemplary, or consequential damages
// (including, but not limited to, procurement of substitute goods or services;
// loss of use, data, or profits; or business interruption) however caused
// and on any theory of liability, whether in contract, strict liability,
// or tort (including negligence or otherwise) arising in any way out of
// the use of this software, even if advised of the possibility of such damage.
//
//M*/
2016-09-30 17:46:29 +08:00
# ifndef OPENCV_IMGCODECS_HPP
# define OPENCV_IMGCODECS_HPP
2012-04-30 22:33:52 +08:00
2014-07-04 22:48:15 +08:00
# include "opencv2/core.hpp"
2010-05-12 01:44:00 +08:00
2014-11-19 16:29:31 +08:00
/**
@ defgroup imgcodecs Image file reading and writing
@ {
@ defgroup imgcodecs_c C API
2020-10-28 09:51:12 +08:00
@ defgroup imgcodecs_flags Flags used for image file reading and writing
2014-11-19 16:29:31 +08:00
@ defgroup imgcodecs_ios iOS glue
2020-10-15 00:58:06 +08:00
@ defgroup imgcodecs_macosx MacOS ( OSX ) glue
2014-11-19 16:29:31 +08:00
@ }
*/
2014-07-04 22:48:15 +08:00
//////////////////////////////// image codec ////////////////////////////////
2012-04-30 22:33:52 +08:00
namespace cv
{
2014-11-19 16:29:31 +08:00
//! @addtogroup imgcodecs
//! @{
2020-10-28 09:51:12 +08:00
//! @addtogroup imgcodecs_flags
//! @{
2015-05-04 19:24:25 +08:00
//! Imread flags
enum ImreadModes {
2020-02-07 06:49:14 +08:00
IMREAD_UNCHANGED = - 1 , //!< If set, return the loaded image as is (with alpha channel, otherwise it gets cropped). Ignore EXIF orientation.
2018-09-30 21:22:26 +08:00
IMREAD_GRAYSCALE = 0 , //!< If set, always convert image to the single channel grayscale image (codec internal conversion).
2015-09-25 03:51:11 +08:00
IMREAD_COLOR = 1 , //!< If set, always convert image to the 3 channel BGR color image.
IMREAD_ANYDEPTH = 2 , //!< If set, return 16-bit/32-bit image when the input has the corresponding depth, otherwise convert it to 8-bit.
IMREAD_ANYCOLOR = 4 , //!< If set, the image is read in any possible color format.
IMREAD_LOAD_GDAL = 8 , //!< If set, use the gdal driver for loading the image.
2015-10-01 22:25:18 +08:00
IMREAD_REDUCED_GRAYSCALE_2 = 16 , //!< If set, always convert image to the single channel grayscale image and the image size reduced 1/2.
IMREAD_REDUCED_COLOR_2 = 17 , //!< If set, always convert image to the 3 channel BGR color image and the image size reduced 1/2.
IMREAD_REDUCED_GRAYSCALE_4 = 32 , //!< If set, always convert image to the single channel grayscale image and the image size reduced 1/4.
IMREAD_REDUCED_COLOR_4 = 33 , //!< If set, always convert image to the 3 channel BGR color image and the image size reduced 1/4.
IMREAD_REDUCED_GRAYSCALE_8 = 64 , //!< If set, always convert image to the single channel grayscale image and the image size reduced 1/8.
2016-11-10 01:09:22 +08:00
IMREAD_REDUCED_COLOR_8 = 65 , //!< If set, always convert image to the 3 channel BGR color image and the image size reduced 1/8.
IMREAD_IGNORE_ORIENTATION = 128 //!< If set, do not rotate the image according to EXIF's orientation flag.
2014-07-04 22:48:15 +08:00
} ;
2012-04-30 22:33:52 +08:00
2015-05-04 19:24:25 +08:00
//! Imwrite flags
enum ImwriteFlags {
IMWRITE_JPEG_QUALITY = 1 , //!< For JPEG, it can be a quality from 0 to 100 (the higher is the better). Default value is 95.
IMWRITE_JPEG_PROGRESSIVE = 2 , //!< Enable JPEG features, 0 or 1, default is False.
IMWRITE_JPEG_OPTIMIZE = 3 , //!< Enable JPEG features, 0 or 1, default is False.
IMWRITE_JPEG_RST_INTERVAL = 4 , //!< JPEG restart interval, 0 - 65535, default is 0 - no restart.
IMWRITE_JPEG_LUMA_QUALITY = 5 , //!< Separate luma quality level, 0 - 100, default is 0 - don't use.
IMWRITE_JPEG_CHROMA_QUALITY = 6 , //!< Separate chroma quality level, 0 - 100, default is 0 - don't use.
2016-12-26 14:44:43 +08:00
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).
2017-05-12 14:01:38 +08:00
IMWRITE_PNG_STRATEGY = 17 , //!< One of cv::ImwritePNGFlags, default is IMWRITE_PNG_STRATEGY_RLE.
2015-05-04 19:24:25 +08:00
IMWRITE_PNG_BILEVEL = 18 , //!< Binary level PNG, 0 or 1, default is 0.
IMWRITE_PXM_BINARY = 32 , //!< For PPM, PGM, or PBM, it can be a binary format flag, 0 or 1. Default value is 1.
2017-12-15 17:23:44 +08:00
IMWRITE_EXR_TYPE = ( 3 < < 4 ) + 0 , /* 48 */ //!< override EXR storage type (FLOAT (FP32) is default)
2016-07-14 21:27:36 +08:00
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.
IMWRITE_PAM_TUPLETYPE = 128 , //!< For PAM, sets the TUPLETYPE field to the corresponding string value that is defined for the format
2018-04-05 12:20:16 +08:00
IMWRITE_TIFF_RESUNIT = 256 , //!< For TIFF, use to specify which DPI resolution unit to set; see libtiff documentation for valid values
IMWRITE_TIFF_XDPI = 257 , //!< For TIFF, use to specify the X direction DPI
2019-02-16 22:05:31 +08:00
IMWRITE_TIFF_YDPI = 258 , //!< For TIFF, use to specify the Y direction DPI
2019-03-12 03:20:22 +08:00
IMWRITE_TIFF_COMPRESSION = 259 , //!< For TIFF, use to specify the image compression scheme. See libtiff for integer constants corresponding to compression formats. 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.
2019-02-16 22:05:31 +08:00
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.
2014-07-04 22:48:15 +08:00
} ;
2012-04-30 22:33:52 +08:00
2017-12-15 17:23:44 +08:00
enum ImwriteEXRTypeFlags {
/*IMWRITE_EXR_TYPE_UNIT = 0, //!< not supported */
IMWRITE_EXR_TYPE_HALF = 1 , //!< store as HALF (FP16)
IMWRITE_EXR_TYPE_FLOAT = 2 //!< store as FP32 (default)
} ;
2015-10-01 22:25:18 +08:00
//! Imwrite PNG specific flags used to tune the compression algorithm.
/** These flags will be modify the way of PNG image compression and will be passed to the underlying zlib processing stage.
- 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 .
- 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 .
- The strategy parameter only affects the compression ratio but not the correctness of the compressed output even if it is not set appropriately .
- IMWRITE_PNG_STRATEGY_FIXED prevents the use of dynamic Huffman codes , allowing for a simpler decoder for special applications .
*/
2015-05-04 19:24:25 +08:00
enum ImwritePNGFlags {
2015-10-01 22:25:18 +08:00
IMWRITE_PNG_STRATEGY_DEFAULT = 0 , //!< Use this value for normal data.
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.
IMWRITE_PNG_STRATEGY_HUFFMAN_ONLY = 2 , //!< Use this value to force Huffman encoding only (no string match).
IMWRITE_PNG_STRATEGY_RLE = 3 , //!< Use this value to limit match distances to one (run-length encoding).
IMWRITE_PNG_STRATEGY_FIXED = 4 //!< Using this value prevents the use of dynamic Huffman codes, allowing for a simpler decoder for special applications.
2014-07-04 22:48:15 +08:00
} ;
2012-04-30 22:33:52 +08:00
2016-07-14 21:27:36 +08:00
//! Imwrite PAM specific tupletype flags used to define the 'TUPETYPE' field of a PAM file.
enum ImwritePAMFlags {
IMWRITE_PAM_FORMAT_NULL = 0 ,
IMWRITE_PAM_FORMAT_BLACKANDWHITE = 1 ,
IMWRITE_PAM_FORMAT_GRAYSCALE = 2 ,
IMWRITE_PAM_FORMAT_GRAYSCALE_ALPHA = 3 ,
IMWRITE_PAM_FORMAT_RGB = 4 ,
IMWRITE_PAM_FORMAT_RGB_ALPHA = 5 ,
} ;
2020-10-28 09:51:12 +08:00
//! @} imgcodecs_flags
2014-11-19 16:29:31 +08:00
/** @brief Loads an image from a file.
2015-01-18 11:28:58 +08:00
@ anchor imread
2014-11-19 16:29:31 +08:00
The function imread loads an image from the specified file and returns it . If the image cannot be
read ( because of missing file , improper permissions , unsupported or invalid format ) , the function
2015-10-01 22:25:18 +08:00
returns an empty matrix ( Mat : : data = = NULL ) .
Currently , the following file formats are supported :
2014-11-19 16:29:31 +08:00
- Windows bitmaps - \ * . bmp , \ * . dib ( always supported )
2018-10-12 04:27:13 +08:00
- JPEG files - \ * . jpeg , \ * . jpg , \ * . jpe ( see the * Note * section )
- JPEG 2000 files - \ * . jp2 ( see the * Note * section )
- Portable Network Graphics - \ * . png ( see the * Note * section )
- WebP - \ * . webp ( see the * Note * section )
2015-08-03 23:57:33 +08:00
- Portable image format - \ * . pbm , \ * . pgm , \ * . ppm \ * . pxm , \ * . pnm ( always supported )
2018-11-22 00:59:37 +08:00
- PFM files - \ * . pfm ( see the * Note * section )
2014-11-19 16:29:31 +08:00
- Sun rasters - \ * . sr , \ * . ras ( always supported )
2018-10-12 04:27:13 +08:00
- TIFF files - \ * . tiff , \ * . tif ( see the * Note * section )
- OpenEXR Image files - \ * . exr ( see the * Note * section )
2015-08-03 23:57:33 +08:00
- Radiance HDR - \ * . hdr , \ * . pic ( always supported )
2018-10-12 04:27:13 +08:00
- Raster and Vector geospatial data supported by GDAL ( see the * Note * section )
2014-11-19 16:29:31 +08:00
@ note
- The function determines the type of an image by the content , not by the file extension .
2015-10-01 22:25:18 +08:00
- In the case of color images , the decoded images will have the channels stored in * * B G R * * order .
2018-09-30 21:22:26 +08:00
- When using IMREAD_GRAYSCALE , the codec ' s internal grayscale conversion will be used , if available .
Results may differ to the output of cvtColor ( )
2014-11-19 16:29:31 +08:00
- On Microsoft Windows \ * OS and MacOSX \ * , the codecs shipped with an OpenCV image ( libjpeg ,
libpng , libtiff , and libjasper ) are used by default . So , OpenCV can always read JPEGs , PNGs ,
and TIFFs . On MacOSX , there is also an option to use native MacOSX image readers . But beware
that currently these native image loaders give images with different pixel values because of
the color management embedded into MacOSX .
- On Linux \ * , BSD flavors and other Unix - like open - source operating systems , OpenCV looks for
codecs supplied with an OS image . Install the relevant packages ( do not forget the development
files , for example , " libjpeg-dev " , in Debian \ * and Ubuntu \ * ) to get the codec support or turn
2014-11-21 16:28:14 +08:00
on the OPENCV_BUILD_3RDPARTY_LIBS flag in CMake .
2015-10-14 15:16:04 +08:00
- In the case you set * WITH_GDAL * flag to true in CMake and @ ref IMREAD_LOAD_GDAL to load the image ,
2018-10-12 04:27:13 +08:00
then the [ GDAL ] ( http : //www.gdal.org) driver will be used in order to decode the image, supporting
2015-10-14 15:16:04 +08:00
the following formats : [ Raster ] ( http : //www.gdal.org/formats_list.html),
[ Vector ] ( http : //www.gdal.org/ogr_formats.html).
2020-02-07 21:54:34 +08:00
- If EXIF information is embedded in the image file , the EXIF orientation will be taken into account
and thus the image will be rotated accordingly except if the flags @ ref IMREAD_IGNORE_ORIENTATION
or @ ref IMREAD_UNCHANGED are passed .
2018-11-22 00:59:37 +08:00
- Use the IMREAD_UNCHANGED flag to keep the floating point values from PFM image .
2018-12-09 20:05:27 +08:00
- By default number of pixels must be less than 2 ^ 30. Limit can be set using system
variable OPENCV_IO_MAX_IMAGE_PIXELS
2018-10-12 04:27:13 +08:00
2015-06-27 22:18:51 +08:00
@ param filename Name of file to be loaded .
2015-10-01 22:25:18 +08:00
@ param flags Flag that can take values of cv : : ImreadModes
*/
2014-07-04 22:48:15 +08:00
CV_EXPORTS_W Mat imread ( const String & filename , int flags = IMREAD_COLOR ) ;
2015-06-27 22:18:51 +08:00
2015-10-01 22:25:18 +08:00
/** @brief Loads a multi-page image from a file.
2014-12-29 23:50:42 +08:00
2015-10-01 22:25:18 +08:00
The function imreadmulti loads a multi - page image from the specified file into a vector of Mat objects .
2014-12-29 23:50:42 +08:00
@ param filename Name of file to be loaded .
2015-10-01 22:25:18 +08:00
@ param flags Flag that can take values of cv : : ImreadModes , default with cv : : IMREAD_ANYCOLOR .
2014-12-29 23:50:42 +08:00
@ param mats A vector of Mat objects holding each page , if more than one .
2015-10-01 22:25:18 +08:00
@ sa cv : : imread
2014-12-29 23:50:42 +08:00
*/
2017-09-08 21:09:00 +08:00
CV_EXPORTS_W bool imreadmulti ( const String & filename , CV_OUT std : : vector < Mat > & mats , int flags = IMREAD_ANYCOLOR ) ;
2014-12-29 23:50:42 +08:00
2014-11-19 16:29:31 +08:00
/** @brief Saves an image to a specified file.
The function imwrite saves the image to the specified file . The image format is chosen based on the
2018-10-12 04:27:13 +08:00
filename extension ( see cv : : imread for the list of extensions ) . In general , only 8 - bit
single - channel or 3 - channel ( with ' BGR ' channel order ) images
can be saved using this function , with these exceptions :
- 16 - bit unsigned ( CV_16U ) images can be saved in the case of PNG , JPEG 2000 , and TIFF formats
2018-11-22 00:59:37 +08:00
- 32 - bit float ( CV_32F ) images can be saved in PFM , TIFF , OpenEXR , and Radiance HDR formats ;
3 - channel ( CV_32FC3 ) TIFF images will be saved using the LogLuv high dynamic range encoding
( 4 bytes per pixel )
2018-10-12 04:27:13 +08:00
- PNG images with an alpha channel can be saved using this function . To do this , create
2014-11-19 16:29:31 +08:00
8 - bit ( or 16 - bit ) 4 - channel image BGRA , where the alpha channel goes last . Fully transparent pixels
2018-10-12 04:27:13 +08:00
should have alpha set to 0 , fully opaque pixels should have alpha set to 255 / 65535 ( see the code sample below ) .
2020-07-02 04:50:09 +08:00
- Multiple images ( vector of Mat ) can be saved in TIFF format ( see the code sample below ) .
2018-10-12 04:27:13 +08:00
If the format , depth or channel order is different , use
Mat : : convertTo and cv : : cvtColor to convert it before saving . Or , use the universal FileStorage I / O
functions to save the image to XML or YAML format .
2015-10-01 22:25:18 +08:00
2020-07-02 04:50:09 +08:00
The sample below shows how to create a BGRA image , how to set custom compression parameters and save it to a PNG file .
It also demonstrates how to save multiple images in a TIFF file :
2017-12-31 19:13:13 +08:00
@ include snippets / imgcodecs_imwrite . cpp
2015-10-01 22:25:18 +08:00
@ param filename Name of the file .
2020-07-02 04:50:09 +08:00
@ param img ( Mat or vector of Mat ) Image or Images to be saved .
2015-10-01 22:25:18 +08:00
@ param params Format - specific parameters encoded as pairs ( paramId_1 , paramValue_1 , paramId_2 , paramValue_2 , . . . . ) see cv : : ImwriteFlags
*/
2014-07-04 22:48:15 +08:00
CV_EXPORTS_W bool imwrite ( const String & filename , InputArray img ,
const std : : vector < int > & params = std : : vector < int > ( ) ) ;
2012-10-17 15:12:04 +08:00
2020-10-07 18:19:17 +08:00
/// @overload multi-image overload for bindings
CV_WRAP static inline
bool imwritemulti ( const String & filename , InputArrayOfArrays img ,
const std : : vector < int > & params = std : : vector < int > ( ) )
{
return imwrite ( filename , img , params ) ;
}
2014-11-19 16:29:31 +08:00
/** @brief Reads an image from a buffer in memory.
2015-10-01 22:25:18 +08:00
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 ) .
2014-11-19 16:29:31 +08:00
2015-10-01 22:25:18 +08:00
See cv : : imread for the list of supported formats and flags description .
2014-11-19 16:29:31 +08:00
2015-10-01 22:25:18 +08:00
@ 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 flags The same flags as in cv : : imread , see cv : : ImreadModes .
*/
CV_EXPORTS_W Mat imdecode ( InputArray buf , int flags ) ;
2014-11-19 16:29:31 +08:00
2015-10-01 22:25:18 +08:00
/** @overload
@ param buf
@ param flags
@ param dst The optional output placeholder for the decoded matrix . It can save the image
reallocations when the function is called repeatedly for images of the same size .
*/
2014-07-04 22:48:15 +08:00
CV_EXPORTS Mat imdecode ( InputArray buf , int flags , Mat * dst ) ;
2010-05-12 01:44:00 +08:00
2014-11-19 16:29:31 +08:00
/** @brief Encodes an image into a memory buffer.
2015-10-01 22:25:18 +08:00
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 .
2014-11-19 16:29:31 +08:00
@ param ext File extension that defines the output format .
@ param img Image to be written .
@ param buf Output buffer resized to fit the compressed image .
2015-10-01 22:25:18 +08:00
@ param params Format - specific parameters . See cv : : imwrite and cv : : ImwriteFlags .
*/
2014-07-04 22:48:15 +08:00
CV_EXPORTS_W bool imencode ( const String & ext , InputArray img ,
CV_OUT std : : vector < uchar > & buf ,
const std : : vector < int > & params = std : : vector < int > ( ) ) ;
2010-05-12 01:44:00 +08:00
2018-11-09 05:52:09 +08:00
/** @brief Returns true if the specified image can be decoded by OpenCV
@ param filename File name of the image
*/
CV_EXPORTS_W bool haveImageReader ( const String & filename ) ;
/** @brief Returns true if an image with the specified filename can be encoded by OpenCV
@ param filename File name of the image
*/
CV_EXPORTS_W bool haveImageWriter ( const String & filename ) ;
2014-11-19 16:29:31 +08:00
//! @} imgcodecs
2014-07-04 22:48:15 +08:00
} // cv
2012-04-30 22:33:52 +08:00
2016-09-30 17:46:29 +08:00
# endif //OPENCV_IMGCODECS_HPP