py-super-xbr

The Super-xBR pixel-art scaling algorithm implemented as a Python module and command line tool.

Examples

Fawful (Mario & Luigi: Superstar Saga) scaled 2x (Image source)

Misery (Cave Story) scaled 4x (Image source)

Requirements

Python 3.12 or later. This was tested on Windows, but should also work on macOS and Linux.

Installation

This isn't uploaded to PyPI yet (orginal still isn't, this probably won't too), so you'll have to build and install this from source.

• pip install git+https://github.com/MikiP98/py-super-xbr.git

OR:

1. Clone this repository to your system
2. Open a terminal and go to the repository's directory
3. Run pip install .

Usage

From the command line

Applies the Super-xBR upscale filter to the image INPUT and saves it to OUTPUT:

superxbr [OPTIONS] INPUT OUTPUT

Options

positional arguments:
  INPUT       Input image file path
  OUTPUT      Output image file path

optional arguments:
  -h, --help  show this help message and exit
  -p PASSES   Number of times to apply the Super-xBR filter. The image
              scale is doubled each time the filter is applied. (default: 1)
  -m MODE     Color mode of the output image file. Choices are 1, L, LA, I, P,
              RGB, RGBA, or CMYK. Note that some color modes are not
              compatible with some image formats and will raise an exception.
              (default: RGBA)
  --quiet     Hide progress updates

In a Python script

Images are scaled using superxbr.scale()

from PIL import Image  # Pillow 7.x
from superxbr import superxbr

# Create an Image object
im = Image.open('example.png')

# Apply the Super-xBR scale filter to the image
im_scaled_2x = superxbr.scale(im)

# You can apply the filter multiple times
# The scale is doubled each time the filter is applied
im_scaled_8x = superxbr.scale(im, 3)

Building

Install required packages:

pip install -r requirements.txt

superxbr.c needs to be regenerated if superxbr.pyx is modified:

cython superxbr/superxbr.pyx

To compile a python extension module (.pyd or .so file):

python3 setup.py build_ext --inplace

To build a wheel:

python3 setup.py bdist_wheel

License

Updated py-super-xbr is available under the Apache License Version 2.0.
The code is based on the py-super-xbr released by n0spaces under the MIT License.
Which code is based on the Super-xBR C++ port released by Hylian also under the MIT License.

See LICENSE.txt.

See also

• Pixel-art scaling algorithms on Wikipedia
• original py-super-xbr by n0spaces
• Super-xBR explanation by Hylian