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:

$ pip install visual-logging

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:

(cv)annalee:VisualLogging adrianrosebrock$ git clone https://github.com/dchaplinsky/visual-logging.git Cloning into 'visual-logging'... remote: Counting objects: 137, done. remote: Total 137 (delta 0), reused 0 (delta 0) Receiving objects: 100% (137/137), 361.23 KiB | 0 bytes/s, done. Resolving deltas: 100% (70/70), done. Checking connectivity... done. (cv)annalee:VisualLogging adrianrosebrock$ cd visual-logging/ (cv)annalee:visual-logging adrianrosebrock$ python setup.py install

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:

# import the necessary packages from logging import FileHandler from vlogging import VisualRecord import logging import cv2 # open the logging file logger = logging.getLogger("visual_logging_example") fh = FileHandler("demo.html", mode = "w") # set the logger attributes logger.setLevel(logging.DEBUG) logger.addHandler(fh) # load our example image and convert it to grayscale image = cv2.imread("lex.jpg") image = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY) # loop over some varying sigma sizes for s in xrange(3, 11, 2): # blur the image and detect edges blurred = cv2.GaussianBlur(image, (s, s), 0) edged = cv2.Canny(blurred, 75, 200) logger.debug(VisualRecord(("Detected edges using sigma = %d" % (s)), [blurred, edged], fmt = "png"))

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:

$ python visual_logging_example.py

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:

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.

Summary

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!

