Skip to main content

Forge: the model pipeline

Scripts that make Popfold props and wall art with local AI models and Blender. A prompt goes in, a low-poly textured .glb that follows Popfold's prop convention comes out.

Alpha. These are working scripts, not a polished tool. They were written on Windows with one GPU.

prompt ── FLUX ──▶ picture ── rembg ──▶ cut-out ── Hunyuan3D 2 ──▶ dense mesh ── Blender ──▶ low-poly .glb + review sheet

What you need​

ThingNotes
ComfyUI, runningWith flux1-schnell-fp8.safetensors and hunyuan3d-dit-v2.safetensors in models/checkpoints/ (sd_xl_base_1.0.safetensors too, for tileable patterns). A 12 GB GPU is enough.
Blender 4.2 or newerTested on 5.3.
Python 3With the packages in requirements.txt. ComfyUI's own virtual environment already has most of them.
Ollama (optional)A local vision language model for director.py. Tested with Qwen3-VL 8B (5.8 GB): ollama pull hf.co/Qwen/Qwen3-VL-8B-Instruct-GGUF:Q4_K_M, then set llm.model to that name.

Check the licence of each model before you publish or sell what it makes. They differ.

Settings​

Copy forge.example.json to forge.json (not committed) and edit it, or set environment variables:

SettingEnvironment variableDefault
comfy_urlCOMFY_URLhttp://127.0.0.1:8188
blenderPOPFOLD_BLENDERblender (on PATH)
outPOPFOLD_FORGE_OUTforge-out in the current folder
llm.urlOLLAMA_URLhttp://127.0.0.1:11434
llm.modelPOPFOLD_LLM_MODELnone

config.py reads them. Keep the output folder outside any site: copy only the finished .glb into <site>/public/models/props/.

Make props​

Run from this folder, with ComfyUI running:

python asset_pipeline.py jobs/example-props.json # every asset in the file
python asset_pipeline.py jobs/example-props.json mushroom-lamp # one asset
python asset_pipeline.py assets.json --from-image # keep the pictures, redo mesh and Blender
python asset_pipeline.py assets.json --from-mesh # redo only the Blender step
python asset_pipeline.py assets.json --style=refined

Each asset lands in <out>/props/<name>/: source.png (the picture), prepared.png and mask.png (the cut-out), raw.glb (the dense mesh), <name>.glb (the finished prop), review.png (four views) and log.json (timings). Look at review.png before using a prop.

A job file is a list:

[{ "name": "armchair", "prompt": "toy armchair, lilac velvet, short gold legs", "seed": 101, "tris": 2500 }]
FieldMeaning
nameFile name of the prop (lowercase, dashes)
promptThe object. The style adds the rest
seedChange it to get a different picture
trisTriangle budget (default from the style)
styleA file in styles/ (default toy)
raw_promptA complete prompt, skipping the style
flat, depthFor thin wall pieces
fillKeep pale glass or panels the cut-out removed
palette, coloursFlat colours per part instead of the projected picture

pick_source.py assets.json --out=DIR --seeds=4 name draws several pictures and keeps the most front-on one.

Styles​

A style is a JSON file in styles/: the prompt wrapped around every subject, and a default triangle budget.

{ "about": "Chunky, glossy toy furniture.", "prompt": "single {subject}, chunky stylised toy, ... 3d render", "tris": 2500 }

A site can keep its own in a styles/ folder where the script is run from; those are added to the ones here. One style per site is what makes forty props look like one set.

Let a local model direct it​

director.py takes a one-line brief instead of a job file. A vision model in Ollama plans the job, picks the best of several pictures, judges the finished review.png, and retries with a new subject or mesh settings on a fail.

python director.py "a chunky mint-green bedside lamp shaped like a mushroom, cream stem" --style toy
python director.py "..." --rounds 3 --seeds 3 --pass 8 --name mushroom-lamp
python director.py --judge <out>/props/mushroom-lamp "the brief" # judge an existing review.png only

It writes the usual files plus candidates/ (every picture and review sheet) and director.json (every plan, pick and verdict). A pass needs the model's own pass and a score of at least --pass: the model is lenient and will pass a prop it has just listed problems for. It still does not replace looking at review.png.

The GPU is shared: each model call frees ComfyUI's models first, and Ollama unloads the language model as soon as it answers. One prop takes about two minutes a round on a 12 GB card.

llm.banned in forge.json is a list of words (brand or character names) that must never reach a prompt; a plan that uses one is sent back. llm.py is the small Ollama client the director uses.

Use Hyper3D Rodin instead of Hunyuan3D​

rodin.py sends one to five pictures (or a text prompt) to Hyper3D Rodin, a paid hosted service, and downloads the textured model it makes. Its meshes are usually cleaner than Hunyuan3D's and come with a full texture, but each one costs credits and the pictures leave the machine.

python rodin.py --balance # free: credits left
python rodin.py <out>/props/armchair/source.png --out <out>/rodin/armchair --faces 8000
python rodin.py --text "a chunky toy armchair, lilac velvet" --out <out>/rodin/armchair

API generation needs a Business or Enterprise plan. On a lower plan the balance check works but a generation fails with API_NO_ACTIVE_SUBSCRIPTION. Set the key with RODIN_API_KEY, or point rodin.key_file in forge.json (or RODIN_KEY_FILE) at a file outside the repository. rodin.tier sets the default tier (Gen-2.5-Medium; about 0.5 credits a model). Ask before a batch: every model costs money.

Rodin from an agent, on any plan (MCP)​

Hyper3D's MCP server bills the workspace you sign in with, at its plan and credits, so it works on Creator where the REST API refuses. Add it once, for every project, and sign in (a browser window opens). Its tools load in the next session.

claude mcp add --transport http hyper3d-rodin --scope user https://api.hyper3d.com/api/mcp
claude mcp login hyper3d-rodin

The tools an agent uses for a prop:

ToolWhat it doesCosts credits
rodin_create_uploadsGives a one-hour URL per picture; PUT the file's bytes there, then pass the upload idno
rodin_generatePictures or text to a textured model: tier, mesh_mode (Raw = triangles, Quad), quality_override (face count), geometry_file_format (glb)yes
rodin_wait, rodin_get_statusWaits up to 45 s, or reads the stage (mesh, texture, pack)no
rodin_get_resultThe result page and signed download URLs (base_basic_pbr.glb, base_basic_shaded.glb)no
rodin_generate_polygenA low-poly remesh of a finished modelyes
rodin_generate_agenticBeta: builds hard-surface subjects from editable n-gonsyes
rodin_generate_bang, rodin_generate_riggingSplit a model into parts; add a skeleton and animationsyes
rodin_list_uploads, rodin_delete_uploads, rodin_list_animation_*The upload library and the animation catalogueno

There is no balance tool; the website shows the credits left. One picture with tier: Gen-2.5-High, mesh_mode: Raw, quality_override: 6000, geometry_file_format: glb took about two minutes and gave a 6,000- triangle model with a 7 MB PBR .glb, as good as the same settings on the website (Gen-2.5 on the website costs about 0.5 credits a model). Download it outside the repository and check it with blender_render.py like any other.

Make wall art​

python art_run.py jobs/example-art.json

Each job has a theme, name, prompt, seed and a frame (main 896 × 1088, square 1024 × 1024, small 832 × 1152) or its own width and height. Pictures land in <out>/art/<theme>/raw/.

The scripts​

ScriptRuns inDoes
asset_pipeline.pyPythonThe whole chain for a list of assets, one phase at a time so the GPU loads each model once
comfy_run.pyPythonText to image through ComfyUI's HTTP API (FLUX schnell or SDXL; "tile": true for seamless patterns)
comfy_3d.pyPythonImage to mesh with Hunyuan3D 2
pick_source.pyPythonSeveral seeds, keeps the most symmetric picture
director.py, llm.pyPythonA brief in, a judged prop out, with a local model in Ollama planning and judging
rodin.pyPythonPictures or text to a textured model with Hyper3D Rodin (paid, hosted; API needs a Business plan)
art_run.pyPythonWall art
blender_lowpoly.pyBlenderCleans the mesh, reduces it, projects the picture as its texture, normalises it
blender_render.pyBlenderA review sheet: blender -b -P blender_render.py -- IN.glb OUT.png --views 4
ortho_views.pyBlenderFront, side, top and back with a measuring grid
blender_assemble.pyBlenderJoins parts into one animated .glb from a JSON spec
scan_cut.py, scan_clean.pyBlenderClean up a phone scan
start-comfyui.ps1, stop-comfyui.ps1PowerShellStart and stop ComfyUI (set COMFYUI_DIR)
config.pyPythonSettings

The workflow graphs sent to ComfyUI are built in code (workflow() in comfy_run.py and comfy_3d.py), not loaded from saved workflow files.

What goes wrong​

  • Thin parts (cords, wires, slim legs) come out lumpy or vanish. Ask for thick, solid parts, or build the piece by hand in Blender.
  • The back is a guess. The mesh model sees only the front, and the texture is the front picture projected through.
  • Pairs never match. Mirror one model; do not generate two.
  • One GPU job at a time. Do not start a second batch while one runs.

More on choosing between this and the other ways to get a model: the repository's docs/models.md.