Image Per Instance documentation

Image Per Instance troubleshooting

Fixes for Image Per Instance in Blender: what each error message means, atlas size limits, missing UVs, instances not found, repeated images and Lite limits.

Each answer below uses the message text the add-on shows at the bottom of Blender. If your problem is not here, write to [email protected] with your Blender version and the add-on version shown at the bottom of the panel.

What does "Choose an image folder first" mean?

Build Atlas was pressed while Image Folder is empty. Click the folder icon next to Image Folder and choose a folder.

Why does Blender say "No images found" in my folder?

The folder exists but holds no supported files directly inside it. Supported types are png, jpg, jpeg, tif, tiff, bmp, webp, exr and tga. Subfolders are not searched, so move the images up one level or point to the subfolder. The message includes the folder path it looked in, so check it for typos.

What if the atlas is too big (limit 16384)?

The message reads "Atlas would be W x H px (limit 16384). Use a smaller tile size or fewer images". The atlas can be at most 16384 px on each side. 256 images at 1024 px fit exactly. 257 do not. Lower Tile Size, or use fewer images. A non-square Tile Shape changes the sizes too.

Why does the Lite version say "This free version supports up to 20 images"?

Lite builds atlases of up to 20 images. Move extra files out of the folder, or use the full version, which has no image limit in the add-on.

Why are some images black or missing in the atlas?

If a file cannot be read, Build Atlas reports "Skipped" with the file name and the reason, and that tile stays black. Open the file in Blender's image editor to see whether it loads, or convert it to png or jpg.

Why does Blender say "Build the atlas first"?

Apply To Selected Objects, Add To Instances (Geometry Nodes), Assign Image To Selected and Match By Object Name need an atlas in the current file. Press Build Atlas first. The atlas is stored in the .blend, so this also appears in a file where it was never built.

Why does Blender say "Select mesh objects"?

The buttons act only on selected objects of type mesh. Curves, empties, lights and cameras are ignored.

Why does my object show one stretched colour instead of an image?

The object probably has no UV map, or its UVs do not cover the whole 0 to 1 square, so only a small part of the atlas is sampled. Unwrap the object so the UVs fill the square, or switch Mapping under Material to Front, Top or Side (no UVs).

Why do some faces look streaked with Front, Top or Side mapping?

These modes are one flat projection across the object's bounding box, not triplanar. Faces that point in other directions stretch the image into a streak. Use a UV map for objects where those faces matter.

Why does the instances button say "No instanced source found"?

The full message is "No instanced source found: select the source objects and press again". The add-on looks for objects used by Object Info and Collection Info nodes in the host's Geometry Nodes modifiers, including nested groups. If your setup gets its objects some other way, select the source meshes together with the host, keep the host active, and press Add To Instances (Geometry Nodes) again.

Why does it say "Make the object with your Array / Instance on Points modifier active"?

The active object must be a mesh. Click the host in the outliner so it is the active one, then press the button.

Why do my instances all show the same image?

Instances show the material of their source objects, not of the host. Check that the source objects have the shared material in slot 1 (the message after the button lists them). The image index is stored on the instance domain by the last modifier, so instances must still exist at that point. If an earlier modifier or node realizes the instances before the IPI Assign Index modifier runs, there is nothing to store the index on. Keep the instances unrealized up to the end of the stack.

Why did my images change after pressing Build Atlas again?

The atlas is always in natural file-name order. Rebuilding keeps each object's picture by file name, but if you renamed or removed files, the objects that pointed at them cannot be matched. They keep their old number, which wraps around if it is beyond the new image count.

Why does Match By Object Name say "Press Build Atlas again"?

The message is "Press Build Atlas again: this file has no image names stored yet". The file was built with an older version that did not store the file names. Press Build Atlas and try again.

Why does Match By Object Name say "No object name matches an image file name"?

None of the selected objects have a name equal to, or containing, a file name. The match ignores case and a trailing .001. Rename the objects, or use Assign Image To Selected.

Why does Assign Image To Selected say the Image Number is too high?

The message reads "Image Number N is too high: the atlas has M images". Lower the number, or rebuild the atlas with more images.

Why do two files like cat.png and cat.jpg appear as one name?

The picker uses file names without the extension, so both show as cat. Choose them by Image Number instead.

Why does Shuffle look repetitive?

Shuffle spreads images evenly, but with few images the pattern can show a rhythm. Change Seed and press the button again, or add Random Variation.

Do the instances and the separate objects shuffle the same way?

No. For separate objects the add-on shuffles the object list with the Seed. For instances the modifier steps through the images with a step that fits the image count and an offset taken from the Seed.

Image Per Instance workflows
Previous page
Image Per Instance changelog
Next page