ColorNamesSharp 1.1.0

<img align="left" height="119" width="119" src="https://meodai.github.io/color-names/logo/cockatoo-fill.svg">

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:<br>

"#ffffff" → White<br> "#facfea" → Classic Rose<br> #abcdef → Alphabet Blue<br> #123456 → Incremental Blue<br> #c1b2a3 → Balanced Beige<br> ...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. <br>

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 ColorLists/Default.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 color 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. <br><br> 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: <br>

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 colors 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

The repository includes a BenchmarkDotNet suite covering:

• exact name and hexadecimal lookups;
• nearest-color lookup using the KD-tree;
• an equivalent precomputed linear CIELAB scan for comparison;
• loading the bundled CSV and constructing the search index.

Run all benchmarks from the repository root in Release mode for either supported runtime:

dotnet run --project benchmarks/ColorNamesSharp.Benchmarks -c Release -f net8.0
dotnet run --project benchmarks/ColorNamesSharp.Benchmarks -c Release -f net10.0

To run one group, pass a BenchmarkDotNet filter:

dotnet run --project benchmarks/ColorNamesSharp.Benchmarks -c Release -f net10.0 -- --filter "*LookupBenchmarks*"

The suite supports both .NET 8 and .NET 10, reports managed allocations, and writes detailed reports to BenchmarkDotNet.Artifacts/results. Run benchmarks on an otherwise idle machine and compare results produced on the same hardware and operating system.

<br>

Pretty notes ✨

You can find many resources online about KD-Trees, here's some visuals made by UwUAroze to help you understand how they work:

<br>

Development

Install the .NET 8 and .NET 10 SDKs to build and test every target framework.

Run the complete test suite from the repository root:

dotnet test ColorNamesSharp.sln

Usage

You can download and install the nuget package from here. <br> Or you can clone this repository and use it as a library in your project.

dotnet add package ColorNamesSharp

Supported frameworks

Creating the instance

ColorNames colorNames = new ColorNamesBuilder()
	.Add("Best Blue", "#3299fe") // Add your own custom colors
	.LoadDefault() // Load the default color list
	.AddFromCsv("path/to/your/colorlist.csv") // Add a custom color list from a csv file
	.Build(); // Get a new ColorNames instance that includes all the colors you've added

Builder methods are chainable, and colors remain in insertion order. Calling LoadDefault() more than once intentionally adds the default list more than once.

Custom CSV files must include a header row followed by name,hex rows:

name,hex
Best Blue,#3299fe
Classic Rose,#facfea

Accessing the configured colors

// Enumerate the colors in their original insertion order
foreach (NamedColor color in colorNames.Colors)
    Console.WriteLine($"{color.Name}: {color.Hex}");

// Exact lookups are case-insensitive and do not calculate color distance
if (colorNames.TryGetByName("alphabet blue", out NamedColor? byName))
    Console.WriteLine(byName.Hex);

if (colorNames.TryGetByHex("#abcdef", out NamedColor? byHex))
    Console.WriteLine(byHex.Name);

Getting a fitting color name

NamedColor customNamedColor = new("Best Blue", 50, 153, 254);

// You can directly get the name of the color as a string
string colorNameFromHex = colorNames.FindClosestColorName("#ffffff");
string colorNameFromRgb = colorNames.FindClosestColorName(255, 255, 255);
string colorNameFromNamedColor = colorNames.FindClosestColorName(customNamedColor);

// Or similarly you can get the NamedColor object
NamedColor? namedColorFromHex = colorNames.FindClosestColor("#ffffff");
NamedColor? namedColorFromRgb = colorNames.FindClosestColor(255, 255, 255);
NamedColor? namedColorFromNamedColor = colorNames.FindClosestColor(customNamedColor);

// Or a random color
NamedColor? randomColor = colorNames.GetRandomNamedColor();

Hexadecimal inputs use the six-digit #RRGGBB form. Invalid values throw ArgumentException; an empty color collection returns null from FindClosestColor and "Unknown" from FindClosestColorName.

The package also includes an XML documentation file, so the public API descriptions and parameter details appear in IDE IntelliSense.

Credits

This library is a C# implementation of the original color names library by meodai and it takes inspiration from UwUAroze's implementation in Kotlin. Huge thanks to both of them for their work!