Exploring conv-kmeans-lab: A C++ Tool for CIELAB Image Color Segmentation
Source: Dev.to
Image segmentation is a fundamental task in computer vision, and grouping pixels by color is one of the most intuitive ways to achieve it. Enter conv‑kmeans‑lab, a specialized “Convolutional K‑means Color Segmenter in CIELAB”. Authored by Arpad K. (GitHub @arpad1337) and copyrighted in 2025, this C++ tool provides an elegant software solution for reducing the color palette of an image using the K‑means clustering algorithm. It is open‑source and freely distributed under the MIT License.
Under the Hood: The CIELAB Advantage and Data Structures
A distinct advantage of conv‑kmeans‑lab is its use of the CIELAB color space, which is designed to be more perceptually uniform than traditional RGB or BGR spaces. The repository uses C++ and relies heavily on the popular OpenCV library (specifically cv::Mat and cv::Vec3b) to handle image matrices and color conversions.
Data Structure
The project introduces a dedicated PixelLAB class that stores the l, a, and b channels as 8‑bit unsigned characters (values ranging from 0 to 255).
Distance Calculations
PixelLAB includes static methods to calculate both 2‑D and 3‑D Euclidean distances, which are crucial for determining how “close” two colors are within the CIELAB space.
Operator Overloading
The class overloads several operators for convenience:
- Subtraction operator (
-) instantly calculates the Euclidean distance between two pixels. - Division operator (
/) cleanly averages the values of two pixels to create a new one.
The KMeansColorSegmenter Engine
The heavy lifting of the library is performed by the KMeansColorSegmenter class. The typical workflow follows a straightforward initialization, training, and conversion pipeline.
Initialization
The segmenter is set up using a static create() method that takes an OpenCV image matrix, a desired number of colors (K), and an optional padding parameter. The algorithm requires that the requested color count have an integer square root. A provided BGR image is automatically converted to the LAB color space for processing.
Training
Calling train(epochs) iteratively refines the color clusters. During each epoch the algorithm:
- Computes the mean value of all pixels assigned to each centroid.
- Updates the centroids with these new mean values.
- Reassigns every pixel to its nearest centroid.
Conversion
The convert() method applies the trained centroids to the output matrix, replacing each pixel with the exact color of the cluster center it belongs to.
Advanced Usage and Multi‑Pass Segmentation
A powerful feature of the library is the ability to chain segmentations. Developers can feed a processed image back into the segmenter as the new input state using setPreviousOutputAsInput(). This enables iterative, multi‑pass refinement:
- Perform an initial training run on the original image.
- Pass the output back in as the active input.
- Set a new, smaller value for the desired number of colors with
setK(colors2). The segmenter intelligently merges existing clusters until the limit is reached. - Train and convert the image again for a more stylized, stepped color reduction.
The final segmented image can be retrieved either in its native LAB format via getLABOutput() or automatically converted back to standard BGR format for viewing with getOutput().
Conclusion
For developers working heavily with C++ and OpenCV, conv‑kmeans‑lab provides a robust, easy‑to‑use API for image segmentation. By leveraging the human‑like perception of the CIELAB color space and allowing recursive clustering passes, it offers an effective mechanism for customized color processing and image manipulation tasks.