Image Per Instance panel reference
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. For problems, see troubleshooting.
Related
- Product page: Image Per Instance
- Troubleshooting
- Guide: different image per instance in Blender