1Load and Display an Image {#tutorial_display_image}
2=========================
3
4Goal
5----
6
7In this tutorial you will learn how to:
8
9-   Load an image (using @ref cv::imread )
10-   Create a named OpenCV window (using @ref cv::namedWindow )
11-   Display an image in an OpenCV window (using @ref cv::imshow )
12
13Source Code
14-----------
15
16Download the source code from
17[here](https://github.com/Itseez/opencv/tree/master/samples/cpp/tutorial_code/introduction/display_image/display_image.cpp).
18
19@include cpp/tutorial_code/introduction/display_image/display_image.cpp
20
21Explanation
22-----------
23
24In OpenCV 2 we have multiple modules. Each one takes care of a different area or approach towards
25image processing. You could already observe this in the structure of the user guide of these
26tutorials itself. Before you use any of them you first need to include the header files where the
27content of each individual module is declared.
28
29You'll almost always end up using the:
30
31-   *core* section, as here are defined the basic building blocks of the library
32-   *highgui* module, as this contains the functions for input and output operations
33
34@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp includes
35
36We also include the *iostream* to facilitate console line output and input. To avoid data structure
37and function name conflicts with other libraries, OpenCV has its own namespace: *cv*. To avoid the
38need appending prior each of these the *cv::* keyword you can import the namespace in the whole file
39by using the lines:
40
41@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp namespace
42
43This is true for the STL library too (used for console I/O). Now, let's analyze the *main* function.
44We start up assuring that we acquire a valid image name argument from the command line. Otherwise
45take a picture by default: "HappyFish.jpg".
46
47@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp load
48
49Then create a *Mat* object that will store the data of the loaded image.
50
51@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp mat
52
53Now we call the @ref cv::imread function which loads the image name specified by the first argument
54(*argv[1]*). The second argument specifies the format in what we want the image. This may be:
55
56-   IMREAD_UNCHANGED (\<0) loads the image as is (including the alpha channel if present)
57-   IMREAD_GRAYSCALE ( 0) loads the image as an intensity one
58-   IMREAD_COLOR (\>0) loads the image in the RGB format
59
60@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp imread
61
62@note
63   OpenCV offers support for the image formats Windows bitmap (bmp), portable image formats (pbm,
64    pgm, ppm) and Sun raster (sr, ras). With help of plugins (you need to specify to use them if you
65    build yourself the library, nevertheless in the packages we ship present by default) you may
66    also load image formats like JPEG (jpeg, jpg, jpe), JPEG 2000 (jp2 - codenamed in the CMake as
67    Jasper), TIFF files (tiff, tif) and portable network graphics (png). Furthermore, OpenEXR is
68    also a possibility.
69
70After checking that the image data was loaded correctly, we want to display our image, so we create
71an OpenCV window using the @ref cv::namedWindow function. These are automatically managed by OpenCV
72once you create them. For this you need to specify its name and how it should handle the change of
73the image it contains from a size point of view. It may be:
74
75-   *WINDOW_AUTOSIZE* is the only supported one if you do not use the Qt backend. In this case the
76    window size will take up the size of the image it shows. No resize permitted!
77-   *WINDOW_NORMAL* on Qt you may use this to allow window resize. The image will resize itself
78    according to the current window size. By using the | operator you also need to specify if you
79    would like the image to keep its aspect ratio (*WINDOW_KEEPRATIO*) or not
80    (*WINDOW_FREERATIO*).
81
82@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp window
83
84Finally, to update the content of the OpenCV window with a new image use the @ref cv::imshow
85function. Specify the OpenCV window name to update and the image to use during this operation:
86
87@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp imshow
88
89Because we want our window to be displayed until the user presses a key (otherwise the program would
90end far too quickly), we use the @ref cv::waitKey function whose only parameter is just how long
91should it wait for a user input (measured in milliseconds). Zero means to wait forever.
92
93@snippet cpp/tutorial_code/introduction/display_image/display_image.cpp wait
94
95Result
96------
97
98-   Compile your code and then run the executable giving an image path as argument. If you're on
99    Windows the executable will of course contain an *exe* extension too. Of course assure the image
100    file is near your program file.
101    @code{.sh}
102    ./DisplayImage HappyFish.jpg
103    @endcode
104-   You should get a nice window as the one shown below:
105
106    ![](images/Display_Image_Tutorial_Result.jpg)
107
108\htmlonly
109<div align="center">
110<iframe title="Introduction - Display an Image" width="560" height="349" src="http://www.youtube.com/embed/1OJEqpuaGc4?rel=0&loop=1" frameborder="0" allowfullscreen align="middle"></iframe>
111</div>
112\endhtmlonly
113