1// Copyright (c) 2012 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef UI_GFX_COLOR_ANALYSIS_H_
6#define UI_GFX_COLOR_ANALYSIS_H_
7
8#include "base/basictypes.h"
9#include "base/compiler_specific.h"
10#include "base/memory/ref_counted.h"
11#include "base/memory/ref_counted_memory.h"
12#include "third_party/skia/include/core/SkColor.h"
13#include "ui/gfx/gfx_export.h"
14#include "ui/gfx/matrix3_f.h"
15
16class SkBitmap;
17
18namespace color_utils {
19
20struct HSL;
21
22// This class exposes the sampling method to the caller, which allows
23// stubbing out for things like unit tests. Might be useful to pass more
24// arguments into the GetSample method in the future (such as which
25// cluster is being worked on, etc.).
26//
27// Note: Samplers should be deterministic, as the same image may be analyzed
28// twice with two sampler instances and the results displayed side-by-side
29// to the user.
30class GFX_EXPORT KMeanImageSampler {
31 public:
32  virtual int GetSample(int width, int height) = 0;
33
34 protected:
35  KMeanImageSampler();
36  virtual ~KMeanImageSampler();
37};
38
39// This sampler will pick pixels from an evenly spaced grid.
40class GFX_EXPORT GridSampler : public KMeanImageSampler {
41  public:
42   GridSampler();
43   virtual ~GridSampler();
44
45   virtual int GetSample(int width, int height) OVERRIDE;
46
47  private:
48   // The number of times GetSample has been called.
49   int calls_;
50};
51
52// Returns the color in an ARGB |image| that is closest in RGB-space to the
53// provided |color|. Exported for testing.
54GFX_EXPORT SkColor FindClosestColor(const uint8_t* image, int width, int height,
55                                    SkColor color);
56
57// Returns an SkColor that represents the calculated dominant color in the
58// image. This uses a KMean clustering algorithm to find clusters of pixel
59// colors in RGB space.
60// |png|/|bitmap| represents the data of a png/bitmap encoded image.
61// |lower_bound| represents the minimum bound of HSL values to allow.
62// |upper_bound| represents the maximum bound of HSL values to allow.
63// See color_utils::IsWithinHSLRange() for description of these bounds.
64//
65// RGB KMean Algorithm (N clusters, M iterations):
66// 1.Pick N starting colors by randomly sampling the pixels. If you see a
67//   color you already saw keep sampling. After a certain number of tries
68//   just remove the cluster and continue with N = N-1 clusters (for an image
69//   with just one color this should devolve to N=1). These colors are the
70//   centers of your N clusters.
71// 2.For each pixel in the image find the cluster that it is closest to in RGB
72//   space. Add that pixel's color to that cluster (we keep a sum and a count
73//   of all of the pixels added to the space, so just add it to the sum and
74//   increment count).
75// 3.Calculate the new cluster centroids by getting the average color of all of
76//   the pixels in each cluster (dividing the sum by the count).
77// 4.See if the new centroids are the same as the old centroids.
78//     a) If this is the case for all N clusters than we have converged and
79//        can move on.
80//     b) If any centroid moved, repeat step 2 with the new centroids for up
81//        to M iterations.
82// 5.Once the clusters have converged or M iterations have been tried, sort
83//   the clusters by weight (where weight is the number of pixels that make up
84//   this cluster).
85// 6.Going through the sorted list of clusters, pick the first cluster with the
86//   largest weight that's centroid falls between |lower_bound| and
87//   |upper_bound|. Return that color.
88//   If no color fulfills that requirement return the color with the largest
89//   weight regardless of whether or not it fulfills the equation above.
90GFX_EXPORT SkColor
91    CalculateKMeanColorOfPNG(scoped_refptr<base::RefCountedMemory> png,
92                             const HSL& lower_bound,
93                             const HSL& upper_bound,
94                             KMeanImageSampler* sampler);
95// Computes a dominant color using the above algorithm and reasonable defaults
96// for |lower_bound|, |upper_bound| and |sampler|.
97GFX_EXPORT SkColor CalculateKMeanColorOfPNG(
98    scoped_refptr<base::RefCountedMemory> png);
99
100// Returns an SkColor that represents the calculated dominant color in the
101// image. See CalculateKMeanColorOfPNG() for details.
102GFX_EXPORT SkColor CalculateKMeanColorOfBitmap(const SkBitmap& bitmap,
103                                               const HSL& lower_bound,
104                                               const HSL& upper_bound,
105                                               KMeanImageSampler* sampler);
106// Computes a dominant color using the above algorithm and reasonable defaults
107// for |lower_bound|, |upper_bound| and |sampler|.
108GFX_EXPORT SkColor CalculateKMeanColorOfBitmap(const SkBitmap& bitmap);
109
110// Compute color covariance matrix for the input bitmap.
111GFX_EXPORT gfx::Matrix3F ComputeColorCovariance(const SkBitmap& bitmap);
112
113// Apply a color reduction transform defined by |color_transform| vector to
114// |source_bitmap|. The result is put into |target_bitmap|, which is expected
115// to be initialized to the required size and type (SkBitmap::kA8_Config).
116// If |fit_to_range|, result is transfored linearly to fit 0-0xFF range.
117// Otherwise, data is clipped.
118// Returns true if the target has been computed.
119GFX_EXPORT bool ApplyColorReduction(const SkBitmap& source_bitmap,
120                                   const gfx::Vector3dF& color_transform,
121                                   bool fit_to_range,
122                                   SkBitmap* target_bitmap);
123
124// Compute a monochrome image representing the principal color component of
125// the |source_bitmap|. The result is stored in |target_bitmap|, which must be
126// initialized to the required size and type (SkBitmap::kA8_Config).
127// Returns true if the conversion succeeded. Note that there might be legitimate
128// reasons for the process to fail even if all input was correct. This is a
129// condition the caller must be able to handle.
130GFX_EXPORT bool ComputePrincipalComponentImage(const SkBitmap& source_bitmap,
131                                              SkBitmap* target_bitmap);
132
133}  // namespace color_utils
134
135#endif  // UI_GFX_COLOR_ANALYSIS_H_
136