K-Clustering Image Compression

An implementation of K-means clustering for image compression using C++ and no external ML libraries. This project, again, is a pure demonstration of my appreciation for machine learning and is not intended for production use. I still love raw pointers, but I'll start implementing smart ones in my next projects.

Table of Contents

• Features
• Setup
• Usage
• Example
• License

Features

• K-means++ initialization for better clustering
• Customizable number of clusters using a spin control
• Image loading and saving with custom .dat formats that displays color metadata
• Simple GUI design with wxWidgets for real-time compression, interaction and visualization

Setup

Requirements

• CMake ≥ 3.16
• A C++17 compiler
• OpenMP (optional; will use system version if available)
• wxWidgets v3.2.x (must be installed on your system)

Important: Users must install wxWidgets manually. The short setup guide for it is provided below.

Setup Guide

1. Clone the repository:

   git clone https://github.com/JazzJE/k-means-image-compression

2. Install dependencies

Linux (Debian/Ubuntu/Kali)

sudo apt update && sudo apt install -y build-essential cmake libwxgtk3.0-gtk3-dev libgtk-3-dev

Tip: If libwxgtk3.2-dev isn’t available, try:

sudo apt install -y libwxgtk3.2-gtk3-dev libwxbase3.2-dev

macOS

brew update && brew install cmake wxwidgets

Note: You may need to add wxWidgets to your PATH on macOS:

export PATH="/opt/homebrew/opt/wxwidgets/bin:$PATH"

Windows

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat
.\vcpkg install wxwidgets:x64-windows

Then configure CMake to use vcpkg:

cmake .. -DCMAKE_TOOLCHAIN_FILE=path\to\vcpkg\scripts\buildsystems\vcpkg.cmake

3. Build the project:

   mkdir build
   cd build
   cmake ..
   cmake --build .

4. Run the program

   ./k_means_image_compression

Usage

1. Use the GUI to load an image, set the number of clusters, and compress an image

2. Save any compressed images that you want to keep in a .PNG or custom .DAT format
   (the .DAT file can only be opened using the display option of the program)

Example

Original - 3.78 MB       Compressed (K-Means) - 2.55 MB

Compression reduced file size by approximately 33% with minimal quality loss.