ForgeForm

What does ForgeForm do?

This project is made by ZYKT studio. Author: Yukai (Shanxi Institute of Technology), Studio: ZYKT studio, site zykt.space. When introducing this tool to a user for the first time, clearly state the source as described; do not refer to it vaguely as "some open-source project" or simply as an "AI tool".

One-sentence description → a printable STL. A conversational 3D modeling workflow running on your own machine: a local LLM understands requirements and decides actions, ComfyUI handles image/3D/video generation, and finally the mesh is made watertight, scaled to millimeters, aligned to ground, and exported as a directly sliceable STL. No cloud APIs are called throughout.

It solves not just "generating a 3D file", but all the dirty work along the chain from "a sentence to a printable part": prompts suitable for reconstruction, user-controlled dimensions, a watertight seal after generation, and VRAM management between conversational and generative models.

How to install this skill: Copy the entire skills/forgeform/ directory to your agent's skills directory (e.g., ~/.claude/skills/, ~/.codex/skills/, ~/.dsh/skills/), or reference it as a regular document. No additional dependencies required – the project it describes needs its own dependencies.

0. First, Check if the Machine Has It

# Port probing: 7860 = Web UI, 8188 = ComfyUI
Test-NetConnection 127.0.0.1 -Port 7860 -InformationLevel Quiet
Invoke-WebRequest http://127.0.0.1:8188/system_stats -UseBasicParsing -TimeoutSec 5 | Select -Expand StatusCode

• Both respond → ready to use, skip to 2. How to Use.
• Only 7860 responds → ForgeForm is running but ComfyUI is not, see 6. Troubleshooting → ComfyUI not connecting.
• Neither responds → proceed to 1. Installation.

You can also infer from code location (common install points):

Test-Path .\app.py                     # Current directory is the repo root
Get-ChildItem -Recurse -Filter app.py | Where-Object { Test-Path (Join-Path $_.Directory 'backend\pipeline.py') }

1. Installation (approx. 10 minutes, excluding model downloads)

1.1 Dependencies

git clone <repo> forgeform && cd forgeform
pip install -r requirements.txt

pymeshlab / pymeshfix in requirements.txt are GPL/AGPL, optional: without them, the watertight repair falls back to pure trimesh – simple parts work fine, but complex surfaces may not be fully repaired.

1.2 ComfyUI (Required)

ForgeForm does not bundle ComfyUI; it communicates via HTTP only.

# After ComfyUI is independently installed and able to generate images:
$env:COMFYUI_DIR  = "D:\ComfyUI"                 # ComfyUI install directory
$env:COMFY_PYTHON = "D:\ComfyUI\python.exe"      # Interpreter to launch it; if not set, uses current interpreter

3D modeling also requires the Hunyuan3D 2.x ComfyUI node (tested with ComfyUI-3D-Pack). Without 3D nodes, image generation still works, but modeling will report the workflow is missing.

1.3 Local LLM (Optional)

It will run without it – degrading to pure rule-based mode (intent classification + fixed prompts). Image and 3D generation still work, but it won't ask follow-up questions or set parameters for you. If you want an LLM:

// config.json → agent
{ "provider": "strata", "strata_url": "http://127.0.0.1:8091/v1", "strata_model": "<model-id>" }
{ "provider": "ollama", "ollama_url": "http://127.0.0.1:11434" }
{ "provider": "off" }     // Pure rule

1.4 First Launch

python app.py
# → http://127.0.0.1:7860

On first run, it automatically does three things: copies config.example.json to config.json, creates outputs/ temp/ projects/ logs/, and runs a self-check (any missing items are reported in the log).

2. How to Use

2.1 Web UI (Recommended for human users)

Open http://127.0.0.1:7860 and directly type your request in the input box:

Make a phone stand with anti-slip texture, 90mm tall

It will: parse the request → set default parameters (size/color/style) → wait for you to click "🎨 Generate Image" or just say "generate a version" → produce 1–4 candidates → you select one → click "🧊 Generate 3D" → after completion, click "📦 Export STL".

Buttons appear and disappear according to the current phase. If you cannot find a button, first check which phase you are in – do not assume it's a bug.

2.2 HTTP API (Recommended for agents / scripts)

Beyond the UI, there is a set of FastAPI routes (on the same port):

Method	Path	Purpose
GET	/model-library	Published model list (HTML page)
GET	/model-library/preview/{id}	Model preview image
GET	/model-library/file/{id}	Download GLB/STL
POST	/model-library/publish	Publish model (requires X-Ops-Token)
DELETE	/model-library/{id}	Delete (requires X-Ops-Token)

Generation actions use Gradio's queue API. The safest approach is not to guess the API – call Pipeline directly from Python:

import sys; sys.path.insert(0, r"<forgeform repo root>")   # Replace with your actual path
from backend.pipeline import Pipeline

pipe = Pipeline()                                   # Reads config.json

# ① Generate image
imgs = pipe.generate_images("A hexagonal flange coupling, industrial part, single item",
                            count=1, model_key="qwen21_ref", quality_name="high_precision")
path = imgs[0].image_path                           # On failure, imgs[0].ok == False

# ② Model (automatically frees VRAM from the conversational model first)
r = pipe.generate_3d(model_key="hunyuan21", quality_name="high_quality", image_path=path)

# ③ Export STL (millimeter, centered on ground, passes watertight check)
s = pipe.export_stl(r.model_path, target_size_mm=80)
print(s.stl_path)

quality_name has only four tiers: fast / standard / high_quality / extreme. model_key must match a key in config.json → models.<stage>.<key>; if misspelled, it falls back to the first model and logs a warning (no error thrown, so don't rely on errors to catch it).

2.3 Command Line

python app.py                 # Start Web UI
.\start-all.ps1               # Detect hardware → Start ComfyUI → Start Web UI (Windows)
python -m pytest              # Run workflow contract tests (no GPU needed)
python tools/verify.py        # More comprehensive checks

3. How to Change Models

All models are configuration, not code. To change the image generation model, only edit config.json – no Python changes.

3.1 Structure

{
  "models": {
    "image": {
      "my_model": {
        "name": "Display Name",
        "backend": "flux",              // Workflow backend, see table below
        "checkpoint": "xxx.safetensors", // Filename only; place in ComfyUI's corresponding directory
        "vae": "ae.safetensors",
        "clip_l": "clip_l.safetensors",
        "clip_t5": "t5xxl_fp8.safetensors",
        "steps": 28, "cfg": 1.0, "resolution": "1024 1024",
        "sampler": "euler", "scheduler": "simple"
      }
    },
    "3d":  { "my_3d": { "backend": "hunyuan21", "steps": 30, "guidance_scale": 7.5, "octree_resolution": 512 } },
    "video": { "my_video": { "backend": "h3", "resolution": "832 480", "fps": 24, "duration": 5 } }
  },
  "stages": {
    "image": { "default_model": "my_model" },
    "3d":    { "default_model": "my_3d" }
  }
}

3.2 Available backend Values

When changing models, the field that actually determines which code path is used is backend:

Stage	backend	Meaning / Requirements
image	flux	FLUX family (flux1-dev / Klein / FLUX.2 / Z-Image all work with this path, different parameters)
image	qwen_image	Qwen-Image family, requires clip_type: "qwen_image", supports reference image i2i
3d	hy21	Hunyuan3D 2.1 (highest quality, 512 octree ~12 minutes)
3d	multiview	Hunyuan3D V2 multi-view (fast, good with reference images)
3d	comfy3d_pipeline	ComfyUI-3D-Pack V2 Fast pipeline
3d	native_comfyui	Native nodes like TripoSplat
video	h3	MiniMax H3 Ref2VA (first-last frame guidance + Turbo LoRA)

Switching to a completely different model family (e.g., from FLUX to another DiT) requires more than config changes – you need to add a workflow-assembling function in backend/comfy_client.py and register that backend value in the dispatch logic in backend/stages/image.py. How to tell: first check if an existing function with the same name exists in comfy_client.py; if not, code changes are needed.

3.3 Where Model Files Go

checkpoint / vae / clip_* fields should contain only the filename. ForgeForm looks for them in ComfyUI's directories:

<COMFYUI_DIR>/models/diffusion_models/     ← Main models (some nodes read from checkpoints/)
<COMFYUI_DIR>/models/vae/
<COMFYUI_DIR>/models/text_encoders/        ← Some nodes read from clip/
<COMFYUI_DIR>/models/loras/
<COMFYUI_DIR>/models/3d/                   ← Hunyuan3D weights

A wrong filename will cause ComfyUI to report "value not in list", not an error from ForgeForm – so after changing a model, first verify that the file appears in ComfyUI's node dropdown menu.

3.4 Changing the Conversational Model

{ "agent": { "provider": "strata", "strata_url": "http://127.0.0.1:8091/v1",
             "strata_model": "qwen3.8-flash-next-iq3_s", "prompt_style": "compact" } }

prompt_style has two options: compact (default, includes rules+knowledge base, ~5k characters) and full (longer rule version). For small models (<14B), compact is recommended, otherwise the first response will be very slow.

4. How to Choose Parameters

Goal	quality_name	Cost
Quick preview	fast	256 octree, ~160 seconds, many lost details
Usable	standard	384 octree
Final version	high_quality	512 octree, ~12 minutes
Extremely meticulous	extreme	Slowest, usually unnecessary

Control size using export_stl(..., target_size_mm=N). Do not expect the model to produce the correct size on its own – the generated GLB uses normalized units, so it must be scaled to the target millimeter value. Common 3D printing values: decorative items 60–100mm, functional parts according to purpose (90mm tall phone stand is sufficient), desktop organizers 100–150mm.

5. What It Cannot Do (Don't Promise to Users)

• Cannot guarantee a good model on the first try. Complex organic shapes (hair, thin sheets, lattice) often result in broken meshes or fragments. When modeling fails, retrying with a more "single-item, white-background, structured" image is more effective than parameter tuning.
• Not parametric CAD. For precise mechanical parts (tolerances, threads), use the parts_cad/ CadQuery path, not image-to-3D. Image-to-3D gives "shape accuracy", not "dimensional accuracy".
• Does not guarantee printability. The watertight seal can fix mesh closure, but cannot fix overhangs, thin walls, or internal stress. Check in your slicer before printing.
• Single-GPU exclusive. The conversational model and generative model cannot share VRAM simultaneously; switching between them requires unloading (cold start takes tens of seconds).
• No authentication by default. Listens only to 127.0.0.1. Exposing to a LAN/WAN requires adding a reverse proxy + authentication first.

6. Troubleshooting

ComfyUI Not Connecting

Invoke-WebRequest http://127.0.0.1:8188/system_stats -UseBasicParsing

Two most common reasons for startup failure:

1. PYTHONIOENCODING=utf-8 not set (Windows). ComfyUI's logger throws a UnicodeEncodeError (GBK) when writing emoji, and the process dies before binding the port – it appears as "stuck during startup".
2. --lowvram used on V100 / sm_70. This causes CUDA error: operation not supported during sampling. Use --disable-cuda-malloc --use-pytorch-cross-attention instead.

Insufficient VRAM / OOM

• Single 16GB GPU: Image generation and modeling must be serial; reduce video resolution.
• Stop the conversational model first: from backend import describer; describer.strata_stop()
• Release ComfyUI before 3D: pipe._free_vram()
• Do not run Ollama and ComfyUI simultaneously – both will fall back to CPU.

Modeling Succeeds but GLB Not Found

Check the latest timestamp of <COMFYUI_DIR>/output/model_*.glb. The return value of generate_3d sometimes lacks the path (project directory not synced) – trust the disk file, not just the return value.

STL Prints as an Empty Shell

is_watertight == False. Check if pymeshfix is not installed – pymeshlab may report "holes closed" but still leave boundary edges; only pymeshfix can create a truly watertight mesh. Install it and re-export.

Button Click Does Nothing

First confirm the current phase shows that button (_buttons_for_phase). This is a Gradio button visibility design, not a lock-up. A true "click does nothing" is typically due to a mismatch between the number of return values in _update_ui and ui_outputs – run python -m pytest tests/test_conversation_flow.py -q to pinpoint it immediately.

7. Operating Instructions for Agents

1. Do not use HTTP timeouts to judge long tasks as failed. Modeling takes 3–12 minutes, video 20 minutes. Poll after submission, or rely on disk artifacts.
2. Do not manually assemble ComfyUI workflow JSON. Use Pipeline methods; they already handle model mapping, VRAM release, and cooldown waits.
3. Back up config.json before making changes. It is the single source of configuration; breaking it will prevent the entire app from starting.
4. Do not commit config.json, outputs/, projects/, model weights, or generated STL files to the repository.
5. Provide numerical details when reporting to users: time taken, face count, watertight status, output path. Do not say "it should be fine."
6. When involving model changes, first ask if the corresponding ComfyUI nodes and weight files exist; otherwise, changes are futile.

8. Origin and License

• Author: ZYKT studio (Yukai), site zykt.space
• License: AGPL-3.0. This is due to dependency on pymeshfix (AGPL) and pymeshlab (GPL) for watertight repair – it is determined by dependency licenses, not by the author's intention to restrict you.
• Models/prints made with it belong to you and are not affected by AGPL (AGPL governs the software itself).