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!
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.
What's next? We recommend PyImageSearch University.
86+ total classes ā¢ 115+ hours hours of on-demand code walkthrough videos ā¢ Last updated: June 2026
ā ā ā ā ā 4.84 (128 Ratings) ā¢ 16,000+ Students Enrolled
I strongly believe that if you had the right teacher you could master computer vision and deep learning.
Do you think learning computer vision and deep learning has to be time-consuming, overwhelming, and complicated? Or has to involve complex mathematics and equations? Or requires a degree in computer science?
Thatās not the case.
All you need to master computer vision and deep learning is for someone to explain things to you in simple, intuitive terms. And thatās exactly what I do. My mission is to change education and how complex Artificial Intelligence topics are taught.
If you're serious about learning computer vision, your next stop should be PyImageSearch University, the most comprehensive computer vision, deep learning, and OpenCV course online today. Here youāll learn how to successfully and confidently apply computer vision to your work, research, and projects. Join me in computer vision mastery.
Inside PyImageSearch University you'll find:
- ✓ 86+ courses on essential computer vision, deep learning, and OpenCV topics
- ✓ 86 Certificates of Completion
- ✓ 115+ hours hours of on-demand video
- ✓ Brand new courses released regularly, ensuring you can keep up with state-of-the-art techniques
- ✓ Pre-configured Jupyter Notebooks in Google Colab
- ✓ Run all code examples in your web browser ā works on Windows, macOS, and Linux (no dev environment configuration required!)
- ✓ Access to centralized code repos for all 540+ tutorials on PyImageSearch
- ✓ Easy one-click downloads for code, datasets, pre-trained models, etc.
- ✓ Access on mobile, laptop, desktop, etc.
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!
Download the Source Code and FREE 17-page Resource Guide
Enter your email address below to get a .zip of the code and 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!
