ClusterSweep
Documentation by Andras Gregori @ Gregorigin. Version: 1.1.0 stable. Framework: .NET Framework 4.8 (Native WPF).
1. INTRODUCTION
ClusterSweep is a specialized, lightweight post-processing utility designed for the "cleanup" phase of 2D game asset production. It addresses specific artifacts common in AI-generated sprites, procedural generation, and downscaled high-resolution art.
Unlike general image editors, ClusterSweep is built on automata logic. It does not "paint"; it mathematically enforcing grid logic and color clustering to remove noise (orphans) and unwanted gradients (blur).
1.1 Core Capabilities
Orphan Destruction: Cellular automata algorithms to identify and merge isolated pixels.
Euclidean Color Snapping: Hard-quantization of pixel colors to crush anti-aliasing artifacts.
Zero-Latency Preview: Direct buffer manipulation for instant feedback.
Pipeline Agnostic: Native Windows Drag-and-Drop support for PNG/JPG/BMP.
2. SYSTEM REQUIREMENTS & INSTALLATION
2.1 Hardware Specifications
ClusterSweep is extremely low-profile.
OS: Windows 10 (1903+) or Windows 11.
RAM: 100MB available (process footprint is typically <40MB).
GPU: Not required (CPU-based arithmetic).
Disk Space: 250KB (approx).
2.2 Software Dependencies
Microsoft .NET Framework 4.8: Pre-installed on all modern Windows installations. No additional runtime downloads are required.
2.3 Installation / Portability
ClusterSweep is portable software. It does not modify the Windows Registry or allow network connections.
Extract the ClusterSweep_v1.1.0.zip file to any location.
Run ClusterSweep.exe.
Note on Windows SmartScreen: Because ClusterSweep is an independent tool without a globally certified corporate signature, Windows may flag it as "Unrecognized." This is normal. Click More Info -> Run Anyway to bypass.
3. INTERFACE OVERVIEW
The GUI is divided into two primary zones: the Control Decks (Left) and the Viewport (Right).
3.1 Sidebar Controls
Status Readout: Displays image resolution and current operation status.
Clean Pass (Quick): Runs a single iteration of the orphan removal algorithm. Best for preserving fine details.
Deep Scrub: Runs 3 recursive iterations. Best for removing heavy dithering noise.
Sensitivity Slider (0-100%): Controls the Euclidean distance threshold for color merging.
Low values: Only merges nearly identical colors.
High values: Aggressively reduces color count.
Palette Snap: Executes the gradient reduction based on the Sensitivity slider.
Compare Toggle: Hold-to-preview mechanism. Switches the viewport buffer to the original file while depressed.
Reset: Reverts the working buffer to the original file state.
Export: Writes the current buffer to disk as a .PNG.
3.2 Viewport
Render Mode: NearestNeighbor. The software strictly prevents bilinear filtering to ensure you see exact pixels.
Background: Checkerboard pattern (programmatically generated) to visualize transparency (Alpha).
4. ALGORITHMIC DOCUMENTATION
Understanding the underlying logic allows for better usage of the tools.
4.1 Orphan Removal (The "Despeckle" Algorithm)
The "Clean Pass" uses a 4-neighbor Cellular Automata rule set.
Logic: For every pixel P(x,y), the algorithm checks neighbors Top, Bottom, Left, Right.
Cluster Rule: If P differs from all adjacent neighbors (a 1x1 island), it determines the "Dominant" neighbor (currently biased slightly to the Upper/Left scanline for waterfall consistency) and adopts that color.
Iteration:
Quick Pass: Scans the buffer once.
Deep Scrub: Scans the buffer, writes changes, then re-scans the new buffer result two more times. This handles "chains" of noise pixels.
4.2 Gradient Crushing (Palette Snapping)
This tool handles "Quantization" without dithering.
Logic: It utilizes a Greedy Euclidean Distance comparison.
Process:
The algorithm scans pixels linearly.
It maintains a dynamic cache of "Seen Colors."
For every new pixel, it calculates the 3D distance in RGB space:
R1−R2)2 + (G1−G2)2 + (B1−B2)2.
If the distance to a "Seen Color" is less than the Sensitivity Threshold, the pixel is forced to match the "Seen Color."
If outside the threshold, the pixel is added to the "Seen Color" cache.
5. WORKFLOW RECOMMENDATIONS
Scenario A: Cleaning AI Generation
AI image generators (Midjourney/DALL-E) often add "noise" to pixel art prompts.
Drop the raw AI image into ClusterSweep.
Slide Sensitivity to ~15-20%.
Click Palette Snap. This flattens the subtle gradients AI adds to flat surfaces.
Click Deep Scrub. This removes the "confetti" pixels often found in empty space.
Export.
Scenario B: Downscaling HD Art
When shrinking a 1080p drawing to 64x64, resampling creates blur.
Drop the downscaled image.
Slide Sensitivity to ~30% (Aggressive).
Click Palette Snap.
Use Quick Pass manually (click 1-2 times) to tidy up edges without destroying the shape.
6. TECHNICAL ARCHITECTURE
ClusterSweep achieves high performance via Unmanaged Memory Access (unsafe context).
Bitmap Handling: It bypasses the standard .NET GetPixel()/SetPixel() methods, which are slow due to overhead.
Direct Buffer Access: The application locks the WriteableBitmap back-buffer and manipulates the raw byte array (byte*) directly using pointer arithmetic.
Format: The engine forces BGRA32 pixel format for consistent stride calculation (Width × 4 bytes) across all input file types.
7. LICENSE & LEGAL
ClusterSweep is proprietary donationware.
Usage: You are free to use assets generated/cleaned by this tool in commercial or non-commercial projects (Games, Art, UI) without attribution.
Distribution: You may not redistribute, repackage, or sell the ClusterSweep.exe binary itself.
Warranty: The software is provided "as is," without warranty of any kind.
(c) 2025 Andras Gregori @ GregOrigin LLC.
Last updated