Iris Lab

One-click detailed procedural eyes for rigged avatars in Blender.

Point Iris Lab at an eye mesh and it builds a fully procedural iris material — no manual UV work, no node wrangling. It detects each eyeball from the geometry, places the iris on the eyeball's own axis, and draws a detailed iris with radial fibre striations, a collarette ring, crypt mottling, a dark limbal ring, and a guaranteed matte-black pupil. Supports heterochromia (a different colour per eye).

Why it exists

MPFB's own procedural_eyes.json node tree is broken on Blender 5.x — socket drift (Voronoi / Vector-Math) during its node-tree import leaves the iris flat white. Iris Lab is a self-contained, version-robust replacement that works Blender 2.93 → 5.x, and it drives avatar eye setup down to a couple of clicks.

What it does

• Auto-detect eyeballs. Splits the eye mesh by object-space X sign, measures each eyeball's centre and radius from the geometry. No hardcoded numbers — works on any eye mesh (MakeHuman/MPFB, custom, etc.).
• Place the iris without UVs. Most eye meshes (MakeHuman included) have a degenerate eye UV that can't be textured. Iris Lab places the iris by object-space radial distance from the detected eyeball centre, front-masked by the surface normal — so it lands correctly regardless of UVs.
• Detailed iris. Two layers of radial fibre striations, a collarette ring (the pupillary/ciliary boundary), Voronoi crypt mottling, a dark limbal ring, and a dark→hue→bright radial colour gradient derived from your chosen colour.
• Heterochromia. Left (objX ≥ 0) and right (objX < 0) eyes get independent colours from one material — hard-selected per eye, no seam.
• Matte-black pupil, always. The pupil region is driven matte (zero specular, high roughness) so it stays black in any environment instead of reflecting the scene.
• Gaze alignment. Gaze Out / Gaze Up sliders nudge both irises to fix cross-eye / wall-eye without touching the rig.

Quick start

Open the Iris Lab tab in the 3D View sidebar (press N):

1. Setup — select your eye mesh (or leave blank to auto-pick), click Detect Eye Geometry. It reports the measured centre and radius.
2. Iris — pick Left Iris / Right Iris colours (toggle Heterochromia off for a single colour), set Iris Size / Pupil Size / Detail / Iris Gloss, then click Build / Update Eyes. Re-click after any change.
3. If the eyes look cross-eyed or wall-eyed, adjust Gaze Out (and Gaze Up) and rebuild.

Controls

Control	Default	Meaning
Heterochromia	on	Different colour per eye (left = objX≥0, right = objX<0)
Left / Right Iris	teal / red	Base iris colour; a dark→hue→bright gradient is derived from it
Iris Size	0.55	Iris radius as a fraction of the eyeball radius
Pupil Size	0.27	Pupil radius as a fraction of the iris radius
Detail	1.0	Strength of fibres / collarette / crypts
Iris Gloss	0.18	Iris roughness (lower = wetter). Pupil is always matte black
Gaze Out	0.18	Nudge irises outward(+)/inward(-) to fix cross/wall-eye (fraction of R)
Gaze Up	0.0	Nudge irises up(+)/down(-) (fraction of R)
Bake UV	Generate New UV	Generate a fresh UV (bake→optimize) or bake onto the existing UV (optimize→bake)
Bake Resolution	1024	Baked texture size (square)
Build baked material	on	Also make a flat Principled material from the baked image (engine-ready)

Installation

Single-file, drop-in add-on.

1. Blender 2.93+: Edit → Preferences → Add-ons (or Extensions on 4.2+) → Install…
2. Select iris_lab.py and enable Iris Lab.
3. Open the Iris Lab panel in the 3D View sidebar (N).

Blender version support

Requires Blender 2.93 or newer (bl_info minimum (2, 93, 0)). Register + material build + bake runtime-verified on Blender 2.93.0 and 5.1.2. Version-specific API is gated: Principled socket renames (Specular/Coat) are resolved by name with legacy fallbacks; Noise/Voronoi socket differences are set defensively; the material uses only nodes present across 2.93 → 5.x.

Unity / VRChat export

The iris is a procedural node material — engines can't run it directly. Use the Export → Bake Iris To Texture button to bake it (Cycles) to a flat image before FBX export. It's order-agnostic: Generate New UV (the default — the eye UV is usually degenerate) for the bake-then-optimize path, or Existing UV (e.g. after a CATS atlas) for the optimize-then-bake path. The bake is non-destructive — the procedural material is kept (a temp image node is added then removed), so you can keep iterating and re-bake; optionally it builds a flat engine-ready material from the baked image. Pupils stay black, ≤4 influences and clean naming are unaffected (this only touches the eye material).

Part of the Unity AI Lab Blender suite

Iris Lab is one of the Unity AI Lab Blender plugins. Each tool is standalone — no hard dependencies — but built to interoperate cleanly with its siblings:

• MPFB — when present, Iris Lab recognises the MPFB "Eyes" object type when auto-picking the eye mesh.
• Deform Doctor / Jiggle Lab — detected and surfaced; Iris Lab only ever touches the eye mesh's own material and never their attributes.
• Cats Blender Expanded / Texturly — sibling suite tools sharing the same avatar-first, VRChat/Unity-safe workflow.

Conflict-proofing is by design: own irislab.* operator namespace, IRISLAB_* classes, scene.iris_lab property, "Iris Lab" sidebar tab, and an IrisLab_ material-name prefix.

The suite is developed on the lab's self-hosted Forgejo host:

git@git.unityailab.com:UnityAILab/blender-iris-lab.git

License

GNU General Public License v3.0 or later (GPL-3.0-or-later). © Unity AI Lab.