# Image Per Instance panel reference

> Every field, button and option of the Image Per Instance panel in Blender: atlas settings, material, animation and random variation, with defaults and ranges.

- Page: https://mendboxstudio.com/docs/image-per-instance/panel
- Updated: 2026-11-16
- Publisher: Mendbox Studio (Dynamic Flower Unipessoal LDA, Portugal)

All controls live in the 3D viewport sidebar (**N**), in the **Image Per Instance** tab. This page follows the panel from top to bottom. Version 0.2.0.

## Main panel: atlas settings

| Control | What it does | Default / range |
|---|---|---|
| Image Folder | Folder with your images. Only files directly inside it are read, not subfolders. Supported types: png, jpg, jpeg, tif, tiff, bmp, webp, exr, tga. | empty |
| Tile Size | Size of one atlas tile in pixels: 128, 256, 512, 1024 or 2048. With a non-square Tile Shape this is the length of the longer side. | 512 px |
| Tile Shape | Shape of one tile: 1 : 1, 2 : 3, 3 : 2, 3 : 4, 4 : 3, 16 : 9 or 9 : 16. Pick the shape of your frames, covers or screens. | 1 : 1 |
| Fit | What happens when an image has a different shape than the tile. **Stretch** fills the tile and distorts the image. **Fit (bars)** shows the whole image with bars around it. **Fill (crop)** covers the whole tile and crops the edges. | Stretch |
| Bar Colour | Colour of the bars. Only shown when Fit is **Fit (bars)**. | black, 0 to 1 per channel |
| Padding | Edge padding in pixels that hides bleeding between neighbouring tiles. | 4, range 0 to 32 |
| Order | **By file name** or **Shuffle**. Shuffle uses every image once before any repeats. It changes which image an object or instance gets, not the order inside the atlas. | By file name |
| Seed | Picks the shuffled arrangement. Only shown when Order is **Shuffle**. | 1 |

## Main panel: buttons and labels

| Control | What it does |
|---|---|
| Build Atlas | Packs all images from the folder into one atlas and creates the shared material. The atlas is always in natural file-name order, so Image Number N is the N-th file. Pressing it again replaces the atlas. Objects keep the picture they showed, matched by file name. |
| Atlas label | Shows "Atlas: N images", or "Atlas: not built" before the first build. |
| Apply To Selected Objects | Gives each selected mesh object its own image and puts the shared material on it. With Order **By file name**, objects are sorted by name (natural order) and get images 1, 2, 3 and so on, wrapping around when there are more objects than images. With **Shuffle**, the objects are shuffled using the Seed. |
| Add To Instances (Geometry Nodes) | The active object is the host with your Array or Instance on Points modifier. The add-on finds the instanced source objects, sets the shared material on them, and adds a modifier named "IPI Assign Index" on the host. Selected mesh objects are added as sources too. Press it again after changing Seed or Order to update the modifier. |
| "Press again after changing Seed to re-shuffle" | A hint. Change Seed, then press Apply To Selected Objects or Add To Instances again. |
| Version label | "Image Per Instance v" followed by the version number. |

How the atlas is laid out: the number of columns is chosen from the image count and the tile shape, so the atlas stays roughly square. The atlas image is named `IPI_Atlas`, the material `IPI_Material`. The atlas can be at most 16384 px on each side.

## Choose Images Yourself

Collapsed by default. Applies to separate objects only, as the panel says.

| Control | What it does | Default / range |
|---|---|---|
| Image Number | Number of the image in the atlas. 1 is the first file. Changing it updates the Image field. | 1, minimum 1 |
| Image (search field) | Pick the image by file name, you can type to search. Choosing a name sets Image Number. | empty |
| Assign Image To Selected | Gives every selected mesh object the image with the chosen number, and the shared material. Fails with a message if the number is higher than the number of images. | |
| Match By Object Name | Each selected object gets the image whose file name equals the object name. If there is no exact match, the longest file name that appears as a whole word in the object name wins (`card_10` gets `10`, not `1`), then the longest file name contained in the name. A Blender duplicate suffix such as `.001` is ignored, and case does not matter. Objects without a match are listed in the message. | |

## Material

Collapsed by default. These options update the material at once, without pressing a button again, as long as the atlas is built.

| Control | What it does | Default / range |
|---|---|---|
| Mapping | Where the image sits on the object. **UV Map** uses the object's UV map, which must fill the 0 to 1 square. **Front (no UVs)**, **Top (no UVs)** and **Side (no UVs)** project the image across the whole object from the front, top or right side. | UV Map |
| Use Image Alpha | PNG transparency cuts the shape out (stickers, round cards, the bars of Fit mode). Sets the material render method to Dithered. | off |
| Emissive (screen) | The image glows by itself, for video walls, billboards and screens. | off |
| Strength | Emission strength. Only shown when Emissive is on. | 1.0, minimum 0, soft maximum 10 |
| Roughness | Roughness of the material. | 0.5, range 0 to 1 |

## Animate

Collapsed by default. The checkbox in the sub-panel header switches animation on.

| Control | What it does | Default / range |
|---|---|---|
| Animate (checkbox) | Every object steps through the images over time, each starting at its own image. | off |
| Frames Per Image | How many frames each image stays before the next one. | 24, minimum 1, soft maximum 240 |

## Random Variation

Collapsed by default. All values start at zero, which adds no nodes to the material.

| Control | What it does | Default / range |
|---|---|---|
| Hue | Random hue shift per object. | 0, range 0 to 1 |
| Saturation | Random saturation change per object. | 0, range 0 to 1 |
| Brightness | Random brightness change per object. | 0, range 0 to 1 |
| Flip X | Mirrors a random half of the objects left to right. | off |
| Flip Y | Mirrors a random half of the objects top to bottom. | off |

## What the add-on creates in your file

| Name | What it is |
|---|---|
| `IPI_Atlas` | The packed atlas image |
| `IPI_Material` | The shared material, used in slot 1 of each affected object |
| `img_index` | Custom property on separate objects holding the image index (the first image is 0) |
| `IPI Assign Index` | Geometry Nodes modifier on the host, using the node group `IPI_Assign_Index` with inputs Image Count, Shuffle, Seed and Shuffle Step. It stores `img_index` on every instance. |

For recipes, see the [workflows](https://mendboxstudio.com/docs/image-per-instance/workflows). For problems, see [troubleshooting](https://mendboxstudio.com/docs/image-per-instance/troubleshooting).

## Related

- Product page: [Image Per Instance](https://mendboxstudio.com/addons/image-per-instance)
- [Troubleshooting](https://mendboxstudio.com/docs/image-per-instance/troubleshooting)
- Guide: [different image per instance in Blender](https://mendboxstudio.com/guides/different-image-per-instance)

---
Source: https://mendboxstudio.com/docs/image-per-instance/panel
