2D Image Filter

A comprehensive collection of pixel art scaling algorithms for upscaling low-resolution computer and console graphics.

2D Image Filter is a powerful library that brings together the most popular image scaling algorithms specifically designed for pixel art and low-resolution graphics. Unlike traditional image scaling methods that often blur or distort pixel art, these algorithms preserve the crisp, clean aesthetic while intelligently enlarging images.

🧭 Vision

🎯 Project goals

• Algorithm Collection: Gather all available pixel art scaling filters in one comprehensive library
• Enhanced Flexibility: Convert rigid color comparisons into parameterized "IsLike" functions
• Wide Compatibility: Support various graphics types with configurable similarity thresholds
• Performance: Optimized implementations using unsafe code for maximum speed

🔧 Key Innovation

Traditional scaling algorithms use hard-coded comparisons:

(color1 == color2) ? color1 : color3

Our enhanced approach uses flexible similarity functions:

(color1.IsLike(color2)) ? Interpolate(color1, color2) : color3

✨ Features

📦 Multiple Distribution Formats

• Standalone Application: GUI application for interactive image processing
• Paint.NET Plugin: Seamless integration with Paint.NET editor
• Library: .NET library for programmatic use in your applications

🎨 Supported Scaling Algorithms

Classic Pixel Art Scalers

• Eagle Family: Eagle 2x/3x, Super Eagle
• SaI Family: 2xSaI, Super2xSaI (Kreed/DOSBox)
• Scale Family: Scale2x/3x (MAME - Andrea Mazzoleni)
• AdvInterp: AdvInterp2x/3x (MAME)

High Quality Scalers

• HQ Family: HQ2x/3x/4x (Maxim Stepin)
• LQ Family: LQ2x/3x/4x (SNES9x/AdvMAME)
• nQ Family: nQx Bold and Smart versions

Modern Advanced Scalers

• XBR Family: XBR2x/3x/4x Normal and NonBlend (Hyllian)
• XBRz: High quality scaling (Zenju), 2x-6x, as released up to 1.8
• XBRz 1.9: XBRz with the 1.9 refinements — a higher steep direction threshold and blends rounded rather than truncated. Offered as its own entry, so the plain XBRz entries keep producing exactly the pixels they always did
• Reverse AA: Anti-aliasing filter (Hyllian)

Specialized Effects

• CRT Effects: MAME TV/RGB, Hawkynt TV effects
• Scanlines: Horizontal/vertical scanline effects
• Bilinear Plus: VBA enhanced bilinear filtering
• FNES Filters: DES, 2xSCL variants

Resampling Kernels

• Comprehensive collection of windowing functions
• Bicubic, Lanczos, and exotic mathematical kernels
• Support for custom radius and parameters

📦 Installation

Prerequisites

• .NET Framework 4.5 or higher
• Windows Vista/7/8/10/11

🚀 Quick start

Option 1: Standalone Application

1. Download from Releases
2. Extract and run ImageResizer.exe
3. Load your image and select a scaling algorithm
4. Configure parameters and export the result

Option 2: Paint.NET Plugin

1. Download the Paint.NET plugin
2. Extract to your Paint.NET Effects folder
3. Restart Paint.NET
4. Find "Pixel Art Scaling" in the Effects menu

Option 3: Command Line Interface

ImageResizer.exe /load input.png /resize auto "Upscaler: HQ 2x" /save output.png
ImageResizer.exe /load sprite.bmp /resize 400% "Upscaler: XBR 3x" /save scaled_sprite.png

🖼️ Screenshots

The Reduce Colours dialog: quantizer and ditherer thumbnails, histogram and detail preview, all generated from deterministic demo data.

📚 Documentation

Command Line Usage

The application supports powerful command-line scripting.

Filter names use the category prefix shown in the GUI dropdown. Scaling prefixes are directional: Upscaler: (integer upscalers such as HQ, XBR, Eagle, Scale), Downscaler: (integer downscalers, future), Resampler: (bidirectional arbitrary-ratio kernels such as Bicubic, Lanczos), Downsampler: (downscale-only resamplers such as DPID, SSIM Downscale). Other categories: Filter: , Plane: , Quantize: , Dither: , Blend: . Pass the full label as the filter argument; the prefix may be omitted where the bare name is unambiguous, which keeps command lines and .irs scripts written before the prefixes existed working.

# Basic usage
ImageResizer.exe /load <input> /resize <dimensions> <method> /save <output>

# Dimension formats
/resize auto "Upscaler: Scale 2x"          # Auto-detect from algorithm
/resize 320x240 "Resampler: Bicubic"       # Specific dimensions
/resize w128 "Upscaler: HQ 2x"             # Width only (height auto)
/resize h96 "Upscaler: Eagle"              # Height only (width auto)
/resize 200% "Upscaler: XBR 3x"            # Percentage scaling
/resize auto "HQ 2x"                       # Prefix omitted - unambiguous

# Parameter examples
/resize auto "Resampler: Bicubic(radius=1.5,vbounds=wrap)"
/resize 2x2 "Upscaler: HQ 2x(thresholds=1)"

Run ImageResizer.exe /? to print the full help including the list of every supported filter method; with no arguments it opens the GUI.

Batch processing

A /load whose name contains * or ? runs the rest of the chain once per matching file. A * in a later file name stands for the matched file's own name, so every target is named after its source — no need to write the same lines out per sprite:

# every png in the folder, upscaled into bigImageResizer.exe /load *.png /resize auto "Upscaler: HQ 2x" /save big\*.png

# convert a whole folder while scaling
ImageResizer.exe /load sprites\*.bmp /resize 400% "Upscaler: XBR 4x" /save out\*.png

Piping

/stdin reads an image from standard input and /stdout writes a PNG to standard output. Standard output carries image data and nothing else — progress reports and errors go to standard error — so a run can be piped straight into another program:

# chain two runs
ImageResizer.exe /load in.png /resize auto "HQ 2x" /stdout | ImageResizer.exe /stdin /resize auto "XBR 3x" /save out.png

# hand the result to another tool
ImageResizer.exe /load in.png /resize auto "XBR 3x" /stdout | magick - out.webp

Supported Parameters

• radius: Filter radius for resampling kernels
• thresholds: Enable/disable similarity thresholds
• repeat: Number of filter repetitions
• vbounds/hbounds: Out-of-bounds handling (const, half, whole, wrap, transparent)
• centered: Use centered grid for filtering

🎮 Perfect For

• Pixel Art: Classic video game sprites and artwork
• Retro Gaming: Emulator enhancement and ROM hacking
• Digital Art: Low-resolution artwork enlargement
• Game Development: Asset upscaling for modern displays
• Academic Research: Comparative analysis of scaling algorithms

🏆 Algorithm Credits

This project implements algorithms from numerous sources:

• Eagle/Super Eagle: Derek Liauw Kie Fa (Kreed), ZSNES team
• Scale2x/3x: Andrea Mazzoleni (MAME)
• HQ2x/3x/4x: Maxim Stepin
• XBR: Hyllian
• XBRz: Zenju
• Resampling Kernels: Pascal Getreuer
• FNES Filters: FNES emulator team
• VBA Enhancements: VBA-rr team

📊 Downloads

• Standalone Application: Download v2.0.0
• Paint.NET Plugin: Download v2.0.0

🛠️ Building

# Clone the repository
git clone https://github.com/Hawkynt/2dimagefilter.git
cd 2dimagefilter

# Build the solution
dotnet build ImageResizer.slnx -c Release

# Run the tests
dotnet test ImageResizer.slnx -c Release

# Or build individual projects
dotnet build ImageResizerLibrary/ImageResizerLibrary.csproj
dotnet build ImageResizer/ImageResizer.csproj

🤝 Contributing

Contributions are welcome! Whether you want to:

• Add new scaling algorithms
• Improve existing implementations
• Fix bugs or enhance performance
• Improve documentation

Please feel free to open an issue or submit a pull request.

❤️ Support

If this project saves you time or money, consider supporting its development:

📜 License

Licensed under LGPL-3.0-or-later — see LICENSE.