🎨 Convert to PixelArt

A high-performance Python utility for batch-converting standard images into retro, stylized pixel art with custom palettes and CRT scanline effects.

📖 About

Convert to PixelArt is an automated image processing script designed to transform regular photographs or digital art into pixel art. It is ideal for rapid asset generation in 2D game development, especially for capturing gritty, atmospheric aesthetics reminiscent of classic top-down shooters or noir-action games.

The script leverages the Pillow library for advanced image manipulation, applying Lanczos downscaling, Floyd-Steinberg dithering against a custom 16-color "Grim" palette, and Nearest-Neighbor upscaling to maintain sharp, perfect pixels before applying a subtle CRT scanline overlay. It runs heavily optimized batch processing using Python's ProcessPoolExecutor.

---

📸 Before & After

---

🧩 Processing Pipeline

The following flowchart illustrates the transformation lifecycle of a single image as it passes through the conversion algorithm.

Snippet de código

sequenceDiagram
    autonumber
    participant FS as File System
    participant Core as Image Processor
    participant Filter as Enhancement & Scaling
    participant Dither as Quantization

    FS->>Core: Load Image (RGB)

    rect rgb(30, 30, 30)
        note right of Core: Dark Mode Enhancements
        Core->>Filter: Increase Contrast (1.2x)
        Core->>Filter: Adjust Brightness (0.85x)
        Core->>Filter: Enhance Color (0.4x)
    end

    Filter->>Core: Return Enhanced Image
    Core->>Filter: Downscale (Lanczos) to BASE_WIDTH (320px)

    Filter->>Dither: Apply "Grim" 16-color Palette
    Dither-->>Core: Floyd-Steinberg Dithering Applied

    Core->>Filter: Upscale (Nearest Neighbor) to 4K (3840px)
    Filter-->>Core: Sharp Pixel Perfect Image

    Core->>Core: Generate & Overlay 2px Scanlines (Alpha 40)
    Core->>FS: Save Output (_pixelart.png)

Loading

---

✨ Features

🚀 High-Performance Batch Processing

• Utilizes ProcessPoolExecutor to process multiple images concurrently, drastically reducing execution time for large asset folders.

🎨 Custom "Grim" Palette

• Hardcodes a specialized 16-color palette designed to give images a moody, low-fi, retro aesthetic.

📺 CRT Scanline Overlay

• Automatically renders horizontal semi-transparent black lines across the upscaled image, simulating the look of old CRT monitors.

⚖️ Smart Scaling

• Downscales images intelligently using the LANCZOS algorithm to preserve visual weight, and upscales the final result using NEAREST resampling to keep the pixel edges perfectly sharp at 4K resolution.

---

🛠 Tech Stack

• Language: Python 3

• Image Processing: Pillow (PIL)

• Concurrency: Built-in concurrent.futures (Multiprocessing)

• OS Operations: Built-in os module

---

⚙️ Installation & Run

Prerequisites

• Python (v3.8 or higher)

🚀 Setup Instructions

1. Clone the repository:

   Bash

   git clone https://github.com/g-brrzzn/convert_to_pixelart
   cd convert_to_pixelart
   
   

2. Install the dependencies: It's highly recommended to use a virtual environment, but you can install directly via pip:

   Bash

   pip install -r requirements.txt
   
   

3. Prepare your files: Place all the .png images you want to convert inside the input_images folder.

4. Run the script:

   Bash

   python convert_to_pixelart.py
   
   

5. Get your results: Check the output_images folder for your processed 4K pixel art files!