Image Per Instance documentation

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.

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

ControlWhat it doesDefault / range
Image FolderFolder 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 SizeSize 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 ShapeShape 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
FitWhat 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 ColourColour of the bars. Only shown when Fit is Fit (bars).black, 0 to 1 per channel
PaddingEdge padding in pixels that hides bleeding between neighbouring tiles.4, range 0 to 32
OrderBy 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
SeedPicks the shuffled arrangement. Only shown when Order is Shuffle.1

Main panel: buttons and labels

ControlWhat it does
Build AtlasPacks 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 labelShows "Atlas: N images", or "Atlas: not built" before the first build.
Apply To Selected ObjectsGives 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.

ControlWhat it doesDefault / range
Image NumberNumber 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 SelectedGives 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 NameEach 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.

ControlWhat it doesDefault / range
MappingWhere 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 AlphaPNG 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
StrengthEmission strength. Only shown when Emissive is on.1.0, minimum 0, soft maximum 10
RoughnessRoughness of the material.0.5, range 0 to 1

Animate

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

ControlWhat it doesDefault / range
Animate (checkbox)Every object steps through the images over time, each starting at its own image.off
Frames Per ImageHow 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.

ControlWhat it doesDefault / range
HueRandom hue shift per object.0, range 0 to 1
SaturationRandom saturation change per object.0, range 0 to 1
BrightnessRandom brightness change per object.0, range 0 to 1
Flip XMirrors a random half of the objects left to right.off
Flip YMirrors a random half of the objects top to bottom.off

What the add-on creates in your file

NameWhat it is
IPI_AtlasThe packed atlas image
IPI_MaterialThe shared material, used in slot 1 of each affected object
img_indexCustom property on separate objects holding the image index (the first image is 0)
IPI Assign IndexGeometry 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.

Install Image Per Instance in Blender
Previous page
Image Per Instance workflows
Next page