Color classification

[Namide]

For a lot of usages of extract-colors, users require one or more specific colors from the image. For example, extract-colors is sometimes used to add a background of a web page (the background need to be an extracted color of an image).
The current version of extract-colors (v4.1.1) return a list of colors with a count of colors that cannot be anticipated.

To add feature that automatically extracts the necessary color(s), and to include the maximum number of use cases, it's important to be agnostic. Which colors define an image (in photography, paint, draw...)?

Here a list of color classification:

• accents (dark + light) = (contrasting colors) [opposite of dominants]
• accentsLight = (contrasting light colors)
• accentsDark = (contrasting dark colors)
• dominants (dark + light) = (largest proportional area colors) [opposite of accents]
• dominantsLight = (largest proportional area light colors)
• dominantsDark = (largest proportional area dark colors)
• vivids (dark + light) = (most saturated color colors) [opposite of dullests]
• vividsLight = (most saturated color light colors)
• vividsDark = (most saturated color dark colors)
• dullests (dark + light) = (least saturated color colors) [opposite of vivids]
• dullestsLight = (least saturated color light colors)
• dullestsDark = (least saturated color dark colors)
• lightests = (most lightest color colors) [opposite of darkests]
• darkests = (most darkest color colors) [opposite of lightests]
• coolest (dark + light) = (most cool colors) [opposite of warmest]
• coolestLight = (most cool light colors)
• coolestDark = (most cool dark colors)
• warmest (dark + light) = (most warm colors) [opposite of coolest]
• warmestLight = (most warm light colors)
• warmestDark = (most warm dark colors)

Here the options proposal:

{
  // List of colors type returned example:
  colorClassifications: ['accents', 'accentsLight', 'dominants', 'dominantsDark', 'vivid', 'dullest'],
  
  // Default value if color not found
  // If defaultColors is false the returned values can be empty
  // Example:
  defaultColors: false,
  
  // Default value if color not found
  // If defaultColors is true the returned values will be calculated by extract-colors
  // Example:
  defaultColors: true,

  // If defaultColors is and object, all values can be set by colorClassification.
  // Example:
  defaultColors: {
    accents: 0xFF0077,
    vivid: false,
    dominants: (classifiedColorsPart) => [0xFF5577, 0x775577],
    dullest: true
  }
}

Here an example of use:

import { extractColors, extract, refine, classify, addDefaults } from "extract-colors"

const imageSrc = "path-to/image.jpg"

// Full use
extractColors(imageSrc, {
    pixels: 64000,
    distance: 0.22,
    colorValidator: (red, green, blue, alpha = 255) => alpha > 250,
    saturationDistance: 0.2,
    lightnessDistance: 0.2,
    hueDistance: 0.083333333,
    colorClassifications: ['coolest', 'warmest'],
    defaultColors: {
      warmest: 0xFF0000,
      coolest: 0x0000FF,
    }
  })
  .then(classifiedColors => console.log(classifiedColors))


// Same calculation with all functions splitted
extract(imageSrc, {
    pixels: 64000,
    distance: 0.22,
    colorValidator: (red, green, blue, alpha = 255) => alpha > 250,
  })
  .then(colors => refine(colors, {
    saturationDistance: 0.2,
    lightnessDistance: 0.2,
    hueDistance: 0.083333333
  }))
  .then(refinedColors => classify(refinedColors, {
    colorClassifications: ['accents', 'dominants']
  }))
  .then(classifiedColors => addDefaults(classifiedColors, {
    defaultColors: {
      accents: false,
      dominants: 0xCCCCCC,
    }
  }))
  .then(classifiedColors => console.log(classifiedColors))

Feel free to comment, this feature is under development and we welcome your feedback.

---

Work in progress in the feature/classify branch.
Linked issue

[sambecker]

This would be incredible! Looking forward to it.

[Namide]

Here is my progress about this feature.
I think most of the work is done, but there are still some tasks left to complete.

✅ Done

• update all code to add the colorClassification process
• add colorClassification options, process and return it
• add defaultColors options and process
• init unit tests

📋 Todo

• improve accents/dominants color classification
• order colors returned
• write documentation about the new feature
• write documentation about the migration
• improve unit tests

❓ Enhancement

• Would it be interesting to find the closest color? Example if I ask for a blue or a red color.

⚒️ Beta version

You can try this new feature with the beta version 5.0.0-beta.1.

# Install beta version with the colorClassification options
npm install extract-colors@5.0.0-beta.1

Your feedback will be greatly appreciated and will help me.

📘 Doc

You can found the started documentation on the GIT branch of the website: https://github.com/Namide/extract-colors-website/tree/feature/classify
But it need to be localy builded.

[sambecker]

So exciting @Namide

Just shipped extract-colors support in my project (sambecker/exif-photo-blog#284, usage @ src/photo/color/server.ts)

Would love to be able to leverage these new classification features. Let me know if this is stable enough to start using/testing.

The reason I'm using it btw is for chromatic photo sorting—demo here:
https://photos.sambecker.com/grid/chromatic/descending

[Namide]

Just shipped extract-colors support in my project (sambecker/exif-photo-blog#284, usage @ src/photo/color/server.ts)

Thank you for your interest @sambecker 🙂

Would love to be able to leverage these new classification features. Let me know if this is stable enough to start using/testing.

If you need it for production, I would advise you to wait because I don't know when I will have finished the release.
I haven't tested everything thoroughly yet, so I can't guarantee against some side effects.

I can already say that for classified colors, the order of the color lists should change, and I will try to improve the accent/dominant process, so the resulting colors should change a little.

But I don't think the global logic will change much, so you can start testing it because the technical specifications will remain the same for the release.

Also, if you have specific feedback about the color classification results, please let me know so I can fine-tune my algorithm.