README.txt:
IMAGE COLOR CUBE DIMENSIONAL FILTERING AND VISUALIZATION
This software is written by Jose-Luis Lisani <joseluis.lisani@uib.es> and
distributed under the terms of the GPLv3 licence <http://www.gnu.org/licenses/>
INFORMATION ABOUT PROGRAM COMPILATION AND EXECUTION
System requirements:
- Operating systems.
The current version is compilable under Unix/Linux, Mac OS and Windows OS.
- Dependencies.
This code requires the libpng library.
The code requires the Eigen library <http://eigen.tuxfamily.org>,
but it does not need to be installed, since version 3.0.0 of the
code is included within the source code.
- Image format.
Only the PNG format is supported.
Source code updates:
Check for updates of the code here:
<http://dev.ipol.im/~lisani/src_updates/>
Compilation:
Step 1 : Download from IPOL paper page the file "rgbprocess.tar.gz".
The content of this .tar.gz archive is :
a) io_png/io_png.h, io_png/io_png.c:
basic library to read/write PNG image format
b) Eigen:
Eigen template library for linear algebra, version 3.0.0
c) cppcode/mdmath.h, cppcode/mdmath.cpp:
code for PCA computation (using Eigen library)
d) cppcode/micIPOL.h, cppcode/miscIPOL.cpp:
miscellaneous vector operations (normalization, scalar and vectorial
product, ...)
e) cppcode/colorfilteringIPOL.h, cppcode/colorfilteringIPOL.cpp:
functions implementing LLP algorithm
f) cppcode/rgbcubeIPOL.h, cppcode/rgbcubeIPOL.cpp:
main functions for color filtering and visualization
g) rgbprocess_lib.h, rgbprocess_lib.cpp:
convert images to appropriate data structures and calls filtering
and visualization functions
h) rgbprocess.cpp:
main program
i) makefile, makefileDebug:
makefiles (debug makefile includes -g compilation directive)
j) test/test.png:
test image
k) README.txt: this file
Step 2 : To compile, once the zip archive files are saved in a directory,
execute the "make" command :
> make
Execution:
To run the program execute "rgbprocess" with one of the following options:
filter: filters the colors of an image using applies LLP2 algorithm
Input: input image (PNG format)
Output: output image (PNG format)
rmisolated: removes isolated color points from an image
Input: input image (PNG format)
Output: output image (PNG format)
pcaviews: creates 3 images displaying the principal views of the
RGB cube of a color image, the principal axis are computed by
Principal Components Analysis of the distribution of colors
of a reference image
Input: input and reference images (PNG format),
dimensions of output images
Output: output images (PNG format)
pcaviewsB: creates 1 image displaying the 3 principal views of the
RGB cube of a color image, the principal axis are computed by
Principal Components Analysis of the distribution of colors
of a reference image
Input: input and reference images (PNG format),
dimensions of the views displayed in the output image
Output: output image (PNG format)
densityimage: given an input color image creates a grey-scale image where
each pixel is displayed with a grey level proportional to
the density of its color in the input image
Input: color image (PNG format)
Output: density image (grey-level image, PNG format)
densityviews: creates 1 image displaying the 3 principal views of the RGB
cube of a color image, each color point is displayed with a
grey level proportional to its density in the color cube
(lighter for higher densities), the principal axis are
computed by Principal Components Analysis of the
distribution of colors of a reference image
Input: input and reference images (PNG format),
dimensions of the views displayed in the output image,
densities image (optional)
Output: output image (PNG format)
mergeimages: creates an output image (out) from two inputs (in1, in2) such
that out=in1 except at pixels with (0, 0, 0) RGB value,
which are replaced by pixels of in2
Input: input images (PNG format)
Output: output image (PNG format)
RGBviewsparams: computes parameters (position and coordinates vectors)
of a set of projection planes for displaying different
views of the RGB color cube. Stores results in a text file
Output: text file
RGBviews: creates a set of images displaying different views of the RGB
cube of a color image
Input: input image (PNG format) and text file with information
about the projection planes,
dimensions of the output image,
flag displayDensity (if displayDensity=1,
each color point is displayed with a grey level value
proportional to its density in RGB space, else display
the point with its original color),
densities image (optional, PNG format)
Output: output image (PNG format)
combineviews: creates a set of output images from a set of three input
images, for each output image the input images are arranged
in two rows: the first row displays two inputs and the
second row the third input
Input: text file with information about the number of output
images,
input images (PNG format)
Output: output images (PNG format)
computeRMSE: compute Root Mean Squared Error (RMSE)
and Average Distance (dmean) between two sets
of colors in RGB space
Input: input image (PNG format)
Output: RMSE and dmean values
countcolors: count the number of different colors in an image
Input: input image (PNG format)
Output: number of colors of the input image
RGB2VRML2: creates a file in VRML 2.0 format containing the list of color
points of an input image. Each point is either displayed with
its original RGB color or with a gray level value proportional
to the density of the color.
Input: input image (PNG format),
flag displayDensity (if displayDensity=1,
each color point is displayed with a grey level value
proportional to its density in RGB space, else display
the point with its original color),
densities image (optional, PNG format)
Output: VRML2.0 text file
Example:
sequence of instructions needed to generate the images of the IPOL demo
1) Remove isolated color points from original image:
rgbprocess rmisolated test/test.png test/testIn.png
2) Apply LLP2:
rgbprocess filter test/testIn.png test/testOut.png
3) Generate perspective views of the color cube of the original (without isolated colors) and filtered images:
3a) Get projection planes parameters:
rgbprocess RGBviewsparams test/RGBviewsparams.txt
3b, 3c)Generate views:
rgbprocess RGBviews test/testIn.png test/RGBviewsparams.txt test/testInRGB 300 300 0
rgbprocess RGBviews test/testOut.png test/RGBviewsparams.txt test/testOutRGB 300 300 0
4) Generate perspective views of the color densities of the filtered image:
(densities image)
rgbprocess densityimage test/testOut.png test/testOutdsty.png
(generate views, from precomputed density image)
rgbprocess RGBviews test/testOut.png test/RGBviewsparams.txt test/testOutRGBdsty 300 300 1 test/testOutdsty.png
5) Combine each perspective view of original, filtered and density color cube
into a single image:
rgbprocess combineviews test/RGBviewsparams.txt test/testInRGB test/testOutRGB test/testOutRGBdsty test/combinedRGB
6) Final output image: display pixels with isolated colors with their original
color
rgbprocess mergeimages test/testOut.png test/test.png test/testOutB.png
7) Count number of colors in final output image:
rgbprocess countcolors test/testOutB.png
8) Compute RMSE and Average Distance between colors of original and output
images:
rgbprocess computeRMSE test/test.png test/testOutB.png
9) Save lists of color points in VRML 2.0 format
rgbprocess RGB2VRML2 test/testIn.png test/testInRGB.wrl 0
rgbprocess RGB2VRML2 test/testOut.png test/testOutRGB.wrl 0
(density, from precomputed density image)
rgbprocess RGB2VRML2 test/testOut.png test/testOutRGBd.wrl 1 test/testOutdsty.png
Note from the author:
The source code was updated on July 5, 2011 to fix a bug that occurs on
images whose colors are sparsely distributed in RGB space.
The modification only affects line 865 of colorfilteringIPOL.cpp:
Old line:
dprev/=(float) ndiff;
Replaced by:
if (ndiff > 0) dprev/=(float) ndiff;
1.6.3