https://github.com/gpoon21/keycolor
Generates unique and consistent colors based on a specific key.
https://github.com/gpoon21/keycolor
color-contrast color-generation color-mapping color-palette data-visualization net-library net-standard nuget-package open-source
Last synced: 4 months ago
JSON representation
Generates unique and consistent colors based on a specific key.
- Host: GitHub
- URL: https://github.com/gpoon21/keycolor
- Owner: gpoon21
- License: mit
- Created: 2025-05-20T23:00:40.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-05-21T23:59:00.000Z (about 1 year ago)
- Last Synced: 2025-06-21T22:39:21.711Z (about 1 year ago)
- Topics: color-contrast, color-generation, color-mapping, color-palette, data-visualization, net-library, net-standard, nuget-package, open-source
- Language: C#
- Homepage:
- Size: 124 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# KeyColor
[](https://www.nuget.org/packages/KeyColor)
KeyColor is a .NET library that generates unique and consistent colors based on input keys. It's perfect for applications that need deterministic color generation, such as data visualization, user interfaces, and color-coded elements.
If you find this project helpful, please consider giving it a star! ⭐
## Features
- **Deterministic Color Generation**: Same input always produces the same color
- **Text Contrast Guarantee**: Default settings ensure text readability on generated colors
- **Type Support**: Generate colors from strings, byte arrays, or structs
- **Customizable Parameters**: Control saturation, lightness, and brightness ranges
- **Framework Support**:
- .NET 9.0
- .NET 8.0
- .NET 7.0
- .NET Standard 2.0
- **High Performance**: Optimized for both modern and legacy .NET frameworks
- **Thread Safety**: Static `ColorFrom` APIs are thread-safe, `KeyColorGenerator` has thread-safe color generation
## Demo
Try out the live demo to see KeyColor in action!
## Installation
Install KeyColor via NuGet:
```bash
dotnet add package KeyColor
```
## Quick Start
```csharp
// Using string as input
var color1 = ColorFrom.String("uniqueKey");
string cssColor1 = color1.ToCssColor(); // Returns "#RRGGBB"
// Using struct as input
var myStruct = new MyStruct();
var color2 = ColorFrom.Key(myStruct);
// Using byte array as input
byte[] data = new byte[] { 1, 2, 3 };
var color3 = ColorFrom.Span(data);
// Generate random color
var randomColor = ColorFrom.Rng();
```
## Advanced Usage
### Customizing Color Generation
```csharp
var generator = new KeyColorGenerator();
// Customize saturation range (0-1)
generator.Saturation.Min = 0.3;
generator.Saturation.Max = 0.7;
// Customize lightness range (0-1)
generator.Lightness.Min = 0.2;
generator.Lightness.Max = 0.8;
// Customize brightness range (0-255)
generator.Brightness.Min = 80;
generator.Brightness.Max = 200;
// Generate color with custom settings
var color = generator.GetUniqueColor("myKey");
```
### Text Visibility
The default configuration ensures that both black and white text will be readable on any generated color:
- **Lightness Range**: Constrained between 0.2 and 0.8 (not too dark, not too light)
- **Brightness Range**: Kept between 80-200 (moderate brightness)
- **Perceived Brightness**: Algorithm considers human eye perception of different colors
This means you can safely overlay text on generated colors without additional contrast checks for most use cases.
## API Reference
### ColorFrom (Static Class)
- `String(string key)`: Generate color from string input
- `Key(T key) where T : struct`: Generate color from struct
- `Span(ReadOnlySpan span) where T : struct`: Generate color from span
- `Rng()`: Generate random color
All methods in `ColorFrom` are thread-safe and can be safely called from multiple threads.
### KeyColorGenerator (Class)
- `GetUniqueColor(string label)`: Generate color from string
- `GetUniqueColor(T key) where T : struct`: Generate color from struct
- `GetUniqueColor(ReadOnlySpan key)`: Generate color from byte span
**Thread Safety Note**: The color generation methods are thread-safe, but modifying properties (Seed, Saturation, Lightness, Brightness) is not thread-safe. If you need to modify these properties, do it before making the generator available to multiple threads.
### GeneratedColor (Struct)
- `R`: Red component (0-255)
- `G`: Green component (0-255)
- `B`: Blue component (0-255)
- `ToArray()`: Convert to byte array
- `ToCssColor()`: Convert to CSS color string
## Performance
Here's a performance comparison of `ColorFrom.Key` across different .NET versions:
| Framework | Mean | Allocated |
|-------------------|-----------|-----------|
| .NET 9.0 | 680.5 ns | 0 bytes |
| .NET 8.0 | 688.6 ns | 0 bytes |
| .NET 7.0 | 689.0 ns | 0 bytes |
| .NET Core 3.1 | 1,475 ns | 1.2 KB |