https://doi.org/10.5201/ipol.2011.g_zwld
Tip revision: f67dafb5664189be7b568fb02d2bf8391831e9ee authored by Software Heritage on 01 January 2010, 00:00:00 UTC
ipol: Deposit 696 in collection ipol
ipol: Deposit 696 in collection ipol
Tip revision: f67dafb
readme.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head><title>Zhang-Wu LMMSE Image Demosaicking</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<style>
th {
padding:3px;
padding-left:8px;
padding-right:8px;
font-weight:normal;
background:#E8F0F8;
}
#t1 td {
padding:3px;
padding-left:8px;
padding-right:8px;
border-bottom:1px solid #F0F0F0;
}
pre.code {
margin-left:18px;
padding:8px;
border-left:4px solid #bfd6ed;
background:#E8F0F8;
}
span.comment {
color:#404040;
font-style:italic;
}
span.lineno {
font-size:80%;
color:#6D9ACE;
}
span.change {
font-weight:bold;
color:black;
}
</style>
</head>
<body>
<div style="width:800px;margin-left:30px;">
<h1>Zhang-Wu LMMSE Image Demosaicking</h1>
<p>Pascal Getreuer</p>
<p>This software was written by
<a href="mailto:getreuer@gmail.com">Pascal Getreuer</a> and
is distributed under the terms of the simplified BSD licence.</p>
<h3>Contents</h3>
<ol>
<li><a href="#overview">Overview</a></li>
<li><a href="#compiling">Compiling</a></li>
<li><a href="#demo">Program Demo</a></li>
<li><a href="#usage">Program Usage</a></li>
<li><a href="#license">Simplified BSD License</a></li>
</ol>
<h2 id="overview">1. Overview</h2>
<p>This package implements the contour stencil windowed interpolation method as
described in the accompanying IPOL demo “Zhang-Wu LMMSE Image Demosaicking .”
The method and bilinear demosaicing are implemented in C as command line programs
<tt>dmzhangwu</tt> and <tt>dmbilinear</tt>.</p>
<p>Also included are sources for building <tt>mosaic</tt> and <tt>imdiff</tt>,
useful command line tools for mosaicing and comparing images.</p>
<p>If Doxygen and Graphviz are installed, HTML documentation of the project source code is generated by</p>
<pre class="code">
doxygen doxygen.conf
</pre>
<h2 id="compiling">2. Compiling</h2>
<p>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:</p>
<table id="t1" border="0" cellspacing="0" style="text-align:center;margin-left:30px">
<tr><th>Format</th><th>Library</th><th>Add preprocessor flag</th></tr>
<tr><td>JPEG</td><td><a href="http://www.ijg.org">libjpeg</a></td><td><tt>LIBJPEG_SUPPORT</tt></td></tr>
<tr><td>PNG</td><td><a href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td><td><tt>LIBPNG_SUPPORT</tt></td></tr>
<tr><td>TIFF</td><td><a href="http://www.remotesensing.org/libtiff">libtiff</a></td><td><tt>LIBTIFF_SUPPORT</tt></td></tr>
<tr><td>BMP</td><td>(native)</td><td>—</td></tr>
</table>
<h3>2.1. Compiling on Linux or Mac OSX</h3>
<h4>Installing Libraries</h4>
<p>On Ubuntu and other Debian-based Linux systems, the libraries can be installed by running the following line in a terminal:</p>
<pre class="code">
sudo apt-get install build-essential libjpeg libjpeg-dev libpng libpng-dev libtiff libtif-dev
</pre>
<p>On Fedora:</p>
<pre class="code">
sudo yum install gcc libjpeg libjpeg-devel libpng libpng-devel libtiff libtiff-devel
</pre>
<p>On Mac OSX, the libraries can be installed with <a href="http://www.finkproject.org">Fink</a>:
<pre class="code">
sudo fink install libjpeg libpng libtiff
</pre>
<h4>Compiling</h4>
<p>To compile, extract the package, <tt>cd</tt> into the <tt>dmzhangwu-src</tt> folder, and run <tt>make</tt>:</p>
<pre class="code">
tar -xf dmzhangwu-src.tar.gz
cd dmzhangwu-src
make -f makefile.gcc
</pre>
<p>This should produce four executables <tt>dmzhangwu</tt>, <tt>dmbilinear</tt>, <tt>mosaic</tt>, and <tt>imdiff</tt>.</p>
<h4>Troubleshooting</h4>
<p>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.</p>
<pre class="code">
<span class="comment">##
# 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).</span>
LDLIBJPEG=-ljpeg
LDLIBPNG=-lpng
LDLIBTIFF=-ltiff
</pre>
<p>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</p>
<pre class="code">
<span class="comment"><span class="change">#LDLIBJPEG=-ljpeg</span></span>
LDLIBPNG=-lpng
<span class="comment"><span class="change">#LDLIBTIFF=-ltiff</span></span>
</pre>
<h3>2.2. Compiling on Windows</h3>
<p>The code can be compiled using Microsoft Visual C++ (MSVC). <a href="http://www.microsoft.com/express/windows">Microsoft Visual Studio Express</a> 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.</p>
<p>These instructions assume familiarity with the MS-DOS Command Prompt. See for example
<a href="http://www.c3scripts.com/tutorials/msdos/open-window.html">How to use DOS</a>.</p>
<h4>Compiling without Libraries (BMP only)</h4>
<p>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 <tt>vcvarsall.bat</tt>.) To compile, use <tt>cd</tt> to navigate into the <tt>dmzhangwu-src</tt> folder and run <tt>nmake</tt>:</p>
<pre class="code">
cd c:\projects\dmzhangwu-src
nmake -f makefile.vc all
</pre>
<p>This should produce four executables <tt>dmzhangwu.exe</tt>, <tt>dmbilinear.exe</tt>, <tt>mosaic.exe</tt>, and <tt>imdiff.exe</tt>.</p>
<h4>Compiling with Libraries (JPEG and PNG)</h4>
<p>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.</p>
<p>First, download the libjpeg, libpng, and also the zlib library sources. The zlib library is needed to compile libpng.</p>
<ul>
<li>libjpeg sources: <a href="http://www.ijg.org/files/jpegsr8b.zip">http://www.ijg.org/files/jpegsr8b.zip</a></li>
<li>libpng sources: <a href="http://download.sourceforge.net/libpng/lpng143.zip">http://download.sourceforge.net/libpng/lpng143.zip</a></li>
<li>zlib sources: <a href="http://gnuwin32.sourceforge.net/downlinks/zlib-src-zip.php">http://gnuwin32.sourceforge.net/downlinks/zlib-src-zip.php</a></li>
</ul>
<p>Create a folder to contain the libraries, <tt>C:\libs</tt> for
instance. Unzip the library sources into the libs folder so that they are structured as</p>
<table cellspacing="0" style="font-size:50%;margin-left:30px">
<tr><td colspan="2" style="font-size:230%"><tt>libs</tt></td><td> </td></tr>
<tr><td> </td>
<td style="border-left:1px solid gray;border-bottom:1px solid gray;"> </td>
<td rowspan="2" valign="middle" style="font-size:230%"><tt>jpeg-8b</tt></td></tr>
<tr><td> </td>
<td style="border-left:1px solid gray;"> </td></tr>
<tr><td> </td>
<td style="border-left:1px solid gray;border-bottom:1px solid gray;"> </td>
<td rowspan="2" valign="middle" style="font-size:230%"><tt>lpng143</tt></td></tr>
<tr><td> </td><td style="border-left:1px solid gray;"> </td></tr>
<tr><td> </td>
<td style="border-left:1px solid gray;border-bottom:1px solid gray;"> </td>
<td rowspan="2" valign="middle" style="font-size:230%"><tt>zlib</tt></td></tr>
<tr><td> </td><td> </td></tr>
</table>
<p>This structure will help keep the code organized. Take care to rename the folder for zlib
to “<tt>zlib</tt>” 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.</p>
<p><b>Building libjpeg</b></p>
<ol>
<li>Rename <tt>jconfig.vc</tt> to <tt>jconfig.h</tt>.</li>
<li>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 <tt>vcvarsall.bat</tt>. Navigate into <tt>libs\jpeg-8b</tt> and run
<pre class="code">
nmake -f makefile.vc libjpeg.lib
</pre>
This should produce <tt>libjpeg.lib</tt>.</li>
</ol>
<p><b>Building zlib</b></p>
<ol>
<li>Change <tt>zconf.h</tt> line 287 to “<tt>#if 0</tt>,”
<pre class="code">
<span class="lineno">287</span> <span class="change">#if 0</span> <span class="comment">/* HAVE_UNISTD_H -- this line is updated by ./configure */</span>
<span class="lineno">288</span> # include <sys/types.h> <span class="comment">/* for off_t */</span>
<span class="lineno">289</span> # include <unistd.h> <span class="comment">/* for SEEK_* and off_t */</span>
</pre></li>
<li>Open a Visual Studio Command Prompt (see step 2 for libjpeg), go into <tt>zlib\projects\visualc6</tt>, and run
<pre class="code">
vcbuild -upgrade zlib.dsp
vcbuild zlib.vcproj "LIB Release|Win32"
</pre>
This should produce a folder “<tt>Win32_LIB_Release</tt>” containing <tt>zlib.lib</tt>.</li>
<li>Copy <tt>zconf.h</tt>, <tt>zlib.h</tt>, and <tt>zlib.lib</tt> to
<tt>libs\zlib</tt> (libpng will look here).</li>
</ol>
<p><b>Building libpng</b></p>
<ol>
<li>First build zlib.</li>
<li>Change <tt>-MD</tt> to <tt>-MT</tt> in CFLAGS in <tt>lpng143\scripts\makefile.vcwin32</tt>
<pre class="code">
CFLAGS = -nologo -DPNG_NO_MMX_CODE <span class="change">-MT</span> -O2 -W3 -I..\zlib
</pre>
</li>
<li>From a Visual Studio Command Prompt, go into <tt>lpng143</tt> and run
<pre class="code">
nmake -f scripts\makefile.vcwin32
</pre>
This should produce <tt>libpng.lib</tt>.</li>
</ol>
<p>Once the libraries are built, <tt>dmzhangwu</tt> can be compiled with JPEG and/or PNG support
by adjusting its makefile. Uncomment and edit the lines at the top of <tt>dmzhangwu-src\makefile.vc</tt> to
reflect the locations of libjpeg, libpng, and zlib:</p>
<pre class="code">
<span class="comment">#
# Uncomment and edit the following lines for JPEG support.
#</span>
LIBJPEG_DIR = "C:/libs/jpeg-8b"
LIBJPEG_INCLUDE = -I$(LIBJPEG_DIR)
LIBJPEG_LIB = $(LIBJPEG_DIR)/libjpeg.lib
<span class="comment">#
# Uncomment and edit the following lines for PNG support.
#</span>
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
</pre>
<p>The makefile will automatically add the corresponding preprocessor symbols based on which libraries are defined.
Then from a Visual Studio Command Prompt, compile with</p>
<pre class="code">
nmake -f makefile.vc all
</pre>
<p>This should produce <tt>dmzhangwu.exe</tt>, <tt>dmbilinear.exe</tt>, <tt>mosaic.exe</tt>, and <tt>imdiff.exe</tt>
with compiled support for JPEG and/or PNG.</p>
<p>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.</p>
<h2 id="demo">3. Program Demo</h2>
<p>A script called “demo” is included to run an example interpolation with the
program. There is also an equivalent BAT program for MS-DOS.</p>
<table border="0px" style="margin-left:30px">
<tr><td><tt>demo</tt></td><td> </td><td>sh script (UNIX)</td></tr>
<tr><td><tt>demo.bat</tt></td><td> </td><td>MS-DOS batch script (Windows)</td></tr>
</table>
<p>To run the demo, open a terminal, navigate to the <tt>dmzhangwu-src</tt> directory, and
enter the command <tt>./demo</tt> (UNIX) or <tt>demo.bat</tt> (Windows).</p>
<p>Image credits: the demo test image is by
<a href="http://armi.usgs.gov/gallery/detail.php?search=Genus&subsearch=Bufo&id=323">John D. Willson, USGS Amphibian Research and Monitoring Initiative</a>.</p>
<h2 id="usage">4. Program Usage</h2>
<p>The usage syntax for <tt>dmzhangwu</tt> is</p>
<pre class="code">
dmzhangwu -p <pattern> <input file> <output file>
</pre>
<p>where <tt><pattern></tt> specifies the CFA pattern:</p>
<div style="float:left;margin-left:1em;text-align:center">
<tt>RGGB</tt>
<table border="0" cellspacing="1" style="font-size:80%">
<tr><td style="background:#F00;width:1em">R</td><td style="background:#0F0;width:1em">G</td></tr>
<tr><td style="background:#0F0;width:1em">G</td><td style="background:#00F;width:1em">B</td></tr>
</table>
</div>
<div style="float:left;margin-left:1em;text-align:center">
<tt>GRBG</tt>
<table border="0" cellspacing="1" style="font-size:80%">
<tr><td style="background:#0F0;width:1em">G</td><td style="background:#F00;width:1em">R</td></tr>
<tr><td style="background:#00F;width:1em">B</td><td style="background:#0F0;width:1em">G</td></tr>
</table>
</div>
<div style="float:left;margin-left:1em;text-align:center">
<tt>GBRG</tt>
<table border="0" cellspacing="1" style="font-size:80%">
<tr><td style="background:#0F0;width:1em">G</td><td style="background:#00F;width:1em">B</td></tr>
<tr><td style="background:#F00;width:1em">R</td><td style="background:#0F0;width:1em">G</td></tr>
</table>
</div>
<div style="float:left;margin-left:1em;text-align:center">
<tt>BGGR</tt>
<table border="0" cellspacing="1" style="font-size:80%">
<tr><td style="background:#00F;width:1em">B</td><td style="background:#0F0;width:1em">G</td></tr>
<tr><td style="background:#0F0;width:1em">G</td><td style="background:#F00;width:1em">R</td></tr>
</table>
</div>
<div style="clear:left"> </div>
<p>For example,</p>
<pre class="code">
dmzhangwu -p RGGB mosaiced.bmp demosaiced.bmp
</pre>
<p><b>Sorry, only BMP/JPEG/PNG/TIFF images are supported.</b></p>
<p>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.</p>
<p>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 <tt>convert</tt> from <a href="http://www.imagemagick.org">ImageMagick</a>.
Alternatively, an image can be converted by opening the image in an image editor, selecting “Save As...,” and setting “Type” to a supported format.</p>
<p>The usage information is also displayed by <tt>dmzhangwu</tt> if executed without arguments.</p>
<p>The package also includes three tools:</p>
<ul>
<li><tt>dmbilinear</tt>: demosaicing by bilinear interpolation.</li>
<li><tt>mosaic</tt>: subsamples an image on the Bayer CFA.</li>
<li><tt>imdiff</tt>: compares two images with a specified metric (e.g., PSNR or MSSIM). </li>
</ul>
<p>Run these programs without arguments for usage details.</p>
<h2 id="license">5. Simplified BSD License</h2>
<p>Copyright © 2010–2011, Pascal Getreuer<br>
All rights reserved.</p>
<p>Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:</p>
<ul>
<li>Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.</li>
<li>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.</li>
</ul>
<p>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.</p>
<p> </p>
<p style="font-size:80%">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.</p>
</div>
</body>
</html>
