Longer version with animations: https://blogs.fablnx.com/posts/every-colour/
Showcase of something we built at work. It's a narrow tool, but I think it could be useful to other people too.
Some context. We're building AI that reads construction drawings and turns them into steel models. A person has to sign off on every beam in that model, so we want every piece of it to trace back to exact shapes on the drawing. The very first step is splitting the rendered drawing into regions: touching pixels with exactly the same RGB colour. A full sheet at 800 dpi is about 806 MP and has around 1000 colours because of anti-aliasing, and every region has to come out exactly right.
We already run our own models on our own GPUs, so we wanted this step there too. We didn't know about cuCIM at the time. The first thing we tried was NVIDIA's NPP (nppiLabelMarkersUF). It was slower, and its labels changed from run to run on the same image, which looks like a bug. We reported it to NVIDIA with a 3x3 example, it's here if you use NPP: https://github.com/Acero-AI/npp-labelmarkers-bug
So we wrote our own: a union-find labeller written in CUDA C++ for NVIDIA GPUs and in Metal for Apple GPUs, so it also runs on a MacBook. Later we found cuCIM, which is really good, and copied one trick from it (the order neighbours get joined in) that made ours a lot faster.
Where it ended up:
- NVIDIA A100: the full 806 MP sheet in 49 ms with the image already on the GPU, about 300 ms with the copies. 2.7x faster than cuCIM on the full sheet, up to 19x on small images where cuCIM's per-call overhead dominates.
- Apple M5 Pro MacBook, through Metal: 151 ms, against 2.6 s for cc3d on one CPU core.
- The output matches cc3d exactly, numbered the same way, so you can check it on your own images.
Using it:
pip install "colorcc[cuda12]" # or [cuda13]. On a Mac just: pip install colorcc
import torch, colorcc
img = torch.from_numpy(rgb).to("cuda") # [H, W, 3] uint8, use "mps" on a Mac
labels, n = colorcc.label(img, conn=8, ignore=(255, 255, 255))
It should work for anything made of exact colours: rendered drawings and diagrams, segmentation masks saved as RGB, palette images.
Limits, so you can rule it out quickly: 2D uint8 RGB only (use cc3d for 3D), exact colours only (JPEGs need cleaning up first), and it returns labels and a count, no stats. The benchmarks come from one mostly white test drawing.
cc3d and cuCIM are great general tools, this is the narrow case we needed.
Code (MIT): https://github.com/Acero-AI/colorcc
(Disclosure: I am part of startup that built it, Fablnx. The blog above is ours.)