Sinapsa.PixelArtGenerator

Small .NET tool for preparing images for an iDotMatrix interactive display.

This project takes source images, reduces them into pixel-art-friendly output, limits the palette, draws a visible grid, and also generates a color legend. It is useful when you want to turn normal artwork into something easier to show on a low-resolution LED matrix display such as the iDotMatrix.

It is part of my workflow for this display:

• device: iDotMatrix programmable LED display
• Python ecosystem/tooling: idotmatrix
• this app: image preparation and pixel-art conversion before sending artwork to the display

What it does

For each image found in the Images folder, the app:

1. Loads the image
2. Removes dark background areas using edge-aware background cleanup
3. Applies some preprocessing for pixel art
4. Downscales the image into a grid-based pixel-art version
5. Reduces the palette to a small number of colors
6. Generates a legend image with the detected palette
7. Saves all generated files into the Output folder

Current defaults

These values are currently hardcoded in Program.cs:

• targetColors = 10
• maxSquares = 64

That means every image is converted to a version that tries to use around 10 colors and fit within a 64 x 64 logical pixel grid.

Output files

For an input image like Images\example.png, the tool produces files in Output\ similar to:

• example_smartRemoveBackground.png
• example_preprocessForPixelArt.png
• example.jpg
• example_legend.png
• example.png

The final image is the grid-based pixel art version intended for display preparation.

Project structure

• Sinapsa.PixelArtGenerator/Program.cs - app entry point, loops through images
• Sinapsa.PixelArtGenerator/App.cs - small app wrapper
• Sinapsa.PixelArtGenerator/Services/PixelArtGenerator.cs - main generation workflow
• Sinapsa.PixelArtGenerator/Extensions/ImageExtensions.cs - background removal, preprocessing, downscaling
• Sinapsa.PixelArtGenerator/Extensions/ImageLegendExtensions.cs - palette legend generation
• Sinapsa.PixelArtGenerator/Services/KMeansColorQuantizer.cs - color quantization helper

Requirements

• .NET 8 SDK
• Windows, macOS, or Linux capable of running .NET 8

Main libraries used:

• SixLabors.ImageSharp
• SixLabors.ImageSharp.Drawing
• Microsoft.Extensions.Hosting

How to run

From the repository root:

dotnet run --project .\Sinapsa.PixelArtGenerator\Sinapsa.PixelArtGenerator.csproj

Or from inside the project folder:

dotnet run

Basic workflow

1. Put one or more source images into Sinapsa.PixelArtGenerator/Images
2. Run the app
3. Check the generated results in Output
4. Pick the version that looks best for your display
5. Use your normal idotmatrix workflow to send that image to the device

Notes

• The app currently processes all files found in the Images folder.
• The app creates the Output directory automatically if it does not exist.
• It is designed as a simple personal utility, so the settings are intentionally minimal and currently live in code.
• A key is read at the end of execution, which keeps the console window open when running interactively.

Why this exists

Low-resolution displays look better when artwork is simplified first. This tool helps convert normal images into something that is much more suitable for an LED matrix by:

• reducing visual noise
• limiting color count
• enforcing a square grid look
• giving a quick legend of the chosen palette

Possible future improvements

• move settings to configuration or command-line arguments
• allow choosing grid size and color count per run
• add filtering by file type
• export directly in the best format for the iDotMatrix toolchain
• preview the final image before sending to the display

License

No license file is currently included in this repository.