CircuitPython displayio requires indexed bitmap graphics. Depending on the assets available, you may need to convert images to this format as well as crop images down and combine them into equally-sized sprite sheets. In this page, I'll go over the commonly-needed graphics manipulations.

Many photo editing software applications can handle these manipulations. One such free tool is GIMP Image Editor, which is what I used to prepare the Octopus game graphics.

This YouTube video shows my process for preparing some of the graphics.

Cropping Sprites

I needed the tentacle segments to be cut out and placed into individual .bmp files. GIMP provides the rectangle select tool for this purpose. Select the rectangle select tool and then drag a box around the thing you want to cut out. Adjust the sides as needed to contain exactly the element you want to cut out. 

Once you've got your selection made, press ctrl-C to copy the selection.

Then press ctrl-shift-V or click Edit -> Paste As -> New Image to paste it into a new file.

Now you can make any required touch ups on this element then convert it to indexed and save it as in the .bmp file format. For the Octopus tentacle segments, I needed to erase a bit in the corner of a different segment. I also changed the background to my transparency green and scaled the image to fit the aspect ratio for my target display size.

Scaling Graphics

The graphics that I found were not quite the same size as the target display I'm making the game for, so I had to scale them to match the target display size. I started with the background, it was 240x160 pixels. The PyGamer's display is 160x128 pixels so we need to scale down some. To find out how much, I divided the pixel sizes to find the scale factor.

160/240 = 0.6666667  Horizontal Scale Factor

128/160 = 0.8  Vertical Scale Factor

So my graphics need to get scaled down to 66.6% size width, and 80% size height. 

After cropping the graphics, I multiplied the size of the cropped image by these scale factors to find the final size of each graphic that will get used in the game. Once you have calculated the new size, the resize tool in GIMP can be used to make the change.

Select the scale tool, then click anywhere in your graphic. In the scale dialog that appears, ensure that the height and width are not linked, and enter the new values for height and width that you calculated. In some cases, I had to round up or down to the closest whole number for my scaled graphics. Once the new values are entered, click the Scale button.

Making Sprite Sheets

In cases where you have multiple sprites of the same size that are used within the same element in the game, you can combine all of the graphics into a sprite sheet instead of having individual graphics broken out. In the Octopus game, the DiverPlayer character is a good candidate for a sprite sheet because there are several different sprites used at different times throughout gameplay. All of them are roughly the same size, so I combined them into a sprite sheet and use a TileGrid to manage which sprite from the sheet is showing at any given time.

In CircuitPython, all tiles in a sprite sheet must have the same size. The full sheet image should be a multiple of the height and width of the tile size. Note that height and width can be different from each other, they just need to be consistent across tiles, the width of all tiles must be equal.

For the DiverPlayer sprite sheet, the sprites are 29x28 pixels and the sprite sheet is laid out as 3 rows by 4 columns. So the total size of the sheet comes out to 116x84 pixels. There is one unused slot in this sprite sheet.

I like to paste each sprite on its own layer within the GIMP project. I save the GIMP project .xcf file with all of these layers broken out so they are easy to update independently from each other later on if needed. When you're ready to export, you can keep an extra copy of your .xcf project file, and then flatten the image to a single layer with Image -> Flatten Image. Then you'll be ready to export it as an indexed bitmap.

Converting to Indexed Bitmap

If the graphics you find are PNG or JPG, you'll need to convert them to indexed bitmaps. Open your image in GIMP and then click Image -> Mode -> Indexed.

Transparency Color Index

Indexed BMPs do not support transparency in the same way that PNG images do. PNGs can contain transparent regions which are typically visually represented by a light and dark grey checkerboard pattern. For our indexed BMP graphics, we can select one or more colors in the palette to not get drawn when the display renders. This has the visual effect of making anything in the image that are those colors to be transparent from the users perspective. Any color(s) can be used; some game sprites use a bright pink for this purpose. I've chosen to use bright green for my bitmap graphics because I think of it similarly to green screen graphics. Try to choose a color that has easy visual contrast with the rest of the colors used by your asset; that will make it easier to imagine at a glance how your asset will appear when rendered in the game.

The pencil and paint bucket fill tools in GIMP are helpful for coloring in the necessary sections of your image with the chosen transparency color.

When you've got your transparent regions filled in with the selected transparency color, you can re-arrange the color map to move your transparency color the beginning of the list. That way, your code can remain the same from project to project.

Export As Bitmap

Once your graphics are prepared, you can export them as a bitmap file.

Click File -> Export As or press ctrl-shift-E

In the export dialog, ensure that "Select File Type (By Extension)" is checked. Navigate to the location you want to save your image. It's best to keep a copy of the project stored on your PC and then copy it from there to your CIRCUITPY drive. Enter a filename to save the image, and be sure to use .bmp as the extension at the end of your file.

Once you've chosen the directory and named your bitmap file, you can press the "Export" button.