D29637: Introduce ImageColors

[Carson Black]

cblack added inline comments.

INLINE COMMENTS

> colorutils.h:182
> +    /**
> +     * Returns the Cielab "Chroma" of the color which is a slightly better quantificator for how much a color appears https://en.wikipedia.org/wiki/Colorfulness
> +     * This is how much a color looks diffenent from a gray of the same

Returns the CIELAB chroma of the given color.
  
  CIELAB chroma may give a better quantification of how vibrant a color is compared to HSV saturation.
  
  \sa https://en.wikipedia.org/wiki/Colorfulness
  \sa https://en.wikipedia.org/wiki/CIELAB_color_space

> imagecolors.h:64-70
> +     * The source which colors should be analyzed, it can be:
> +     * * Any Item: it will be rendered to an image and the static grab 
> +     * analyzed. It won't be updated if the item changes, but manual 
> +     * calls to update() are needed.
> +     * * A QImage (for example coming from a QAbstractItemModel data role)
> +     * * A QIcon (for example coming from a QAbstractItemModel data role)
> +     * * An icon name: an icon name present in the theme.

The source from which colors should be extracted from.
  `source` can be one of the following:
  * Item
  * QImage
  * QIcon
  * Icon name
  
  Note that an Item's color palette will only be extracted once unless you call `update()`, regardless of how the item hanges.

> imagecolors.h:75-82
> +     * A list of the color palette extracted from the image.
> +     * It uses K-means-clustering tecnique, by averaging groups of
> +     * "similar" colors https://en.wikipedia.org/wiki/K-means_clustering
> +     * it's a list of maps containing the following keys:
> +     * * "color": the color of the cluster
> +     * * "ratio": the ratio from 0 to 1 of diffusion of the cluster in the image
> +     * * "contrastingColor": another color from the clusters (if possible) that is the nearest to its negative

A list of colors and related information about then.
  
  Each list item has the following properties:
  * `color`: The color of the list item.
  * `ratio`: How dominant the color is in the source image.
  * `contrastingColor`: The color from the source image that's closest to the inverse of `color`.
  
  The list is sorted by `ratio`; the first element is the most dominant color in the source image and the last element is the least dominant color of the image.
  
  \note K-means clustering is used to extract these colors; see https://en.wikipedia.org/wiki/K-means_clustering.

> imagecolors.h:86-89
> +    /**
> +     * If true, it should be considered a "Dark" color palette (this if the dominant color is darker than a 50% gray
> +     */
> +    Q_PROPERTY(bool isDarkPalette READ isDarkPalette NOTIFY paletteChanged)

I think it would be better to have this return a `ColorUtils::Brightness` enum.

> imagecolors.h:92
> +    /**
> +     * The average color of the whole image.
> +     */

The average color of the source image.

> imagecolors.h:97
> +    /**
> +     * The dominant color of the image. This is the color of the cluster which covers the bigger area of the image
> +     */

The dominant color of the source image.
  
  The dominant color of the image is the color of the largest cluster in the image.
  \sa https://en.wikipedia.org/wiki/K-means_clustering

> imagecolors.h:102
> +    /**
> +     * Suggested "contrasting" color to the dominant one. It's the color in the palette nearest to the negative of the dominant
> +     */

The color closest to the inverse of the dominant color found in the source image.

> imagecolors.h:107-109
> +     * An "accent" color extracted from the image, heuristically found most "vibrant" color from the cluster with highest CIELab Chroma
> +     * https://en.wikipedia.org/wiki/Colorfulness#Chroma
> +     * which is a better indication than saturation as doesn't decrease with lightness

An accent color extracted from the source image.
  
  The accent color is the color cluster with the highest CIELAB chroma in the source image.
  
  \sa https://en.wikipedia.org/wiki/Colorfulness#Chroma

> imagecolors.h:114-116
> +     * A color suggested for foreground items over the image
> +     * * on dark palettes will be closestToWhite if light enough, or a very light gray otherwise
> +     * * on light palettes will be closestToBlack if dark enough or a very dark gray

A color suitable for rendering text and other foreground over the source image.
  
  On dark items, this will be the color closest to white in the image if it's light enough, or a bright gray otherwise.
  On light items, this will be the color closest to black in the image if it's dark enough, or a dark gray otherwise.

> imagecolors.h:120-124
> +    /**
> +     * A color suggested for background items over the image, like a dialog frame
> +     * * on light palettes will be closestToWhite if light enough, or a very light gray otherwise
> +     * * on dark palettes will be closestToBlack if dark enough or a very dark gray
> +     */

A color suitable for rendering a background behind the source image.
  
  On dark items, this will be the color closest to black in the image if it's dark enough, or a dark gray otherwise.
  On light items, this will be the color closest to white in the image if it's light enough, or a bright gray otherwise.

> imagecolors.h:128
> +    /**
> +     * The lightest color that was found in clusters
> +     */

The lightest color of the source image.

> imagecolors.h:133
> +    /**
> +     * The darkest color found in clusters
> +     */

The darkest color of the source image.

REPOSITORY
  R169 Kirigami

REVISION DETAIL
  https://phabricator.kde.org/D29637

To: mart, #kirigami
Cc: cblack, plasma-devel, fbampaloukas, GB_2, domson, dkardarakos, ngraham, apol, ahiemstra, davidedmundson, mart
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/plasma-devel/attachments/20200511/64ea5fa0/attachment-0001.htm>