Skip to content

Latest commit

 

History

History
116 lines (98 loc) · 6.83 KB

README.md

File metadata and controls

116 lines (98 loc) · 6.83 KB
Raw

Color names

This library's primary purpose is to be able to specify a color and end up with a fitting name for that color 🌈

Examples:

"#ffffff" -> White
"#facfea" -> Classic Rose
#abcdef -> Alphabet Blue
#123456 -> Incremental Blue
#c1b2a3 -> Balanced Beige
...and so on

Where do the names come from?!

Color Names is meant to act as an easy drop-in dependency you can import and start using, meaning it's already bundled with a list of color names, a list that is maintained by another awesome open-sourced project: meodai/color-names. There's around 16.7 million sRGB colors, obviously not all of these are named, but this list provides plenty to work with, we can just extrapolate the closest color from the list.

Ermm actually I don't like the bundled color list 🤓🤓

Color Names remain customisable for those who'd like the extra control: you can use the ColorNameBuilder (usage outlined below) to fully customize the color names used, enabling you to add your own colors and even bypass the default list entirely. Alternatively, you could fork this project yourself and replace/modify the list in src/main/resources/colornames.csv with whatever you'd like. If you'd like to make changes to the default list, consider reviewing the naming rules of the open sourced list mentioned above and contributing there.

How about performance, and how accurate is the "nearest" color?

The default colour list has over 30,000 names (that's a lot). Trying to find the closest color by comparing distance in the 3D color space can be pretty computationally expensive.

Other libraries with similar functionality seem to often approach this by iterating over all the colors, plotting the sRGB values and calculating Euclidian distance and whatever has the lowest distance is the "closest" color. This has 2 notable concerns:

  1. The sRGB color space isn't all that accurate in terms of visual similarity, ie: 3 sRGB values that are equally apart in terms of raw numerical value are unlikely to be visually "different" by the same factor. Okay... so, how do we put a number on the visual similarity of colors? Fortunately, that's not my job. The CIELAB Color Space has us covered! This color space precisely revolves around positioning colors with uniform visual perception and for this reason, its used for all sorts of color correction work, and is exactly what we need. Perfect, we convert our values from the sRGB color space to the CIELAB color space, problem one solved!
  2. Iterating through >30,000 vectors in a 3D space and finding the distance between all of them to a point is... a lot of calculations. But it's exactly what we need, since that's how we find the Delta-E variance between all our CIELAB colours to see whats the closest. So, we should really try to optimise this. For this we cache our colors in a K-D Tree with 3 dimensions, providing us with fast nearest neighbour searches. This takes the time complexity for searches from O(n) to O(logn). In practice, this makes a pretty substantial difference.

Benchmarks:

10 lookups - size of list: Linear approach K-D Tree approach 30,000 colors - No. of lookups: Linear approach K-D Tree approach
1,000 0.027ms 0.0088ms 1 0.17ms 0.009ms
10,000 0.23ms 0.012ms 10 1.05ms 0.024ms
20,000 0.62ms 0.018ms 100 8.07ms 0.12ms
30,000 (~ default list) 1.05ms 0.024ms 1,000 78.42ms 0.84ms
300,000 9.24ms 0.067ms 10,000 800.94ms 5.59ms

Note

All of these tests were conducted ~100 times and averaged. Tests were ran on an i9 13900k. Your results may vary, but relative performance should be a lot faster with the K-D Tree.


Pretty notes ✨

While researching K-D trees, I put together some visuals to help me understand, and I figured why not make them pretty and provide it here. Hopfully these prove to be helpful for anyone interested in learning about K-D trees. And remember, there are plenty of other great resources out there (YouTube videos did it for me!). Untitled-2024-03-21-21563x

Note

You can open that image in a new tab for a nicer, full-resolution view.


Usage

Importing

Gradle.kts

repositories {
      maven("https://jitpack.io")
}

dependencies {
      implementation("me.aroze:color-names:1.0.3")
}

Maven

<repository>
  <id>jitpack.io</id>
  <url>https://jitpack.io</url>
</repository>

<dependency>
  <groupId>me.aroze</groupId>
  <artifactId>color-names</artifactId>
  <version>1.0.3</version>
</dependency>

Creating the instance

Java

public ColorNames colorNames = ColorNames.create() // Easily create an instance with the default color list
public ColorNames colorNames = new ColorNameBuilder() // Builder with extra customisability
  .addColor("Peachy Pink", "#ffdbed") // Custom color!! There's also .addColors() and various overloads
  .loadDefaults() // Loads the default list, can be skipped entirely if you'd like to
  .build();

Kotlin

val colorNames = ColorNames.create() // Easily create an instance with the default color list
val colorNames = ColorNameBuilder() // Builder with extra customisability
  .addColor("Peachy Pink", "#ffdbed") // Custom color!! There's also .addColors() and various overloads
  .loadDefaults() // Loads the default list, can be skipped entirely if you'd like to
  .build();

Getting a fitting color name

Java

String fromHex = colorNames.getName("#facfea"); // "Classic Rose"
String fromRGB = colorNames.getName(224, 224, 255); // "Stoic White"
String fromColor = colorNames.getName(new Color(255, 219, 240)); // "Silky Pink"

Kotlin

// Kotlin
val fromHex = colorNames.getName("#facfea") // "Classic Rose"
val fromRGB = colorNames.getName(224, 224, 255) // "Stoic White"
val fromColor = colorNames.getName(Color(255, 219, 240)) // "Silky Pink"