doc/tutorials/introduction/display_image/display_image.markdown

   1 Getting Started with Images {#tutorial_display_image}
   2 ===========================
   3
   4 Goal
   5 ----
   6
   7 In this tutorial you will learn how to:
   8
   9 -   Read an image from file (using @ref cv::imread)
  10 -   Display an image in an OpenCV window (using @ref cv::imshow)
  11 -   Write an image to a file (using @ref cv::imwrite)
  12
  13 Source Code
  14 -----------
  15
  16 @add_toggle_cpp
  17 -   **Downloadable code**: Click
  18     [here](https://github.com/opencv/opencv/tree/3.4/samples/cpp/tutorial_code/introduction/display_image/display_image.cpp)
  19
  20 -   **Code at glance:**
  21     @include samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
  22 @end_toggle
  23
  24 @add_toggle_python
  25 -   **Downloadable code**: Click
  26     [here](https://github.com/opencv/opencv/tree/3.4/samples/python/tutorial_code/introduction/display_image/display_image.py)
  27
  28 -   **Code at glance:**
  29     @include samples/python/tutorial_code/introduction/display_image/display_image.py
  30 @end_toggle
  31
  32
  33 Explanation
  34 -----------
  35
  36 @add_toggle_cpp
  37 In OpenCV 3 we have multiple modules. Each one takes care of a different area or approach towards
  38 image processing. You could already observe this in the structure of the user guide of these
  39 tutorials itself. Before you use any of them you first need to include the header files where the
  40 content of each individual module is declared.
  41
  42 You'll almost always end up using the:
  43
  44 - @ref core "core" section, as here are defined the basic building blocks of the library
  45 - @ref imgcodecs "imgcodecs" module, which provides functions for reading and writing
  46 - @ref highgui "highgui" module, as this contains the functions to show an image in a window
  47
  48 We also include the *iostream* to facilitate console line output and input.
  49
  50 By declaring `using namespace cv;`, in the following, the library functions can be accessed without explicitly stating the namespace.
  51
  52 @snippet cpp/tutorial_code/introduction/display_image/display_image.cpp includes
  53 @end_toggle
  54
  55 @add_toggle_python
  56 As a first step, the OpenCV python library is imported.
  57 The proper way to do this is to additionally assign it the name *cv*, which is used in the following to reference the library.
  58
  59 @snippet samples/python/tutorial_code/introduction/display_image/display_image.py imports
  60 @end_toggle
  61
  62 Now, let's analyze the main code.
  63 As a first step, we read the image "starry_night.jpg" from the OpenCV samples.
  64 In order to do so, a call to the @ref cv::imread function loads the image using the file path specified by the first argument.
  65 The second argument is optional and specifies the format in which we want the image. This may be:
  66
  67 -   IMREAD_COLOR loads the image in the BGR 8-bit format. This is the **default** that is used here.
  68 -   IMREAD_UNCHANGED loads the image as is (including the alpha channel if present)
  69 -   IMREAD_GRAYSCALE loads the image as an intensity one
  70
  71 After reading in the image data will be stored in a @ref cv::Mat object.
  72
  73 @add_toggle_cpp
  74 @snippet cpp/tutorial_code/introduction/display_image/display_image.cpp imread
  75 @end_toggle
  76
  77 @add_toggle_python
  78 @snippet samples/python/tutorial_code/introduction/display_image/display_image.py imread
  79 @end_toggle
  80
  81 @note
  82    OpenCV offers support for the image formats Windows bitmap (bmp), portable image formats (pbm,
  83     pgm, ppm) and Sun raster (sr, ras). With help of plugins (you need to specify to use them if you
  84     build yourself the library, nevertheless in the packages we ship present by default) you may
  85     also load image formats like JPEG (jpeg, jpg, jpe), JPEG 2000 (jp2 - codenamed in the CMake as
  86     Jasper), TIFF files (tiff, tif) and portable network graphics (png). Furthermore, OpenEXR is
  87     also a possibility.
  88
  89 Afterwards, a check is executed, if the image was loaded correctly.
  90 @add_toggle_cpp
  91 @snippet cpp/tutorial_code/introduction/display_image/display_image.cpp empty
  92 @end_toggle
  93
  94 @add_toggle_python
  95 @snippet samples/python/tutorial_code/introduction/display_image/display_image.py empty
  96 @end_toggle
  97
  98 Then, the image is shown using a call to the @ref cv::imshow function.
  99 The first argument is the title of the window and the second argument is the @ref cv::Mat object that will be shown.
 100
 101 Because we want our window to be displayed until the user presses a key (otherwise the program would
 102 end far too quickly), we use the @ref cv::waitKey function whose only parameter is just how long
 103 should it wait for a user input (measured in milliseconds). Zero means to wait forever.
 104 The return value is the key that was pressed.
 105
 106 @add_toggle_cpp
 107 @snippet cpp/tutorial_code/introduction/display_image/display_image.cpp imshow
 108 @end_toggle
 109
 110 @add_toggle_python
 111 @snippet samples/python/tutorial_code/introduction/display_image/display_image.py imshow
 112 @end_toggle
 113
 114 In the end, the image is written to a file if the pressed key was the "s"-key.
 115 For this the cv::imwrite function is called that has the file path and the cv::Mat object as an argument.
 116
 117 @add_toggle_cpp
 118 @snippet cpp/tutorial_code/introduction/display_image/display_image.cpp imsave
 119 @end_toggle
 120
 121 @add_toggle_python
 122 @snippet samples/python/tutorial_code/introduction/display_image/display_image.py imsave
 123 @end_toggle