Photoreal Blender scenes from a one-paragraph brief, built by AI agents: image→3D props on fal, scripted layout, lighting, camera and grade.
Python
"""Effects classifier for the AnyScene -> Unreal exporter (NIAGARA.md §4): turns volume-shader effects and particle
systems into `scene.json["fx"]` entries (schema in NIAGARA.md §4.2) with a technique, an AnySceneFX template and its
User parameters filled in, so build_level.py only places and sets them.
Used two ways:
* from export_blend.py: `import fx_export; fx = fx_export.classify(sc, frame, emitters, volumes)`
* standalone (no mesh bakes; patches an existing export):
blender -b <copy>.blend --python unreal_fx/fx_export.py -- --scene <export>/scene.json --out <dir>/scene.json [--frame 60]
writes the input scene.json + "fx" (and marks the volumes an fx entry claims) to --out.
Detection is evidence-based (material node tree, drivers, particle settings, names as a tie-breaker). Parameters
come from measurements: procedural volumes are baked on horizontal slices (density / emission per texel) to get
the plume's base, lean, spread and reach; driver expressions on mapping nodes give the scroll (rise) speed; particle
settings give rate, speed, size and lifetime; the ground under a drip line comes from a ray cast.
"""
import json
import math
import os
import re
import sys
import zlib
import bpy
import numpy as np
from mathutils import Vector
LM_PER_W = 683.0
TEMPLATES = "/Game/AnySceneFX/Systems/{0}.{0}"
TYPE_WORDS = {"fire": ("flame", "fire", "burner"), "steam": ("steam", "vapor", "vapour"), "smoke": ("smoke", "curl"),
"haze": ("haze", "fog", "mist"), "rain": ("rain", "drizzle"), "drips": ("drip",), "dust": ("dust", "mote"),
"sparks": ("spark",), "embers": ("ember",)}
PARAM_TYPES = None # filled from templates.json when present
def log(*a):
print("FXEXPORT", *a, flush=True)
def ue_vec(v, s=100.0):
return [v[0] * s, -v[1] * s, v[2] * s]
def ue_dir(v, s=100.0):
return [v[0] * s, -v[1] * s, v[2] * s]
def crc(s):
return zlib.crc32(s.encode()) & 0x7FFFFFFF
def name_hint(name):
n = name.lower()
return {t for t, ws in TYPE_WORDS.items() if any(w in n for w in ws)}
# ------------------------------------------------------------------ node-tree evidence
def out_node(nt):
outs = [n for n in nt.nodes if n.type == "OUTPUT_MATERIAL"]
return next((n for n in outs if n.is_active_output), outs[0] if outs else None)
def volume_material(o):
for s in o.material_slots:
m = s.material
if m and m.node_tree:
o_ = out_node(m.node_tree)
if o_ and o_.inputs["Volume"].is_linked and not o_.inputs["Surface"].is_linked:
return m
return None
def principled_volume(m):
return next((n for n in m.node_tree.nodes if n.type == "PRINCIPLED_VOLUME"), None)
def drivers(m):
ad = m.node_tree.animation_data if m.node_tree else None
return list(ad.drivers) if ad else []
def driver_rate(d, fps):
"""Per-second rate of a driver expression that is linear in `frame` (e.g. "-frame * 0.055")."""
ex = d.driver.expression
try:
f = lambda fr: eval(ex, {"__builtins__": {}}, {"frame": fr, "sin": math.sin, "cos": math.cos}) # noqa: E731
return (f(101.0) - f(100.0)) * fps
except Exception:
return None
def mapping_scroll(m, fps):
"""Pattern velocity in object space (m/s) from Mapping-node Location drivers: the pattern moves by -dL/scale."""
v = [0.0, 0.0, 0.0]
found = False
for d in drivers(m):
mt = re.match(r'nodes\["([^"]+)"\]\.inputs\[(\d+)\]\.default_value', d.data_path)
if not mt:
continue
nd = m.node_tree.nodes.get(mt.group(1))
if not nd or nd.type != "MAPPING" or int(mt.group(2)) != 1: # inputs[1] = Location
continue
r = driver_rate(d, fps)
if r is None:
continue
sc = nd.inputs["Scale"].default_value[d.array_index] or 1.0
v[d.array_index] = -r / sc
found = True
return v if found else None
def noise_evolution(m, fps):
"""Fastest 4D-noise W rate (1/s): how quickly the pattern re-forms (flicker / boil)."""
rates = []
for d in drivers(m):
mt = re.match(r'nodes\["([^"]+)"\]\.inputs\[\d+\]\.default_value', d.data_path)
if mt and m.node_tree.nodes.get(mt.group(1)) and m.node_tree.nodes[mt.group(1)].type == "TEX_NOISE":
r = driver_rate(d, fps)
if r is not None:
rates.append(abs(r))
return max(rates) if rates else 0.0
def emission_colour(m, levels_z, weights):
"""Emission-weighted mean colour. Handles a ColorRamp on Emission Color (evaluated at each level's generated z
when its factor comes from a generated/Z chain; otherwise at 0.6)."""
pv = principled_volume(m)
s = pv.inputs["Emission Color"]
if not s.is_linked:
return list(s.default_value)[:3]
n0 = s.links[0].from_node
if n0.type != "VALTORGB":
return [1.0, 0.5, 0.1]
fac = n0.inputs[0]
by_z = fac.is_linked and fac.links[0].from_node.type == "SEPXYZ" and fac.links[0].from_socket.name == "Z"
if not by_z:
return list(n0.color_ramp.evaluate(0.6))[:3]
acc, w = np.zeros(3), 0.0
for z, wt in zip(levels_z, weights):
acc += np.array(n0.color_ramp.evaluate(float(z))[:3]) * wt
w += wt
return list(acc / max(w, 1e-9))
# ------------------------------------------------------------------ slice sampling (Cycles EMIT bakes)
_BS = None
def bake_scene(frame):
global _BS
if _BS is None:
bs = bpy.data.scenes.new("__fxbake")
bs.render.engine = "CYCLES"
bs.cycles.device = "CPU"
bs.cycles.samples = 1
bs.cycles.use_denoising = False
bs.render.bake.target = "IMAGE_TEXTURES"
bs.frame_current = frame
_BS = bs
return _BS
def sample_slices(o, m, frame, n=32, levels=12):
"""Bake Density and Emission Strength of a volume material on `levels` horizontal slices through the object's box
(sharing its object and texture space). Returns lo, hi (object space) and arrays [levels, n, n] per channel."""
me0 = o.data
xs = [v.co for v in me0.vertices]
lo = Vector([min(c[i] for c in xs) for i in range(3)])
hi = Vector([max(c[i] for c in xs) for i in range(3)])
pv = principled_volume(m)
zs = [lo.z + (k + 0.5) / levels * (hi.z - lo.z) for k in range(levels)]
out = {"density": np.zeros((levels, n, n)), "emission": np.zeros((levels, n, n))}
bs = bake_scene(frame)
for li, z in enumerate(zs):
me = bpy.data.meshes.new("__fxslice")
me.from_pydata([(lo.x, lo.y, z), (hi.x, lo.y, z), (hi.x, hi.y, z), (lo.x, hi.y, z)], [], [(0, 1, 2, 3)])
uv = me.uv_layers.new(name="UVMap")
for i, c in enumerate([(0, 0), (1, 0), (1, 1), (0, 1)]):
uv.data[i].uv = c
me.use_auto_texspace = False
me.texspace_location = me0.texspace_location
me.texspace_size = me0.texspace_size
sl = bpy.data.objects.new("__fxslice", me)
bs.collection.objects.link(sl)
sl.matrix_world = o.matrix_world.copy()
mc = m.copy()
me.materials.append(mc)
nt = mc.node_tree
pvc = next(nd for nd in nt.nodes if nd.type == "PRINCIPLED_VOLUME")
on = out_node(nt)
for l in list(on.inputs["Volume"].links):
nt.links.remove(l)
for key, sock in (("density", "Density"), ("emission", "Emission Strength")):
s = pvc.inputs[sock]
if not s.is_linked and s.default_value == 0:
continue
em = nt.nodes.new("ShaderNodeEmission")
if s.is_linked:
nt.links.new(s.links[0].from_socket, em.inputs["Color"])
else:
em.inputs["Color"].default_value = (s.default_value,) * 3 + (1,)
nt.links.new(em.outputs[0], on.inputs["Surface"])
img = bpy.data.images.new("__fxvol", n, n, alpha=False, float_buffer=True)
img.colorspace_settings.name = "Non-Color"
tx = nt.nodes.new("ShaderNodeTexImage")
tx.image = img
nt.nodes.active = tx
with bpy.context.temp_override(scene=bs, view_layer=bs.view_layers[0], object=sl, active_object=sl,
selected_objects=[sl], selected_editable_objects=[sl]):
bpy.ops.object.bake(type="EMIT", margin=0, use_clear=True)
px = np.empty(n * n * 4, np.float32)
img.pixels.foreach_get(px)
out[key][li] = px.reshape(n, n, 4)[:, :, 0] # [row = y, col = x]
nt.nodes.remove(tx)
nt.nodes.remove(em)
bpy.data.images.remove(img)
bpy.data.objects.remove(sl)
bpy.data.meshes.remove(me)
bpy.data.materials.remove(mc)
return lo, hi, zs, out
def plume_stats(o, lo, hi, zs, field, n):
"""Per-level weighted centroid (world), radial spread (m) and peak, from a [levels, n, n] field."""
mw = o.matrix_world
xs = np.linspace(lo.x, hi.x, n, endpoint=False) + (hi.x - lo.x) / (2 * n)
ys = np.linspace(lo.y, hi.y, n, endpoint=False) + (hi.y - lo.y) / (2 * n)
X, Y = np.meshgrid(xs, ys)
sx, sy, sz = mw.to_scale()
rows = []
for k, z in enumerate(zs):
f = np.clip(field[k], 0, None)
tot = f.sum()
if tot <= 1e-9:
rows.append(None)
continue
cx, cy = (f * X).sum() / tot, (f * Y).sum() / tot
r = np.sqrt(((X - cx) * sx) ** 2 + ((Y - cy) * sy) ** 2)
rows.append({"c": mw @ Vector((cx, cy, z)), "spread": float((f * r).sum() / tot), "r_peak": float(r[np.unravel_index(np.argmax(f), f.shape)]),
"peak": float(np.percentile(f, 98)), "mean": float(f.mean()), "sum": float(tot)})
return rows
# ------------------------------------------------------------------ entries
def template_for(typ, default):
"""Template whose recipe lists this fx type (templates.json "fx_types"), so a recipe an agent adds for a new type
is picked up without code changes; falls back to the built-in default."""
for name, t in (PARAM_TYPES or {}).items():
if typ in t.get("fx_types", []):
return name
return default
def base_entry(fid, typ, conf, kind, objs, mat, evidence, center_ue, extent_ue, technique, template, fps, preroll):
template = template_for(typ, template) if template else template
if technique == "niagara" and template is None:
technique = "agent" # no template for this type yet: queued for the look-match agent (FX_AGENT.md)
return {"id": re.sub(r"[^A-Za-z0-9_]", "_", fid), "type": typ, "confidence": round(conf, 2),
"source": {"kind": kind, "objects": objs, "material": mat, "evidence": evidence},
"transform": {"loc": center_ue, "quat": [0, 0, 0, 1], "scale": [1, 1, 1]},
"bounds_ue": {"center": center_ue, "extent": extent_ue},
"technique": technique, "template": TEMPLATES.format(template) if template else None,
"params": {}, "param_types": {}, "physical": {}, "time": {"preroll_s": preroll, "fps": fps},
"seed": crc(fid), "notes": []}
def set_params(e, params):
tpl = e["template"].split("/")[-1].split(".")[0] if e["template"] else None
types = (PARAM_TYPES or {}).get(tpl, {}).get("params", {})
for k, v in params.items():
if types and k not in types:
e["notes"].append(f"param {k} not on {tpl}: dropped")
continue
e["params"][k] = [round(x, 4) for x in v] if isinstance(v, (list, tuple)) else round(float(v), 4)
e["param_types"][k] = types.get(k) or ("color" if k == "Color" else "vec3" if isinstance(v, (list, tuple)) else "float")
def nearest_light(sc, p_world, radius=1.0):
"""The dominant light near the effect (highest energy within radius), so fire never double-lights."""
best = None
for o in sc.objects:
if o.type == "LIGHT" and not o.hide_render:
d = (o.matrix_world.translation - p_world).length
if d <= radius and (best is None or o.data.energy > best[0]):
best = (o.data.energy, o.name)
return best[1] if best else None
def flicker(sc, light_name, frame, n, fps):
o = sc.objects.get(light_name)
if not o or not (o.data.animation_data and o.data.animation_data.drivers):
return None
vals = []
for f in range(frame, frame + n):
sc.frame_set(f)
vals.append(o.data.energy)
sc.frame_set(frame)
base = vals[0] or 1.0
return {"target": light_name, "property": "intensity", "fps": fps, "start_frame": frame,
"values": [round(v / base, 4) for v in vals], "note": "multiplier on the light's exported intensity"}
def classify_volume(sc, o, m, frame, fps):
pv = principled_volume(m)
ev, score = [], {}
emit_linked = pv.inputs["Emission Strength"].is_linked or pv.inputs["Emission Strength"].default_value > 0
bb = pv.inputs["Blackbody Intensity"].default_value > 0
if emit_linked or bb:
score["fire"] = score.get("fire", 0) + 4
ev.append("principled volume emission")
scroll = mapping_scroll(m, fps)
has_noise = any(n.type == "TEX_NOISE" for n in m.node_tree.nodes)
alb = list(pv.inputs["Color"].default_value)[:3]
dims = o.dimensions
if not emit_linked:
if has_noise and scroll and scroll[2] > 0.3:
score["steam" if min(alb) > 0.85 else "smoke"] = 4
ev.append(f"noise scrolling up {scroll[2]:.2f} m/s, albedo {min(alb):.2f}")
if max(dims) > 3.0 and (not scroll or abs(scroll[2]) < 0.05 * fps):
score["haze"] = score.get("haze", 0) + 3
ev.append(f"large box {max(dims):.1f} m")
for t in name_hint(o.name) | name_hint(m.name):
score[t] = score.get(t, 0) + 2
ev.append(f"name hint {t}")
if not score:
return None, ev, 0.0
ranked = sorted(score.items(), key=lambda kv: -kv[1])
top = ranked[0]
runner = ranked[1][1] if len(ranked) > 1 else 0
return top[0], ev, top[1] / (top[1] + runner)
def seen_from(sc, dg, p, cams, skip):
"""True if the world point p has an unobstructed line to any camera (volume-only objects are see-through)."""
for cpos in cams:
d = cpos - p
dist = d.length
d.normalize()
q, left = p.copy(), dist
for _ in range(16):
hit, loc, _n, _i, ob, _m = sc.ray_cast(dg, q, d, distance=left)
if not hit:
return True
if ob is not None and (getattr(ob, "original", ob).name in skip or volume_material(getattr(ob, "original", ob))):
step = (loc - q).length + 1e-3
q, left = loc + d * 1e-3, left - step
continue
break
return False
def visible_field(sc, o, lo, hi, zs, field, n, rel=0.02):
"""Mask each slice of `field` to the samples some scene camera can see, which is what Cycles shows: burner jets
under a wok, flame inside a collar, a fire behind fireplace walls are hidden by opaque geometry. Samples under
`rel` x the field's peak are dropped. Returns the masked field and the visible fraction per level."""
cams = [c.matrix_world.translation.copy() for c in sc.objects if c.type == "CAMERA"]
mw = o.matrix_world
if not cams:
return field.copy(), [1.0] * len(zs)
dg = bpy.context.evaluated_depsgraph_get()
xs = np.linspace(lo.x, hi.x, n, endpoint=False) + (hi.x - lo.x) / (2 * n)
ys = np.linspace(lo.y, hi.y, n, endpoint=False) + (hi.y - lo.y) / (2 * n)
thr = rel * float(np.clip(field, 0, None).max())
out, frac = np.zeros_like(field), []
for k, z in enumerate(zs):
f = np.clip(field[k], 0, None)
for j, i in zip(*np.nonzero(f > thr)):
if seen_from(sc, dg, mw @ Vector((xs[i], ys[j], z)), cams, {o.name}):
out[k, j, i] = f[j, i]
frac.append(float(out[k].sum() / f.sum()) if f.sum() > 1e-9 else 0.0)
return out, frac
def view_radiance(sc, o, lo, hi, zs, field, vis, n):
"""Line integral of `field` (emission per metre) along each camera's view ray through every camera-visible sample:
the radiance Cycles shows there (a ray grazing a ring of flame crosses far more than one tongue's width).
Returns the 90th percentile over samples and cameras, in the field's units x metres."""
cams = [c.matrix_world.translation.copy() for c in sc.objects if c.type == "CAMERA"]
if not cams:
return 0.0
mw = o.matrix_world
inv = mw.inverted()
levels = len(zs)
dz = (zs[1] - zs[0]) if levels > 1 else (hi.z - lo.z)
sx, sy, sz = mw.to_scale()
step = 0.5 * min((hi.x - lo.x) / n, (hi.y - lo.y) / n, dz)
step_m = step * (sx + sy + sz) / 3
span = (hi - lo).length
xs = np.linspace(lo.x, hi.x, n, endpoint=False) + (hi.x - lo.x) / (2 * n)
ys = np.linspace(lo.y, hi.y, n, endpoint=False) + (hi.y - lo.y) / (2 * n)
out = []
for k, j, i in zip(*np.nonzero(vis > 0)):
p = Vector((xs[i], ys[j], zs[k]))
best = 0.0
for c in cams:
d = (p - inv @ c).normalized()
ts = np.arange(-span, span, step)
P = np.array(p)[None] + ts[:, None] * np.array(d)[None]
ii = np.floor((P[:, 0] - lo.x) / (hi.x - lo.x) * n).astype(int)
jj = np.floor((P[:, 1] - lo.y) / (hi.y - lo.y) * n).astype(int)
kk = np.floor((P[:, 2] - lo.z) / (hi.z - lo.z) * levels).astype(int)
ok = (ii >= 0) & (ii < n) & (jj >= 0) & (jj < n) & (kk >= 0) & (kk < levels)
best = max(best, float(np.clip(field[kk[ok], jj[ok], ii[ok]], 0, None).sum() * step_m))
out.append(best)
return float(np.percentile(out, 90)) if out else 0.0
def visible_rz(em, R, zw):
w = np.clip(em, 0, None)
if w.sum() <= 0:
return None
rr = np.broadcast_to(R[None], w.shape).ravel()
zz = np.broadcast_to(np.array(zw)[:, None, None], w.shape).ravel()
ww = w.ravel()
o = np.argsort(rr)
c = np.cumsum(ww[o]) / ww.sum()
return {"r": round(float((rr * ww).sum() / ww.sum()), 3), "z": round(float((zz * ww).sum() / ww.sum()), 3),
"r10": round(float(rr[o][np.searchsorted(c, 0.1)]), 3), "r90": round(float(rr[o][np.searchsorted(c, 0.9)]), 3)}
def fire_entry(sc, o, m, frame, fps, ev, conf):
n = 32
lo, hi, zs, f = sample_slices(o, m, frame, n=n, levels=12)
em_all = f["emission"]
st_all = plume_stats(o, lo, hi, zs, em_all, n)
pk_all = max(x["peak"] for x in st_all if x)
# Only what a scene camera can see counts (Cycles hides the rest the same way): burner jets under a wok, flame
# inside a collar, a fire behind fireplace walls. Measure the visible part; fall back to the upper half of the band
# when nothing is visible (a fire inside a closed box is still worth a glow).
em, vfrac = visible_field(sc, o, lo, hi, zs, em_all, n)
st = plume_stats(o, lo, hi, zs, em, n)
# A visible arc covers few texels: compare per-level maxima, not the slice-wide percentile in plume_stats.
mx_vis = em.reshape(len(zs), -1).max(axis=1)
occluded = bool(mx_vis.max() < 0.01 * float(em_all.max()))
lev = [k for k in range(len(zs)) if st[k] and mx_vis[k] > 0.08 * mx_vis.max()] if not occluded else []
if occluded:
em, st = em_all, st_all
lev = [k for k, r in enumerate(st) if r and r["peak"] > 0.08 * pk_all]
mw = o.matrix_world
zw = [(mw @ Vector((0, 0, zs[k]))).z for k in range(len(zs))]
vis = (lev[len(lev) // 2:] if len(lev) > 3 else lev) if occluded else lev
z0, z1 = zw[vis[0]], zw[lev[-1]]
dz = (zw[1] - zw[0]) if len(zw) > 1 else 0.05
# The ring is the emission-weighted radius of the visible part about the whole flame's axis (only the arc facing
# the camera is visible, so the visible centroid itself is off-axis).
axis = st_all[lev[0]]["c"] if st_all[lev[0]] else st[lev[0]]["c"]
ax, ay = (mw.inverted() @ axis).xy
sx, sy, _ = mw.to_scale()
gx = np.linspace(lo.x, hi.x, n, endpoint=False) + (hi.x - lo.x) / (2 * n)
gy = np.linspace(lo.y, hi.y, n, endpoint=False) + (hi.y - lo.y) / (2 * n)
GX, GY = np.meshgrid(gx, gy)
R = np.hypot((GX - ax) * sx, (GY - ay) * sy)
wv = np.clip(em[vis], 0, None)
ring = float((wv * R[None]).sum() / wv.sum()) if not occluded else float(max(st[k]["r_peak"] for k in vis))
base = {"c": Vector((axis.x, axis.y, z0))}
width = max(0.01, float(np.average([st_all[k]["spread"] for k in vis if st_all[k]])) * 0.5)
E = float(np.percentile(em[lev][em[lev] > 0], 99)) if (em[lev] > 0).any() else float(np.percentile(em_all, 99))
# Colour from the visible upper part of the flame (the blue base is the Core emitter's job).
# The licking tips (faint, above the 8% body threshold) carry the flame colour; the blue base is the Core emitter.
pk = max(x["peak"] for x in st_all if x)
faint = [k for k, r in enumerate(st_all) if r and r["peak"] > 0.01 * pk]
upper = set(faint[-3:])
weights = [st_all[k]["sum"] if st_all[k] and k in upper else 0 for k in range(len(zs))]
gz = [(k + 0.5) / len(zs) for k in range(len(zs))]
# Flame body colour = the warmest colour among emitting levels (the blue base is drawn by the Core emitter).
cands = [emission_colour(m, [gz[k]], [1.0]) for k in faint]
col = max(cands, key=lambda c: c[0] / (c[2] + 0.05)) if cands else emission_colour(m, gz, weights)
if max(col) < 1e-3: # an emissive flame is never black: fall back to the whole flame's emission-weighted colour
col = emission_colour(m, gz, [st_all[k]["sum"] if st_all[k] else 0 for k in range(len(zs))])
mx = max(col) or 1.0
height = max(0.03, z1 - z0 + dz)
scroll = mapping_scroll(m, fps) or [0, 0, 1.0]
boil = noise_evolution(m, fps)
life = float(np.clip(height / max(scroll[2], 0.3), 0.18, 0.5))
c = Vector((base["c"].x, base["c"].y, z0))
e = base_entry(o.name, "fire", conf, "volume_shader", [o.name], m.name, ev, ue_vec(c),
[(hi.x - lo.x) * 50 * mw.to_scale()[0], (hi.y - lo.y) * 50 * mw.to_scale()[1], (height + 0.1) * 100],
"niagara", "NS_Fire", fps, 1.0)
e["bounds_local"] = {"min": [-(ring + 0.15) * 100, -(ring + 0.15) * 100, -10], "max": [(ring + 0.15) * 100, (ring + 0.15) * 100, (height + 0.25) * 100]}
e["emitter_shape"] = {"kind": "ring", "extent_cm": [ring * 100, ring * 100, 2]}
tongue = max(height, 0.08) * 100
# What Cycles shows is the emission integrated along the view ray, through the whole flame in front of and behind
# the visible sample (the hidden core still glows through the gap). Sprites overlap ~2x (see SpawnRate).
L = view_radiance(sc, o, lo, hi, zs, em_all, em if not occluded else em_all, n)
nits = LM_PER_W * (L if L > 0 else E * 0.45 * tongue / 100) * 0.5
set_params(e, {
"RingRadius": ring * 100, "BoxExtent": [ring * 100, ring * 100, 2],
"Velocity": [0, 0, tongue / life], "LifetimeMin": life * 0.7, "LifetimeMax": life * 1.1,
# Tongue sprites: ~1/4 of the flame height wide, 2.5x as tall (the slice spread of a ring is ~ its radius,
# so it cannot give the tongue width).
"SizeMin": max(2.0, tongue * 0.35), "SizeMax": max(3.0, tongue * 0.55), "Aspect": 2.5,
# Enough tongues for a continuous ring: circumference / tongue width, refreshed every lifetime, x2 overlap.
"SpawnRate": float(np.clip(2 * (2 * math.pi * ring * 100) / max(tongue * 0.32, 1) / life, 30, 600)),
"Color": [col[0] / mx, col[1] / mx, col[2] / mx, 1.0], "Intensity": nits, "Opacity": 1.0,
"NoiseStrength": 300 + 30 * boil, "NoiseFreq": 0.06, "Drag": 2.0, "VelocityJitter": 0.3, "Grow": -0.5,
"CoreIntensity": 0.35, "LightIntensity": 0.0, "LightRadius": max(100.0, tongue * 6), "LightOffset": [0, 0, tongue * 0.5],
})
e["physical"] = {"emission_nits": round(nits, 1), "view_radiance_p90": round(L, 4), "emission_color": col, "emission_per_m_p99": E, "ring_radius_m": ring,
"height_m": height, "tongue_halfwidth_m": width,
"profile": [[round(zw[k], 3), round(st[k]["r_peak"], 3), round(st[k]["peak"], 2)] for k in lev], "scroll_m_s": scroll, "noise_w_rate": boil,
# [z, emission seen by a scene camera / total] per emitting level
"visibility": [[round(zw[k], 3), round(vfrac[k], 3)] for k in range(len(zs)) if st_all[k]],
"occluded_fallback": occluded,
# where the camera-visible emission sits: weighted r (m, about the axis) and z (m, world), r 10/90 %
"visible_rz": visible_rz(em, R, zw)}
e["time"]["preroll_s"] = round(life * 3, 2)
L = nearest_light(sc, c, 1.0)
e["light_link"] = L
if L:
e["notes"].append(f"practical light {L} lights the set; Niagara LightIntensity left at 0 (no double lighting)")
fl = flicker(sc, L, frame, 240, fps)
if fl:
e["flicker"] = fl
return e
def steam_entry(sc, o, m, frame, fps, typ, ev, conf):
n = 32
lo, hi, zs, f = sample_slices(o, m, frame, n=n, levels=12)
d = f["density"]
st = plume_stats(o, lo, hi, zs, d, n)
mw = o.matrix_world
good = [k for k, r in enumerate(st) if r and r["peak"] > 0.05 * max(x["peak"] for x in st if x)]
if not good:
return None
b, t = st[good[0]], st[good[-1]]
z0 = (mw @ Vector((0, 0, lo.z))).z
ztop = t["c"].z
height = max(0.2, ztop - z0)
scroll = mapping_scroll(m, fps) or [0, 0, 0.5]
rise = max(0.15, scroll[2])
# The 4D noise scrolls fast but the plume body is only ~height/rise old at the top: lifetime = reach / rise.
life = float(np.clip(height / rise, 1.0, 6.0))
lean = (t["c"] - b["c"]) / life # m/s horizontal drift of the centroid
sigma = float(np.percentile(d[good], 95)) # 1/m in the wisps
width = 2 * float(np.mean([st[k]["spread"] for k in good]))
tau = sigma * width # optical depth across the plume in the dense wisps
base_r = max(0.04, b["spread"])
alb = list(principled_volume(m).inputs["Color"].default_value)[:3]
# Sprites: start ~2 x base radius, grow so the top spread matches.
s0 = base_r * 2 * 100
grow = float(np.clip((2 * t["spread"] * 100) / max(s0, 1) - 1, 1.0, 6.0))
rate = float(np.clip(60.0 * height, 40, 160)) # puffs per second: ~100-300 alive per plume
alive = rate * life
overlap = max(1.0, alive * (s0 * (1 + grow / 2)) ** 2 / max((width * 100) * (height * 100), 1))
alpha = float(np.clip(1 - math.exp(-tau / overlap), 0.02, 0.6))
c = Vector((b["c"].x, b["c"].y, z0))
e = base_entry(o.name, typ, conf, "volume_shader", [o.name], m.name, ev, ue_vec(c),
[(hi.x - lo.x) * 50 * mw.to_scale()[0], (hi.y - lo.y) * 50 * mw.to_scale()[1], height * 50 + 30],
"niagara", "NS_Steam" if typ == "steam" else "NS_Steam", fps, round(life * 1.5, 2))
ext = [(hi.x - lo.x) * mw.to_scale()[0] * 100, (hi.y - lo.y) * mw.to_scale()[1] * 100]
e["bounds_local"] = {"min": [-ext[0], -ext[1], -20], "max": [ext[0], ext[1], height * 100 + 80]}
e["emitter_shape"] = {"kind": "disc", "extent_cm": [base_r * 100, base_r * 100, 2]}
set_params(e, {
"SpawnRate": rate, "LifetimeMin": life * 0.8, "LifetimeMax": life * 1.1,
"SizeMin": s0 * 0.8, "SizeMax": s0 * 1.3, "Grow": grow,
"Velocity": [0, 0, rise * 100], "Wind": ue_dir(Vector((lean.x, lean.y, 0))), "Drag": 1.2, "VelocityJitter": 0.3,
"BoxExtent": [base_r * 100, base_r * 100, 2], "Color": alb + [1.0], "Opacity": alpha, "Intensity": 0.0,
"NoiseStrength": 40 + 30 * rise, "NoiseFreq": 0.02,
})
e["physical"] = {"density_per_m": sigma, "optical_depth": tau, "albedo": alb,
"anisotropy": principled_volume(m).inputs["Anisotropy"].default_value, "lifetime_s": [life],
"drift_cm_s": [x * 100 for x in lean], "noise_scale_cm": None, "height_m": height, "width_m": width,
"base_radius_m": base_r, "scroll_m_s": scroll}
e["notes"].append(f"alive ~{alive:.0f} sprites, est. overlap {overlap:.1f}")
return e
def particle_entry(sc, o, frame, fps, shutter):
md = next(md for md in o.modifiers if md.type == "PARTICLE_SYSTEM")
ps = md.particle_system.settings
span = max(1, ps.frame_end - ps.frame_start)
life_s = ps.lifetime / fps
v = Vector(ps.object_align_factor)
speed = v.length
g = ps.effector_weights.gravity
ev = [f"particles count {ps.count} over {span} frames, life {life_s:.2f}s, velocity {tuple(round(x, 2) for x in v)}, gravity {g}"]
inst = ps.instance_object
radius, length = 0.001, 0.02
if inst:
dims = sorted(inst.dimensions)
radius, length = dims[0] / 2, dims[2]
score = {}
if speed >= 3 and v.z < 0 and g < 0.5:
score["rain"] = 4
if speed < 1 and g >= 0.5:
score["drips"] = 4
if speed < 0.2 and g < 0.1:
score["dust"] = 3
if v.z > 0.5 and g >= 0.5:
score["fountain"] = 3 # launched upward, falls back: jets, sprinklers
if g >= 0.3 and life_s < 1.5 and speed >= 1:
score["sparks"] = score.get("sparks", 0) + 2 # short-lived ballistic bits (+ emissive instance below)
for t in name_hint(o.name):
score[t] = score.get(t, 0) + 2
if not score:
return unknown_entry(o, "particles", ev, fps)
ranked = sorted(score.items(), key=lambda kv: -kv[1])
typ = ranked[0][0]
conf = ranked[0][1] / (ranked[0][1] + (ranked[1][1] if len(ranked) > 1 else 0))
corners = [o.matrix_world @ Vector(c) for c in o.bound_box]
lo = Vector([min(c[i] for c in corners) for i in range(3)])
hi = Vector([max(c[i] for c in corners) for i in range(3)])
ctr = (lo + hi) / 2
half = [(hi[i] - lo[i]) * 50 for i in range(3)]
rate = ps.count / span * fps
# Drop material: emission strength + alpha of the instance (Principled).
emis, alpha, colr = 0.0, 1.0, [0.8, 0.85, 0.9]
if inst and inst.material_slots and inst.material_slots[0].material and inst.material_slots[0].material.node_tree:
b = next((n for n in inst.material_slots[0].material.node_tree.nodes if n.type == "BSDF_PRINCIPLED"), None)
if b:
emis = b.inputs["Emission Strength"].default_value
alpha = b.inputs["Alpha"].default_value
colr = list(b.inputs["Emission Color"].default_value)[:3] if emis > 0 else list(b.inputs["Base Color"].default_value)[:3]
width_cm = max(0.15, radius * 2 * 100)
preroll = max(0.0, -ps.frame_start / fps)
if typ == "rain":
# Streak = drop length + distance travelled during the shutter (Cycles renders the drops motion-blurred).
streak = length + speed * shutter / fps
fall_h = hi.z - ground_z(sc, ctr, lo.z)
life = min(life_s, fall_h / max(speed, 0.1) + 0.05)
e = base_entry(o.name, "rain", conf, "particles", [o.name], inst.name if inst else None, ev, ue_vec(ctr), half, "niagara", "NS_Rain", fps, round(life * 1.5, 2))
e["bounds_local"] = {"min": [-half[0] - 50, -half[1] - 50, -fall_h * 100 - 50], "max": [half[0] + 50, half[1] + 50, 50]}
e["emitter_shape"] = {"kind": "box", "extent_cm": half}
# Same alive density as Blender (count over its own lifetime), but only for the part above the ground.
set_params(e, {"SpawnRate": rate, "LifetimeMin": life * 0.95, "LifetimeMax": life,
"Velocity": ue_dir(v), "VelocityJitter": ps.factor_random * 0.2, "BoxExtent": half,
"SizeMin": width_cm * (1 - ps.size_random), "SizeMax": width_cm, "Aspect": streak * 100 / width_cm,
"Color": colr + [1.0], "Intensity": LM_PER_W * emis * length / streak, "Opacity": alpha, "Gravity": 0.0, "Drag": 0.0})
e["physical"] = {"count": ps.count, "lifetime_s": [life_s], "velocity_cm_s": ue_dir(v), "size_cm": [width_cm, streak * 100],
"emission_nits": LM_PER_W * emis, "fall_m": fall_h}
e["notes"].append(f"streak {streak * 100:.1f} cm = drop {length * 100:.1f} cm + {speed:.1f} m/s x {shutter / fps * 1000:.0f} ms shutter")
else:
gz = ground_z(sc, ctr, lo.z)
fall_h = max(0.05, lo.z - gz)
v0 = -v.z
t_fall = (-v0 + math.sqrt(v0 * v0 + 2 * 9.81 * g * fall_h)) / (9.81 * g) if g > 0 else fall_h / max(v0, 0.1)
life = min(life_s, t_fall)
e = base_entry(o.name, typ, conf, "particles", [o.name], inst.name if inst else None, ev, ue_vec(ctr), half, "niagara",
{"drips": "NS_Drips", "dust": "NS_DustMotes", "sparks": "NS_Sparks", "fountain": "NS_FountainJet"}.get(typ, "NS_Drips"),
fps, round(life * 2, 2))
e["bounds_local"] = {"min": [-half[0] - 30, -half[1] - 30, -fall_h * 100 - 30], "max": [half[0] + 30, half[1] + 30, 30]}
e["emitter_shape"] = {"kind": "line" if min(half[0], half[1]) < 5 else "box", "extent_cm": half}
streak = length + (v0 + 9.81 * g * life * 0.5) * shutter / fps * 0.5
set_params(e, {"SpawnRate": rate, "LifetimeMin": life, "LifetimeMax": life, "Velocity": ue_dir(v), "Gravity": g, "Drag": 0.0,
"VelocityJitter": ps.factor_random * 0.2, "BoxExtent": half, "SizeMin": width_cm * (1 - ps.size_random),
"SizeMax": width_cm, "Aspect": max(1.0, streak * 100 / width_cm), "Color": colr + [1.0],
"Intensity": LM_PER_W * emis * length / max(streak, length), "Opacity": alpha})
e["physical"] = {"count": ps.count, "lifetime_s": [life_s], "gravity": g, "size_cm": [width_cm, length * 100], "fall_m": fall_h,
"ground_z_m": gz}
e["notes"].append("Intensity = 683 x drop emission x drop / streak length: Cycles smears the drop's radiance over its motion-blurred"
" streak; sub-pixel streaks keep their energy through the sprite renderer's pixel coverage")
return e
def unknown_entry(o, kind, ev, fps, mat=None):
"""Something animated we could not classify: keep its box and evidence, queue it for the agent (FX_AGENT.md)."""
corners = [o.matrix_world @ Vector(c) for c in o.bound_box]
lo = Vector([min(c[i] for c in corners) for i in range(3)])
hi = Vector([max(c[i] for c in corners) for i in range(3)])
e = base_entry(o.name, "unknown", 0.0, kind, [o.name], mat, ev, ue_vec((lo + hi) / 2), [(hi[i] - lo[i]) * 50 for i in range(3)],
"agent", None, fps, 0.0)
e["notes"].append("unclassified: pick or author a template (fx_recipes), then set technique/template/params")
return e
def ground_z(sc, p, below):
dg = bpy.context.evaluated_depsgraph_get()
hit, loc, *_ = sc.ray_cast(dg, Vector((p.x, p.y, below - 0.01)), Vector((0, 0, -1)), distance=50.0)
return loc.z if hit else 0.0
def classify(sc, frame, emitter_names, volume_objects, templates_json=None):
"""Return the fx list for the scene. `volume_objects`: names of volume-only mesh objects; `emitter_names`: objects
with particle systems. Entries claiming a volume carry source.objects = [name]."""
global PARAM_TYPES
if templates_json and os.path.exists(templates_json):
PARAM_TYPES = json.load(open(templates_json))
fps = sc.render.fps / sc.render.fps_base
shutter = sc.render.motion_blur_shutter if sc.render.use_motion_blur else 0.0
sc.frame_set(frame)
out = []
for name in volume_objects:
o = sc.objects[name]
m = volume_material(o)
if not m:
continue
typ, ev, conf = classify_volume(sc, o, m, frame, fps)
log("volume", name, typ, round(conf, 2), ev)
if typ == "fire":
out.append(fire_entry(sc, o, m, frame, fps, ev, conf))
elif typ in ("steam", "smoke"):
e = steam_entry(sc, o, m, frame, fps, typ, ev, conf)
if e:
out.append(e)
elif typ is None:
out.append(unknown_entry(o, "volume_shader", ev, fps, m.name))
# haze stays on the fog path (height fog / local fog volumes)
for name in emitter_names:
o = sc.objects[name]
e = particle_entry(sc, o, frame, fps, shutter)
if e:
out.append(e)
log("particles", name, e["type"], e["confidence"])
sc.frame_set(frame)
return out
def main():
argv = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []
a = lambda k, d=None: argv[argv.index(k) + 1] if k in argv else d # noqa: E731
scene_in, out = a("--scene"), a("--out")
frame = int(a("--frame", "60"))
sc = bpy.context.scene
vols = [o.name for o in sc.objects if o.type == "MESH" and not o.hide_render and volume_material(o)
and all((s.material is None) or s.material == volume_material(o) or True for s in o.material_slots)]
ems = [o.name for o in sc.objects if not o.hide_render and any(md.type == "PARTICLE_SYSTEM" for md in o.modifiers)]
fx = classify(sc, frame, ems, vols, a("--templates", os.path.join(os.path.dirname(os.path.abspath(__file__)), "templates.json")))
scene = json.load(open(scene_in, encoding="utf-8")) if scene_in else {}
scene["fx"] = fx
claimed = {o for e in fx for o in e["source"]["objects"]}
for k, v in scene.get("volumes", {}).items():
if k in claimed:
v["claimed_by_fx"] = True
json.dump(scene, open(out, "w", encoding="utf-8"), indent=1)
log("wrote", out, len(fx), "fx entries", [(e["id"], e["type"]) for e in fx])
if __name__ == "__main__":
main()