Home | History | Annotate | Download | only in gfx 
      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 
     16 class SkBitmap;
     17 
     18 namespace color_utils {
     19 
     20 struct 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.
     30 class 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.
     40 class 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.
     54 GFX_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.
     90 GFX_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|.
     97 GFX_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.
    102 GFX_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|.
    108 GFX_EXPORT SkColor CalculateKMeanColorOfBitmap(const SkBitmap& bitmap);
    109 
    110 // Compute color covariance matrix for the input bitmap.
    111 GFX_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.
    119 GFX_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.
    130 GFX_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