Bilateral Grid Source Code
Current Version is: 0.1 (10/22/2007)
This code has been tested on Windows XP SP2 (32-bit) and Windows Vista (64-bit running as a 32-bit process). One alpha tester managed to compile and run it under Fedora Core 6. It should run on any GPU from the NVIDIA GeForce 8 series and has been tested on the GeForce 8800 GTX and the mobile GeForce 8600M GT on the MacBook Pro. I have not tested it under any AMD hardware.
List of external dependencies
Being a GPU application that also has a GUI, we unfortunately depend on quite a few external libraries. I will try to release a version that depends on
only GLUT, GLEW, and Cg in the future. We use the following:
- Microsoft Visual Studio 2005 (Visual Studio 2003 will probably work but has not been tested. The Intel C++ compiler also works well.)
- Trolltech Qt 4.3.1 (GUI toolkit)
- NVIDIA Cg 1.5 (September 2007) (shaders)
- GLEW 1.4.0 (OpenGL extensions)
- ffmpeg r9017 2007-05-13 (decoding video)
- ffmpeg depends on msinttypes (C99 int types for Visual Studio. We tested with msinttypes r19)
- libcgt 0.1 (my own utility libraries)
Installing external dependencies
- Visual Studio and Cg are straightforward to install.
- The open source version of Qt is only supported by Trolltech under MinGW. To build it using Visual Studio, please follow the instructions below. Trolltech also offers a free license for Academic Users that comes with a very nice installer, documentation, and examples for Windows.
- First, download the Open Source Windows version of Qt 4.3.1. Make sure it's the open source one and not the binary MinGW one.
- Next, follow these instructions to compile it using Visual Studio. When running qconfigure.bat, please use the following options:
- qconfigure.bat msvc2005 -debug-and-release -qt-zlib -qt-gif -qt-libpng -qt-libmng -qt-libtiff -qt-libjpeg
- We use an "unofficial Windows" build of ffmpeg that can be found here.
- Download ffmpeg-r9017-include.tar.bz2 and ffmpeg-r9017-lshared-win32.tar.bz2.
- Those are all you'll need to programmatically access ffmpeg. If the page is down, please email me and I will provide a copy.
- It can be found here
- We used r19.
- It can be found here. Just download the Windows binaries.
- libcgt is my static library of "computer graphics tools".
- Binaries are here
- Sources are here
- INCLUDE path (defined by the environment variable INCLUDE)
- If Qt was built correctly, qmake automatically knows how to #include Qt.
- Put glew.h and wglew.h in a directory called "GL" and put its parent in the include path so that it can be included using "#include <GL/glew.h>". For example, I have glew.h under C:\work\include\GL
- Similarly, for cg.h and cgGL.h, add the parent of the containing directory in the include path. I reference them using "#include Cg/cg.h".
- ffmpeg-r9017-include.tar.bz2 has a single directory inside called "include", which contains a single directory named "ffmpeg". Extract it so that the parent of "ffmpeg" is in the include path. For example, I have it set up as C:\work\include\ffmpeg. The absolute path for swscale.h would be "C:\work\include\ffmpeg\swscale.h". It's referenced as "#include <ffmpeg/swscale.h>".
- For msinttypes, put the directory that contains inttypes.h and stdint.h in your include path. It's referenced as "#include <inttypes.h>"
- For libcgt, put the contents of "include" in your include path. Vector3f.h is referenced as "#include <vecmath/Vector3f.h>"
- Library path (defined by the environment variable LIB)
- Library paths are easier. Just ensure that the directories that contain the .lib files from all the dependencies are in your library path.
- DLL path (defined by the environment variable PATH)
- Make sure all the DLLs from all the dependencies are either in your PATH or copied to the current directory.
Compiling libbilagrid and libcgt
libbilagrid and libcgt both use Qt and are built using qmake. qmake is a fantastic build tool that generates either Makefiles or Visual Studio Projects.
- Building using Makefiles (either libbilagrid or libcgt)
- Extract the .zip
- Generate the makefiles by typing "qmake"
- Type "nmake debug" to build the debug version or "nmake release" to build the release version.
- Building using Visual Studio Projects
- Extract the .zip
- For libcgt, generate a libcgt.vcproj by typing "qmake -t vclib"
- For libbilagrid, generate libbilagrid.vcproj by typing "qmake -t vcapp"
- Open the .vcproj files in the Visual Studio IDE and compile as usual.
Running the tests
libbilagrid operates by parsing a Directed Acyclic Graph of GPU kernels specified in an XML file and pulling data at the output node. The input data is read from the "data" directory. The data files I used for our SIGGRAPH paper are located: here. I have a few batch files set up to get everything started. More graphs and batch files will be forthcoming (along with the associated data).
- Mouse Controls
- Hold the shift key and double click on the image to zoom in to 1:1 mode.
- Holding the shift key while dragging pans.
- Bilateral Filter on 720p video: bilateral.bat
- Local Histogram Equalization: lhe.bat
- Bilateral Grid Painting: gp.bat
- Hold the mouse button down to paint. The initial mouseclick determines the z-level in the grid you're painting at.
- Scribble Interpolation: scribble.bat
- Left click to draw a black stroke. Right click to draw a white stroke.
- Scribbles seem to be a bit buggy. It mysteriously does not seem to run from the commandline but works fine from within the Visual Studio IDE (in either debug or release mode).
- On the same inputs, the OpenGL occlusion query which tests for convergence of the Poisson solver fails for some reason. I welcome any suggestions.
- Upcoming: complex pipelines
- Photographic Style Transfer
- Local Tone Mapping
Email me if you have any problems!
Copyright (c) 2007 Jiawen Chen, Sylvain Paris, Fredo Durand
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.