---
license: mit
library_name: scikit-learn
tags:
  - color-classification
  - random-forest
  - tabular-classification
  - scikit-learn
---

# Color AI — chroma classifiers

Three trained color-naming classifiers: given a color, they name it —
"red", "navy", "charcoal", etc. Each is a `scikit-learn`
`RandomForestClassifier`, trained entirely on synthetic labeled data (no
photos, no dataset needed to build them) — see
[color-ai-core](https://pypi.org/project/color-ai-core/) on PyPI for the
code that trained these and the functions to use them correctly.

## Files

| File | Code name | Colors | Trees | Samples/class | Validation accuracy |
|---|---|---|---|---|---|
| `color_classifier_nano.joblib` | `chromav1n-clf` | 12 | 60 | 400 | 92.4% |
| `color_classifier_micro.joblib` | `chromav1u-clf` | 24 | 80 | 500 | 82.7% |
| `color_classifier_microsuper.joblib` | `chromav1us-clf` | 24 | 80 | 800 | 84.4% |

**Nano** covers the basics: red, orange, yellow, green, teal, blue,
purple, pink, brown, black, gray, white.

**Micro** and **Micro Super** add 12 more: maroon, navy, olive, lime,
cyan, magenta, indigo, coral, mint, lavender, beige, charcoal. Micro
Super is the same 24 classes as Micro, just trained on more samples per
class (800 vs 500), which measurably improves accuracy — same anchors,
same architecture, purely more training evidence.

Micro and Micro Super also support a **two-stage fallback**: when the
model isn't confident (below 50%) in its specific pick, it's meant to
report the broader Nano-family color instead of guessing between two
close options (e.g. "brown" instead of a shaky call between beige and
charcoal). This logic lives in the `color-ai-core` package, not baked
into the `.joblib` file itself — see Usage below.

## Usage

⚠️ These models do **not** take raw RGB as input. They were trained on a
4-value feature vector — `[sin(hue), cos(hue), saturation, value]` — not
`[R, G, B]` directly. Feeding raw RGB straight to `.predict()` will run
without error but give meaningless results. Use the matching feature
function from `color-ai-core` rather than hand-rolling it:

```bash
pip install color-ai-core huggingface_hub
```

```python
from huggingface_hub import hf_hub_download
from color_ai_core import load_model, predict_color

path = hf_hub_download(repo_id="YOUR_USERNAME/YOUR_REPO_NAME",
                        filename="color_classifier_micro.joblib")
clf = load_model(path)

name, confidence, used_fallback = predict_color(clf, [220, 40, 30], tier="micro")
print(name)  # "red"
```

`predict_color()` handles the RGB → feature conversion and the two-stage
fallback correctly — that's why it's the supported way to use these
files rather than calling `clf.predict()` directly.

## Training

All three were trained on jittered synthetic data generated around fixed
HSV anchor points per color (e.g. red ≈ hue 0°, high saturation, high
value) — noise is added to hue, saturation, value, and the final RGB to
simulate lighting and camera variation, so each model learns a color's
*range* rather than one exact shade. No photos were used to train these
specific files. `color-ai-core` also includes `train_from_images()` for
training a classifier on your own labeled photos instead, if you'd
rather have that.

## License

MIT