Port Android palette API for deriving a prominent color from an image.

ui/gfx/color_analysis.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef UI_GFX_COLOR_ANALYSIS_H_
 #define UI_GFX_COLOR_ANALYSIS_H_
 
 #include <stdint.h>
 
 #include "base/compiler_specific.h"
@@ skipping 90 matching lines @@
 // Returns an SkColor that represents the calculated dominant color in the
 // image. See CalculateKMeanColorOfPNG() for details.
 GFX_EXPORT SkColor CalculateKMeanColorOfBitmap(const SkBitmap& bitmap,
                                                const HSL& lower_bound,
                                                const HSL& upper_bound,
                                                KMeanImageSampler* sampler);
 // Computes a dominant color using the above algorithm and reasonable defaults
 // for |lower_bound|, |upper_bound| and |sampler|.
 GFX_EXPORT SkColor CalculateKMeanColorOfBitmap(const SkBitmap& bitmap);
 
+// These enums specify general values to look for when calculating prominent
+// colors from an image.
+enum class LumaRange {

[sky, 2017/02/17 21:42:20]

Without any context and looking at these enum values I haven't a clue as to when
I would use them and why. Please better document why I would want to futz with
these values. Maybe CalculateProminentColorOfBitmap() should have default values
to make the recommended choices more obvious?

[Evan Stade, 2017/02/17 23:23:19]

CalculateProminentColorOfBitmap() translates these enums into more specific
values (i.e. something specific for what it means to be "dark vibrant"). The
combinations of these enums matches the Android API, so I don't really want to
change them, but I have added better docs.

We're probably only going to use dark muted at first but it's cheap and easy to
support the same set of values that Android has, and design has requested that
all the values be available to tinker with.

[sky, 2017/02/18 00:01:34]

If you only intend to call with one value, I recommend moving them to the .cc.
That way you still have them, but consumers of this api don't have to understand
what the default should be.

[Evan Stade, 2017/02/18 00:05:00]

There is no default. Each consumer of the API (i.e. each UX designer who asks
that a feature make use of this functionality) needs to consciously decide which
combination to ask for depending on how the color will be used. They may even
want to try one combination but fall back to another if the first one fails
(that's not explicitly supported yet but we've been talking about doing that for
wallpapers).

+  LIGHT,
+  NORMAL,
+  DARK,
+};

[oshima, 2017/02/14 02:18:08]

nit: newline

[Evan Stade, 2017/02/17 23:23:19]

Done.

+enum class SaturationRange {
+  VIBRANT,
+  MUTED,
+};
+
+// Returns a single RGB color that represents the bitmap. If a value is
+// succesfully calculated, the return value is fully opaque. For failure, the
+// return value is transparent. This currently calculates one color at a time.

[Nico, 2017/02/17 21:37:06]

Maybe base::Optional<SkColor> or bool and SkColor as outparm? Having special
failure case objects feels a bit brittle.

[Evan Stade, 2017/02/17 23:23:19]

This function should only return fully opaque colors --- that's an inherent
guarantee in the API. As such there's a range of values that would be invalid
and it doesn't seem brittle to me to reuse something in that range as an
indicator of failure.

+// We could save computation by calculating multiple colors at once, but there's
+// currently no need to calculate multiple colors.
+GFX_EXPORT SkColor CalculateProminentColorOfBitmap(const SkBitmap& bitmap,
+                                                   LumaRange luma,
+                                                   SaturationRange saturation);
+
 // Compute color covariance matrix for the input bitmap.
 GFX_EXPORT gfx::Matrix3F ComputeColorCovariance(const SkBitmap& bitmap);
 
 // Apply a color reduction transform defined by |color_transform| vector to
 // |source_bitmap|. The result is put into |target_bitmap|, which is expected
 // to be initialized to the required size and type (SkBitmap::kA8_Config).
 // If |fit_to_range|, result is transfored linearly to fit 0-0xFF range.
 // Otherwise, data is clipped.
 // Returns true if the target has been computed.
 GFX_EXPORT bool ApplyColorReduction(const SkBitmap& source_bitmap,
                                    const gfx::Vector3dF& color_transform,
                                    bool fit_to_range,
                                    SkBitmap* target_bitmap);
 
 // Compute a monochrome image representing the principal color component of
 // the |source_bitmap|. The result is stored in |target_bitmap|, which must be
 // initialized to the required size and type (SkBitmap::kA8_Config).
 // Returns true if the conversion succeeded. Note that there might be legitimate
 // reasons for the process to fail even if all input was correct. This is a
 // condition the caller must be able to handle.
 GFX_EXPORT bool ComputePrincipalComponentImage(const SkBitmap& source_bitmap,
                                               SkBitmap* target_bitmap);
 
 }  // namespace color_utils
 
 #endif  // UI_GFX_COLOR_ANALYSIS_H_