colorcorrect 1.0.0

colorcorrect by Shunsuke Aihara - http://argmax.jp

date:

February 2012

description:

Imprement some of color correction algorithms

require:

python3.10 or later
numpy>=2.0
Pillow>=10.0
a C++ compiler (the block based algorithms and the sampled ACE are in C++)

install:

% pip install .

(a C++ compiler is needed; "python -m build" creates sdist and wheel)

test:

% pip install -e .
% python -m unittest discover -s test -p "*_test.py"

impement algorithms:

gray world
     colorcorrect.algorithm.gray_world
     usage: image
max white
    colorcorrect.algorithm.max_white
    usage: image
stretch
    colorcorrect.algorithm.stretch
    usage: image
retinex
    colorcorrect.algorithm.retinex
    usage: image
retinex with adjust (gray world + retinex quadratic mapping)
        colorcorrect.algorithm.retinex_with_adjust
        usage: image
standard deviation weighted grey world
         colorcorrect.algorithm.standard_deviation_weighted_grey_world
         usage: image,subblock width(default:20), subblock height(default:20)
standard deviation and luminance weighted gray world
         colorcorrect.algorithm.standard_deviation_and_luminance_weighted_gray_world
         usage: image,subblock width(default:20), subblock height(default:20)
luminance weighted gray world
          colorcorrect.algorithm.luminance_weighted_gray_world
         usage: image,subblock width(default:20), subblock height(default:20)
(each block based algorithm also has a pure numpy twin with a _python suffix)
automatic color equalization
          colorcorrect.algorithm.automatic_color_equalization
          usage: image,slope(default:10),limit(default:1000),samples(default:500),
                 method(default:"fft"),levels(default:16),seed(default:None),workers(default:None),
                 min_distance(default:None),preserve_chroma(default:False)
          method="fft" evaluates the full image sum of the paper with FFT
          convolutions (exact up to the interpolation over `levels` grey
          levels, deterministic, multi-threaded).  method="sampling" is the
          Monte-Carlo C++ implementation comparing every pixel with
          `samples` random pixels; pass `seed` for reproducible output and
          `min_distance` (default: half the mean sample spacing) to keep a
          sample right next to a pixel from dominating it.
          The saturation function is r(x) = clip(slope*x, -limit, limit) on
          pixel differences in [-255, 255]; only slope/limit matters.
          preserve_chroma=True runs ACE on the luminance only and keeps the
          colour of every pixel (an extension of the paper); combined with
          retinex_with_adjust it adds local contrast without desaturating:

          >>> cca.automatic_color_equalization(cca.retinex_with_adjust(img), preserve_chroma=True)

          alpha gives the slope in the papers' normalised units (overrides
          slope/limit); scaling selects the tone reproduction scaling:
          "minmax" (linear), "wp_gw" (R=0 -> middle grey), "wp_gw_black"
          and "keep_gray" (Chambah et al. 2003).
film restoration ACE
          colorcorrect.algorithm.film_restoration_ace
          usage: image,saturation(default:0.2),scaling(default:"keep_gray"),
                 enhance_saturation(default:None),**ace keyword arguments
          Chambah, Rizzi, Gatta, Besserer, Marini 2003: ACE tuned for faded film
          (saturation shape 0.2, WP+GW (black) scaling centred on the original
          mean grey level, "keep original gray"),
          optionally preceded by saturation_enhancement(image, factor) which
          stretches the a*b* chroma cloud about its centre along its principal axes.
complementary cast removal
          colorcorrect.algorithm.complementary_cast_removal
          usage: image,k
          Machidon & Ivanovici 2018: add k times the complement of the mean colour
          (the paper fits k per film stock from a colour chart, 0.28 .. 0.36).
          color_chart_transform / apply_color_transform implement the paper's
          3x3 colour correction from a colour chart.
simplest color balance
          colorcorrect.algorithm.simplest_color_balance
          usage: image,clip(default:0.01)
          Limare et al. 2011: clip 1% at both ends of each channel and stretch.

shades of gray
          colorcorrect.algorithm.shades_of_gray
          usage: image,p(default:6),saturation_threshold(default:255)
          Minkowski p-norm grey world (p=1 grey world, p=None max-RGB)
grey edge
          colorcorrect.algorithm.grey_edge
          usage: image,order(default:1),p(default:6),sigma(default:2.0),saturation_threshold(default:255)
          illuminant from the p-norm of Gaussian derivatives of order 1 or 2;
          order=0 is the general grey world (Shades of Gray with smoothing).
          estimate_illuminant_grey_edge returns the estimate itself.
pca color constancy
          colorcorrect.algorithm.pca_color_constancy
          usage: image,fraction(default:0.035),saturation_threshold(default:255)
          Cheng et al. 2014: PCA of the brightest/darkest pixels along the mean colour.
          estimate_illuminant_pca returns the estimate itself.
multi scale retinex (MSR / MSRCR)
          colorcorrect.algorithm.multi_scale_retinex
          usage: image,sigmas(default:(15,80,250)),color_restoration(default:True),
                 alpha(default:125),beta(default:46),clip(default:0.01)
          Jobson et al. 1997 with the simplest colour balance output scaling of
          the IPOL implementation (Petro, Sbert, Morel 2014).
random spray retinex
          colorcorrect.algorithm.random_spray_retinex
          usage: image,sprays(default:10),points(default:250),radius(default:None),
                 seed(default:None),workers(default:None)
          Provenzi et al. 2007; cost grows with sprays*points*pixels (C++, threaded).

RACE / sigma-RACE
          colorcorrect.algorithm.race
          usage: image,sprays(default:10),points(default:250),alpha(default:20),
                 regularize(default:True),radius(default:None),seed(default:None),workers(default:None)
          Provenzi et al. 2008: spray fusion of RSR (local white patch) and ACE
          (local grey world); regularize=True is sigma-RACE, which keeps uniform
          areas by mixing with the original according to local/global contrast.
gray pixel / grayness index
          colorcorrect.algorithm.gray_pixel
          usage: image,fraction(default:0.001),epsilon(default:1e-4),saturation_threshold(default:255)
          Qian et al. 2019: illuminant = mean of the 0.1% pixels with the smallest
          grayness index (grayness_index returns the map,
          estimate_illuminant_grayness_index the estimate).
weighted grey edge
          colorcorrect.algorithm.weighted_grey_edge
          usage: image,weighting(default:"specular"),kappa(default:10),p(default:1),sigma(default:2.0),
                 iterations(default:10),tolerance(default:0.1),saturation_threshold(default:255)
          Gijsenij et al. 2012: grey edge with photometric edge weights
          (specular / shadow / material), applied iteratively.
          estimate_illuminant_weighted_grey_edge returns the estimate itself.

All functions take and return (height, width, 3) uint8 numpy arrays and never modify their input. The illuminant estimation methods (grey world, shades of gray, grey edge, weighted grey edge, PCA, gray pixel) assume a diagonal (von Kries) colour cast and keep G as the reference channel.

sample usage:

>>> from PIL import Image
>>> import colorcorrect.algorithm as cca
>>> from colorcorrect.util import from_pil, to_pil
>>> img = Image.open('/path/to/image')
>>> to_pil(cca.stretch(from_pil(img))).show()

References:

Denis. Nikitenko, M. Wirth and K. Trudel, "Applicability Of White-Balancing Algorithms to Restoring Faded Colour Slides: An Empirical Evaluation.", Journal of Multimedia, vol. 3, no. 5, 2008.
HK. Lam, OC. Au and CW. Wong, "Automatic white balancing using luminance component and standard deviation of RGB components", in Proc. ICASSP, 2004.
E. Lam, "Combining gray world and retinex theory for automatic white balance in digital photography", in Proc. ISCE, 2005.
A. Rizzi, C. Gatta and D. Marini, "A new algorithm for unsupervised global and local color correction.", Pattern Recognition Letters, vol. 24, no. 11, 2003.
P. Getreuer, "Automatic Color Enhancement (ACE) and its Fast Implementation", Image Processing On Line, 2012. (FFT evaluation of ACE)
G. Finlayson and E. Trezzi, "Shades of Gray and Colour Constancy", Color Imaging Conference, 2004.
J. van de Weijer, T. Gevers and A. Gijsenij, "Edge-Based Color Constancy", IEEE Trans. Image Processing, vol. 16, no. 9, 2007.
D. Cheng, D. K. Prasad and M. S. Brown, "Illuminant estimation for color constancy: why spatial-domain methods work and the role of the color distribution", JOSA A, vol. 31, no. 5, 2014.
D. Jobson, Z. Rahman and G. Woodell, "A multiscale retinex for bridging the gap between color images and the human observation of scenes", IEEE Trans. Image Processing, vol. 6, no. 7, 1997.
A. Petro, C. Sbert and J.-M. Morel, "Multiscale Retinex", Image Processing On Line, 2014.
E. Provenzi, M. Fierro, A. Rizzi, L. De Carli, D. Gadia and D. Marini, "Random Spray Retinex", IEEE Trans. Image Processing, vol. 16, no. 1, 2007.
E. Provenzi, C. Gatta, M. Fierro and A. Rizzi, "A Spatially Variant White-Patch and Gray-World Method for Color Image Enhancement Driven by Local Contrast", IEEE Trans. PAMI, vol. 30, no. 10, 2008.
Y. Qian, J.-K. Kamarainen, J. Nikkanen and J. Matas, "On Finding Gray Pixels", CVPR, 2019.
A. Gijsenij, T. Gevers and J. van de Weijer, "Improving Color Constancy by Photometric Edge Weighting", IEEE Trans. PAMI, vol. 34, no. 5, 2012.
M. Chambah, A. Rizzi, C. Gatta, B. Besserer and D. Marini, "Perceptual approach for unsupervised digital color restoration of cinematographic archives", Proc. SPIE 5008, Color Imaging VIII, 2003.
O.-M. Machidon and M. Ivanovici, "Digital color restoration for the preservation of reversal film heritage", Journal of Cultural Heritage, vol. 33, 2018.
N. Limare, J.-L. Lisani, J.-M. Morel, A. B. Petro and C. Sbert, "Simplest Color Balance", Image Processing On Line, 2011.