Metadata-Version: 2.4
Name: colorcorrect
Version: 1.0.0
Summary: Implementation of some color correction / automatic white balance algorithms
Author-email: Shunsuke Aihara <s.aihara@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/shunsukeaihara/colorcorrect
Keywords: image-processing,computer-vision,white-balance,color-correction
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy>=2.0
Requires-Dist: Pillow>=10.0
Dynamic: license-file

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.
