DEV Community

Frank
Frank

Posted on

Creating SD versions of @2x osu! skin files with Python and Pillow (without dark edges)

Many osu! skins are now drawn at high resolution only, with files like hitcircle@2x.png and no matching hitcircle.png. osu! can still use them, but players who run the game at low resolutions load images twice the size they need and rely on osu!'s own scaling. Skin authors who ship both versions also avoid the guesswork of how osu! will scale each file.

Shrinking by hand in an image editor is tedious with a hundred files, and naive resizing of transparent PNGs often adds a dark fringe around circles and cursors. Here is a short script that does it properly.

The script

#!/usr/bin/env python3
"""make_sd.py SKIN_DIR [--overwrite] - create SD (@1x) PNGs from @2x PNGs in an osu! skin."""
import sys
from pathlib import Path
from PIL import Image

def main():
    if len(sys.argv) < 2:
        sys.exit("usage: make_sd.py SKIN_DIR [--overwrite]")
    skin = Path(sys.argv[1])
    overwrite = "--overwrite" in sys.argv[2:]
    made = skipped = 0
    for hd in sorted(skin.rglob("*@2x.png")):
        sd = hd.with_name(hd.name.replace("@2x.png", ".png"))
        if sd.exists() and not overwrite:
            skipped += 1
            continue
        with Image.open(hd) as im:
            im = im.convert("RGBA")
            w, h = im.size
            if w % 2 or h % 2:
                print(f"warning: {hd.name} is {w}x{h}; odd sizes lose half a pixel")
            size = (max(1, round(w / 2)), max(1, round(h / 2)))
            # premultiply-safe resize: LANCZOS on RGBA can create dark fringes,
            # so resize colour and alpha separately using the alpha as weight
            r, g, b, a = im.split()
            rgb = Image.merge("RGB", (r, g, b))
            black = Image.new("RGB", im.size)
            premul = Image.composite(rgb, black, a).resize(size, Image.LANCZOS)
            a_small = a.resize(size, Image.LANCZOS)
            out = Image.new("RGBA", size)
            px_c, px_a, px_o = premul.load(), a_small.load(), out.load()
            for y in range(size[1]):
                for x in range(size[0]):
                    al = px_a[x, y]
                    if al == 0:
                        px_o[x, y] = (0, 0, 0, 0)
                    else:
                        c = px_c[x, y]
                        px_o[x, y] = tuple(min(255, v * 255 // al) for v in c) + (al,)
            out.save(sd, optimize=True)
        made += 1
        print(f"{hd.name} {w}x{h} -> {sd.name} {size[0]}x{size[1]}")
    print(f"done: {made} created, {skipped} already had an SD file")

if __name__ == "__main__":
    main()
Enter fullscreen mode Exit fullscreen mode

Run it with python3 make_sd.py "path/to/skin". It only creates files that are missing; add --overwrite to regenerate every SD file from its @2x source.

Why the premultiply step matters

Transparent pixels in a PNG still have a colour, and in many exported images that colour is black. A resampling filter like LANCZOS mixes neighbouring pixels, so at the edge of a circle it blends your pink with the invisible black. The result is a thin grey or dark ring that is very visible on hitcircle.png and cursor.png.

The script avoids that by multiplying each pixel's colour by its alpha before resizing, resizing alpha separately, then dividing the colour by the new alpha. Fully transparent pixels no longer contribute any colour, so edges stay clean. It is slower than a single resize() call because of the per-pixel loop, but a skin folder is processed in a few seconds.

Things to check afterwards

  • Odd sizes. The script warns when an @2x image has an odd width or height. osu! expects @2x files to be exactly twice the SD size, so a 101-pixel-wide file cannot be halved cleanly. Fix the source canvas rather than living with half-pixel offsets.
  • Animations. Frames such as hit300-0@2x.png are converted one by one. Make sure every frame of an animation has the same size, otherwise the animation wobbles.
  • Pixel art. For deliberately pixelated skins, change Image.LANCZOS to Image.NEAREST so pixels stay sharp.
  • Fonts. For score- and default- digits, check that the halved images still line up. Thin strokes can disappear at SD size and may need a manual touch-up.

Testing in game

Lower the game resolution (for example to 1024x768), reload the skin with Ctrl+Shift+Alt+S, and play a map. The circles and cursor should look identical in shape, only smaller, with no halo around them.

Related

If you want reference skins to test against, osuskins.org has a large library with gameplay screenshots, and its install guide explains how to import and switch skins. I also wrote earlier about generating a contact sheet for a whole skin folder with Pillow, which pairs well with this script for a quick visual check.

Top comments (0)