# Working with Images

## Loading Images

This is an easy way to load and display images in Minicube64.

To load external data into memory we use the `incbin` directive. This is usually done at the end, below any previous existing code.

In this example we are loading an image and it's palette into memory. This can be done in any order but we will call the palette first:

```bash
  incbin "owl.pal"
  incbin "owl.raw"
```

In this example the `VIDEO` register has not been set and so it defaults to `0x0000` This is so that we can see the beginning of memory and the zero-page, and in turn the palette and image, as it exists in memory.

When we run our program, it should look like this:

![](https://1901532303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYlgFz1gOz3pvCbWdEb%2Fuploads%2Fcl1LWyG5Dik0d8EnPbai%2FScreenshot%202022-01-06%20at%2018.20.34.png?alt=media\&token=f4d300cc-ef91-451b-8023-1168f1ace1ed)

The image is clearly visible, along with the palette data above it. The palette data is 256 bytes and the image begins exactly after the palette ends. However the image is not aligned properly and is using the default colours, not the palette data we provided.

To display the image correctly we need to do a couple of things.

Before the `incbin` directive we can set the data origin to `0x0d00.` This ensures we position the data where we need it to be in memory.

```asm6502
 org $0d00
```

Next we need to set the `COLORS` register to point to the high-byte of the memory address where the palette is now located, which will then apply the correct colours.

```bash
  lda #$0d
  sta COLORS
```

By previously setting the origin to `0x0d00`, this has pushed the image to the next page in memory. We can now change the `VIDEO` register to `0x1000`

```bash
  lda #$1
  sta VIDEO
```

Now when we run the program we can see the image in full, with the correct palette.

![](https://1901532303-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MYlgFz1gOz3pvCbWdEb%2F-MZVC3BmF9XQqFZH719d%2F-MZVUPw8Yhs9y3Erj5j-%2FScreenshot%202021-04-30%20at%2001.53.20.png?alt=media\&token=f200c7dd-b471-4040-9912-e402520cff5b)

Because the image is a 64x64 full screen graphic, we can display this image without needing to use a draw routine.

{% hint style="info" %}
If your palette data is smaller than 256 bytes, you can use `org $1000` before including the image data which will force it into the next memory page rather than rely on the size of the palette to do that.
{% endhint %}

You can download and try out this example here:

{% file src="<https://1901532303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYlgFz1gOz3pvCbWdEb%2Fuploads%2FqCl12I8oKb4kHeY98t9X%2Fminicube64_images_example_22010501.zip?alt=media&token=f2214fe0-cf8e-479d-82c6-d86f817d8a4c>" %}

## Generating Images

Included with Minicube64 is a Python script that will convert a palette indexed `.png` image to a `.raw` format that can be used. A separate palette file will also be generated.

You can find the script called `im2cube.py` in the Tools folder.

{% hint style="danger" %}
Images must be `.png` format with an indexed palette.
{% endhint %}

To convert an image, run the script like so:

```python
python3 im2cube.py owl.png
```

By default the script will generate a palette based on luminance.

The script will also output a list of colours in hex format that can be copied into your code and used instead of the palette file.

{% hint style="info" %}
If you need to generate an unsorted palette, you can run the same command with a second argument such as `unsorted`
{% endhint %}