# random_color_hex

A random color generator that produces visually distinct colors, unlike most libraries that rely on arbitrary gradient RGB separation.

This library is special in that it uses Gaurav Sharma's 2001 paper CIEDE2000 to calculate the distance between colors actually ***looks*** different instead of just being mathmatically different. Many versions of RGB generators do the latter, being separated by only some arbitrary number between colors: if they have smart color separation at all.

## Installation

```bash
pip install random-color-hex
```

## Quick Start

### Plot Integrated Usage:
```python
import random_color_hex as RCH

# Simple random color
MyColor = RCH.main()  # Returns '#A3F2B6'

# Multiple distinct colors
plt.plot(x, y1, color=RCH.main(HowDifferentShouldColorsBe='L'))
plt.plot(x, y2, color=RCH.main(HowDifferentShouldColorsBe='L'))
plt.plot(x, y3, color=RCH.main(HowDifferentShouldColorsBe='L'))
```
It will automatically separate the colors!

***Using color=RCH.main(), as integrated into the plot function, is the intended use. You can make it a variable by "Variable=RCH.main()", but its designed for easy integration with matplotlib (color=RCH.main()).***

### Jupyter/Non Local Usage:
```python
import random_color_hex as RCH; RCH.JupyterReset()
```
This is needed because the Smart Color Separation subroutine stores its colors as a class variable. When you restart your script on a local machine, it is designed to reset this variable
so you can run it many times without storing the colors from past runs.
However, in some online environments, this doesnt occur because of how they were designed. So, I made a function that specifically clears this to prevent problems in different environments.

### Non-Seperated, RGB generated Color Seperated Colors
```python
import random_color_hex as RCH

print(RCH.BasicMain()) #Will print a random hex code
```
This generates a random color via RGB which is not separated. This is only put in to expand what the library *can* do, not really as a drawing feature.

## Key Features

### Smart Color Separation
Uses CIEDE2000 algorithm to ensure colors are **visually** distinct, not just mathematically different.

```python
# Control color separation
HowDifferentShouldColorsBe='s'   # Slight difference (~663 colors)
HowDifferentShouldColorsBe='m'   # Clear difference (~68 colors, default)
HowDifferentShouldColorsBe='l'   # Very different (~40 colors)
HowDifferentShouldColorsBe='sl'  # Extremely different (~23 colors)
```
### Other Functions
```python
# Get package credits and author information
RCH.Credits()

# Display usage examples and help
RCH.Help()
```

### Brightness Control

```python
# Avoid light colors (great for white backgrounds)
RCH.main(SuperLightColorsAllowed=False)

# Avoid dark colors (great for dark mode)
RCH.main(SuperDarkColorsAllowed=False)

# Mid-tones only
RCH.main(SuperLightColorsAllowed=False, SuperDarkColorsAllowed=False)
```

## Examples

### Multi-line Plot
```python
import matplotlib.pyplot as plt
import random_color_hex as RCH

x = [1, 2, 3, 4, 5]
plt.plot(x, [1, 2, 3, 4, 5], color=RCH.main(), label='Linear')
plt.plot(x, [1, 4, 9, 16, 25], color=RCH.main(), label='Quadratic')
plt.plot(x, [1, 8, 27, 64, 125], color=RCH.main(), label='Cubic')
plt.legend()
plt.show()
```

### Bar Chart
```python
categories = ['Python', 'JavaScript', 'Java', 'C++']
values = [100, 2, 44, 90]

for cat, val in zip(categories, values):
    plt.bar(cat, val, color=RCH.main(SuperLightColorsAllowed=False))
plt.show()
```

### Stateful Generation
```python
# Track color history across calls
generator = RCH.RandomColorHex()
color1 = generator.main()  # First color
color2 = generator.main()  # Guaranteed different from color1
color3 = generator.main()  # Different from both
```
This is an alternative to the much more simple RCH.main() setup. This comes from an older version of this, but I left it in as an option.

## Technical Details

- **Zero dependencies** - stdlib only
- **Python ≥3.11**
- **Cryptographically random** using `secrets` module
- **Auto-fallback**: If color separation is too restrictive, falls back to simple random generation
- **License**: Unlicense (public domain)

## Links

- **PyPI**: [https://pypi.org/project/random-color-hex/](https://pypi.org/project/random-color-hex/)
- **GitHub**: [https://github.com/BobSanders64/RandomColorHex](https://github.com/BobSanders64/RandomColorHex)
- **Author**: Nathan Honn (randomhexman@gmail.com)