
Coloring
========

``graph_color_ccs``
-------------------

``Image`` [RGB] **graph_color_ccs** ([object *ccs*], object *colors*, ``Choice`` [CC center|20% contour points|voronoi diagram] *method* = 20% contour points)


:Operates on: ``Image`` [OneBit]
:Returns: ``Image`` [RGB]
:Category: Coloring
:Defined in: color.py
:Author: Oliver Christen and Tobias Bolten


Returns an RGB Image where each segment is colored with one of the colors
from *colors* with the constraint that segments adjacent in the 
neighborship graph have different colors.

This function can be used to verify that the pagesegmentation 
e.g. ``cc_analysis`` is working correctly for your image.

The graph coloring algorithm is based on the "6-COLOR" alorithm for
planar graphs, as described in:

    D. Matula, Y. Shiloach, R. Tarjan:
    `Two linear-time algorithms for five-coloring a planar graph.`__
    Tech Rep STAN-CS-80-830, Computer Science Dep., Stanford Univ., 
    Stanford, Calif., 1980

.. __: ftp://db.stanford.edu/pub/cstr/reports/cs/tr/80/830/CS-TR-80-830.pdf

We have modified the algorithm in such way that the color distribution is
balanced, i.e. that each color is assigned approximately to the same
number of nodes (also known as "equitable coloring").

*ccs*:
    ImageList which contains ccs to be colored. Must be views on
    the image an which this method is called.

*colors*:
    list of colors (instances of RGBPixel) which will be used for coloring

*method*:
    Controls the calculation of the neighborhood graph:
            0 = from the CC center points
            1 = from a 20 percent sample of the contour points
            2 = from the exact area Voronoi diagram

.. code:: Python

   ccs = imgage.cc_analysis()
   colors = [ RGBPixel(180, 0, 0),
              RGBPixel(0, 255, 0),
              RGBPixel(0, 0, 255),
              RGBPixel(255, 200, 20),
              RGBPixel(255, 0, 255),
              RGBPixel(50, 150, 50) ]
   rgb = imgage.mycolor_ccs(ccs, colors, 1)

.. note:: *colors* may not contain less than six colors.


