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;