doc/tutorials/introduction/windows_visual_studio_image_watch/windows_visual_studio_image_watch.markdown

   1 Image Watch: viewing in-memory images in the Visual Studio debugger {#tutorial_windows_visual_studio_image_watch}
   2 ===================================================================
   3
   4 @prev_tutorial{tutorial_windows_visual_studio_opencv}
   5 @next_tutorial{tutorial_java_dev_intro}
   6
   7 |    |    |
   8 | -: | :- |
   9 | Original author | Wolf Kienzle |
  10 | Compatibility | OpenCV >= 3.0 |
  11
  12 @warning
  13 This tutorial can contain obsolete information.
  14
  15 Image Watch is a plug-in for Microsoft Visual Studio that lets you to visualize in-memory images
  16 (*cv::Mat* or *IplImage_* objects, for example) while debugging an application. This can be helpful
  17 for tracking down bugs, or for simply understanding what a given piece of code is doing.
  18
  19 Prerequisites
  20 -------------
  21
  22 This tutorial assumes that you have the following available:
  23
  24 -#  Visual Studio 2012 Professional (or better) with Update 1 installed. Update 1 can be downloaded
  25     [here](http://www.microsoft.com/en-us/download/details.aspx?id=35774).
  26 -#  An OpenCV installation on your Windows machine (Tutorial: @ref tutorial_windows_install).
  27 -#  Ability to create and build OpenCV projects in Visual Studio (Tutorial: @ref tutorial_windows_visual_studio_opencv).
  28
  29 Installation
  30 ------------
  31
  32 Download the Image Watch installer. ([Visual Studio 2019](https://marketplace.visualstudio.com/items?itemName=VisualCPPTeam.ImageWatch2019) | [Visual Studio 2017](https://marketplace.visualstudio.com/items?itemName=VisualCPPTeam.ImageWatch2017) | [Visual Studio 2012, 2013, 2015](https://marketplace.visualstudio.com/items?itemName=VisualCPPTeam.ImageWatch))
  33 The installer comes in a single file with extension .vsix (*Visual Studio Extension*). To launch it, simply
  34 double-click on the .vsix file in Windows Explorer. When the installer has finished, make sure to
  35 restart Visual Studio to complete the installation.
  36
  37 Example
  38 -------
  39
  40 Image Watch works with any existing project that uses OpenCV image objects (for example, *cv::Mat*).
  41 In this example, we use a minimal test program that loads an image from a file and runs an edge
  42 detector. To build the program, create a console application project in Visual Studio, name it
  43 "image-watch-demo", and insert the source code below.
  44 @code{.cpp}
  45 // Test application for the Visual Studio Image Watch Debugger extension
  46
  47 #include <iostream>                        // std::cout
  48 #include <opencv2/core/core.hpp>           // cv::Mat
  49 #include <opencv2/imgcodecs/imgcodecs.hpp>     // cv::imread()
  50 #include <opencv2/imgproc/imgproc.hpp>     // cv::Canny()
  51
  52 using namespace std;
  53 using namespace cv;
  54
  55 void help()
  56 {
  57     cout
  58         << "----------------------------------------------------" << endl
  59         << "This is a test program for the Image Watch Debugger " << endl
  60         << "plug-in for Visual Studio. The program loads an     " << endl
  61         << "image from a file and runs the Canny edge detector. " << endl
  62         << "No output is displayed or written to disk."
  63         << endl
  64         << "Usage:"                                               << endl
  65         << "image-watch-demo inputimage"                          << endl
  66         << "----------------------------------------------------" << endl
  67         << endl;
  68 }
  69
  70 int main(int argc, char *argv[])
  71 {
  72     help();
  73
  74     if (argc != 2)
  75     {
  76         cout << "Wrong number of parameters" << endl;
  77         return -1;
  78     }
  79
  80     cout << "Loading input image: " << argv[1] << endl;
  81     Mat input;
  82     input = imread(argv[1], IMREAD_COLOR);
  83
  84     cout << "Detecting edges in input image" << endl;
  85     Mat edges;
  86     Canny(input, edges, 10, 100);
  87
  88     return 0;
  89 }
  90 @endcode
  91 Make sure your active solution configuration (Build --\> Configuration Manager) is set to a debug
  92 build (usually called "Debug"). This should disable compiler optimizations so that viewing variables
  93 in the debugger can work reliably.
  94
  95 Build your solution (Build --\> Build Solution, or press *F7*).
  96
  97 Before continuing, do not forget to add the command line argument of your input image to your
  98 project (Right click on project --\> Properties --\> Configuration Properties --\> Debugging and
  99 then set the field Command Arguments with the location of the image).
 100
 101 Now set a breakpoint on the source line that says
 102 @code{.cpp}
 103 Mat edges;
 104 @endcode
 105 To set the breakpoint, right-click on the source line and select Breakpoints --\> Insert Breakpoint
 106 from the context menu.
 107
 108 Launch the program in the debugger (Debug --\> Start Debugging, or hit *F5*). When the breakpoint is
 109 hit, the program is paused and Visual Studio displays a yellow instruction pointer at the
 110 breakpoint:
 111
 112 ![](images/breakpoint.png)
 113
 114 Now you can inspect the state of you program. For example, you can bring up the *Locals* window
 115 (Debug --\> Windows --\> Locals), which will show the names and values of the variables in the
 116 current scope:
 117
 118 ![](images/vs_locals.png)
 119
 120 Note that the built-in *Locals* window will display text only. This is where the Image Watch plug-in
 121 comes in. Image Watch is like another *Locals* window, but with an image viewer built into it. To
 122 bring up Image Watch, select View --\> Other Windows --\> Image Watch. Like Visual Studio's *Locals*
 123 window, Image Watch can dock to the Visual Studio IDE. Also, Visual Studio will remember whether you
 124 had Image Watch open, and where it was located between debugging sessions. This means you only have
 125 to do this once--the next time you start debugging, Image Watch will be back where you left it.
 126 Here's what the docked Image Watch window looks like at our breakpoint:
 127
 128 ![](images/toolwindow.jpg)
 129
 130 The radio button at the top left (*Locals/Watch*) selects what is shown in the *Image List* below:
 131 *Locals* lists all OpenCV image objects in the current scope (this list is automatically populated).
 132 *Watch* shows image expressions that have been pinned for continuous inspection (not described here,
 133 see [Image Watch documentation](http://go.microsoft.com/fwlink/?LinkId=285461) for details). The
 134 image list shows basic information such as width, height, number of channels, and, if available, a
 135 thumbnail. In our example, the image list contains our two local image variables, *input* and
 136 *edges*.
 137
 138 If an image has a thumbnail, left-clicking on that image will select it for detailed viewing in the
 139 *Image Viewer* on the right. The viewer lets you pan (drag mouse) and zoom (mouse wheel). It also
 140 displays the pixel coordinate and value at the current mouse position.
 141
 142 ![](images/viewer.jpg)
 143
 144 Note that the second image in the list, *edges*, is shown as "invalid". This indicates that some
 145 data members of this image object have corrupt or invalid values (for example, a negative image
 146 width). This is expected at this point in the program, since the C++ constructor for *edges* has not
 147 run yet, and so its members have undefined values (in debug mode they are usually filled with "0xCD"
 148 bytes).
 149
 150 From here you can single-step through your code (Debug-\>Step Over, or press *F10*) and watch the
 151 pixels change: if you step once, over the *Mat edges;* statement, the *edges* image will change from
 152 "invalid" to "empty", which means that it is now in a valid state (default constructed), even though
 153 it has not been initialized yet (using *cv::Mat::create()*, for example). If you make one more step
 154 over the *cv::Canny()* call, you will see a thumbnail of the edge image appear in the image list.
 155
 156 Now assume you want to do a visual sanity check of the *cv::Canny()* implementation. Bring the
 157 *edges* image into the viewer by selecting it in the *Image List* and zoom into a region with a
 158 clearly defined edge:
 159
 160 ![](images/edges_zoom.png)
 161
 162 Right-click on the *Image Viewer* to bring up the view context menu and enable Link Views (a check
 163 box next to the menu item indicates whether the option is enabled).
 164
 165 ![](images/viewer_context_menu.png)
 166
 167 The Link Views feature keeps the view region fixed when flipping between images of the same size. To
 168 see how this works, select the input image from the image list--you should now see the corresponding
 169 zoomed-in region in the input image:
 170
 171 ![](images/input_zoom.png)
 172
 173 You may also switch back and forth between viewing input and edges with your up/down cursor keys.
 174 That way you can easily verify that the detected edges line up nicely with the data in the input
 175 image.
 176
 177 More ...
 178 --------
 179
 180 Image watch has a number of more advanced features, such as
 181
 182 -#  pinning images to a *Watch* list for inspection across scopes or between debugging sessions
 183 -#  clamping, thresholding, or diff'ing images directly inside the Watch window
 184 -#  comparing an in-memory image against a reference image from a file
 185
 186 Please refer to the online [Image Watch
 187 Documentation](http://go.microsoft.com/fwlink/?LinkId=285461) for details--you also can get to the
 188 documentation page by clicking on the *Help* link in the Image Watch window:
 189
 190 ![](images/help_button.jpg)