Free Open‑Source Tool Turns Photos into Pixel Art in Minutes

If you love the nostalgic look of 8‑bit graphics but don’t want to learn how to hand‑paint pixels, Photo2Pixel is the answer. It’s a Python repository that uses PyTorch to automatically convert any photograph into a pixel‑art style image. The algorithm applies a blur kernel for smooth color transitions, quantizes the image into fixed‑size pixel blocks, and adds optional black edge lines to give that classic retro feel.

What is Photo2Pixel?

Photo2Pixel is more than just a script; it’s a tiny ecosystem:

• Online Demo – Visit photo2pixel.co to see the converter running in the browser.
• Colab Notebook – The repo includes a ready‑to‑run notebook that lets you experiment without installing anything locally.
• CLI Tool – A lightweight command‑line interface (convert.py) that accepts an image path and a few tweakable parameters.

The project is released under the Apache‑2.0 license, has over 500 stars on GitHub, and is actively maintained.

Key Features

Installation & Setup

# Clone the repository
git clone https://github.com/Jzou44/photo2pixel.git
cd photo2pixel

# Create a virtual environment (optional but recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

If you only want to run the online converter, you can skip the local installation and use the Web UI at photo2pixel.co.

Basic Usage

python convert.py --input ./images/example_input_mountain.jpg

By default the output is written to ./result.png. The command will use:

• kernel_size=10
• pixel_size=16
• edge_thresh=100

These defaults work well for most images.

Customizing the Output

Adjust the three parameters to fit your style:

python convert.py \
  --input ./images/hero.png \
  --kernel_size 12 \
  --pixel_size 12 \
  --edge_thresh 80 \
  --output ./output/hero_pixel.png

• kernel_size – Larger values (≥15) give a smoother look, while smaller values (≤5) keep sharp transitions.
• pixel_size – 8‑bit pixel art is usually 8–16 px; test with 4 for pixel‑perfect results on very small images.
• edge_thresh – Set lower (e.g., 50) to get thicker black outlines. Keep it high (>200) to remove most outlines.

Example: Turning a Landscape into Retro 8‑bit

Below is a quick example of turning a high‑resolution mountain photo into a retro‑style pixel art:

python convert.py --input ./images/example_input_mountain.jpg \
  --kernel_size 12 \
  --pixel_size 12 \
  --edge_thresh 120 \
  --output ./output/mountain_pixel.png

The resulting image is a perfect blend of smooth color gradients and crisp pixel blocks, reminiscent of early console games.

Running in Colab

If you prefer a web‑based environment, copy the content of the convert.ipynb notebook into Google Colab:

1. Upload the repository’s convert.ipynb.
2. Install the dependencies with !pip install -r requirements.txt.
3. Upload an image file.
4. Run the cells to see the conversion live.

This method is ideal for quick experiments or sharing results with collaborators.

Contributing

The project welcomes contributions!

• Bug Reports – Open an issue if you spot a problem.
• Pull Requests – Fork the repo, make changes, and submit a PR. Follow the existing style and keep tests (if any) passing.
• Feature Enhancements – Ideas such as new edge detection algorithms, more interactive UI, or a batch‑processing mode are great.

Feel free to also add documentation in your native language or create a tutorial for new users.

Community & Support

• GitHub Discussions for general questions.
• Discord (link in README) for real‑time help.
• Twitter handle @photo2pixel for updates.

Conclusion

Photo2Pixel demonstrates how powerful image‑processing tools can be packaged into a simple, open‑source command‑line app. Whether you’re a developer looking to embed pixel‑style effects in a game or a hobbyist wanting to create retro art, this project gives you control and flexibility without the overhead of manual pixel art tools.

Download the repo, play with the parameters, and enjoy crafting your own 8‑bit masterpiece—all in minutes.

Happy pixel‑arting!