Sprite sheets module

[ctimmer]

I am working on a module to extract raw images from a sprite sheets. See code below.
The 'raw' image format has many variations but I can't find an image utility that creates a raw format used by OLED displays (pixel data only in RGB565 format). I'm using a custom python app (img2rgb565.py) to do the conversion. Anyone know of a utility that does this, I use Gimp but have not been able to create a raw file with the correct format.

Do most displays support this image format?

I am using this module on a Pico 2 w which seems to have enough memory to handle the raw images stored in memory.

Curt

################################################################################
#
## SpriteHandler - extract raw images from raw sprite sheets for displays
#
# Notes:
#   o Images must contain only pixel data in RGB565 (16bit) format,
#     no extra information
#   o All images must be the same size
#   o Images are accessed via an index
#
# Example usage:
'''
display = 480x320 display

raw_image = SpriteHandler ()
raw_image.load_raw_file ("tarot240x300.raw" ,
                        image_width = 40 ,
                        image_height = 75 ,
                        image_rows = 4)
#raw_image.buffer_images ()
#raw_image.store_all_images ("tarot")
for img_idx in range (0,11) :
    display.draw_sprite (raw_image[img_idx], x=5 + (img_idx * 42), y=10,w=40,h=75)
for img_idx in range (0,11) :
    display.draw_sprite (raw_image[img_idx+11], x=5 + (img_idx * 42), y=90,w=40,h=75)
'''

class SpriteHandler :
    def __init__ (self) :
        self.file_path = None        # Sprite image file input
        self.buffer = None           # Sprite images buffer
        self.image_count = 0         # number of images in buffer
        self.image_rows = None       # number of image rows
        self.image_columns = None    # number of image columns
        self.image_width = None      # individual image width
        self.image_height = None     # individual image height
        self.image_size = None       # image_width * image_height * 2
        self.image_buffers = None    # optional - stores individual sprite images

    ## load_row_sprite loads buffer from raw_image, saves image information
    def load_raw_sprite (self ,
                        raw_buffer ,
                        image_width ,
                        image_height ,
                        image_rows = 1) :
        buf_len = len (raw_buffer)
        self.image_count = 0
        self.image_buffers = None
        self.image_size = image_width * image_height * 2
        if buf_len % self.image_size != 0 :
            #raise RuntimeError (f"raw_sprite: buffer length error ({buf_len})")
            return None
        self.image_count = buf_len // self.image_size
        self.buffer = raw_buffer
        self.image_rows = image_rows
        self.image_columns = self.image_count // self.image_rows
        self.image_width = image_width
        self.image_height = image_height

    ## load_raw_file - reads raw sprite file and loads it to the buffer
    def load_raw_file (self ,
                        file_path ,
                        image_width ,
                        image_height,
                        image_rows = 1) :
        try :
            with open (file_path, "rb") as raw_file :
                buffer = raw_file.read ()
        except Exception as e :
            print (e)
            return
        self.file_path = file_path
        self.load_raw_sprite (bytes (buffer), image_width, image_height, image_rows)

    ## __getitem__ returns the indexed sprite image
    def __getitem__(self, index) :
        if self.image_count <= 0 :
            return
        if index < 0 \
        or index >= self.image_count :
            return
        if self.image_buffers is None :
            return self.extract_image (index)  # return image from buffer
        else :
            return self.image_buffers [index]  # return buffered image

    ## extract_image extracts raw image from buffer
    def extract_image (self, index) :
        image = bytearray ()
        row_offset = (index // self.image_columns) * (self.image_columns * self.image_size)
        row_offset += (index % self.image_columns) * self.image_width * 2
        #print ("row_offset:", row_offset)
        for idx in range (0, self.image_height) :
            image_offset = (self.image_width * 2) * idx
            image += self.buffer [row_offset:(row_offset + (self.image_width * 2))]
            row_offset += self.image_columns * self.image_width * 2
        return bytes (image)

    ## buffer_images extact all images to array
    # your device may not have enough memory to use this function
    # running garbage collect is recomended after calling
    def buffer_images (self):
        if self.buffer is None :
            return
        self.image_buffers = []
        for index in range (0, self.image_count) :
            self.image_buffers.append (self.extract_image (index))
        self.buffer = None

    ## store_all_images extract all images to files
    def store_all_images (self, path_base = "sprite_") :
        for index in range (0, self.image_count) :
            raw_image = self.__getitem__ (index)
            with open (f"{path_base}{index:04d}.raw", "wb") as raw_file :
                raw_file.write (raw_image)

[Gadgetoid]

If there's an off the shelf utility to produce raw format images, I haven't found it yet. It might be worthwhile building a tool that targets all of the formats MicroPython's framebuf supports.

Note: AIUI a FrameBuf instance can be set up with a width/height/stride and pointed at an existing buffer (your spritesheet) such that it represents the individual sprite without producing a copy of the data. stride defaults to width, but what it represents is the number of bytes until the next horizontal line of pixels. If your width and height are 32x32 but your spritesheet is 128x128 then you can cut a 32x32 slice out of it by using a stride of 128. Even if you're not using FrameBuf you can recreate this behaviour with a memory view and some basic metrics.

Most (possibly all?) colour LCDs and OLEDs support RGB565 (16bit) "natively", though there are many reasons to work in a reduced colour space (performance, memory restrictions) and E-Ink displays and monochrome LCDs tend to be a world unto themselves. Sometimes you want 24bit (an LED matrix display done right will usually take 24bit and gamma correct that up to 10+ bits per channel.)

I "solved" the image conversion problem with custom builds, and bindings into a C PNG decoder (https://github.com/bitbank2/PNGdec) but that's currently not very portable. Just chucking PNG and JPEG files onto a MicroPython device (though even those have caveats) is so much easier than preprocessing images, though there are always tradeoffs.

Sorry for the info dump- I've spent way too long mucking about with custom graphic libraries, sprite handling, animation, layering, blending, and so on and so forth.

[ctimmer]

Lots of good information here. Glad I'm not the only one struggling with this, it seems so simple. Based on your comments, I have already made changes to my module to allow for different pixel sizes.

Thanks,
Curt

[bikeNomad]

There is this on Github: https://github.com/cirquit/UTFTConverter

Also, Google Gemini suggests using ffmpeg like this:

FFmpeg (Command Line - Highly Recommended):
FFmpeg is a powerful multimedia tool that can handle a vast array of formats, including raw video and image data. It's often the easiest and most reliable command-line option.

From a PNG/BMP to RGB565 raw:

ffmpeg -i input.png -vcodec rawvideo -f rawvideo -pix_fmt rgb565 output.raw

Replace input.png with your source image file (JPG, BMP, etc.) and output.raw with your desired output filename. You might need to specify the resolution if FFmpeg can't infer it, especially if your image isn't rectangular:

ffmpeg -s WxH -i input.png -vcodec rawvideo -f rawvideo -pix_fmt rgb565 output.raw

(where W is width and H is height, e.g., 320x240)

Notes:

FFmpeg generally produces raw pixel data without any headers, which is what OLED displays often expect.

It can handle various input formats (PNG, JPEG, BMP, etc.).

Some users have noted that FFmpeg implicitly flips the image vertically during this conversion, which can sometimes be beneficial for embedded displays (where the origin might be top-left). Test this with your specific display setup.

However, I haven't tried this yet.

[ctimmer]

Tried both examples. The output was the correct size but was different than my converted file.
ffmpeg displayed this message many times:
full chroma interpolation for destination format 'rgb565le' not yet implemented
It kind of worked, the image was there, but the colors were messed up. Maybe due to byte ordering.

Thanks for the feedback, I will keep this as it may work in the future.
Curt

[ctimmer]

I made a demo to test the sprite sheets module. Seems to be very responsive.

The demo video:
https://github.com/user-attachments/assets/45dc957b-6baf-4b9a-9fc9-e9197c1c8305

And the png image the sprite sheet was generated from:

Curt