Skip to content

elithril/blender-kiln / plugin

Makes and fixes 3D assets in Blender, for games, the web and AR. Use when the user wants a 3D model, prop, character or GLB/glTF/FBX/USDZ file made — from a text brief, a reference image, a free marketplace (PolyHaven, Sketchfab) or AI generation — AND when they bring an existing 3D file to fix: too heavy or too many polygons (optimize, compress, LODs), broken normals, scale or origin, materials lost on glTF export, conversion between GLB, FBX and USDZ, texturing, rigging for animation, animating it (walk and idle cycles, text-to-motion, looping clips, articulated props), or inspection. Drives Blender through a Blender MCP server (ahujasid's or the official Blender Lab one). Batch mode produces many consistent assets unattended. Kiln Studio (`/kiln studio`) opens the project's models in the browser, where the user reviews them and pins notes for Claude to act on.

FileKindSize
.claude-plugin/plugin.jsonconfig1.2 KB
.mcp.jsonconfig236 B
LICENSEother1.0 KB
NOTICEother2.5 KB
SKILL.mdskill md29.0 KB
references/ai-generation.mdmarkdown21.0 KB
references/animation.mdmarkdown21.6 KB
references/batch-mode.mdmarkdown19.5 KB
references/blender-mcp.mdmarkdown9.4 KB
references/characters.mdmarkdown52.8 KB
references/cli-tools.mdmarkdown6.5 KB
references/commands.mdmarkdown10.7 KB
references/export-targets.mdmarkdown14.3 KB
references/log-format.mdmarkdown2.2 KB
references/naming-conventions.mdmarkdown5.8 KB
references/photo-projection.mdmarkdown6.3 KB
references/pipeline-brief.mdmarkdown4.2 KB
references/pipeline-import-cleanup.mdmarkdown6.3 KB
references/pipeline-optimize-export.mdmarkdown6.4 KB
references/pipeline-rig-animate.mdmarkdown5.8 KB
references/pipeline-source.mdmarkdown9.7 KB
references/print.mdmarkdown41.5 KB
references/reference-fidelity.mdmarkdown31.8 KB
references/review-rounds.mdmarkdown10.4 KB
references/setup-install.mdmarkdown2.8 KB
references/setup.mdmarkdown9.2 KB
references/sourcing-strategy.mdmarkdown6.1 KB
references/studio.mdmarkdown38.9 KB
references/texturing-strategy.mdmarkdown14.4 KB
references/topology-rules.mdmarkdown3.9 KB
references/uv-materials.mdmarkdown6.8 KB
references/validation-checklist.mdmarkdown10.5 KB
studio/approval_hook.pyscript14.2 KB
studio/blender_live.pyscript2.3 KB
studio/checks.pyscript38.1 KB
studio/estimate.pyscript4.2 KB
studio/example/barrel/barrel_final.glbbinary111.9 KB
studio/example/barrel/barrel_log.mdmarkdown445 B
studio/handoff.pyscript17.8 KB
studio/mcp_server.pyscript32.7 KB
studio/phoneshare.pyscript17.1 KB
studio/server.pyscript47.9 KB
studio/setup_status.pyscript7.5 KB
studio/static/app.jsscript241.4 KB
studio/static/apple-touch-icon.pngbinary20.6 KB
studio/static/fonts/OFL-JetBrainsMono.txtmarkdown4.3 KB
studio/static/fonts/OFL-Sora.txtmarkdown4.3 KB
studio/static/fonts/jetbrains-mono-latin-ext.woff2binary11.3 KB
studio/static/fonts/jetbrains-mono-latin.woff2binary30.6 KB
studio/static/fonts/sora-latin-ext.woff2binary11.8 KB
studio/static/fonts/sora-latin.woff2binary24.6 KB
studio/static/i18n.jsscript6.2 KB
studio/static/i18n/fr.jsonconfig101.2 KB
studio/static/icon-32.pngbinary2.6 KB
studio/static/icon-64.pngbinary6.6 KB
studio/static/icon-96.pngbinary12.8 KB
studio/static/index.htmlother39.5 KB
studio/static/style.cssother114.5 KB
studio/static/tutorial.jsscript49.0 KB
studio/static/tutorial/barrel_after.glbbinary117.3 KB
studio/static/tutorial/barrel_before.glbbinary111.9 KB
studio/static/tutorial/fixtures.jsonconfig13.5 KB
studio/static/tutorial/lantern_1_blockout.glbbinary83.1 KB
studio/static/tutorial/lantern_2_details.glbbinary101.8 KB
studio/static/tutorial/lantern_3_materials.glbbinary102.0 KB
studio/static/tutorial/lantern_4_final.glbbinary141.1 KB
studio/static/tutorial/make_tutorial.pyscript4.9 KB
studio/static/viewer.jsscript41.4 KB
studio/studio.pyscript29.2 KB
studio/studiolib.pyscript77.8 KB
studio/test_studio.pyscript90.2 KB
studio/test_worker.pyscript31.5 KB
studio/worker.pyscript56.8 KB
studio/worker_blender.pyscript2.7 KB
tools/autorig.pyscript44.1 KB
tools/bind_rigid_parts.pyscript3.6 KB
tools/blender_mcp_start.pyscript1.5 KB
tools/check_usdz.pyscript1004 B
tools/cutout.swiftscript2.0 KB
tools/export_outputs.pyscript5.2 KB
tools/fidelity_check.pyscript39.0 KB
tools/fit_coupon.pyscript11.3 KB
tools/fixtures/skintokens_raw_child.glbbinary88.8 KB
tools/fixtures/skintokens_skeletons.jsonconfig6.5 KB
tools/flatten.pyscript14.9 KB
tools/glb_to_fbx.pyscript2.1 KB
tools/glb_to_usdz.pyscript6.2 KB
tools/motion_loop.pyscript5.9 KB
tools/motion_measure.pyscript15.2 KB
tools/motions/LICENSE-image-to-3dlab.txtmarkdown11.1 KB
tools/motions/cheer.npzbinary48.4 KB
tools/motions/cheer_b.npzbinary48.1 KB
tools/motions/dance.npzbinary78.2 KB
tools/motions/dance_b.npzbinary78.9 KB
tools/motions/death.npzbinary45.9 KB
tools/motions/death_b.npzbinary46.5 KB
tools/motions/fight_stance.npzbinary60.3 KB
tools/motions/fight_stance_b.npzbinary61.3 KB
tools/motions/flying_kick.npzbinary39.7 KB
tools/motions/flying_kick_b.npzbinary39.9 KB
tools/motions/hit_react.npzbinary31.9 KB
tools/motions/hit_react_b.npzbinary31.8 KB
tools/motions/idle.npzbinary51.8 KB
tools/motions/idle_b.npzbinary57.7 KB
tools/motions/jump.npzbinary39.8 KB
tools/motions/jump_b.npzbinary39.9 KB
tools/motions/kata.npzbinary77.4 KB
tools/motions/kata_b.npzbinary75.3 KB
tools/motions/kick.npzbinary32.4 KB
tools/motions/kick_b.npzbinary32.5 KB
tools/motions/presets.jsonconfig9.6 KB
tools/motions/punch.npzbinary32.0 KB
tools/motions/punch_b.npzbinary32.1 KB
tools/motions/punch_combo.npzbinary47.4 KB
tools/motions/punch_combo_b.npzbinary47.5 KB
tools/motions/roll.npzbinary46.7 KB
tools/motions/roll_b.npzbinary47.5 KB
tools/motions/roundhouse.npzbinary39.7 KB
tools/motions/roundhouse_b.npzbinary39.9 KB
tools/motions/run.npzbinary47.2 KB
tools/motions/run_b.npzbinary47.7 KB
tools/motions/sit.npzbinary47.2 KB
tools/motions/sit_b.npzbinary47.2 KB
tools/motions/sneak.npzbinary61.6 KB
tools/motions/sneak_b.npzbinary61.8 KB
tools/motions/strafe_left.npzbinary45.9 KB
tools/motions/strafe_left_b.npzbinary47.1 KB
tools/motions/sword_swing.npzbinary39.7 KB
tools/motions/sword_swing_b.npzbinary39.4 KB
tools/motions/walk.npzbinary62.8 KB
tools/motions/walk_b.npzbinary62.6 KB
tools/motions/walk_woman.npzbinary62.9 KB
tools/motions/wave.npzbinary46.3 KB
tools/motions/wave_b.npzbinary46.3 KB
tools/open_blender.pyscript5.0 KB
tools/photo_project.pyscript37.8 KB
tools/presets.pyscript16.3 KB
tools/print_check.pyscript47.2 KB
tools/quadruped.pyscript19.4 KB
tools/retarget.pyscript46.9 KB
tools/review_renders.pyscript13.8 KB
tools/review_sheet.pyscript11.0 KB
tools/skintokens-requirements.txtmarkdown2.4 KB
tools/skintokens.patchother9.2 KB
tools/template_profile.pyscript5.8 KB
tools/test_autorig.pyscript15.9 KB
tools/test_fidelity_check.pyscript20.7 KB
tools/test_fit_coupon.pyscript6.4 KB
tools/test_flatten.pyscript15.0 KB
tools/test_open_blender.pyscript1.3 KB
tools/test_photo_project.pyscript12.6 KB
tools/test_presets.pyscript17.6 KB
tools/test_print_check.pyscript33.1 KB
tools/test_review_renders.pyscript11.4 KB
tools/test_review_sheet.pyscript4.0 KB
tools/test_template_profile.pyscript3.6 KB
tools/test_uv_check.pyscript5.0 KB
tools/test_verify_docs.pyexecutablescript7.9 KB
tools/unimate.patchother3.5 KB
tools/unimate.pyscript17.5 KB
tools/uv_check.pyscript8.4 KB
tools/verify_blender.pyexecutablescript29.2 KB
tools/verify_docs.pyexecutablescript16.6 KB

tools/fit_coupon.py

View on GitHub
"""A test print for a peg in a hole: the clearance measured on the printer, not assumed.

    blender -b --factory-startup --python-exit-code 1 --python tools/fit_coupon.py -- \\
        --out DIR [--shape diamond|round] [--peg-mm 4.0] [--depth-mm 3.5] \\
        [--clear-mm 0.1 0.2 0.3] [--chamfer-mm 0.5]

The clearance of a joint (print.md, § Like the photo rule 9) is a usual value, not one
measured here, and the sources disagree on what 0.2 mm is: a slip fit per side for some, a
total over the diameter for others. Printed parts also come out 0.1-0.3 mm larger than the
model. This writes two STLs (mm) that answer it for one printer:

- `fit_holes.stl`, a plate --depth-mm thick laid flat, with one diamond hole per clearance:
  the peg's side plus twice the clearance (the clearance is per face). Then one more hole at
  the middle clearance with a 45 degree lead-in chamfer --chamfer-mm deep on the bed face:
  the first layer is squashed outward (the "elephant's foot") and closes a hole that opens
  on the bed. Hole n is marked by n dots, engraved 0.6 mm on the top face;
- `fit_peg.stl`, a wall standing on the bed with the peg sticking out sideways, a square
  turned 45 degrees: the same shape and the same way of printing as a peg kiln models on an
  upright part (its lower faces at 45 degrees, no support).

--shape round is the other joint kiln models: a round peg standing up from a part, its hole
in the part above (a mushroom's cap on its stem, a flame on its forge). Its holes are round,
--peg-mm is the diameter, and `fit_peg.stl` is that peg standing on a 2 mm base, printed the
way the model's is. A circle is a 64-sided polygon: the hole's flats sit on the asked
diameter (its corners outside it), the peg's corners on it (its flats inside), so the
faceting never makes a joint tighter than asked.

The peg goes into each hole by hand: the tightest hole it enters is the clearance to model
with. FDM only. Every hole is checked to the micron before writing, and both parts must be
closed solids; exit 0, 1 on an error.
"""
import json, math, os, sys

import bmesh
import bpy
import numpy as np
from mathutils import Matrix

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import print_check as pc                                          # noqa: E402

PITCH, MARGIN, DOT_R, DOT_DEPTH = 12.0, 5.0, 0.75, 0.6
ROUND = 64                                    # sides of a round hole or peg
BASE = 2.0                                    # mm: the round peg's base on the bed


def args():
    p = pc.Parser(prog="fit_coupon.py")
    p.add_argument("--out", required=True, help="a folder; fit_holes.stl and fit_peg.stl are written there")
    p.add_argument("--shape", choices=["diamond", "round"], default="diamond",
                   help="diamond: printed on its side; round: standing up")
    p.add_argument("--peg-mm", type=float, default=4.0, help="the diamond's side, or the round peg's diameter")
    p.add_argument("--depth-mm", type=float, default=3.5, help="the plate's thickness: how deep the peg goes")
    p.add_argument("--clear-mm", type=float, nargs="+", default=[0.1, 0.2, 0.3], help="per face")
    p.add_argument("--chamfer-mm", type=float, default=0.5, help="the lead-in on the extra hole (0: none)")
    p.add_argument("--json")
    argv = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []
    a = p.parse_args(argv)
    if a.peg_mm < 2 or a.depth_mm < 1.5 or min(a.clear_mm) < 0 or a.chamfer_mm < 0:
        pc.die("peg >= 2 mm, depth >= 1.5 mm, clearances and chamfer >= 0")
    return a


def obj(name, bm):
    me = bpy.data.meshes.new(name)
    bm.to_mesh(me)
    bm.free()
    ob = bpy.data.objects.new(name, me)
    bpy.context.scene.collection.objects.link(ob)
    return ob


def box(name, lo, hi):
    bm = bmesh.new()
    bmesh.ops.create_cube(bm, size=1.0)
    bmesh.ops.scale(bm, vec=[h - l for l, h in zip(lo, hi)], verts=bm.verts)
    bmesh.ops.translate(bm, vec=[(l + h) / 2 for l, h in zip(lo, hi)], verts=bm.verts)
    return obj(name, bm)


def prism(name, side_lo, side_hi, z0, z1, centre, segments=4, axis="Z", flats=False):
    """A frustum along Z from z0 to z1: a diamond (corners on the axes) for 4 segments, a
    square side going from side_lo to side_hi; a round dot for more segments (side = diameter,
    on the corners — or on the flats with flats=True, for a hole that must not come out tighter)."""
    k = 1 / math.sqrt(2) if segments == 4 else 0.5 / (math.cos(math.pi / segments) if flats else 1.0)
    bm = bmesh.new()
    bmesh.ops.create_cone(bm, cap_ends=True, segments=segments, radius1=side_lo * k, radius2=side_hi * k,
                          depth=z1 - z0)
    bmesh.ops.translate(bm, vec=(0, 0, (z0 + z1) / 2), verts=bm.verts)
    if axis == "-Y":                     # the peg: along -Y, a corner up and a corner down
        bmesh.ops.rotate(bm, verts=bm.verts, cent=(0, 0, 0), matrix=Matrix.Rotation(math.pi / 2, 3, "X"))
    bmesh.ops.translate(bm, vec=centre, verts=bm.verts)
    return obj(name, bm)


def boolean(target, cutter, op):
    m = target.modifiers.new("b", "BOOLEAN")
    m.operation, m.solver, m.object = op, "EXACT", cutter
    bpy.context.view_layer.objects.active = target
    bpy.ops.object.modifier_apply(modifier="b")
    bpy.data.objects.remove(cutter)


def arrays(ob):
    me = ob.data
    me.calc_loop_triangles()
    V = np.array([v.co for v in me.vertices], dtype=float)
    F = np.array([t.vertices for t in me.loop_triangles], dtype=np.int64)
    return V, F


def closed(V, F):
    t, _, nparts, _ = pc.topology(V, F)
    return nparts == 1 and t["open_edges"] == 0 and t["nonmanifold_edges"] == 0 and t["inconsistent_edges"] == 0


def width_at(V, F, x, y, z, reach, shape="diamond"):
    """The hole's side measured where a plane at height z cuts it: the largest |dx|+|dy| of the
    section's points round the hole centre, i.e. half the diamond's diagonal, back to a side.
    Round: the largest radius, its corners, back to the diameter across the flats."""
    if shape == "round":
        best = 0.0
        for tri in V[F]:
            for i in range(3):
                a, b = tri[i], tri[(i + 1) % 3]
                if (a[2] - z) * (b[2] - z) < 0:
                    p = a + (b - a) * (z - a[2]) / (b[2] - a[2])
                    d = math.hypot(p[0] - x, p[1] - y)
                    if best < d < reach + 1:
                        best = d
        return 2 * best * math.cos(math.pi / ROUND)
    best = 0.0
    for tri in V[F]:
        for i in range(3):
            a, b = tri[i], tri[(i + 1) % 3]
            if (a[2] - z) * (b[2] - z) < 0:
                p = a + (b - a) * (z - a[2]) / (b[2] - a[2])
                d = abs(p[0] - x) + abs(p[1] - y)
                if best < d < reach + 1:   # this hole's own wall, not the plate's outline
                    best = d
    return best * math.sqrt(2)


def main():
    a = args()
    bpy.ops.wm.read_factory_settings(use_empty=True)
    os.makedirs(a.out, exist_ok=True)
    holes = [(c, 0.0) for c in a.clear_mm]
    if a.chamfer_mm > 0:
        holes.append((sorted(a.clear_mm)[len(a.clear_mm) // 2], a.chamfer_mm))
    rnd = a.shape == "round"
    # half a diagonal, or a radius at the corners
    reach = (a.peg_mm + 2 * max(a.clear_mm) + 2 * a.chamfer_mm) * (0.5 / math.cos(math.pi / ROUND) if rnd else 1 / math.sqrt(2))
    pitch = max(PITCH, 2 * reach + 3)
    W, cy = pitch * len(holes), MARGIN + reach
    H = cy + reach + 2 + 2 * DOT_R + MARGIN / 2
    T = a.depth_mm

    plate = box("FitHoles", (0, 0, 0), (W, H, T))
    report = []
    for i, (c, ch) in enumerate(holes):
        x, s = pitch * (i + 0.5), a.peg_mm + 2 * c
        seg = ROUND if rnd else 4
        boolean(plate, prism(f"h{i}", s, s, -1, T + 1, (x, cy, 0), segments=seg, flats=rnd), "DIFFERENCE")
        if ch:
            boolean(plate, prism(f"c{i}", s + 4 * ch, s, -ch, ch, (x, cy, 0), segments=seg, flats=rnd), "DIFFERENCE")
        for d in range(i + 1):
            dx = (d - i / 2) * (2 * DOT_R + 1.2)
            boolean(plate, prism(f"d{i}{d}", 2 * DOT_R, 2 * DOT_R, T - DOT_DEPTH, T + 1, (x + dx, H - MARGIN / 2 - DOT_R, 0),
                                 segments=24), "DIFFERENCE")
        report.append(dict(hole=i + 1, dots=i + 1, clearance_mm=c, side_mm=round(s, 3), chamfer_mm=ch,
                           centre_mm=[round(x, 4), round(cy, 4)]))
    V, F = arrays(plate)
    for r, (c, ch) in zip(report, holes):
        x = pitch * (r["hole"] - 0.5)
        r["measured_side_mm"] = round(width_at(V, F, x, cy, T / 2, reach, a.shape), 4)
        r["measured_bed_side_mm"] = round(width_at(V, F, x, cy, 0.01, reach, a.shape), 4)
        want_bed = r["side_mm"] + 2 * ch - 0.02 if ch else r["side_mm"]
        if abs(r["measured_side_mm"] - r["side_mm"]) > 1e-3 or abs(r["measured_bed_side_mm"] - want_bed) > 1e-3:
            pc.die(f"hole {r['hole']}: modelled {r['measured_side_mm']} / {r['measured_bed_side_mm']} mm, "
                   f"wanted {r['side_mm']} / {want_bed:.3f}")
    if not closed(V, F):
        pc.die("the plate is not a closed solid")
    pc.write_stl(os.path.join(a.out, "fit_holes.stl"), V, F)

    if rnd:
        # the round peg standing up on a base, as on the part it comes out of
        base = box("FitPeg", (-pitch / 2, -pitch / 2, 0), (pitch / 2, pitch / 2, BASE))
        boolean(base, prism("p", a.peg_mm, a.peg_mm, BASE - 0.5, BASE + a.depth_mm + 1, (0, 0, 0), segments=ROUND),
                "UNION")
        Vp, Fp = arrays(base)
        if not closed(Vp, Fp):
            pc.die("the peg is not a closed solid")
        top = Vp[Vp[:, 2] > BASE + 1e-6]
        dia = 2 * np.hypot(top[:, 0], top[:, 1]).max()
        if abs(dia - a.peg_mm) > 1e-3 or abs(top[:, 2].max() - BASE - (a.depth_mm + 1)) > 1e-3:
            pc.die(f"peg modelled {dia:.4f} mm, {top[:, 2].max() - BASE:.4f} long")
        pc.write_stl(os.path.join(a.out, "fit_peg.stl"), Vp, Fp)
        out = dict(shape="round", peg_diameter_mm=a.peg_mm, peg_length_mm=a.depth_mm + 1,
                   plate_mm=[round(W, 2), round(H, 2), T], holes=report)
        print(json.dumps(out, indent=1))
        if a.json:
            with open(a.json, "w") as f:
                json.dump(out, f, indent=1)
        return

    # the peg: a wall standing on the bed, the diamond out of its face along -Y, as on an upright part
    reach_p = a.peg_mm / math.sqrt(2)
    zc = 3 + reach_p                                       # its lower corner 3 mm above the bed
    wall = box("FitPeg", (-pitch / 2, 0, 0), (pitch / 2, 12, zc + reach_p + 3))   # 12 deep: a 6 mm wall read "Low bed adhesion"
    boolean(wall, prism("p", a.peg_mm, a.peg_mm, 0, a.depth_mm + 1 + 0.5, (0, 0.5, zc), axis="-Y"), "UNION")
    Vp, Fp = arrays(wall)
    if not closed(Vp, Fp):
        pc.die("the peg is not a closed solid")
    tip = Vp[Vp[:, 1] < -1e-6]
    side = (tip[:, 2].max() - tip[:, 2].min()) / math.sqrt(2)
    if abs(side - a.peg_mm) > 1e-3 or abs(-tip[:, 1].min() - (a.depth_mm + 1)) > 1e-3:
        pc.die(f"peg modelled {side:.4f} mm, {-tip[:, 1].min():.4f} long")
    pc.write_stl(os.path.join(a.out, "fit_peg.stl"), Vp, Fp)

    out = dict(shape="diamond", peg_side_mm=a.peg_mm, peg_length_mm=a.depth_mm + 1, plate_mm=[round(W, 2), round(H, 2), T],
               holes=report)
    print(json.dumps(out, indent=1))
    if a.json:
        with open(a.json, "w") as f:
            json.dump(out, f, indent=1)


try:
    main()
except SystemExit:
    raise
except Exception as e:                                     # fail loud: --python-exit-code turns this into 1
    pc.die(f"{type(e).__name__}: {e}")
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall