From 978ad4981ee1d2e902291e52bdd8daa81f6a1e20 Mon Sep 17 00:00:00 2001 From: drkoller Date: Thu, 11 Oct 2018 16:27:13 -0400 Subject: [PATCH] Clean up documentation for imread and imwrite --- .../imgcodecs/include/opencv2/imgcodecs.hpp | 43 +++++++++++-------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/modules/imgcodecs/include/opencv2/imgcodecs.hpp b/modules/imgcodecs/include/opencv2/imgcodecs.hpp index c5ffff97b2..a27d4be74e 100644 --- a/modules/imgcodecs/include/opencv2/imgcodecs.hpp +++ b/modules/imgcodecs/include/opencv2/imgcodecs.hpp @@ -140,19 +140,18 @@ returns an empty matrix ( Mat::data==NULL ). Currently, the following file formats are supported: - Windows bitmaps - \*.bmp, \*.dib (always supported) -- JPEG files - \*.jpeg, \*.jpg, \*.jpe (see the *Notes* section) -- JPEG 2000 files - \*.jp2 (see the *Notes* section) -- Portable Network Graphics - \*.png (see the *Notes* section) -- WebP - \*.webp (see the *Notes* section) +- 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) - Portable image format - \*.pbm, \*.pgm, \*.ppm \*.pxm, \*.pnm (always supported) - Sun rasters - \*.sr, \*.ras (always supported) -- TIFF files - \*.tiff, \*.tif (see the *Notes* section) -- OpenEXR Image files - \*.exr (see the *Notes* section) +- TIFF files - \*.tiff, \*.tif (see the *Note* section) +- OpenEXR Image files - \*.exr (see the *Note* section) - Radiance HDR - \*.hdr, \*.pic (always supported) -- Raster and Vector geospatial data supported by Gdal (see the *Notes* section) +- Raster and Vector geospatial data supported by GDAL (see the *Note* section) @note - - The function determines the type of an image by the content, not by the file extension. - In the case of color images, the decoded images will have the channels stored in **B G R** order. - When using IMREAD_GRAYSCALE, the codec's internal grayscale conversion will be used, if available. @@ -167,11 +166,12 @@ Currently, the following file formats are supported: files, for example, "libjpeg-dev", in Debian\* and Ubuntu\*) to get the codec support or turn on the OPENCV_BUILD_3RDPARTY_LIBS flag in CMake. - In the case you set *WITH_GDAL* flag to true in CMake and @ref IMREAD_LOAD_GDAL to load the image, - then [GDAL](http://www.gdal.org) driver will be used in order to decode the image by supporting + then the [GDAL](http://www.gdal.org) driver will be used in order to decode the image, supporting the following formats: [Raster](http://www.gdal.org/formats_list.html), [Vector](http://www.gdal.org/ogr_formats.html). - If EXIF information are embedded in the image file, the EXIF orientation will be taken into account and thus the image will be rotated accordingly except if the flag @ref IMREAD_IGNORE_ORIENTATION is passed. + @param filename Name of file to be loaded. @param flags Flag that can take values of cv::ImreadModes */ @@ -190,18 +190,23 @@ CV_EXPORTS_W bool imreadmulti(const String& filename, CV_OUT std::vector& m /** @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 -filename extension (see cv::imread for the list of extensions). Only 8-bit (or 16-bit unsigned (CV_16U) -in case of PNG, JPEG 2000, and TIFF) single-channel or 3-channel (with 'BGR' channel order) images -can be saved using this function. 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. - -It is possible to store PNG images with an alpha channel using this function. To do this, create +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 +- 32-bit float (CV_32F) images can be saved in 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) +- PNG images with an alpha channel can be saved using this function. To do this, create 8-bit (or 16-bit) 4-channel image BGRA, where the alpha channel goes last. Fully transparent pixels -should have alpha set to 0, fully opaque pixels should have alpha set to 255/65535. +should have alpha set to 0, fully opaque pixels should have alpha set to 255/65535 (see the code sample below). + +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. -The sample below shows how to create such a BGRA image and store to PNG file. It also demonstrates how to set custom -compression parameters : +The sample below shows how to create a BGRA image and save it to a PNG file. It also demonstrates how to set custom +compression parameters: @include snippets/imgcodecs_imwrite.cpp @param filename Name of the file. @param img Image to be saved.