Imagedb - The Portable Image Debugger


In many applications, especially in graphics research, it is common to have a memory buffer containing raw image data that will be used or manipulated. Frequently, it will be necessary to visualize this data for debugging purposes, as a string buffer or other data primitives can be "visualized" using a call to printf. The printf style of debugging has many advantages - no additional application framework is required; the output remains, even if the program crashes, and can be stored and manipulated independently; and debugging does not interrupt the logical flow or control of the program.

We implement a simple framework for printf-style debugging of images, inspired by the excellent imdebug library written by Bill Baxter, and the imshow functionality of Matlab. Ours is quite similar to the more mature and feature-rich imdebug, though intends to be portable across arbitrary platforms (currently only on Linux), and support network transparency. Currently the program interface is a bit rudimentary, and not entirely robust, but I have found it exceptionally useful in my work.


Programming Interface

The library interface is usable by a client application by including the imagedb.h header, and placing the imagedb executable in the working directory. The interface is as follows:

 
imagedb(void* data, const char* format, ... args )

The syntax is similar to sprintf, in that the first argument contains the address of the image data, the second is a format string that indicates the type of data and how the data is to be shown, and this is followed by a variable length list of arguments that follows the same syntax as in sprintf.

The syntax of format is: "(field=data)*", where the fields are:

 
b:	8*	8-bit per component
	16	16-bit per component
	32	32-bit per component
	32f	Single precision per component
	64f	Double precision per component
 
f:	l	Single luminance value
	la	Luminiance and alpha
	i	Intensity (use same for luminance and alpha)
	rgb*	Three component rgb
	rgba	Four component rgb and alpha
	rgbe	Four component rgb and an exponent
 
w:	width
h:	height
sk:	bytes to skip
rs:	rows to skip after each row
cs:	cols to skip after each col
t:	title text
d:  action when a duplicate title is found
    ignore (i): ignore the duplicate and add as usual (the default)
    replace (r): replace the last item having duplicate title with new image
       this is useful when you are using something as a progress update,
       and the image will be updated many times
    
fr:	title of frame to put into
    If the named frame does not already exist, it will be created
    This allows certain images to be sent to targeted frames, allowing
    side-by-side updates of images
 
flip: flips the image in y (sometimes necessary to match OpenGL ordering)
 
svr:address of server (not necessary for localhost)
pg:	path to client program (not necessary if in path)
The library is affected by the following environment variables
 
IMAGEDB_SERVER:	address of server to send data 
		if ="" or =0, imagedb is disabled
		if undefined, defaults to localhost
		Can set this in program with imagedb_set_server()
 
IMAGEDB_PROGRAM: path to imagedb program
		if undefined, searches $PATH and local directory
		Can set this in program with imagedb_set_program()
Upon calling the imagedb function, the library will create the server on the localhost if so indicated, connect to the server, transmit the image data, and block until the entire image data has been transferred.

User Interface

In the viewer, we have the following functionality:
 
Mouse-drag:	translate image
Mouse-motion: pixel coords and color value under cursor are put in title
-/=:	zoom image
left/right:	move to previous/next image in frame
pgup/pgdown:	move to previous/next image with same tag in frame
l		flip current image in frame
[ ]		change scale
; '		change bias
, .     change gamma
a		perform auto linear rescale
i		set scale=1, bias=0
d		delete current image
c		clears (deletes) all images
f		fit current frame to image, zoom=1
s		change/don't change image in current frame to new data	
e		open new frame viewing current image stack
w		save current image to targa file
z		save all images to single file
q       closes the current extra frame (wont close last one)
 
Menu options:
Channels: Show all RGBA, RGB Only, R Only, G Only, B Only, Alpha As Grey
Save:
   As TGA: Saves the current image as currently rendered to TGA file
   As BMP: Saves the current image as currently rendered to TGA file
      Note that if you want the unscaled image, press 'i' to reset scaling
   As PFM: Saves RGB to the Portable FloatMap format
      Can be loaded back in by passing as cmdline argument
   Stack: Saves all images and the entire state of the program to a .stk file
      Can be loaded back in by passing as cmdline argument
Display 
   Gridlines:  Shows grid over pixels when image is zoomed
   Background: Shows/Hides checkerboard background
Settings: Causes the scale/bias/gamma settings to be per-frame, per-image, or global
 
Single images will be written out as numbered targa files, and multiple images will be written out in our local stack format. An image stack can be loaded into a new instance of imagedb by passing the path to the file as a command line argument.


Portability

I have compiled and tested both the client and the server on 32 and 64-bit Linux, Windows with Cygwin, and Windows with Visual Studio 2005. Makefiles are included for both Linux and Cygwin, and a project file is included for VS2005. Imagedb was intended to be as portable and as minimal as possible, so there are no external library dependencies other than OpenGL and GLUT. It should compile almost anywhere. NOTE: The Visual Studio version depends on the standard WIN32 preprocessor variable being defined to abstract some of the differences in the API.


Known Issues

In some implementations of GLUT, menu clicks are delegated to the window over which the cursor is positioned at the time of the click, which is not necessarily the one on which the menu was originally opened.

The zoom does not zoom into the center of the view, but the top left corner


Source (and Windows binary) imagedb-7-7-2007.zip

Old Source code: imagedb-5-20-2005.tar.gz

This code is being released under the conditions of the GNU Public License. If you find it useful, please drop me a line, I'd love to hear about it.