Image Demosaicking with Contour Stencils
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
Image Demosaicking with Contour Stencils Documentation
Image Demosaicking with Contour Stencils

Image Demosaicking with Contour Stencils

Version 20130706 (July 6, 2013)
Pascal Getreuer, getreuer@cmla.ens-cachan.fr, CMLA, ENS Cachan

Please cite IPOL article “Image Demosaicking with Contour Stencils” if you publish results obtained with this software.

This software was written by Pascal Getreuer and is distributed under the terms of the simplified BSD license.

Contents

  1. Overview
  2. Compiling
  3. Program Demo
  4. Program Usage
  5. Simplified BSD License

1. Overview

This C source code is a revision of the code accompanying Image Processing On Line (IPOL) article “Image Demosaicking with Contour Stencils” at

http://dx.doi.org/10.5201/ipol.2012.g-dwcs

The original peer-reviewed IPOL version of the code is available from the article page.

Future software releases and updates will be posted at

http://dev.ipol.im/~getreuer/code

Compared to the IPOL version, this revision differs in the following ways:

  • Included zlib.h in imageio.c for compatibility with libpng 1.5 and later
  • Improved makefiles for correct linker argument order
  • Bug fix in imageio.c when writing RGBA-mode PNG images
  • Renamed LIBxxx_SUPPORT flags more concisely as USE_LIBxxx

2. Compiling

The compilation is configurable. No libraries are required to compile, but in this case, only BMP images are supported. JPEG, PNG, and TIFF support can be added by compiling with the libaries as summarized in the table:

FormatLibraryAdd preprocessor flag
JPEGlibjpegUSE_LIBJPEG
PNGlibpngUSE_LIBPNG
TIFFlibtiffUSE_LIBTIFF
BMP(native)

2.1. Compiling on Linux or Mac OSX

Installing Libraries

On Ubuntu and other Debian-based Linux systems, the libraries can be installed by running the following line in a terminal:

sudo apt-get install build-essential libjpeg libjpeg-dev libpng libpng-dev libtiff libtif-dev

On Fedora:

sudo yum install gcc libjpeg libjpeg-devel libpng libpng-devel libtiff libtiff-devel

On Mac OSX, the libraries can be installed with Fink:

sudo fink install libjpeg libpng libtiff

Compiling

To compile, extract the package, cd into the dmcswl1_20130706 folder, and run make:

tar -xf dmcswl1_20130706.tgz
cd dmcswl1_20130706
make -f makefile.gcc

This should produce four executables dmcswl1, dmbilinear, mosaic, and imdiff.

The radius of the contour stencil neighborhood can be specified by changing the RADIUS variable in makefile.gcc. The suggested radius is 2.5. The makefile runs the included program gen_mstencils to generate the file mstencils.c according to the specified radius.

Troubleshooting

The included makefile will try to use libjpeg, libpng, and libtiff. If linking with these libraries is a problem, they can be disabled by commenting their line at the top of the makefile.

##
# The following three statements determine the build configuration.
# For handling different image formats, the program can be linked with
# the libjpeg, libpng, and libtiff libraries.  For each library, set
# the flags needed for linking.  To disable use of a library, comment
# its statement.  You can disable all three (BMP is always supported).
LDLIBJPEG=-ljpeg
LDLIBPNG=-lpng
LDLIBTIFF=-ltiff

The makefile will automatically set the corresponding preprocessor symbols; only these lines need to be changed. For example, to disable libjpeg and libtiff but to keep libpng support, comment the first and third lines

#LDLIBJPEG=-ljpeg
LDLIBPNG=-lpng
#LDLIBTIFF=-ltiff

If Doxygen and Graphviz are installed, HTML documentation of the project source code is generated by

doxygen doxygen.conf

2.2. Compiling on Windows

The code can be compiled using Microsoft Visual C++ (MSVC). Microsoft Visual Studio Express can be downloaded for free. Since libraries are problematic under Windows, no libraries are used by default and the program will only support BMP images.

These instructions assume familiarity with the MS-DOS Command Prompt. See for example How to use DOS.

The radius of the contour stencil neighborhood can be specified by changing the RADIUS variable in makefile.vc. The suggested radius is 2.5. The makefile runs the included program gen_mstencils.exe to generate the file mstencils.c according to the specified radius.

Compiling without Libraries (BMP only)

First, open a command prompt with the visual studio environment by clicking Start Menu → Microsoft Visual Studio → Visual Studio Tools → Visual Studio Command Prompt. (Alternatively, open a regular command prompt and run the vcvarsall.bat.) To compile, use cd to navigate into the dmcswl1_20130706 folder and run nmake:

cd c:\projects\dmcswl1_20130706
nmake -f makefile.vc all

This should produce four executables dmcswl1.exe, dmbilinear.exe, mosaic.exe, and imdiff.exe.

Compiling with Libraries (JPEG and PNG)

It is possible under Windows to compile the program with libjpeg and libpng to add support for JPEG and PNG images (libtiff should be possible as well, but it is not explored here). To avoid incompatibility problems, the reliable way to compile with a library is to build that library from source using the same compiler.

First, download the libjpeg, libpng, and also the zlib library sources. The zlib library is needed to compile libpng.

Create a folder to contain the libraries, C:\libs for instance. Unzip the library sources into the libs folder so that they are structured as

libs 
    jpeg-8b
   
    lpng143
  
    zlib
  

This structure will help keep the code organized. Take care to rename the folder for zlib to “zlib” since libpng will look for it. Below are the steps to build each library. If you want JPEG support, build libjpeg. For PNG support, build zlib first and then build libpng.

Building libjpeg

  1. Rename jconfig.vc to jconfig.h.
  2. Open a Visual Studio Command Prompt by clicking Start Menu → Microsoft Visual Studio → Visual Studio Tools → Visual Studio Command Prompt, or open a regular command prompt and run the vcvarsall.bat. Navigate into libs\jpeg-8b and run
    nmake -f makefile.vc libjpeg.lib
    
    This should produce libjpeg.lib.

Building zlib

  1. Change zconf.h line 287 to “#if 0,”
    287  #if 0                    /* HAVE_UNISTD_H -- this line is updated by ./configure */
    288  #  include <sys/types.h> /* for off_t */
    289  #  include <unistd.h>    /* for SEEK_* and off_t */
    
  2. Open a Visual Studio Command Prompt (see step 2 for libjpeg), go into zlib\projects\visualc6, and run
    vcbuild -upgrade zlib.dsp
    vcbuild zlib.vcproj "LIB Release|Win32"
    
    This should produce a folder “Win32_LIB_Release” containing zlib.lib.
  3. Copy zconf.h, zlib.h, and zlib.lib to libs\zlib (libpng will look here).

Building libpng

  1. First build zlib.
  2. Change -MD to -MT in CFLAGS in lpng143\scripts\makefile.vcwin32
    CFLAGS  = -nologo -DPNG_NO_MMX_CODE -MT -O2 -W3 -I..\zlib
    
  3. From a Visual Studio Command Prompt, go into lpng143 and run
    nmake -f scripts\makefile.vcwin32
    
    This should produce libpng.lib.

Once the libraries are built, dmcswl1 can be compiled with JPEG and/or PNG support by adjusting its makefile. Uncomment and edit the lines at the top of dmcswl1_20130706\makefile.vc to reflect the locations of libjpeg, libpng, and zlib:

#
# Uncomment and edit the following lines for JPEG support.
#
LIBJPEG_DIR     = "C:/libs/jpeg-8b"
LIBJPEG_INCLUDE = -I$(LIBJPEG_DIR)
LIBJPEG_LIB     = $(LIBJPEG_DIR)/libjpeg.lib

#
# Uncomment and edit the following lines for PNG support.
#
ZLIB_DIR     = "C:/libs/zlib"
ZLIB_INCLUDE = -I$(ZLIB_DIR)
ZLIB_LIB     = $(ZLIB_DIR)/zlib.lib
LIBPNG_DIR     = "C:/libs/lpng143"
LIBPNG_INCLUDE = -I$(LIBPNG_DIR)
LIBPNG_LIB     = $(LIBPNG_DIR)/libpng.lib

The makefile will automatically add the corresponding preprocessor symbols based on which libraries are defined. Then from a Visual Studio Command Prompt, compile with

nmake -f makefile.vc all

This should produce dmcswl1.exe, dmbilinear.exe, mosaic.exe, and imdiff.exe with compiled support for JPEG and/or PNG.

Under the approach shown here, libraries are statically linked. The executables do not depend on libjpeg, libpng, or zlib DLL files, so they should still work if transferred to another Windows machine.

3. Program Demo

A script called “demo” is included to run an example interpolation with the program. There is also an equivalent BAT program for MS-DOS.

demo   sh script (UNIX)
demo.bat MS-DOS batch script (Windows)

To run the demo, open a terminal, navigate to the dmcswl1_20130706 directory, and enter the command ./demo (UNIX) or demo.bat (Windows).

Image credits: the demo test image is by John D. Willson, USGS Amphibian Research and Monitoring Initiative.

4. Program Usage

The usage syntax for dmcswl1 is

dmcswl1 [options] <input file> <output file>

Program options

-p <pattern>   CFA pattern
-sShow estimated contours instead of demosaicing. The output is written as an EPS file.
-EDisplay energy value after each iteration.
-a <number>α, chroma weight (default 1.8)
-e <number>ε, graph weight (default 0.15)
-f <number>σ, graph spatial filtering parameter (default 0.6)
-t <number>convergence tolerance (default 0.001)
-m <number>maximum number of iterations (default 250)

The option <pattern> specifies the CFA pattern:

RGGB
RG
GB
GRBG
GR
BG
GBRG
GB
RG
BGGR
BG
GR
 

For example,

dmcswl1 -p RGGB mosaiced.bmp demosaiced.bmp

Sorry, only BMP/JPEG/PNG/TIFF images are supported.

The program only supports BMP, JPEG, PNG, and TIFF images. If you disabled some of the libraries when compiling, the support for the corresponding formats will be disabled. Regardless of compilation settings, the program always supports Windows Bitmap BMP images.

To use an image that is in an unsupported format, please convert it to a supported format. Images can be conveniently converted using the command line program convert from ImageMagick. Alternatively, an image can be converted by opening the image in an image editor, selecting “Save As...,” and setting “Type” to a supported format.

The usage information is also displayed by dmcswl1 if executed without arguments.

This package includes imdiff, an image difference calculator that compares two images with a specified metric. The usage syntax of imdiff is

imdiff [options] <exact file> <distorted file>

Options:

-m <metric>   metric to use for comparison, choices are
 maxmaximum absolute difference, maxn |An − Bn|
 msemean squared error, 1/N sum |An − Bn|2
 rmseroot mean squared error, (MSE)½
 psnrpeak signal-to-noise ratio, −10 log10(MSE/2552)
 mssim   mean structural similarity index
-s   compute metric separately for each channel
-p <pad>   remove a margin of <pad> pixels before comparison
-D <number>   D parameter for difference image (explained below)
-q <number> quality for saving JPEG images (0 to 100)

Alternatively, a difference image is generated by the syntax

imdiff [-D <number>] <exact file> <distorted file> <output file>

The difference image is computed as Dn = 255/D (AnBn) + 255/2. Values outside of the range [0,255] are saturated.

The package also includes

  • dmbilinear: demosaicing by bilinear interpolation.
  • mosaic: subsamples an image on the Bayer CFA.

Run these programs without arguments for further usage details.

5. Simplified BSD License

Copyright © 2010–2011, Pascal Getreuer
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 

This material is based upon work supported by the National Science Foundation under Award No. DMS-1004694. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.