EL4CTEO/blender-skills / skills/blender-asset-qa
blender-asset-qa
VerifiedMandatory review gate for any mesh or asset created or edited in Blender. Detects z-fighting, floating/detached parts, inverted or inconsistent normals, non-manifold/open geometry, degenerate faces, duplicate verts, n-gons, unapplied scale, UV problems, bad skin weights, material/texture errors, and renders multi-angle review sheets. Use before calling any modeling, export or delivery task done.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.1 KB |
| scripts/_bpyx.py | script | 4.4 KB |
| scripts/qa_check.py | script | 19.8 KB |
| scripts/review_shots.py | script | 6.3 KB |
scripts/qa_check.py
View on GitHub"""Mesh/asset QA: z-fighting, detached parts, normals, topology, transforms, UVs, weights, materials
(faces on empty slots, unused slots, missing texture files, data maps set to sRGB).
Pass the objects of ONE asset (they are checked together: islands far from all others = floating).
Usage:
blender -b f.blend -P qa_check.py -- [--objects A B] [--profile game|render|print|roblox]
[--eps 0.001] [--tol 0.002] [--no-modifiers] [--max-tris 300000]
MCP: import qa_check; print(qa_check.run(objects=["Chair"], profile="game"))
Returns {"pass": bool, "errors": [...], "warnings": [...], "objects": {name: metrics}}.
"""
import math
import os
import sys
from collections import Counter, defaultdict
import bmesh
import bpy
import numpy as np
from mathutils import Vector
from mathutils.bvhtree import BVHTree
from mathutils.kdtree import KDTree
sys.path.insert(0, os.path.dirname(__file__))
import _bpyx as bx # noqa: E402
# check -> severity per profile ("e" error, "w" warning, None skip)
PROFILES = {
# zfight floating inverted inconsist nonmanif boundary degen dupes ngons scale uv weights materials
"game": dict(zf="e", fl="e", inv="e", inc="e", nm="w", bd=None, dg="e", dup="w", ng="w", sc="e", uv="e", wt="e", mt="e"),
"render": dict(zf="e", fl="e", inv="w", inc="w", nm=None, bd=None, dg="w", dup="w", ng=None, sc="w", uv="w", wt="w", mt="e"),
"print": dict(zf="e", fl="e", inv="e", inc="e", nm="e", bd="e", dg="e", dup="e", ng=None, sc="w", uv=None, wt=None, mt=None),
"roblox": dict(zf="e", fl="e", inv="e", inc="e", nm="w", bd="w", dg="e", dup="w", ng="e", sc="e", uv="e", wt="e", mt="e"),
}
TRI_LIMIT = {"roblox": 20000}
DATA_INPUTS = {"Roughness", "Metallic", "Normal", "Alpha", "Specular IOR Level", "Coat Weight", "Coat Roughness",
"Transmission Weight", "Subsurface Weight", "Anisotropic", "Sheen Weight", "IOR"}
DATA_NODES = {"NORMAL_MAP", "BUMP", "DISPLACEMENT", "VECTOR_DISPLACEMENT"}
def _feeds(sock, depth=4):
"""(node type, input name) pairs a socket reaches through up to `depth` nodes."""
out = set()
for lk in sock.links:
n = lk.to_node
out.add((n.type, lk.to_socket.name))
if depth and n.type not in DATA_NODES and n.type != "BSDF_PRINCIPLED":
for o in n.outputs:
out |= _feeds(o, depth - 1)
return out
def _material_issues(ob):
"""[(severity_is_error, message)] for slots, faces and image textures."""
me, slots, out = ob.data, ob.material_slots, []
idx = [0] * len(me.polygons)
me.polygons.foreach_get("material_index", idx)
used = set(idx)
bad = sorted(i for i in used if i >= len(slots) or slots[i].material is None)
if bad or not slots:
out.append((True, f"{ob.name}: faces use empty/missing material slot(s) {bad or [0]} (grey in engines)"))
unused = [s.name or str(i) for i, s in enumerate(slots) if i not in used]
if unused:
out.append((False, f"{ob.name}: unused material slot(s) {unused} (extra draw calls in some exporters)"))
for i in sorted(used):
mat = slots[i].material if i < len(slots) else None
if mat is None or not mat.node_tree:
continue
for n in mat.node_tree.nodes:
if n.type != "TEX_IMAGE":
continue
img = n.image
if img is None:
if n.outputs["Color"].is_linked or n.outputs["Alpha"].is_linked:
out.append((False, f"{mat.name}: image node {n.name!r} has no image"))
continue
if img.source == "FILE" and not img.packed_file and not os.path.exists(bpy.path.abspath(img.filepath)):
out.append((True, f"{mat.name}: missing texture file {img.filepath!r}"))
reach = _feeds(n.outputs["Color"])
data_use = sorted({s for t, s in reach if t == "BSDF_PRINCIPLED" and s in DATA_INPUTS}
| {t.lower() for t, _s in reach if t in DATA_NODES})
if data_use and not img.colorspace_settings.is_data:
out.append((True, f"{mat.name}: {img.name} feeds {data_use} but is {img.colorspace_settings.name} "
"(must be Non-Color)"))
if img.colorspace_settings.is_data and ("BSDF_PRINCIPLED", "Base Color") in reach:
out.append((False, f"{mat.name}: {img.name} is Non-Color but drives Base Color (looks washed out)"))
return out
def _mesh_world(ob, use_mods):
"""bmesh of the (evaluated) object in world space, triangulated copy kept separately."""
bm = bmesh.new()
if use_mods:
dg = bpy.context.evaluated_depsgraph_get()
bm.from_object(ob, dg)
else:
bm.from_mesh(ob.data)
bm.transform(ob.matrix_world)
bm.verts.ensure_lookup_table()
bm.faces.ensure_lookup_table()
return bm
def _islands(bm):
parent = list(range(len(bm.verts)))
def find(i):
while parent[i] != i:
parent[i] = parent[parent[i]]
i = parent[i]
return i
for e in bm.edges:
a, b = find(e.verts[0].index), find(e.verts[1].index)
if a != b:
parent[a] = b
roots = [find(i) for i in range(len(bm.verts))]
remap = {r: n for n, r in enumerate(dict.fromkeys(roots))}
return [remap[r] for r in roots]
def _point_in_tri(p, a, b, c, n):
for u, v in ((a, b), (b, c), (c, a)):
if (v - u).cross(p - u).dot(n) < -1e-9:
return False
return True
def _uv_stats(ob, bm_local):
me = ob.data
if not me.uv_layers:
return {"uv_maps": 0}
uv = bm_local.loops.layers.uv.active
oob = total = zero = 0
n = 128
# coarse raster: a cell is used when its centre lies in a face, overlapped when in 2+ faces.
# Fixed-size arrays: memory does not grow with faces stacked on the same cells.
owner = np.full((n, n), -1, dtype=np.int64)
over = np.zeros((n, n), dtype=bool)
step = max(1, len(bm_local.faces) // 30000) # sample huge meshes
for f in list(bm_local.faces)[::step]:
pts = [l[uv].uv.copy() for l in f.loops]
for p in pts:
total += 1
if p.x < -1e-4 or p.y < -1e-4 or p.x > 1.0001 or p.y > 1.0001:
oob += 1
a2 = sum(pts[i].x * pts[(i + 1) % len(pts)].y - pts[(i + 1) % len(pts)].x * pts[i].y
for i in range(len(pts)))
if abs(a2) < 1e-12:
zero += 1
continue
xs, ys = [p.x for p in pts], [p.y for p in pts]
x0, x1 = max(0, int(min(xs) * n)), min(n, int(max(xs) * n) + 1)
y0, y1 = max(0, int(min(ys) * n)), min(n, int(max(ys) * n) + 1)
if x0 >= x1 or y0 >= y1:
continue
cx, cy = np.meshgrid((np.arange(x0, x1) + .5) / n, (np.arange(y0, y1) + .5) / n, indexing="ij")
inside = np.zeros(cx.shape, dtype=bool)
for i in range(1, len(pts) - 1): # fan triangles
t = (pts[0], pts[i], pts[i + 1])
d = [(t[(k + 1) % 3].x - t[k].x) * (cy - t[k].y) - (t[(k + 1) % 3].y - t[k].y) * (cx - t[k].x)
for k in range(3)]
inside |= ((d[0] >= 0) & (d[1] >= 0) & (d[2] >= 0)) | ((d[0] <= 0) & (d[1] <= 0) & (d[2] <= 0))
win, ov = owner[x0:x1, y0:y1], over[x0:x1, y0:y1] # views
ov |= inside & (win >= 0) & (win != f.index)
win[inside & (win < 0)] = f.index
used = int((owner >= 0).sum())
overlap = int(over.sum())
return {"uv_maps": len(me.uv_layers), "uv_oob_pct": round(100 * oob / max(total, 1), 2),
"uv_zero_area_faces": zero, "uv_overlap_pct": round(100 * overlap / max(used, 1), 2),
"uv_coverage_pct": round(100 * used / n / n, 1)}
def run(objects=None, profile="game", eps=0.001, tol=0.002, no_modifiers=False, max_tris=300000,
uv=True, **_):
bx.object_mode()
sev = PROFILES[profile]
obs = [o for o in bx.objects(objects) if o.type == "MESH"]
if not obs:
raise ValueError("no mesh objects to check")
errors, warnings, per = [], [], {}
def flag(key, msg):
s = sev.get(key)
if s == "e":
errors.append(msg)
elif s == "w":
warnings.append(msg)
# ---- gather world-space triangles of all objects --------------------------------
verts, tris, tri_meta = [], [], [] # tri_meta: (obj_i, island_gid, normal)
island_info = {} # gid -> dict(ob, verts, tris, bbox)
gid_base = 0
min_z = math.inf
for oi, ob in enumerate(obs):
bm = _mesh_world(ob, not no_modifiers)
m = {}
isl = _islands(bm)
n_isl = max(isl) + 1 if isl else 0
base_v = len(verts)
verts.extend(v.co.copy() for v in bm.verts)
if bm.verts:
min_z = min(min_z, min(v.co.z for v in bm.verts))
# topology
ecount = Counter(len(e.link_faces) for e in bm.edges)
m["verts"], m["faces"] = len(bm.verts), len(bm.faces)
m["tris"] = sum(len(f.verts) - 2 for f in bm.faces)
m["ngons"] = sum(1 for f in bm.faces if len(f.verts) > 4)
m["boundary_edges"] = ecount.get(1, 0)
m["nonmanifold_edges"] = sum(c for k, c in ecount.items() if k > 2)
m["wire_edges"] = ecount.get(0, 0)
m["loose_verts"] = sum(1 for v in bm.verts if not v.link_edges)
m["degenerate_faces"] = sum(1 for f in bm.faces if f.calc_area() < 1e-10)
m["zero_length_edges"] = sum(1 for e in bm.edges if e.calc_length() < 1e-7)
directed = Counter((l.vert.index, l.link_loop_next.vert.index) for f in bm.faces for l in f.loops)
m["inconsistent_normals_edges"] = sum(1 for k, c in directed.items() if c > 1)
kd = KDTree(len(bm.verts))
for v in bm.verts:
kd.insert(v.co, v.index)
kd.balance()
m["duplicate_verts"] = sum(1 for v in bm.verts
if len(kd.find_range(v.co, 1e-5)) > 1) // 2
m["islands"] = n_isl
# per-island volume sign + bbox (closed islands only for inversion test)
vol, closed = defaultdict(float), defaultdict(lambda: True)
for e in bm.edges:
if len(e.link_faces) != 2:
closed[isl[e.verts[0].index]] = False
bm_t = bm.copy()
bmesh.ops.triangulate(bm_t, faces=bm_t.faces[:])
bm_t.verts.ensure_lookup_table()
# signed volume about a point of the island itself: about the world origin, float32
# cancellation turns small parts far from it (3 mm parts 2 m out) "inside out"
ref = {}
for v in bm.verts:
ref.setdefault(isl[v.index], v.co.copy())
for f in bm_t.faces:
g = isl[f.verts[0].index]
o = ref[g]
a, b, c = (v.co - o for v in f.verts)
vol[g] += a.dot(b.cross(c)) / 6.0
tris.append(tuple(base_v + v.index for v in f.verts))
tri_meta.append((oi, gid_base + g, f.normal.copy()))
bm_t.free()
m["inside_out_islands"] = sum(1 for g in range(n_isl) if closed[g] and vol[g] < -1e-9)
groups = defaultdict(list)
for i, g in enumerate(isl):
groups[g].append(i)
for g, idx in groups.items():
pts = [bm.verts[i].co for i in idx]
lo = Vector((min(p.x for p in pts), min(p.y for p in pts), min(p.z for p in pts)))
hi = Vector((max(p.x for p in pts), max(p.y for p in pts), max(p.z for p in pts)))
island_info[gid_base + g] = {"ob": ob.name, "verts": [base_v + i for i in idx],
"center": (lo + hi) / 2, "size": (hi - lo).length,
"closed": closed[g], "tris": []}
gid_base += n_isl
# transforms
s = ob.scale
m["scale"] = bx.r(tuple(s), 3)
if any(abs(x - 1) > 1e-4 for x in s):
flag("sc", f"{ob.name}: unapplied scale {m['scale']}")
if s.x * s.y * s.z < 0:
errors.append(f"{ob.name}: negative scale (flips normals on export)")
# materials
m["materials"] = len(ob.material_slots)
for is_err, msg in _material_issues(ob):
if is_err:
flag("mt", msg)
else:
warnings.append(msg)
# weights
arm_mod = next((md for md in ob.modifiers if md.type == "ARMATURE" and md.object), None)
if arm_mod and ob.vertex_groups:
deform = {b.name for b in arm_mod.object.data.bones if b.use_deform}
gidx = {g.index for g in ob.vertex_groups if g.name in deform}
unweighted = over4 = 0
for v in ob.data.vertices:
ws = [g for g in v.groups if g.group in gidx and g.weight > 1e-4]
unweighted += not ws
over4 += len(ws) > 4
m["unweighted_verts"], m["verts_over_4_influences"] = unweighted, over4
if unweighted:
flag("wt", f"{ob.name}: {unweighted} verts with no deform weights")
if over4:
flag("wt", f"{ob.name}: {over4} verts with >4 bone influences")
# uv
if uv:
bm_l = bmesh.new()
bm_l.from_mesh(ob.data)
m.update(_uv_stats(ob, bm_l))
bm_l.free()
if m["uv_maps"] == 0:
flag("uv", f"{ob.name}: no UV map")
else:
if m["uv_zero_area_faces"]:
flag("uv", f"{ob.name}: {m['uv_zero_area_faces']} zero-area UV faces")
if m["uv_oob_pct"] > 0 and profile in ("roblox",):
flag("uv", f"{ob.name}: {m['uv_oob_pct']}% UVs outside 0-1")
if m["uv_overlap_pct"] > 5:
warnings.append(f"{ob.name}: ~{m['uv_overlap_pct']}% UV overlap "
"(ok only if mirrored/stacked on purpose; bakes break)")
bm.free()
# flags
if m["inside_out_islands"]:
flag("inv", f"{ob.name}: {m['inside_out_islands']} closed parts with normals pointing inward")
if m["inconsistent_normals_edges"]:
flag("inc", f"{ob.name}: {m['inconsistent_normals_edges']} edges with inconsistent face winding")
if m["nonmanifold_edges"] or m["wire_edges"]:
flag("nm", f"{ob.name}: non-manifold edges={m['nonmanifold_edges']} wire={m['wire_edges']}")
if m["boundary_edges"]:
flag("bd", f"{ob.name}: {m['boundary_edges']} open boundary edges (not watertight)")
if m["degenerate_faces"] or m["zero_length_edges"]:
flag("dg", f"{ob.name}: degenerate faces={m['degenerate_faces']} zero-len edges={m['zero_length_edges']}")
if m["duplicate_verts"] or m["loose_verts"]:
flag("dup", f"{ob.name}: duplicate verts={m['duplicate_verts']} loose verts={m['loose_verts']}")
if m["ngons"]:
flag("ng", f"{ob.name}: {m['ngons']} n-gons")
lim = TRI_LIMIT.get(profile)
if lim and m["tris"] > lim:
errors.append(f"{ob.name}: {m['tris']} tris > {profile} limit {lim}")
per[ob.name] = m
if len(tris) > max_tris:
warnings.append(f"{len(tris)} tris > max_tris {max_tris}: z-fighting/floating checks skipped")
return _result(errors, warnings, per, min_z, tol, [], [], [])
bvh = BVHTree.FromPolygons(verts, tris, epsilon=0.0)
tri_sets = [set(t) for t in tris]
for ti, (_, g, _) in enumerate(tri_meta):
island_info[g]["tris"].append(ti)
# ---- z-fighting: parallel faces within eps whose areas overlap --------------------
zf_pairs, contact_pairs = set(), set()
for ti, t in enumerate(tris):
a, b, c = (verts[i] for i in t)
n = tri_meta[ti][2]
if n.length < 0.5:
continue
cen = (a + b + c) / 3
for p in (cen, cen.lerp(a, .6), cen.lerp(b, .6), cen.lerp(c, .6)):
for _, _, tj, _ in bvh.find_nearest_range(p, eps):
if tj is None or tj == ti:
continue
if tri_sets[ti] & tri_sets[tj]:
continue
n2 = tri_meta[tj][2]
d = n.dot(n2)
if abs(d) < 0.999:
continue
a2, b2, c2 = (verts[i] for i in tris[tj])
q = p - n2 * n2.dot(p - a2)
if _point_in_tri(q, a2, b2, c2, n2):
(zf_pairs if d > 0 else contact_pairs).add((min(ti, tj), max(ti, tj)))
def _describe(pairs):
out = Counter()
for i, j in pairs:
oa, ob_ = obs[tri_meta[i][0]].name, obs[tri_meta[j][0]].name
out[f"{oa}<->{ob_}" if oa != ob_ else oa] += 1
return [{"where": k, "tri_pairs": v} for k, v in out.most_common(20)]
zf = _describe(zf_pairs)
for z in zf:
flag("zf", f"z-fighting: {z['where']} ({z['tri_pairs']} overlapping coplanar tri pairs)")
contact = _describe(contact_pairs)
for z in contact:
warnings.append(f"hidden back-to-back faces: {z['where']} ({z['tri_pairs']} pairs) - delete to save tris")
# ---- floating / detached islands ------------------------------------------------------
floating, enclosed = [], []
if len(island_info) > 1:
tri_island = [m_[1] for m_ in tri_meta]
biggest = max(island_info, key=lambda g: island_info[g]["size"])
for g, info in island_info.items():
if g == biggest:
continue
touching = False
vs = info["verts"]
step = max(1, len(vs) // 400)
for vi in vs[::step]:
for _, _, tj, _ in bvh.find_nearest_range(verts[vi], tol):
if tj is not None and tri_island[tj] != g:
touching = True
break
if touching:
break
if not touching and info["tris"]:
sub = BVHTree.FromPolygons(verts, [tris[t] for t in info["tris"]], epsilon=0.0)
touching = any(tri_island[j] != g for _, j in sub.overlap(bvh))
if touching:
continue
# inside another closed island? (eyes in a head, internal parts) -> parity ray test
org, hits, d = info["center"], 0, Vector((0.137, 0.271, 0.953)).normalized()
p = org.copy()
for _ in range(64):
loc, _, tj, _ = bvh.ray_cast(p, d)
if loc is None:
break
if tri_island[tj] != g:
hits += 1
p = loc + d * 1e-5
rec = {"object": info["ob"], "island_verts": len(vs), "center": bx.r(tuple(info["center"]), 3)}
(enclosed if hits % 2 == 1 else floating).append(rec)
for f in floating:
flag("fl", f"floating/detached part in {f['object']} ({f['island_verts']} verts at {f['center']})")
if enclosed:
warnings.append(f"{len(enclosed)} parts fully enclosed, not touching (eyes/internals?): "
f"{[e['object'] for e in enclosed][:5]}")
return _result(errors, warnings, per, min_z, tol, zf, floating, contact, enclosed)
def _result(errors, warnings, per, min_z, tol, zf, floating, contact, enclosed=()):
ground = None if min_z == math.inf else round(min_z, 4)
if ground is not None and abs(ground) > max(tol, 1e-3):
warnings.append(f"asset lowest point z={ground} (not resting on ground plane z=0)")
return {"ok": True, "pass": not errors, "errors": errors, "warnings": warnings,
"ground_z": ground, "zfighting": zf, "floating": floating,
"back_to_back": contact, "enclosed": list(enclosed), "objects": per}
if __name__ == "__main__":
p = bx.add_common(bx.parser(__doc__), save=False)
p.add_argument("--profile", default="game", choices=list(PROFILES))
p.add_argument("--eps", type=float, default=0.001, help="z-fight plane distance (m)")
p.add_argument("--tol", type=float, default=0.002, help="contact tolerance for detached parts (m)")
p.add_argument("--no-modifiers", action="store_true")
p.add_argument("--max-tris", type=int, default=300000)
p.add_argument("--no-uv", dest="uv", action="store_false")
bx.cli(run, p)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |