Median Cut

This project is a Java Maven application built using NetBeans IDE that performs color quantization using the Median Cut algorithm. It supports multiple color spaces (RGB, HSL, HSB, OKLAB, and Grayscale), configurable channel sorting, and bucket control to generate optimized color palettes for images.

---

Table of Contents

1. Features
2. Usage
3. How It Works
4. Color Spaces Supported
5. Additional Examples

---

Features

• Median Cut Quantization
  • Reduces an image to a limited color palette by recursively subdividing the color space.
  • Supports an arbitrary number of buckets (palette size).
• Multi-Color-Space Conversion
  • RGB, HSL, HSB, OKLAB, and Grayscale conversion support via plugin architecture.
• Channel Sorting
  • Custom ordering of channels before quantization for fine control (e.g., prioritize Lightness or Brightness).
• KD-Tree Palette Mapping
  • Efficient color mapping using a KD-Tree nearest-neighbor search.
• Parallelized Image Reconstruction
  • Multi-threaded pixel mapping for fast processing.
• Automatic File Naming and Saving
  • Output images are automatically named and saved with the current configuration.
• Optional Display
  • Configurable flags to display or skip preview (skip / save).

---

Usage

1. Build or Run the Application
   • Run and execute:

   java -jar MedianCut.jar

2. Configure the Process
   • Define the color space and your desired order for sorting priority.
   • The output will be automatically generated with a descriptive filename such as:

   MedianCut[COLOR_SPACE;CHANNEL_1;CHANNEL_2;CHANNEL_3;N_BUCKETS]
   

   • Flags
     • Skip All → skip all next display windows.
     • Save → save image to same folder as original.

---

How It Works

Below is a high-level description of the Median Cut pipeline:

1. Color Space Conversion
   • Converts the input image into the target color space (RGB, HSL, HSB, OKLAB, etc.) using modular plugins.
2. Unique Pixel Extraction
   • Each pixel is normalized and stored as a unique 3-channel Pixel object with reference counting.
3. Pixel Sorting
   • Pixels are sorted according to a configurable channel order (e.g., prioritize Lightness or Saturation).
4. Recursive Median Cut
   • The pixel list is split recursively into “buckets” by the axis with the largest variance until the desired number of clusters is reached.
5. Palette Generation
   • Each bucket’s average color forms a palette entry.
6. KD-Tree Construction
   • A KdTreeRGB is built from the palette for efficient nearest-color search.
7. Image Reconstruction
   • Each pixel in the original image is replaced by the nearest color from the palette (multi-threaded).

---

Color Spaces Supported

Color Space	Description
RGB	Red, Green, Blue
HSL	Hue, Saturation, Lightness
HSB	Hue, Saturation, Brightness
OKLAB	L, A, B
Grayscale	Sum of RGB values

---

Additional Examples

Input	RGB Red Sorted (8 colors)	HSL Lightness Sorted (8 colors)	OKLAB L Sorted (8 colors)

---