visual-logging, my new favorite tool for debugging OpenCV and Python apps

A couple months ago, my friend Dmitry Chaplinsky sent me an email telling me about a new library that I just had to checkout. Always curious about new computer vision and image processing packages, I became intrigued.

You see, Dmitry’s work involves applying Python and OpenCV to tag and categorize shredded documents in hope of uncovering corruption in the in Ukraine. His library, unshred, does much of the dirty work.

But in order to build unshred he needed an easy way to debug OpenCV applications.

Just like we use print  statements to debug simple Python apps, we use the OpenCV cv2.imshow  and cv2.waitKey  functions to visually display our images to our screen so that we can debug them.

In all honestly it’s a real pain in the ass and before you know it, your pipeline is completely filled up with cv2.imshow  calls.

To fix this cv2.imshow  hell, Dmitry created visual-logging, a library that lets you debug and log your OpenCV pipeline directly to file. And it formats it all using a pretty HTML structure.

Before a few months ago, I had no idea that a tool like this even existed — and now I am incorporating it into my everyday computer vision workflow.

So if you’re interested in how you can (better) debug and log your OpenCV + Python apps, then read on. You won’t want to miss this awesome library.

Thanks again Dmitry!

Looking for the source code to this post?
Jump right to the downloads section.

OpenCV and Python versions:
This example will run on Python 2.7 and OpenCV 2.4.X/OpenCV 3.0+.

visual-logging, my new favorite tool for debugging OpenCV and Python apps

At the time of this writing, the visual-logging documentation claims that the package is pip -installable:

However, when I executed the above command I got the dreaded “No distributions at all found for visual-logging”. I’m assuming that the package is not yet registered with PyPi.

Regardless, that’s not a big deal. We can simply clone from the GitHub repo and install the “old-fashioned” way:

Now that we have visual-logging  installed, let’s create a simple script that demonstrates how visual-logging  can be used to help us visualize our pipeline:

The code here is fairly simple. On Lines 2-5 we import the packages we’ll need.

We then setup our logging handlers and attributes on Lines 8-13.

We load an example image of Lex Murphy (from Jurassic Park, duh) on Line 16 and convert the image to grayscale on Line 17.

Lines 20-25 test out our visual logger. We are going to progressively blur the image using a larger and larger sigma size. We then detect edges in the blurred image.

Normally, to view the output of our blurring and edge detection we would have to make a call to cv2.imshow  and cv2.waitKey .

But those days are done.

Instead, we are going to create a VisualRecord  and log both the Gaussian blurred and edged map to file. This will allow us to debug our pipeline and easily view our results.

Speaking of results, execute the following command to generate your visual log file:

Assuming the script executed without error, you should have a new file named demo.html  in your current working directory.

Here is a screenshot of what my demo.html  file looks like:

Figure 1: Example of using visual-logger to log and debug OpenCV + Python computer vision pipelines.

Figure 1: Example of using visual-logger to log and debug OpenCV + Python computer vision pipelines.

As we can see from this example, as the size of the Gaussian sigma increases, the image becomes progressively more blurred. And as the image becomes more blurred, less edges are detected.

Of course, this is a fairly trivial example of debugging and logging an OpenCV + Python application. But I think you get the point — the days of clogging your code up with  cv2.imshow  and cv2.waitKey  statements are gone!

Instead, just use visual-logging — your life will be much simpler.


In this blog post we explored visual-logging, my new favorite tool for debugging Python + OpenCV applications.

Up until now, debugging OpenCV apps has been a mess of cv2.imshow  and cv2.waitKey  calls. All of these functions calls are a pain in the ass to manage, and even worse for debugging. You’ll be taking screenshot after screenshot of each iteration of your computer vision pipeline.

But now we have a better way. We can utilize Dmitry Chaplinsky’s visual-logging package to help us easily debug and log our OpenCV apps.

Thanks Dmitry for such a great library!


If you would like to download the code and images used in this post, please enter your email address in the form below. Not only will you get a .zip of the code, I’ll also send you a FREE 17-page Resource Guide on Computer Vision, OpenCV, and Deep Learning. Inside you'll find my hand-picked tutorials, books, courses, and libraries to help you master CV and DL! Sound good? If so, enter your email address and I’ll send you the code immediately!

, , ,

17 Responses to visual-logging, my new favorite tool for debugging OpenCV and Python apps

  1. Dmitry December 22, 2014 at 11:52 am #

    Thanks for the great blog post, Adrian, glad you’ve liked my tool.

    Also it’s now pip installable 🙂

    • Adrian Rosebrock December 22, 2014 at 3:20 pm #

      I should be the one thanking you for the excellent library!

  2. Guri Ross December 25, 2014 at 5:26 am #

    Thanks Adrian and Dmitry for sharing and developing such an awesome library respectively.
    Adrian you are doing a great work on this blog. Definitely, one of the best Computer Vision blog that is regularly updated these days. I hope to see more from you.

    • Adrian Rosebrock December 25, 2014 at 11:31 am #

      Hi Guri, thank you for such an awesome compliment, I appreciate it! 🙂

  3. Jean-Philippe Jodoin February 4, 2015 at 12:11 am #

    Awesome tool Dmitry. Just started using it a few hours ago and I already love it. Thanks for sharing Adrian. Great blog.

    • Adrian Rosebrock February 4, 2015 at 6:28 am #

      I’m glad you’re enjoying the blog! And yes, Dmitry’s tool is fantastic. It’s a must-have when working with OpenCV and Python.

  4. Mike Ream April 8, 2015 at 10:56 am #

    This tool is super handy. I have found it as a great way to share my results with others in a very easy was in addition to using it for debugging. I do notice the file seems to stay open after I run my python project. Is there a call to close the file? In order to delete the file, I have to kill my python window since python.exe holds the file open. Thanks for creating the tool!

    • Adrian Rosebrock April 8, 2015 at 11:39 am #

      I’m glad you’re enjoying the tool Mike! As for the process staying open, I’m not sure why that would happen. That sounds very strange. I would ask Dmitry on the GitHub page.

  5. Joaquim March 23, 2017 at 10:20 pm #

    Wow, exactly what I wanted. Thank you for directing me here.
    the pip install is working but it doesn’t seems to work in virtualenv. It ask that python should be installed as a framework. There is a workaround ?

    • Adrian Rosebrock March 25, 2017 at 9:29 am #

      I’ve used visual-logging inside Python virtual environments, it should work just fine. Perhaps this is due to another package you may have installed?

  6. Ben August 23, 2017 at 4:05 pm #

    It generated a html file, but cannot see the images. Tried to open using Firefox and Chrome on Ubuntu. Do you know the reason?

    As you may know, the generated html file is not a complete html file; it only contains four plus <img src="data:image/png;base64, … parts.

  7. Ben Kang August 24, 2017 at 9:50 am #

    Try your demo code. However, there were no images shown in the browsers I tested (Firefox and Chrome on Ubuntu 14.04 and Safari on macOS). Is there any thing I missed? Or do you know why it did work?

    PS. I left a reply after testing on Ubuntu, but where is my previous reply?

    • Adrian Rosebrock August 24, 2017 at 3:28 pm #

      Hi Ben:

      1. The PyImageSearch blog gets a lot of spam so I actually have to manually approve comments before they are displayed. After submitting a comment you’ll see a message that says your comment is awaiting moderation. I normally go through comments every 48-72 hours.

      2. It’s very odd that you can’t see any images in the output log file. Which version of OpenCV and Python are you using?

      • Bob Estes September 27, 2017 at 1:42 pm #

        My html isn’t being rendered in my previous comments.

        There is an issue and a pull request to fix this outstanding on the visual-logging git repo.

        • Adrian Rosebrock September 28, 2017 at 9:10 am #

          Thanks for sharing, Bob!

        • Daniel November 8, 2017 at 6:33 am #

          Same Problem here… any fix yet?

Leave a Reply