Converts images to Joy of Painting .paint files

JoyConverter.py

# Joy of Painting Image Converter
# by fynntimes in 2024
#
# Required packages:
# - Pillow (python3 -m pip install Pillow)
# - nbtlib (python3 -m pip install nbtlib)

import argparse
from PIL import Image
from nbtlib import File
from nbtlib.tag import Byte, Int, IntArray, String
import uuid
import time

CANVAS_TYPES = {
    # ct ordinal byte, width, height
    "small": (0, 16, 16),
    "large": (1, 32, 32),
    "long": (2, 32, 16),
    "tall": (3, 16, 32),
}

parser = argparse.ArgumentParser(
    prog="JoyConverter",
    description="Converts images to Joy of Painting .paint files"
)

parser.add_argument("input", help="Path to input image")
parser.add_argument("output", help="Path to output file, i.e. output.paint")
parser.add_argument("canvas_type", help="Canvas type", choices=CANVAS_TYPES.keys())

args = parser.parse_args()

ct, width, height = CANVAS_TYPES[args.canvas_type]
im = Image.open(args.input).convert("RGBA")
pixels = im.load()
bitmap = []
for y in range(height):
    for x in range(width):
        r, g, b, a = pixels[(x, y)]
        # From https://github.com/ercanserteli/xercamods/blob/1.20/XercaPaintMod/src/main/java/xerca/xercapaint/common/PaletteUtil.java#L27
        val = r
        val = (val << 8) + g
        val = (val << 8) + b
        val += 0xFF000000
        bitmap.append(val)

out = File({
    'ct': Byte(ct),
    'generation': Int(0),
    'name': String(f"{uuid.uuid1()}_{int(time.time())}"),
    'pixels': IntArray(bitmap),
    'v': Int(1),
})
out.save(args.output)

print(f"Wrote converted image to {args.output} ({width}x{height}).")
print("Place it in the 'paintings' directory within your modpack folder.")

Usage

You need to have Python 3.x installed on your computer. You can check by opening a terminal (command prompt) and typing python3 -version. If it shows a version number, you're good.

Next, install the required packages for this script by running the following command in a terminal:

python3 -m pip install numpy==1.26.4 Pillow nbtlib

numpy 2.0 and later will break this script because nbtlib has not yet been updated to account for numpy's new data promotion rules. The latest supported numpy version is 1.26.4.

Once that's done, you can use the script!

python3 JoyConverter.py <input image> <output path> <canvas type {small, large, long, tall}>

• input image is the path to the image you want to convert.
• output path is where you want the converted Joy of Painting file to be. It should end in ".paint"
• canvas type is the type of canvas to use, one of "small" (16x16), "large" (32x32), "long" (32x16), "tall" (16x32)

The input image size should be the same as the canvas size or else it will get cut off!