Official Codebase of 3DCodeVerse
Python
toolkits: vendor the complete 3dcode_toolkit (CLI package + docs + config example) next to the curation scripts, so nothing from the toolchain is left out; note how to rename the folder
gaoypeng3f222c58fb2e
diff --git a/toolkits/3dcode_cli/.gitignore b/toolkits/3dcode_cli/.gitignorenew file mode 100644index 00000000..bf912d3e--- /dev/null+++ b/toolkits/3dcode_cli/.gitignore@@ -0,0 +1,14 @@+# dev environment + build artifacts — never commit secrets or local config+.venv/+.venv*/+__pycache__/+*.egg-info/+build/+dist/+*.pyc+.DS_Store++# real credentials live in ~/.config/3dcode/config.toml, NEVER in the repo.+# (config.toml.example, with placeholders, IS committed.)+config.toml+.envdiff --git a/toolkits/3dcode_cli/CLAUDE.md b/toolkits/3dcode_cli/CLAUDE.mdnew file mode 100644index 00000000..a4fc7f32--- /dev/null+++ b/toolkits/3dcode_cli/CLAUDE.md@@ -0,0 +1,80 @@+# CLAUDE.md — 3dcode toolkit & 3DCodeVerse++Orientation for coding agents (Claude Code et al.) working in this repo or using it to+author data. Read this first.++## What this project is++**3DCodeVerse** is a community-curated corpus that pairs **3D objects with the *code* that+builds them** — not static meshes, but runnable programs (Blender Python, CadQuery, …) plus+their reference images / prompt / renders. The goal: a large (TB-scale), multi-source,+multi-dialect, license-clean corpus for training & evaluating 3D-from-code generation.++**This repo (`3dcode`)** is the CLI toolkit contributors run **on their own machine** to+validate, fingerprint (dedup), executability-check, render, and upload (code → 3D) *projects*.+Data flows: `3dcode push` → private R2 staging + a validation report → a maintainer reviews in+a web Inbox → approve → `3dcode ingest` pulls it into the canonical store. Everything that can+run locally runs locally — nothing routes heavy compute/bandwidth through a central server.++## The data model (memorize this)++- A **source** = one origin/contributor (a top-level folder).+- A **project / sample** = one independent asset: a sub-folder with **code at the top**,+ `renders/` (images + `.glb`), an optional `prompt.txt`, and an auto-generated `meta.json`.++```+<source>/<project>/+ model.py # the code — the core artifact (must be self-contained & runnable)+ renders/ # rendered images + mesh+ prompt.txt # text prompt (optional)+ meta.json # id, dialect, modality, dedup hashes, exec results, status+```++## The toolkit (commands)++`config` · `validate` · `check` (dedup vs corpus) · `anomalies` (length/char outliers) ·+`exec` (run the code, must build non-empty geometry) · `render` (clay/textured into renders/) ·+`push` (validate→fingerprint→upload→register) · `ingest` (admin: pull approved → core).++## If you are a coding agent AUTHORING / CONVERTING a sample++The corpus is built by turning assets into **standalone runnable code**. Do it as a loop with+your eyes open — never author blind:++1. Write **self-contained** code for the target dialect (no project-local imports; e.g. a+ Blender script must NOT `import infinigen` — inline what it needs).+2. `3dcode exec ./dir` → it must run **error-free AND produce a non-empty mesh**. Fix until green.+ (Blender Python is checked in Blender 5.0 **and** 5.1 — make it work in both.)+3. `3dcode render ./dir` → look at the render. Iterate until the shape/material is right.+4. `3dcode check ./dir` → if it's a near-duplicate of the corpus, drop or justify it.+5. `3dcode push ./dir --source <name>` → uploads + registers for review.++**Quality bar:** runs + builds geometry; grounded by a reference image and/or prompt; not a+near-duplicate; not absurdly long (anomaly-flagged); permissive `license`/`provenance` in meta.++## Code layout++```+threedcode/+ cli.py # the `3dcode` entry (Typer)+ config.py storage.py(R2) schema.py hashing.py registry.py+ dialects/ # per-dialect adapters: blender_python, cadquery_dialect, build123d_dialect,+ # openscad_dialect, freecad_dialect (CadQuery & build123d = separate venvs)+ runners/ # runtime wrappers: blender_exec.py, blender_render.py, blender_render_mesh.py, freecad_exec.py+docs/contributing.md # contributor onboarding+```++## Adding a new dialect++Add `threedcode/dialects/<name>_dialect.py` with `run(code_file) -> {status,...}` (exec) and+`render(code_file, renders_dir, blender_bin, mode) -> {status, images}` (render — export a mesh+and reuse `runners/blender_render_mesh.py` if the runtime can't render images itself). Wire it+into `dialects/__init__.py` (`run_dialect`/`render_dialect`) and add an optional extra in+`pyproject.toml`. Reference the proven renderers in the upstream+`infinigen/data_pipeline_operators/` (renderer.py, renderer_texture.py) for camera/lighting.++## Conventions++- Keep modules small and single-purpose. Match the existing style.+- Secrets live in `~/.config/3dcode/config.toml` / env — **never commit them**.+- Optional heavy deps (trimesh/imagehash, cadquery) are extras — base install stays light.diff --git a/toolkits/3dcode_cli/README.md b/toolkits/3dcode_cli/README.mdnew file mode 100644index 00000000..74050b83--- /dev/null+++ b/toolkits/3dcode_cli/README.md@@ -0,0 +1,115 @@+# 3dcode — 3DCodeVerse data toolkit++CLI to validate, fingerprint (dedup), and upload **(code → 3D)** projects to the+3DCodeVerse corpus. Contributors run `3dcode push` from their own machine; data goes+straight to a private staging bucket (Cloudflare R2), gets reviewed, then ingested to the+canonical store.++## What's a "project"++One independent asset = its **code** + reference images / text prompt / video / derived+renders+glb + a `meta.json`. A **source** folder holds many projects:++```+<source>/<project>/+ meta.json # auto-generated identity card (id, dialect, hashes, status, …)+ model.py # the code (the core artifact)+ renders/ Image_015.webp # reference / rendered images+ prompt.txt # text prompt+ *.glb # mesh+```++## Install++```bash+pipx install "git+https://github.com/gaoypeng/3dcode_toolkit"+# optional extras (per dialect / for dedup):+pipx install "3dcode[dedup] @ git+https://github.com/gaoypeng/3dcode_toolkit"+# [dedup] geometry + perceptual hashing+# [cadquery] CadQuery exec/render \ conflicting OCP builds —+# [build123d] build123d exec/render / install in SEPARATE environments+# OpenSCAD + FreeCAD are system binaries (not pip) — point `config set` at them.+```++## Configure (once)++```bash+3dcode config set \+ --endpoint https://<ACCOUNT_ID>.r2.cloudflarestorage.com \+ --bucket 3dcodeverse \+ --access-key-id <YOUR_KEY> --secret-access-key <YOUR_SECRET> \+ --source yourname+```+Saved to `~/.config/3dcode/config.toml` (chmod 600). You can also use `R2_*` env vars.+**Never commit your filled-in config** — only `config.toml.example` (placeholders) is in the repo.++## Use++```bash+3dcode validate ./data # layout + structure + anomaly checks, no upload+3dcode check ./data # validate + flag duplicates vs the corpus, no upload+3dcode anomalies ./data # distribution outliers (code length / char count)+3dcode exec ./data # run the code locally; record pass/fail in meta.json+3dcode render ./data --mode white # render the code locally into renders/ (white | textured)+3dcode grid ./data # contact-sheet PNG of all thumbnails (visual review)+3dcode push ./data --source you # validate → hash → dedup-check → upload → register+```++### Executability (`3dcode exec`)++Runs each project's code **locally, in your own runtimes** (nothing is uploaded) and records+the result in `meta.json`. Pass = ran error-free **and** produced a non-empty mesh. Configure+the runtimes once:++```bash+3dcode config set --blender-5-0 /path/to/blender-5.0/blender \+ --blender-5-1 /path/to/blender-5.1/blender+```+Wired dialects: Blender Python (5.0 + 5.1), CadQuery, build123d, OpenSCAD, FreeCAD.+Missing runtimes are reported `n/a` (skipped, not failed). A maintainer may optionally re-run+`exec` on ingest as a backstop.++`./data` may be a single project, or a folder of project subdirs — each is uploaded under+`<source>/<project>/`.++## Fingerprints (dedup)++Computed on your machine, light deps, no Blender/GPU:++- `code_hash` — sha256 of normalized code (exact-code dups)+- `geom_hash` — sampled GLB mesh signature (geometric dups) · needs `[dedup]`+- `phash` — perceptual hash of a render (visual dups) · needs `[dedup]`++## 3D code dialects++Each code type plugs in how to validate / find code / hash for that dialect:++- **Blender Python** (`.py`, default) — exec runs in Blender 5.0 + 5.1; render = Workbench clay / EEVEE.+- **CadQuery** (`.py`, `--dialect cadquery`, `3dcode[cadquery]`) — exec verifies a non-empty+ solid (volume>0); render exports STL → clay-render in Blender.+- **build123d** (`.py`, `--dialect build123d`, `3dcode[build123d]`) — same as CadQuery (shared+ OCC kernel). ⚠️ CadQuery and build123d ship **conflicting OCP builds** — install them in+ **separate environments**, not one venv.+- **OpenSCAD** (`.scad`, auto-detected) — exec compiles to STL (must be non-empty); render =+ STL → clay-render in Blender. Needs the `openscad` binary/AppImage (`config set --openscad`).+- **FreeCAD** (`.py`, `--dialect freecad`) — exec/render run inside `freecadcmd` (checks for a+ non-empty solid, tessellates → clay-render). Needs `freecadcmd` (`config set --freecadcmd`).++…extensible: add a `threedcode/dialects/<name>_dialect.py` adapter (`run()` for exec, `render()` for render).++## Admin (lab-side)++After reviewing uploads in the web Inbox (`/data/inbox`) and approving them:++```bash+3dcode config set --core-dir /path/to/canonical/store+3dcode ingest --all-approved # pull approved R2 → core dir, mark ingested, clear staging+3dcode ingest <source>/<project> # or a single project+```++## Status++`config` / `validate` / `check` / `anomalies` / `exec` / `render` / `grid` / `push` / `ingest`+working end-to-end: contributor pushes → R2 staging + validation report in the registry →+admin reviews in the web Inbox → approve → `ingest` pulls to the canonical store. Five dialects+wired (Blender Python, CadQuery, build123d, OpenSCAD, FreeCAD) — each with exec + render.diff --git a/toolkits/3dcode_cli/VENDORED.md b/toolkits/3dcode_cli/VENDORED.mdnew file mode 100644index 00000000..38e54ff4--- /dev/null+++ b/toolkits/3dcode_cli/VENDORED.md@@ -0,0 +1,11 @@+# Vendored copy++This is the complete [gaoypeng/3dcode_toolkit](https://github.com/gaoypeng/3dcode_toolkit) repository+(everything except `.git/` and `curation_tools/`, which lives in `../curation/`), copied here so the whole data+toolchain is maintained in one place.++* upstream: https://github.com/gaoypeng/3dcode_toolkit+* copied at: 2026-08-28+* files: 25 here + 49 curation scripts in `../curation/` = the upstream repo's 74 tracked files++Edits made here do not flow upstream automatically. Decide which copy is canonical before changing either.diff --git a/toolkits/3dcode_cli/config.toml.example b/toolkits/3dcode_cli/config.toml.examplenew file mode 100644index 00000000..56a11791--- /dev/null+++ b/toolkits/3dcode_cli/config.toml.example@@ -0,0 +1,17 @@+# Copy to ~/.config/3dcode/config.toml and fill in your scoped R2 token.+# (Or set the matching R2_* / SOURCE env vars — env always wins over this file.)+# NEVER commit a filled-in copy — it holds your secret key.++endpoint = "https://<ACCOUNT_ID>.r2.cloudflarestorage.com"+bucket = "3dcodeverse"+access_key_id = "<YOUR_R2_ACCESS_KEY_ID>"+secret_access_key = "<YOUR_R2_SECRET_ACCESS_KEY>"++# Default source folder for your uploads (overridable with --source).+source = "<your-source-name>"++# Optional: local runtimes for `3dcode exec` / `render` (only the dialects you use).+# blender_5_0 = "/path/to/blender-5.0/blender"+# blender_5_1 = "/path/to/blender-5.1/blender"+# openscad = "/path/to/OpenSCAD.AppImage"+# freecadcmd = "/path/to/freecadcmd"diff --git a/toolkits/3dcode_cli/docs/contributing.md b/toolkits/3dcode_cli/docs/contributing.mdnew file mode 100644index 00000000..058315e9--- /dev/null+++ b/toolkits/3dcode_cli/docs/contributing.md@@ -0,0 +1,65 @@+# Contributing data to 3DCodeVerse++Thanks for contributing! The corpus pairs **3D objects with the code that builds them**.+You upload (code → 3D) *projects* straight from your machine; they're auto-validated and+dedup-checked, a maintainer reviews them, and approved projects are ingested into the corpus.++## 1. Install & configure (once)++```bash+pipx install "git+https://github.com/gaoypeng/3dcode_toolkit"+# optional extras:+# [dedup] geometry + perceptual hashing (recommended)+# [cadquery] CadQuery exec/render++3dcode config set \+ --endpoint https://<ACCOUNT_ID>.r2.cloudflarestorage.com \+ --bucket 3dcodeverse \+ --access-key-id <YOUR_KEY> --secret-access-key <YOUR_SECRET> \+ --contrib-token <FROM_A_MAINTAINER> \+ --source yourname+```+A maintainer gives you a scoped R2 token (write to your `source/` only) + the contributor token.+Secrets live in `~/.config/3dcode/config.toml` — **never commit them**.++## 2. Lay out your data++One **source** = you; one sub-folder per **data sample** (an independent, runnable project):++```+yourname/+ chair_01/+ model.py # the code (the core artifact)+ renders/ # rendered images + .glb mesh+ prompt.txt # text prompt (optional)+ meta.json # auto-generated by `3dcode`+ chair_02/+ ...+```++## 3. Workflow++```bash+3dcode validate ./yourname # layout + anomaly checks+3dcode exec ./yourname # run the code locally, confirm it builds geometry+3dcode render ./yourname # (optional) render thumbnails into renders/+3dcode check ./yourname # flag duplicates against the existing corpus+3dcode push ./yourname --source yourname # validate → fingerprint → upload → register+```+Everything runs **on your machine** (your runtimes, your bandwidth) — nothing routes through a+central server. `push` uploads directly to the private staging bucket and registers a+validation report. A maintainer then reviews it in the web Inbox and ingests it.++## 4. Code dialects++- **Blender Python** (`.py`, default) — exec runs in Blender 5.0 + 5.1.+- **CadQuery** (`.py`, add `--dialect cadquery`, install `3dcode[cadquery]`).+- More (FreeCAD, OpenSCAD, shaders) coming — see `threedcode/dialects/`.++## 5. What makes a good sample++- Code that **runs error-free and produces non-empty geometry** (`3dcode exec` checks this).+- A grounding signal: a **reference image and/or a text prompt**.+- **Not a near-duplicate** of something already in the corpus (`3dcode check` flags these).+- Reasonable size — wildly over-long code is flagged by `3dcode anomalies`.+- A permissive, attributable **license** (set `license`/`provenance` in `meta.json`).diff --git a/toolkits/3dcode_cli/pyproject.toml b/toolkits/3dcode_cli/pyproject.tomlnew file mode 100644index 00000000..ecd4a4f7--- /dev/null+++ b/toolkits/3dcode_cli/pyproject.toml@@ -0,0 +1,29 @@+[build-system]+requires = ["setuptools>=68", "wheel"]+build-backend = "setuptools.build_meta"++[project]+name = "3dcode"+version = "0.1.0"+description = "3DCodeVerse data toolkit — validate, dedup, and upload (code -> 3D) projects"+readme = "README.md"+requires-python = ">=3.10"+license = { text = "MIT" }+dependencies = [+ "boto3>=1.34",+ "typer>=0.12",+ "tomli>=2.0 ; python_version < '3.11'",+]++# Heavier, optional: geometry + perceptual hashing for dedup. Base install stays light.+[project.optional-dependencies]+dedup = ["trimesh>=4.0", "imagehash>=4.3", "Pillow>=10.0", "numpy>=1.24"]+cadquery = ["cadquery>=2.5"]+build123d = ["build123d>=0.5"]+# OpenSCAD + FreeCAD are system binaries (not pip) — set their paths via `3dcode config set`.++[project.scripts]+"3dcode" = "threedcode.cli:app"++[tool.setuptools.packages.find]+include = ["threedcode*"]diff --git a/toolkits/3dcode_cli/threedcode/__init__.py b/toolkits/3dcode_cli/threedcode/__init__.pynew file mode 100644index 00000000..9971cede--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/__init__.py@@ -0,0 +1,3 @@+"""3DCodeVerse data toolkit (`3dcode`) — validate, dedup, and upload (code -> 3D) projects."""++__version__ = "0.1.0"diff --git a/toolkits/3dcode_cli/threedcode/cli.py b/toolkits/3dcode_cli/threedcode/cli.pynew file mode 100644index 00000000..93df5875--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/cli.py@@ -0,0 +1,365 @@+"""`3dcode` CLI — contributor-side commands to validate and upload (code -> 3D) projects.++ 3dcode config set --endpoint ... --access-key-id ... --secret-access-key ...+ 3dcode validate ./data+ 3dcode push ./data --source yourname+"""++from __future__ import annotations++import json+from pathlib import Path++import typer++from . import __version__, registry+from .config import load_config, save_config+from .hashing import project_hashes+from .schema import META_NAME, find_projects, merge_preserved, validate_project++app = typer.Typer(add_completion=False, help="3DCodeVerse data toolkit.")+config_app = typer.Typer(help="Manage R2 endpoint / token / default source.")+app.add_typer(config_app, name="config")+++def version():+ """Print the toolkit version."""+ typer.echo(f"3dcode {__version__}")+++@config_app.command("set")+def config_set(+ endpoint: str = typer.Option(None),+ bucket: str = typer.Option(None),+ access_key_id: str = typer.Option(None),+ secret_access_key: str = typer.Option(None),+ source: str = typer.Option(None, help="default source folder for your uploads"),+ api: str = typer.Option(None, help="registry API base (default 3dcodebench.com)"),+ contrib_token: str = typer.Option(None, help="shared contributor token for the registry"),+ blender_5_0: str = typer.Option(None, help="local Blender 5.0 binary (for 3dcode exec)"),+ blender_5_1: str = typer.Option(None, help="local Blender 5.1 binary"),+ openscad: str = typer.Option(None, help="local OpenSCAD binary/AppImage (.scad)"),+ freecadcmd: str = typer.Option(None, help="local freecadcmd binary (FreeCAD)"),+ core_dir: str = typer.Option(None, help="admin canonical store dir (for 3dcode ingest)"),+):+ """Write R2 settings to ~/.config/3dcode/config.toml (chmod 600)."""+ path = save_config({+ "endpoint": endpoint, "bucket": bucket, "access_key_id": access_key_id,+ "secret_access_key": secret_access_key, "source": source,+ "api": api, "contrib_token": contrib_token,+ "blender_5_0": blender_5_0, "blender_5_1": blender_5_1,+ "openscad": openscad, "freecadcmd": freecadcmd, "core_dir": core_dir,+ })+ typer.echo(f"saved -> {path}")+++@config_app.command("show")+def config_show():+ """Show the active config (secret masked)."""+ c = load_config()+ secret = (c.secret_access_key[:4] + "…") if c.secret_access_key else "(unset)"+ for k, v in {"endpoint": c.endpoint, "bucket": c.bucket,+ "access_key_id": c.access_key_id or "(unset)",+ "secret_access_key": secret, "source": c.source or "(unset)"}.items():+ typer.echo(f" {k:18} {v}")+++def _iter(root: Path, source: str):+ projects = find_projects(root)+ if not projects:+ typer.echo(f"no projects found under {root}", err=True)+ raise typer.Exit(1)+ for d in projects:+ errors, warnings, meta = validate_project(d, source)+ yield d, errors, warnings, meta+++def validate(path: Path = typer.Argument(..., exists=True),+ source: str = typer.Option(None, help="source name (defaults to config)")):+ """Validate project(s) locally — no upload."""+ source = source or load_config().source or "unknown"+ bad = 0+ for d, errors, warnings, _ in _iter(path, source):+ if errors:+ bad += 1+ typer.secho(f"✗ {d.name}: {'; '.join(errors)}", fg="red")+ else:+ tag = typer.style("✓", fg="green")+ typer.echo(f"{tag} {d.name}" + (f" ⚠ {'; '.join(warnings)}" if warnings else ""))+ if bad:+ raise typer.Exit(1)+++def check(path: Path = typer.Argument(..., exists=True),+ source: str = typer.Option(None, help="source name (defaults to config)")):+ """Validate + fingerprint locally, and flag duplicates vs the existing corpus — no upload."""+ cfg = load_config()+ source = source or cfg.source or "unknown"+ index = registry.fetch_index(cfg)+ n = dups = 0+ for d, errors, warnings, meta in _iter(path, source):+ n += 1+ if errors:+ typer.secho(f"✗ {d.name}: {'; '.join(errors)}", fg="red")+ continue+ meta["dedup"] = project_hashes(d, meta)+ hits = registry.dedup_matches(meta, index)+ if hits:+ dups += 1+ for ex, why in hits:+ typer.secho(f"⚠ {d.name}: {why} as {ex}", fg="yellow")+ else:+ tail = f" ⚠ {'; '.join(warnings)}" if warnings else ""+ typer.secho(f"✓ {d.name}: unique{tail}", fg="green")+ typer.echo(f"\nchecked {n} · {dups} with potential duplicates · index size {len(index)}")+++def anomalies(path: Path = typer.Argument(..., exists=True),+ source: str = typer.Option(None, help="source name (defaults to config)")):+ """Distribution-based outlier scan — flag projects whose code length / char count is an outlier."""+ source = source or load_config().source or "unknown"+ rows = []+ for d, errors, _, meta in _iter(path, source):+ if errors or not meta:+ continue+ chars = len((d / meta["code"]["file"]).read_text(errors="replace"))+ rows.append((d.name, meta["code"]["lines"], chars))+ if len(rows) < 4:+ typer.echo(f"need >= 4 valid projects for a distribution (got {len(rows)})")+ return++ def bounds(vals: list[int]) -> tuple[float, float]:+ s = sorted(vals)+ q1, q3 = s[len(s) // 4], s[(3 * len(s)) // 4]+ iqr = q3 - q1+ return q1 - 1.5 * iqr, q3 + 1.5 * iqr++ lo_l, hi_l = bounds([r[1] for r in rows])+ lo_c, hi_c = bounds([r[2] for r in rows])+ flagged = 0+ for name, lines, chars in rows:+ why = []+ if lines < lo_l or lines > hi_l:+ why.append(f"lines={lines} (typical {int(max(0, lo_l))}–{int(hi_l)})")+ if chars < lo_c or chars > hi_c:+ why.append(f"chars={chars} (typical {int(max(0, lo_c))}–{int(hi_c)})")+ if why:+ flagged += 1+ typer.secho(f"⚠ {name}: {'; '.join(why)}", fg="yellow")+ typer.echo(f"\nscanned {len(rows)} · {flagged} length/char outliers")++[email protected]("exec")+def exec_run(path: Path = typer.Argument(..., exists=True),+ source: str = typer.Option(None, help="source name (defaults to config)"),+ dialect: str = typer.Option(None, help="override code dialect (e.g. cadquery)"),+ write: bool = typer.Option(True, help="write the result into each meta.json")):+ """Run each project's code in its dialect runtime(s); record pass/fail in meta.json.++ Runs LOCALLY in your own runtimes (configure Blender via `3dcode config set+ --blender-5-0 ... --blender-5-1 ...`); nothing is uploaded. Pass = error-free AND a non-empty mesh.+ """+ from .dialects import run_dialect+ cfg = load_config()+ source = source or cfg.source or "unknown"+ npass = nfail = 0+ for d, errors, _, meta in _iter(path, source):+ if errors:+ typer.secho(f"✗ {d.name}: {'; '.join(errors)}", fg="red")+ continue+ merge_preserved(d, meta) # don't clobber license / provenance+ if dialect:+ meta["dialect"] = dialect+ res = run_dialect(meta["dialect"], d, meta, cfg)+ meta["exec"] = res+ if write:+ (d / META_NAME).write_text(json.dumps(meta, indent=2, ensure_ascii=False))+ parts, passed = [], True+ for rt, r in res.items():+ st = r.get("status")+ extra = ""+ if st == "ok":+ if r.get("verts"):+ extra = f"({r['verts']}v)"+ elif r.get("volume") is not None:+ extra = f"(vol {r['volume']})"+ parts.append(f"{rt}={st}{extra}")+ if st not in ("ok", "n/a", "unsupported"):+ passed = False+ typer.secho(f"{'✓' if passed else '✗'} {d.name}: {' '.join(parts)}",+ fg="green" if passed else "red")+ npass += passed+ nfail += not passed+ typer.echo(f"\nexec: {npass} passed · {nfail} failed")+++def push(path: Path = typer.Argument(..., exists=True),+ source: str = typer.Option(None, help="source name (defaults to config)"),+ owner: str = typer.Option(None, help="who is responsible for this data"),+ dialect: str = typer.Option(None, help="override code dialect"),+ dry_run: bool = typer.Option(False, "--dry-run", help="validate + hash, do not upload"),+ no_dedup: bool = typer.Option(False, "--no-dedup", help="skip the duplicate check"),+ no_register: bool = typer.Option(False, "--no-register", help="upload but don't register in the registry")):+ """Validate -> hash -> dedup-check -> write meta.json -> upload to R2 -> register."""+ cfg = load_config()+ source = source or cfg.source+ if not source:+ typer.secho("no --source and no default source in config", fg="red", err=True)+ raise typer.Exit(1)+ contributor = owner or source++ r2 = None+ if not dry_run:+ from .storage import R2 # imported lazily so validate/dry-run need no creds+ r2 = R2(cfg)+ index = [] if no_dedup else registry.fetch_index(cfg)++ up = skip = warn = dup = 0+ for d, errors, warnings, meta in _iter(path, source):+ if errors:+ skip += 1+ typer.secho(f"✗ {d.name}: {'; '.join(errors)} — skipped", fg="red")+ continue+ if dialect:+ meta["dialect"] = dialect+ merge_preserved(d, meta) # keep exec / license / provenance from disk+ meta["owner"] = owner or meta.get("owner", "")+ meta["contributor"] = contributor+ meta["dedup"] = project_hashes(d, meta)+ matches = registry.dedup_matches(meta, index)+ # validation report — travels with the project so the admin Inbox can review it+ meta["report"] = {+ "warnings": warnings,+ "duplicates": [{"of": ex, "why": why} for ex, why in matches],+ "exec": meta.get("exec"),+ "files": sorted(p.relative_to(d).as_posix() for p in d.rglob("*") if p.is_file()),+ }+ (d / META_NAME).write_text(json.dumps(meta, indent=2, ensure_ascii=False))++ for ex, why in matches:+ dup += 1+ typer.secho(f"⚠ {d.name}: {why} as {ex}", fg="yellow")+ if warnings:+ warn += 1+ typer.secho(f"⚠ {d.name}: {'; '.join(warnings)}", fg="yellow")+ if dry_run:+ up += 1+ typer.echo(f" (dry-run) {meta['id']} ready — {len(meta['dedup'])} fingerprints")+ continue+ result = r2.upload_tree(d, f"{source}/{d.name}")+ up += 1+ typer.secho(f"↑ {meta['id']} ({result.files} files, {result.bytes/1e6:.1f} MB)", fg="green")+ if not no_register:+ resp = registry.register(cfg, meta)+ if resp.get("error"):+ typer.secho(f" ! registry: {resp['error']}", fg="red")++ typer.echo(f"\n{'validated' if dry_run else 'uploaded'}: {up} · dup-flagged: {dup} · warn: {warn} · skipped: {skip}")+++def render(path: Path = typer.Argument(..., exists=True),+ source: str = typer.Option(None, help="source name (defaults to config)"),+ dialect: str = typer.Option(None, help="override code dialect (e.g. cadquery)"),+ mode: str = typer.Option("white", help="white | textured")):+ """Render each project's code LOCALLY into renders/ (white clay or textured) — no upload.++ Runs the code in your local Blender (config --blender-5-0) and writes view_00..03.png ++ thumb.png. Then `3dcode push` picks up the renders (modality + phash dedup + Inbox preview).+ """+ from .dialects import render_dialect+ cfg = load_config()+ source = source or cfg.source or "unknown"+ n = fail = 0+ for d, errors, _, meta in _iter(path, source):+ if errors:+ typer.secho(f"✗ {d.name}: {'; '.join(errors)}", fg="red"); continue+ if dialect:+ meta["dialect"] = dialect+ res = render_dialect(meta["dialect"], d, meta, cfg, mode)+ st = res.get("status")+ if st == "ok":+ n += 1+ typer.secho(f"🖼 {d.name}: {len(res.get('images', []))} views → renders/", fg="green")+ else:+ fail += 1+ typer.secho(f"✗ {d.name}: {st}" + (f" — {res['error']}" if res.get("error") else ""), fg="red")+ typer.echo(f"\nrendered: {n} · failed: {fail}")+++def grid(path: Path = typer.Argument(..., exists=True),+ out: Path = typer.Option(None, help="output PNG (default <dir>/_grid.png)"),+ cols: int = typer.Option(6, help="columns")):+ """Compose a contact-sheet PNG of a source's project thumbnails (quick visual review)."""+ from .grid import make_grid+ projects = find_projects(path)+ if not projects:+ typer.secho(f"no projects under {path}", fg="red", err=True)+ raise typer.Exit(1)+ dest = out or (path / "_grid.png")+ try:+ n = make_grid(projects, dest, cols=cols)+ except ImportError:+ typer.secho("grid needs Pillow — install 3dcode[dedup]", fg="red", err=True)+ raise typer.Exit(1)+ if n == 0:+ typer.secho("no thumbnails found — run `3dcode render` first?", fg="yellow")+ else:+ typer.secho(f"grid: {n} thumbnails → {dest}", fg="green")+++def ingest(project_id: str = typer.Argument(None, help="<source>/<project> to ingest (or use --all-approved)"),+ all_approved: bool = typer.Option(False, "--all-approved", help="ingest every approved project"),+ keep_staging: bool = typer.Option(False, "--keep-staging", help="don't delete from R2 after pulling")):+ """ADMIN (lab-side): pull approved projects R2 → core dir, mark ingested, clear staging."""+ cfg = load_config()+ from .storage import R2+ r2 = R2(cfg)+ core = Path(cfg.core_dir)++ if all_approved:+ ids = [a["id"] for a in registry.fetch_approved(cfg)]+ elif project_id:+ ids = [project_id]+ else:+ typer.secho("give a <source>/<project> or --all-approved", fg="red", err=True)+ raise typer.Exit(1)+ if not ids:+ typer.echo("nothing approved to ingest")+ return++ done = fail = 0+ for pid in ids:+ try:+ dest = core / pid # core/<source>/<project>+ res = r2.download_tree(pid, dest)+ if res.files == 0:+ typer.secho(f"✗ {pid}: nothing in staging", fg="red"); fail += 1; continue+ meta_path = dest / META_NAME+ if meta_path.exists():+ meta = json.loads(meta_path.read_text())+ else:+ src, _, proj = pid.partition("/")+ meta = {"id": pid, "source": src, "project": proj}+ meta["status"] = "ingested"+ resp = registry.register(cfg, meta)+ if resp.get("error"):+ typer.secho(f" ! mark-ingested: {resp['error']}", fg="yellow")+ if not keep_staging:+ r2.delete_prefix(pid.rstrip("/") + "/")+ typer.secho(f"↓ {pid} ({res.files} files, {res.bytes / 1e6:.1f} MB) → {dest}", fg="green")+ done += 1+ except Exception as e:+ typer.secho(f"✗ {pid}: {e}", fg="red"); fail += 1+ typer.echo(f"\ningested: {done} · failed: {fail}")+++if __name__ == "__main__":+ app()diff --git a/toolkits/3dcode_cli/threedcode/config.py b/toolkits/3dcode_cli/threedcode/config.pynew file mode 100644index 00000000..f2cf0f53--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/config.py@@ -0,0 +1,84 @@+"""Config: R2 endpoint + bucket + scoped token + default source.++Resolution order (first hit wins): environment variables, then+``~/.config/3dcode/config.toml``. Secrets live ONLY here / in env — never in the repo.+"""++from __future__ import annotations++import os+from dataclasses import dataclass+from pathlib import Path++try:+ import tomllib # Python 3.11++except ModuleNotFoundError: # 3.10+ import tomli as tomllib # type: ignore++CONFIG_PATH = Path(os.path.expanduser("~/.config/3dcode/config.toml"))++# config key -> environment variable that overrides it+_ENV = {+ "endpoint": "R2_ENDPOINT",+ "bucket": "R2_BUCKET",+ "access_key_id": "R2_ACCESS_KEY_ID",+ "secret_access_key": "R2_SECRET_ACCESS_KEY",+ "source": "DCODE_SOURCE",+ "api": "CV_API",+ "contrib_token": "CV_CONTRIB_TOKEN",+ "blender_5_0": "BLENDER_5_0",+ "blender_5_1": "BLENDER_5_1",+ "openscad": "OPENSCAD",+ "freecadcmd": "FREECADCMD",+ "core_dir": "DCODE_CORE_DIR",+}+++@dataclass+class Config:+ endpoint: str = ""+ bucket: str = "3dcodeverse"+ access_key_id: str = ""+ secret_access_key: str = ""+ source: str = ""+ api: str = "https://www.3dcodebench.com" # registry + dedup-index endpoints+ contrib_token: str = "" # shared contributor token for those endpoints+ blender_5_0: str = "" # local Blender 5.0 binary, for `3dcode exec`+ blender_5_1: str = "" # local Blender 5.1 binary+ openscad: str = "" # local OpenSCAD binary/AppImage (.scad exec/render)+ freecadcmd: str = "" # local freecadcmd binary (FreeCAD exec/render)+ core_dir: str = "/lab/yipeng/infinigen/3dcodeverse" # admin-side canonical store (for `3dcode ingest`)++ def require_r2(self) -> None:+ missing = [k for k in ("endpoint", "bucket", "access_key_id", "secret_access_key")+ if not getattr(self, k)]+ if missing:+ raise SystemExit(+ f"R2 not configured (missing {', '.join(missing)}). "+ f"Run `3dcode config set ...` or set the R2_* env vars."+ )+++def _file_values() -> dict:+ if not CONFIG_PATH.exists():+ return {}+ with open(CONFIG_PATH, "rb") as fh:+ return tomllib.load(fh)+++def load_config() -> Config:+ raw = _file_values()+ # only pass non-empty values so dataclass defaults (e.g. `api`) survive+ vals = {k: (os.environ.get(env) or raw.get(k, "")) for k, env in _ENV.items()}+ return Config(**{k: v for k, v in vals.items() if v})+++def save_config(updates: dict) -> Path:+ """Merge ``updates`` into the on-disk config (creating it if needed)."""+ raw = _file_values()+ raw.update({k: v for k, v in updates.items() if v is not None})+ CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)+ lines = [f'{k} = "{v}"' for k, v in raw.items()]+ CONFIG_PATH.write_text("\n".join(lines) + "\n")+ CONFIG_PATH.chmod(0o600) # secret key inside — keep it private+ return CONFIG_PATHdiff --git a/toolkits/3dcode_cli/threedcode/dialects/__init__.py b/toolkits/3dcode_cli/threedcode/dialects/__init__.pynew file mode 100644index 00000000..f08ca5b7--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/dialects/__init__.py@@ -0,0 +1,45 @@+"""Per-dialect executability runners. Each 3D-code type plugs in how to RUN a project's+code in its runtime(s) and report pass/fail. Runs on the CONTRIBUTOR's machine, in the+contributor's own runtimes — never sends data anywhere.+"""++from __future__ import annotations++from pathlib import Path++from ..config import Config+from . import blender_python, build123d_dialect, cadquery_dialect, freecad_dialect, openscad_dialect+++def run_dialect(dialect: str, project_dir: Path, meta: dict, cfg: Config) -> dict:+ """Execute the project in its runtime(s); return {runtime: {status, ...}}."""+ code_file = project_dir / meta["code"]["file"]+ if dialect == "blender_python":+ return blender_python.run(code_file, {"5.0": cfg.blender_5_0, "5.1": cfg.blender_5_1})+ if dialect == "cadquery":+ return {"cadquery": cadquery_dialect.run(code_file)}+ if dialect == "build123d":+ return {"build123d": build123d_dialect.run(code_file)}+ if dialect == "openscad":+ return {"openscad": openscad_dialect.run(code_file, cfg.openscad)}+ if dialect == "freecad":+ return {"freecad": freecad_dialect.run(code_file, cfg.freecadcmd)}+ return {"runtime": {"status": "unsupported", "error": f"no exec runner for dialect '{dialect}'"}}+++def render_dialect(dialect: str, project_dir: Path, meta: dict, cfg: Config, mode: str) -> dict:+ """Render the project's code into project_dir/renders/. mode = white|textured."""+ code_file = project_dir / meta["code"]["file"]+ blender = cfg.blender_5_0 or cfg.blender_5_1+ rdir = project_dir / "renders"+ if dialect == "blender_python":+ return blender_python.render(code_file, rdir, blender, mode)+ if dialect == "cadquery":+ return cadquery_dialect.render(code_file, rdir, blender, mode)+ if dialect == "build123d":+ return build123d_dialect.render(code_file, rdir, blender, mode)+ if dialect == "openscad":+ return openscad_dialect.render(code_file, rdir, blender, mode, cfg.openscad)+ if dialect == "freecad":+ return freecad_dialect.render(code_file, rdir, blender, mode, cfg.freecadcmd)+ return {"status": "unsupported", "error": f"no render runner for dialect '{dialect}'"}diff --git a/toolkits/3dcode_cli/threedcode/dialects/blender_python.py b/toolkits/3dcode_cli/threedcode/dialects/blender_python.pynew file mode 100644index 00000000..996aed83--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/dialects/blender_python.py@@ -0,0 +1,66 @@+"""Blender-Python executability: run the project's code headless in each configured+Blender version and report {status, verts}. Pass = ran error-free AND produced a non-empty+mesh. Missing/unconfigured Blender binaries are reported as `n/a` (skipped, not failed).+"""++from __future__ import annotations++import json+import subprocess+import tempfile+from pathlib import Path++WRAPPER = Path(__file__).resolve().parent.parent / "runners" / "blender_exec.py"+RENDER_WRAPPER = Path(__file__).resolve().parent.parent / "runners" / "blender_render.py"+TIMEOUT = 600 # seconds per run+++def _run_one(blender_bin: str, code_file: Path) -> dict:+ if not blender_bin or not Path(blender_bin).exists():+ return {"status": "n/a"}+ tf = tempfile.NamedTemporaryFile("r", suffix=".json", delete=False)+ out = tf.name+ tf.close()+ try:+ proc = subprocess.run(+ [blender_bin, "--background", "--factory-startup", "--python", str(WRAPPER),+ "--", str(code_file), out],+ capture_output=True, timeout=TIMEOUT,+ )+ with open(out) as fh:+ return json.load(fh)+ except subprocess.TimeoutExpired:+ return {"status": "timeout"}+ except Exception as e: # wrapper didn't write output (e.g. blender crashed)+ tail = (proc.stderr.decode(errors="replace").strip().splitlines()[-1:] if "proc" in dir() else [])+ return {"status": "error", "error": (tail[0] if tail else str(e))[:300]}+ finally:+ Path(out).unlink(missing_ok=True)+++def run(code_file: Path, blender_bins: dict[str, str]) -> dict:+ return {f"blender_{ver}": _run_one(bin_, code_file) for ver, bin_ in blender_bins.items()}+++def render(code_file: Path, renders_dir: Path, blender_bin: str, mode: str) -> dict:+ """Run the code in Blender and render turntable views into renders_dir."""+ if not blender_bin or not Path(blender_bin).exists():+ return {"status": "n/a"}+ tf = tempfile.NamedTemporaryFile("r", suffix=".json", delete=False)+ out = tf.name+ tf.close()+ try:+ proc = subprocess.run(+ [blender_bin, "--background", "--factory-startup", "--python", str(RENDER_WRAPPER),+ "--", str(code_file), str(renders_dir), mode, out],+ capture_output=True, timeout=900,+ )+ with open(out) as fh:+ return json.load(fh)+ except subprocess.TimeoutExpired:+ return {"status": "timeout"}+ except Exception as e:+ tail = proc.stderr.decode(errors="replace").strip().splitlines()[-1:] if "proc" in dir() else []+ return {"status": "error", "error": (tail[0] if tail else str(e))[:300]}+ finally:+ Path(out).unlink(missing_ok=True)diff --git a/toolkits/3dcode_cli/threedcode/dialects/build123d_dialect.py b/toolkits/3dcode_cli/threedcode/dialects/build123d_dialect.pynew file mode 100644index 00000000..2e01ebe5--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/dialects/build123d_dialect.py@@ -0,0 +1,93 @@+"""build123d dialect runners. exec = run the script + verify a non-empty solid; render =+export STL → clay-render in Blender. build123d is an optional dep (`3dcode[build123d]`).+Same OCC kernel as CadQuery — mirrors cadquery_dialect.py."""++from __future__ import annotations++import json+import subprocess+import tempfile+import traceback+from pathlib import Path++MESH_WRAPPER = Path(__file__).resolve().parent.parent / "runners" / "blender_render_mesh.py"+NO_SOLID = "no solid with positive volume"+++def _build(code_file: Path):+ """Run the build123d script; return (shape_with_volume | None, error | None)."""+ import build123d as bd+ captured: list = []+ g = {"__name__": "__main__",+ "show_object": lambda o, *a, **k: captured.append(o),+ "show": lambda o, *a, **k: captured.append(o)}+ try:+ exec(compile(code_file.read_text(), str(code_file), "exec"), g)+ except Exception:+ tb = traceback.format_exc().strip().splitlines()+ return None, (tb[-1] if tb else "error")[:300]+ # candidates: show()/show_object() args, common result globals, then any build123d shape+ objs = list(captured)+ for name in ("result", "part", "obj"):+ if name in g:+ objs.insert(0, g[name])+ shape_types = tuple(t for t in (getattr(bd, n, None) for n in+ ("BuildPart", "Part", "Solid", "Compound", "Shape")) if isinstance(t, type))+ objs += [v for v in g.values() if isinstance(v, shape_types)]+ for o in objs:+ try:+ shape = o.part if hasattr(o, "part") else o # BuildPart → its .part+ vol = getattr(shape, "volume", None)+ if vol and vol > 1e-9:+ return shape, None+ except Exception:+ continue+ return None, NO_SOLID+++def run(code_file: Path) -> dict:+ try:+ import build123d # noqa+ except ImportError:+ return {"status": "n/a", "error": "build123d not installed"}+ shape, err = _build(code_file)+ if shape is None:+ return {"status": "no_geometry" if err == NO_SOLID else "error", "error": err or ""}+ try:+ return {"status": "ok", "volume": round(shape.volume, 3)}+ except Exception:+ return {"status": "ok"}+++def render(code_file: Path, renders_dir: Path, blender_bin: str, mode: str) -> dict:+ try:+ import build123d as bd+ except ImportError:+ return {"status": "n/a", "error": "build123d not installed"}+ if not blender_bin or not Path(blender_bin).exists():+ return {"status": "n/a", "error": "no blender configured for mesh render"}+ shape, err = _build(code_file)+ if shape is None:+ return {"status": "no_geometry" if err == NO_SOLID else "error", "error": err or ""}+ renders_dir.mkdir(parents=True, exist_ok=True)+ stl = renders_dir.parent / "_b123d_export.stl"+ try:+ diag = getattr(shape.bounding_box(), "diagonal", 0) or 10.0+ bd.export_stl(shape, str(stl), tolerance=max(diag * 0.002, 1e-3), angular_tolerance=0.2)+ except Exception as e:+ return {"status": "error", "error": f"stl export failed: {str(e)[:200]}"}+ tf = tempfile.NamedTemporaryFile("r", suffix=".json", delete=False)+ out = tf.name+ tf.close()+ try:+ subprocess.run([blender_bin, "--background", "--factory-startup", "--python", str(MESH_WRAPPER),+ "--", str(stl), str(renders_dir), mode, out], capture_output=True, timeout=600)+ with open(out) as fh:+ return json.load(fh)+ except subprocess.TimeoutExpired:+ return {"status": "timeout"}+ except Exception as e:+ return {"status": "error", "error": str(e)[:200]}+ finally:+ Path(out).unlink(missing_ok=True)+ stl.unlink(missing_ok=True)diff --git a/toolkits/3dcode_cli/threedcode/dialects/cadquery_dialect.py b/toolkits/3dcode_cli/threedcode/dialects/cadquery_dialect.pynew file mode 100644index 00000000..b45fc929--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/dialects/cadquery_dialect.py@@ -0,0 +1,87 @@+"""CadQuery dialect runners. exec = run the script and verify it builds a non-empty+solid; render = export the solid to STL, then clay-render it in Blender (CadQuery has+no native image renderer). cadquery is an optional dep (`3dcode[cadquery]`)."""++from __future__ import annotations++import json+import subprocess+import tempfile+import traceback+from pathlib import Path++MESH_WRAPPER = Path(__file__).resolve().parent.parent / "runners" / "blender_render_mesh.py"+NO_SOLID = "no solid with positive volume"+++def _build(code_file: Path):+ """Run the CadQuery script; return (Workplane | None, error_str | None)."""+ import cadquery as cq+ captured: list = []+ g = {"__name__": "__main__", "show_object": lambda o, *a, **k: captured.append(o)}+ try:+ exec(compile(code_file.read_text(), str(code_file), "exec"), g)+ except Exception:+ tb = traceback.format_exc().strip().splitlines()+ return None, (tb[-1] if tb else "error")[:300]+ # candidates: show_object() args, a `result` global, then any Workplane+ objs = list(captured)+ if "result" in g:+ objs.insert(0, g["result"])+ objs += [v for v in g.values() if isinstance(v, cq.Workplane)]+ for o in objs:+ try:+ wp = o if isinstance(o, cq.Workplane) else (cq.Workplane(obj=o) if isinstance(o, cq.Shape) else None)+ if wp is not None and wp.val().Volume() > 1e-9:+ return wp, None+ except Exception:+ continue+ return None, NO_SOLID+++def run(code_file: Path) -> dict:+ try:+ import cadquery # noqa+ except ImportError:+ return {"status": "n/a", "error": "cadquery not installed"}+ wp, err = _build(code_file)+ if wp is None:+ return {"status": "no_geometry" if err == NO_SOLID else "error", "error": err or ""}+ try:+ return {"status": "ok", "volume": round(wp.val().Volume(), 3)}+ except Exception:+ return {"status": "ok"}+++def render(code_file: Path, renders_dir: Path, blender_bin: str, mode: str) -> dict:+ try:+ import cadquery as cq+ except ImportError:+ return {"status": "n/a", "error": "cadquery not installed"}+ if not blender_bin or not Path(blender_bin).exists():+ return {"status": "n/a", "error": "no blender configured for mesh render"}+ wp, err = _build(code_file)+ if wp is None:+ return {"status": "no_geometry" if err == NO_SOLID else "error", "error": err or ""}+ renders_dir.mkdir(parents=True, exist_ok=True)+ stl = renders_dir.parent / "_cq_export.stl"+ try:+ diag = getattr(wp.val().BoundingBox(), "DiagonalLength", 0) or 10.0+ cq.exporters.export(wp, str(stl), tolerance=max(diag * 0.002, 1e-3), angularTolerance=0.2)+ except Exception as e:+ return {"status": "error", "error": f"stl export failed: {str(e)[:200]}"}+ tf = tempfile.NamedTemporaryFile("r", suffix=".json", delete=False)+ out = tf.name+ tf.close()+ try:+ subprocess.run([blender_bin, "--background", "--factory-startup", "--python", str(MESH_WRAPPER),+ "--", str(stl), str(renders_dir), mode, out], capture_output=True, timeout=600)+ with open(out) as fh:+ return json.load(fh)+ except subprocess.TimeoutExpired:+ return {"status": "timeout"}+ except Exception as e:+ return {"status": "error", "error": str(e)[:200]}+ finally:+ Path(out).unlink(missing_ok=True)+ stl.unlink(missing_ok=True)diff --git a/toolkits/3dcode_cli/threedcode/dialects/freecad_dialect.py b/toolkits/3dcode_cli/threedcode/dialects/freecad_dialect.pynew file mode 100644index 00000000..c89d889e--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/dialects/freecad_dialect.py@@ -0,0 +1,75 @@+"""FreeCAD dialect runners. exec/render run the user script inside freecadcmd (via+runners/freecad_exec.py): exec checks for a non-empty solid; render tessellates the+largest shape to STL → clay-render in Blender. Needs freecadcmd (config `freecadcmd`)."""++from __future__ import annotations++import json+import os+import subprocess+import tempfile+from pathlib import Path++FREECAD_WRAPPER = Path(__file__).resolve().parent.parent / "runners" / "freecad_exec.py"+MESH_WRAPPER = Path(__file__).resolve().parent.parent / "runners" / "blender_render_mesh.py"+++def _run_freecad(code_file: Path, freecadcmd_bin: str, stl_out: str = ""):+ tf = tempfile.NamedTemporaryFile("r", suffix=".json", delete=False)+ out = tf.name+ tf.close()+ # args go via env: freecadcmd treats every positional arg as another script to run+ env = dict(os.environ, FC_CODE=str(code_file), FC_OUT=out, FC_STL=str(stl_out or ""))+ try:+ subprocess.run([str(freecadcmd_bin), str(FREECAD_WRAPPER)],+ capture_output=True, timeout=600, env=env)+ with open(out) as fh:+ return json.load(fh), None+ except subprocess.TimeoutExpired:+ return None, "timeout"+ except Exception as e:+ return None, str(e)[:200]+ finally:+ Path(out).unlink(missing_ok=True)+++def run(code_file: Path, freecadcmd_bin: str) -> dict:+ if not freecadcmd_bin or not Path(str(freecadcmd_bin)).exists():+ return {"status": "n/a", "error": "freecadcmd not configured"}+ res, err = _run_freecad(code_file, freecadcmd_bin)+ if err:+ return {"status": "error", "error": err}+ out = {"status": res.get("status", "error")}+ if res.get("volume"):+ out["volume"] = res["volume"]+ if res.get("error"):+ out["error"] = res["error"]+ return out+++def render(code_file: Path, renders_dir: Path, blender_bin: str, mode: str, freecadcmd_bin: str) -> dict:+ if not freecadcmd_bin or not Path(str(freecadcmd_bin)).exists():+ return {"status": "n/a", "error": "freecadcmd not configured"}+ if not blender_bin or not Path(blender_bin).exists():+ return {"status": "n/a", "error": "no blender configured for mesh render"}+ renders_dir.mkdir(parents=True, exist_ok=True)+ stl = renders_dir.parent / "_fc_export.stl"+ res, err = _run_freecad(code_file, freecadcmd_bin, stl)+ if err:+ return {"status": "error", "error": err}+ if res.get("status") != "ok" or not stl.exists():+ return {"status": res.get("status", "no_geometry"),+ "error": res.get("error", res.get("stl_error", ""))}+ tf = tempfile.NamedTemporaryFile("r", suffix=".json", delete=False)+ out = tf.name+ tf.close()+ try:+ subprocess.run([blender_bin, "--background", "--factory-startup", "--python", str(MESH_WRAPPER),+ "--", str(stl), str(renders_dir), mode, out], capture_output=True, timeout=600)+ with open(out) as fh:+ return json.load(fh)+ except Exception as e:+ return {"status": "error", "error": str(e)[:200]}+ finally:+ Path(out).unlink(missing_ok=True)+ stl.unlink(missing_ok=True)diff --git a/toolkits/3dcode_cli/threedcode/dialects/openscad_dialect.py b/toolkits/3dcode_cli/threedcode/dialects/openscad_dialect.pynew file mode 100644index 00000000..2829a1f0--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/dialects/openscad_dialect.py@@ -0,0 +1,85 @@+"""OpenSCAD dialect runners. exec = compile the .scad to STL (must be non-empty); render =+STL → clay-render in Blender. Needs the openscad binary/AppImage (config `openscad`)."""++from __future__ import annotations++import json+import struct+import subprocess+import tempfile+from pathlib import Path++MESH_WRAPPER = Path(__file__).resolve().parent.parent / "runners" / "blender_render_mesh.py"+++def _wrap(openscad_bin: str) -> list:+ # AppImages run via extract-and-run on hosts without FUSE auto-mount+ b = str(openscad_bin)+ return [b, "--appimage-extract-and-run"] if b.lower().endswith(".appimage") else [b]+++def _stl_tris(stl_path: Path) -> int:+ data = stl_path.read_bytes()+ if data[:5] == b"solid" and b"facet" in data[:2000]: # ASCII STL+ return data.count(b"facet normal")+ if len(data) >= 84: # binary STL: count at offset 80+ return struct.unpack("<I", data[80:84])[0]+ return 0+++def _compile_stl(code_file: Path, openscad_bin: str, stl_path: Path):+ """openscad -o out.stl <scad>; return (triangle_count, error). Retries headless via xvfb."""+ base = _wrap(openscad_bin) + ["-o", str(stl_path), str(code_file)]+ for cmd in (base, ["xvfb-run", "-a"] + base):+ try:+ p = subprocess.run(cmd, capture_output=True, text=True, timeout=600)+ except FileNotFoundError:+ continue # no xvfb-run → skip retry+ except subprocess.TimeoutExpired:+ return 0, "timeout"+ if p.returncode == 0 and stl_path.exists():+ return _stl_tris(stl_path), None+ err = (p.stderr or p.stdout or "openscad failed").strip().splitlines()+ last = (err[-1] if err else "openscad failed")[:300]+ if "DISPLAY" not in (p.stderr or "") and "display" not in (p.stderr or "").lower():+ return 0, last # not a display issue → real error+ return 0, last+++def run(code_file: Path, openscad_bin: str) -> dict:+ if not openscad_bin or not Path(str(openscad_bin)).exists():+ return {"status": "n/a", "error": "openscad not configured"}+ with tempfile.TemporaryDirectory() as td:+ stl = Path(td) / "out.stl"+ tris, err = _compile_stl(code_file, openscad_bin, stl)+ if err:+ return {"status": "error", "error": err}+ if tris == 0:+ return {"status": "no_geometry", "error": "empty STL (0 triangles)"}+ return {"status": "ok", "triangles": tris}+++def render(code_file: Path, renders_dir: Path, blender_bin: str, mode: str, openscad_bin: str) -> dict:+ if not openscad_bin or not Path(str(openscad_bin)).exists():+ return {"status": "n/a", "error": "openscad not configured"}+ if not blender_bin or not Path(blender_bin).exists():+ return {"status": "n/a", "error": "no blender configured for mesh render"}+ renders_dir.mkdir(parents=True, exist_ok=True)+ stl = renders_dir.parent / "_scad_export.stl"+ tris, err = _compile_stl(code_file, openscad_bin, stl)+ if err or tris == 0:+ stl.unlink(missing_ok=True)+ return {"status": "error" if err else "no_geometry", "error": err or ""}+ tf = tempfile.NamedTemporaryFile("r", suffix=".json", delete=False)+ out = tf.name+ tf.close()+ try:+ subprocess.run([blender_bin, "--background", "--factory-startup", "--python", str(MESH_WRAPPER),+ "--", str(stl), str(renders_dir), mode, out], capture_output=True, timeout=600)+ with open(out) as fh:+ return json.load(fh)+ except Exception as e:+ return {"status": "error", "error": str(e)[:200]}+ finally:+ Path(out).unlink(missing_ok=True)+ stl.unlink(missing_ok=True)diff --git a/toolkits/3dcode_cli/threedcode/grid.py b/toolkits/3dcode_cli/threedcode/grid.pynew file mode 100644index 00000000..72838b1e--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/grid.py@@ -0,0 +1,53 @@+"""Compose a contact-sheet montage of a source's project thumbnails — a quick visual+overview for review (adapted from data_pipeline_operators/viz_factory.py's grid step).+Pillow only; reuses each project's existing renders."""++from __future__ import annotations++import math+from pathlib import Path++IMG_EXT = (".png", ".webp", ".jpg", ".jpeg")+++def _thumb(project_dir: Path):+ from PIL import Image+ r = project_dir / "renders"+ cands = []+ if r.is_dir():+ cands.append(r / "thumb.png")+ cands += sorted(r.glob("*"))+ cands += sorted(project_dir.glob("*"))+ for c in cands:+ if c.is_file() and c.suffix.lower() in IMG_EXT:+ try:+ return Image.open(c)+ except Exception:+ continue+ return None+++def make_grid(project_dirs, out_path: Path, cols: int = 6, cell: int = 180) -> int:+ """Montage each project's thumbnail into a labelled grid PNG. Returns #cells drawn."""+ from PIL import Image, ImageDraw+ items = [(d.name, t) for d in project_dirs if (t := _thumb(d)) is not None]+ if not items:+ return 0+ pad, lbl = 6, 16+ rows = math.ceil(len(items) / cols)+ W = cols * (cell + pad) + pad+ H = rows * (cell + lbl + pad) + pad+ sheet = Image.new("RGB", (W, H), (245, 245, 247))+ draw = ImageDraw.Draw(sheet)+ for i, (name, img) in enumerate(items):+ r, c = divmod(i, cols)+ x, y = pad + c * (cell + pad), pad + r * (cell + lbl + pad)+ thumb = img.convert("RGBA")+ thumb.thumbnail((cell, cell))+ bg = Image.new("RGBA", (cell, cell), (255, 255, 255, 255))+ bg.alpha_composite(thumb, ((cell - thumb.width) // 2, (cell - thumb.height) // 2))+ sheet.paste(bg.convert("RGB"), (x, y))+ draw.text((x + 2, y + cell + 2), name[:30], fill=(90, 90, 90))+ out_path.parent.mkdir(parents=True, exist_ok=True)+ sheet.save(out_path)+ return len(items)diff --git a/toolkits/3dcode_cli/threedcode/hashing.py b/toolkits/3dcode_cli/threedcode/hashing.pynew file mode 100644index 00000000..290ceaf1--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/hashing.py@@ -0,0 +1,80 @@+"""Dedup fingerprints, computed on the contributor's own machine.++- code_hash : sha256 of normalized code (exact-code duplicates)+- geom_hash : sampled mesh hash of a GLB (geometric duplicates) [needs `[dedup]` extra]+- phash : perceptual hash of a render (visual duplicates) [needs `[dedup]` extra]++geom/phash are best-effort: if the optional deps aren't installed (or no mesh/render is+present) they're simply omitted — the toolkit's base install stays light, no Blender/GPU.+"""++from __future__ import annotations++import hashlib+import re+from pathlib import Path++from .schema import IMAGE_EXTS, MESH_EXTS++_WS = re.compile(r"\s+")+++def code_hash(text: str) -> str:+ """sha256 of code with comments + whitespace normalized, so cosmetic edits collide."""+ no_block = re.sub(r'""".*?"""|\'\'\'.*?\'\'\'', "", text, flags=re.S)+ no_line = "\n".join(ln.split("#", 1)[0] for ln in no_block.splitlines())+ return "sha256:" + hashlib.sha256(_WS.sub(" ", no_line).strip().encode()).hexdigest()+++def geom_hash(glb: Path) -> str | None:+ try:+ import numpy as np+ import trimesh+ except ImportError:+ return None+ try:+ mesh = trimesh.load(str(glb), force="mesh")+ if mesh.is_empty or mesh.vertices.shape[0] == 0:+ return None+ # DETERMINISTIC translate/scale-invariant signature: center, scale-normalize,+ # round, then sort vertex rows (random sampling would hash differently every run).+ v = np.asarray(mesh.vertices, dtype=float)+ v -= v.mean(0)+ scale = float(np.linalg.norm(v, axis=1).max()) or 1.0+ v = np.round(v / scale, 3)+ v = v[np.lexsort(v.T)]+ return "geom:" + hashlib.sha256(v.tobytes()).hexdigest()[:32]+ except Exception:+ return None+++def phash(image: Path) -> str | None:+ try:+ import imagehash+ from PIL import Image+ except ImportError:+ return None+ try:+ return "phash:" + str(imagehash.phash(Image.open(image).convert("RGB")))+ except Exception:+ return None+++def project_hashes(project_dir: Path, meta: dict) -> dict:+ out: dict[str, str] = {}+ code_file = project_dir / meta["code"]["file"]+ if code_file.exists():+ out["code_hash"] = code_hash(code_file.read_text(errors="replace"))++ meshes = sorted(c for c in project_dir.rglob("*") if c.suffix.lower() in MESH_EXTS)+ if meshes:+ gh = geom_hash(meshes[0])+ if gh:+ out["geom_hash"] = gh++ images = sorted(c for c in project_dir.rglob("*") if c.suffix.lower() in IMAGE_EXTS)+ if images:+ ph = phash(images[0])+ if ph:+ out["phash"] = ph+ return outdiff --git a/toolkits/3dcode_cli/threedcode/registry.py b/toolkits/3dcode_cli/threedcode/registry.pynew file mode 100644index 00000000..aa77e3f5--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/registry.py@@ -0,0 +1,69 @@+"""Registry + dedup-index client — talks to the 3dcodebench API (Vercel).++`register` records a pushed project; `fetch_index` pulls the compact hash index so+`check`/`push` can flag duplicates locally. Plain urllib — no extra dependency.+"""++from __future__ import annotations++import json+import urllib.error+import urllib.request++from .config import Config++_UA = "3dcode-toolkit"+++def _req(cfg: Config, path: str, method: str, body: dict | None = None) -> dict:+ headers = {"User-Agent": _UA, "x-cv-token": cfg.contrib_token}+ data = None+ if body is not None:+ headers["Content-Type"] = "application/json"+ data = json.dumps(body, ensure_ascii=False).encode()+ req = urllib.request.Request(cfg.api.rstrip("/") + path, data=data, headers=headers, method=method)+ try:+ with urllib.request.urlopen(req, timeout=30) as r:+ return json.loads(r.read().decode())+ except urllib.error.HTTPError as e:+ return {"error": f"HTTP {e.code}: {e.read().decode()[:200]}"}+ except Exception as e: # network/timeout+ return {"error": str(e)}+++def register(cfg: Config, meta: dict) -> dict:+ return _req(cfg, "/api/data/cv/register", "POST", meta)+++def fetch_index(cfg: Config, source: str | None = None) -> list[dict]:+ path = "/api/data/cv/index" + (f"?source={source}" if source else "")+ return _req(cfg, path, "GET").get("index", [])+++def fetch_approved(cfg: Config) -> list[dict]:+ """Admin-approved projects awaiting ingest: [{id, source, project}]."""+ return _req(cfg, "/api/data/cv/approved", "GET").get("approved", [])+++def _phash_close(a: str, b: str, thresh: int = 6) -> bool:+ try:+ ha, hb = int(a.split(":", 1)[1], 16), int(b.split(":", 1)[1], 16)+ return bin(ha ^ hb).count("1") <= thresh+ except Exception:+ return False+++def dedup_matches(meta: dict, index: list[dict]) -> list[tuple[str, str]]:+ """(existing_id, reason) for each existing project the new one likely duplicates."""+ d = meta.get("dedup", {})+ hits: list[tuple[str, str]] = []+ for row in index:+ if row.get("id") == meta.get("id"):+ continue+ if d.get("code_hash") and row.get("code_hash") == d["code_hash"]:+ hits.append((row["id"], "identical code"))+ elif d.get("geom_hash") and row.get("geom_hash") == d["geom_hash"]:+ hits.append((row["id"], "identical geometry"))+ elif d.get("phash") and row.get("phash") and _phash_close(d["phash"], row["phash"]):+ hits.append((row["id"], "near-identical render"))+ return hitsdiff --git a/toolkits/3dcode_cli/threedcode/runners/__init__.py b/toolkits/3dcode_cli/threedcode/runners/__init__.pynew file mode 100644index 00000000..e69de29bdiff --git a/toolkits/3dcode_cli/threedcode/runners/blender_exec.py b/toolkits/3dcode_cli/threedcode/runners/blender_exec.pynew file mode 100644index 00000000..742a95aa--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/runners/blender_exec.py@@ -0,0 +1,67 @@+"""Run a contributor's Blender-Python project INSIDE Blender and report the outcome.++Logic adapted from infinigen `data_pipeline_operators/validate_blender_scripts.py`.+Invoked as: <blender> --background --factory-startup --python blender_exec.py -- <code.py> <out.json>+Writes {status, error, mesh_objects, verts, faces} to <out.json>. status:+ ok | no_geometry (ran but produced no mesh) | error (raised / non-zero exit).+"""++import json+import runpy+import sys+import traceback++import bpy # noqa: provided by Blender+++def _write(path, result):+ with open(path, "w") as fh:+ json.dump(result, fh)+++def main():+ argv = sys.argv[sys.argv.index("--") + 1:]+ code_path, out_path = argv[0], argv[1]+ result = {"status": "ok", "error": "", "mesh_objects": 0, "verts": 0, "faces": 0, "material_slots": 0}++ # clean slate — robust even to scripts that don't clear the default scene themselves+ bpy.ops.object.select_all(action="SELECT")+ bpy.ops.object.delete()+ for coll in (bpy.data.meshes, bpy.data.curves, bpy.data.node_groups):+ for item in list(coll):+ coll.remove(item)+ bpy.context.scene.cursor.location = (0, 0, 0)++ try:+ saved_argv = sys.argv[:]+ sys.argv = [code_path] # script sees clean argv+ runpy.run_path(code_path, run_name="__main__")+ sys.argv = saved_argv+ except SystemExit as e:+ if e.code not in (None, 0):+ result["status"] = "error"+ result["error"] = f"script called sys.exit({e.code})"+ _write(out_path, result)+ return+ except BaseException:+ tb = traceback.format_exc().strip().splitlines()+ result["status"] = "error"+ result["error"] = (tb[-1] if tb else "unknown")[:300]+ _write(out_path, result)+ return++ bpy.context.view_layer.update()+ meshes = [o for o in bpy.context.scene.objects if o.type == "MESH"]+ result["mesh_objects"] = len(meshes)+ result["verts"] = sum(len(o.data.vertices) for o in meshes if o.data)+ result["faces"] = sum(len(o.data.polygons) for o in meshes if o.data)+ # material slots — a textured submission with geometry but no materials is suspect+ # (essence of data_pipeline_operators/validate_texture_material_slots.py)+ result["material_slots"] = sum(sum(1 for m in o.data.materials if m is not None)+ for o in meshes if o.data)+ if result["verts"] == 0:+ result["status"] = "no_geometry"+ _write(out_path, result)+++main()diff --git a/toolkits/3dcode_cli/threedcode/runners/blender_render.py b/toolkits/3dcode_cli/threedcode/runners/blender_render.pynew file mode 100644index 00000000..b21139fa--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/runners/blender_render.py@@ -0,0 +1,118 @@+"""Run a project's Blender-Python code, then render turntable views into renders/.++Invoked: <blender> --background --factory-startup --python blender_render.py+ -- <code.py> <renders_dir> <mode:white|textured> <result.json>+Writes {status, error, images[]}. white = Workbench studio clay (transparent bg);+textured = EEVEE keeping the script's own materials + 3-point lighting.+Camera/lighting approach adapted from infinigen data_pipeline_operators/renderer.py.+"""++import json+import math+import os+import runpy+import shutil+import sys+import traceback++import bpy # noqa: provided by Blender+from mathutils import Vector # noqa++VIEWS = [("00", 0), ("01", 90), ("02", 180), ("03", 270)] # turntable azimuths+RES = 512+++def _write(p, r):+ with open(p, "w") as fh:+ json.dump(r, fh)+++def main():+ argv = sys.argv[sys.argv.index("--") + 1:]+ code_path, renders_dir, mode, result_path = argv[0], argv[1], argv[2], argv[3]+ result = {"status": "ok", "error": "", "images": []}+ os.makedirs(renders_dir, exist_ok=True)++ bpy.ops.object.select_all(action="SELECT"); bpy.ops.object.delete()+ for coll in (bpy.data.meshes, bpy.data.curves, bpy.data.node_groups):+ for it in list(coll):+ coll.remove(it)++ try:+ sys.argv = [code_path]+ runpy.run_path(code_path, run_name="__main__")+ except BaseException:+ tb = traceback.format_exc().strip().splitlines()+ result["status"] = "error"; result["error"] = (tb[-1] if tb else "unknown")[:300]+ return _write(result_path, result)++ # drop any camera/lights the script added; keep meshes+ for o in list(bpy.data.objects):+ if o.type in ("CAMERA", "LIGHT"):+ bpy.data.objects.remove(o, do_unlink=True)+ meshes = [o for o in bpy.context.scene.objects if o.type == "MESH"]+ if not meshes or sum(len(o.data.vertices) for o in meshes if o.data) == 0:+ result["status"] = "no_geometry"+ return _write(result_path, result)++ mn = Vector((1e9,) * 3); mx = Vector((-1e9,) * 3)+ for o in meshes:+ for c in o.bound_box:+ w = o.matrix_world @ Vector(c)+ mn = Vector(min(mn[i], w[i]) for i in range(3)); mx = Vector(max(mx[i], w[i]) for i in range(3))+ center = (mn + mx) / 2; size = mx - mn; extent = max(size) or 1.0+ dist = extent * 2.2++ scn = bpy.context.scene+ scn.render.resolution_x = scn.render.resolution_y = RES+ scn.render.image_settings.file_format = "PNG"+ scn.render.image_settings.color_mode = "RGBA"+ cam_d = bpy.data.cameras.new("C"); cam = bpy.data.objects.new("C", cam_d)+ scn.collection.objects.link(cam); scn.camera = cam+ cam.data.lens = 50; cam.data.clip_end = extent * 25++ if mode == "white":+ scn.render.engine = "BLENDER_WORKBENCH"+ scn.render.film_transparent = True+ sh = scn.display.shading+ sh.light = "STUDIO"; sh.color_type = "SINGLE"; sh.single_color = (0.92, 0.92, 0.93)+ sh.show_cavity = False; sh.show_shadows = False; sh.show_object_outline = False+ else: # textured: keep the script's materials; neutral white studio (per data_pipeline_operators/renderer_texture.py)+ for eng in ("BLENDER_EEVEE_NEXT", "BLENDER_EEVEE"):+ try:+ scn.render.engine = eng; break+ except Exception:+ continue+ # neutral white world so material colour/roughness reads true-to-shader+ world = bpy.data.worlds.new("w"); scn.world = world; world.use_nodes = True+ nt = world.node_tree; nt.nodes.clear()+ bg = nt.nodes.new("ShaderNodeBackground"); wout = nt.nodes.new("ShaderNodeOutputWorld")+ bg.inputs[0].default_value = (1, 1, 1, 1); bg.inputs[1].default_value = 0.6+ nt.links.new(bg.outputs[0], wout.inputs[0])+ # 3-point area lights; energy scaled by extent^2 keeps illuminance constant across object sizes+ for name, loc, energy in [+ ("Key", (dist * 0.9, -dist * 0.7, dist * 1.5), 1400),+ ("Fill", (-dist * 0.7, -dist * 0.4, dist * 1.0), 500),+ ("Rim", (0.0, dist * 0.9, dist * 1.3), 800),+ ]:+ ld = bpy.data.lights.new(name, "AREA"); ld.energy = energy * (extent ** 2); ld.size = extent+ lo = bpy.data.objects.new(name, ld); scn.collection.objects.link(lo)+ lo.location = center + Vector(loc)++ for tag, deg in VIEWS:+ rad = math.radians(deg)+ bx, by = 0.45, -1.0+ dirv = Vector((bx * math.cos(rad) - by * math.sin(rad),+ bx * math.sin(rad) + by * math.cos(rad), 0.6)).normalized()+ cam.location = center + dirv * dist+ cam.rotation_euler = (center - cam.location).normalized().to_track_quat("-Z", "Y").to_euler()+ scn.render.filepath = os.path.join(renders_dir, f"view_{tag}.png")+ bpy.ops.render.render(write_still=True)+ result["images"].append(f"view_{tag}.png")++ shutil.copy(os.path.join(renders_dir, "view_00.png"), os.path.join(renders_dir, "thumb.png"))+ result["images"].append("thumb.png")+ _write(result_path, result)+++main()diff --git a/toolkits/3dcode_cli/threedcode/runners/blender_render_mesh.py b/toolkits/3dcode_cli/threedcode/runners/blender_render_mesh.pynew file mode 100644index 00000000..d9c38bb1--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/runners/blender_render_mesh.py@@ -0,0 +1,115 @@+"""Render a MESH FILE (glb/gltf/stl) into renders_dir — clay turntable, no code run.++For dialects whose code doesn't execute in Blender (e.g. CadQuery exports a mesh first).+Invoked: <blender> --background --factory-startup --python blender_render_mesh.py+ -- <mesh_path> <renders_dir> <mode:white|textured> <result.json>+"""++import json+import math+import os+import shutil+import sys++import bpy # noqa+from mathutils import Vector # noqa++VIEWS = [("00", 0), ("01", 90), ("02", 180), ("03", 270)]+RES = 512+++def _write(p, r):+ with open(p, "w") as fh:+ json.dump(r, fh)+++def _import(mesh_path):+ ext = os.path.splitext(mesh_path)[1].lower()+ if ext in (".glb", ".gltf"):+ bpy.ops.import_scene.gltf(filepath=mesh_path)+ elif ext == ".stl":+ try:+ bpy.ops.wm.stl_import(filepath=mesh_path) # Blender 4.0++ except AttributeError:+ bpy.ops.import_mesh.stl(filepath=mesh_path) # older+ elif ext == ".obj":+ bpy.ops.wm.obj_import(filepath=mesh_path)+ else:+ raise ValueError(f"unsupported mesh format: {ext}")+++def main():+ argv = sys.argv[sys.argv.index("--") + 1:]+ mesh_path, renders_dir, mode, result_path = argv[0], argv[1], argv[2], argv[3]+ result = {"status": "ok", "error": "", "images": []}+ os.makedirs(renders_dir, exist_ok=True)++ bpy.ops.object.select_all(action="SELECT"); bpy.ops.object.delete()+ try:+ _import(mesh_path)+ except Exception as e:+ result["status"] = "error"; result["error"] = str(e)[:300]+ return _write(result_path, result)++ meshes = [o for o in bpy.context.scene.objects if o.type == "MESH"]+ if not meshes or sum(len(o.data.vertices) for o in meshes if o.data) == 0:+ result["status"] = "no_geometry"+ return _write(result_path, result)++ # auto-smooth: interpolate normals on curved surfaces (no facet ribbing) while keeping+ # sharp feature edges crisp — the right "CAD look" for tessellated B-rep exports.+ bpy.ops.object.select_all(action="DESELECT")+ for o in meshes:+ o.select_set(True)+ bpy.context.view_layer.objects.active = o+ bpy.ops.object.shade_smooth()+ for op in ("shade_auto_smooth", "shade_smooth_by_angle"):+ try:+ getattr(bpy.ops.object, op)(angle=math.radians(35))+ break+ except Exception:+ continue++ mn = Vector((1e9,) * 3); mx = Vector((-1e9,) * 3)+ for o in meshes:+ for c in o.bound_box:+ w = o.matrix_world @ Vector(c)+ mn = Vector(min(mn[i], w[i]) for i in range(3)); mx = Vector(max(mx[i], w[i]) for i in range(3))+ center = (mn + mx) / 2; size = mx - mn; extent = max(size) or 1.0+ dist = extent * 2.2++ scn = bpy.context.scene+ scn.render.resolution_x = scn.render.resolution_y = RES+ scn.render.image_settings.file_format = "PNG"; scn.render.image_settings.color_mode = "RGBA"+ cam_d = bpy.data.cameras.new("C"); cam = bpy.data.objects.new("C", cam_d)+ scn.collection.objects.link(cam); scn.camera = cam+ cam.data.lens = 50; cam.data.clip_end = extent * 25++ scn.render.engine = "BLENDER_WORKBENCH"+ scn.render.film_transparent = True+ sh = scn.display.shading+ sh.light = "STUDIO"; sh.color_type = "SINGLE"; sh.single_color = (0.92, 0.92, 0.93)+ sh.show_shadows = False+ sh.show_cavity = False # cavity ribbons curved tessellation — let auto-smooth carry the shape+ sh.show_object_outline = True # silhouette edge only → subtle CAD-drawing feel, no facet ribbing+ try:+ sh.object_outline_color = (0.15, 0.15, 0.17)+ except Exception:+ pass++ for tag, deg in VIEWS:+ rad = math.radians(deg)+ bx, by = 0.45, -1.0+ dirv = Vector((bx * math.cos(rad) - by * math.sin(rad),+ bx * math.sin(rad) + by * math.cos(rad), 0.6)).normalized()+ cam.location = center + dirv * dist+ cam.rotation_euler = (center - cam.location).normalized().to_track_quat("-Z", "Y").to_euler()+ scn.render.filepath = os.path.join(renders_dir, f"view_{tag}.png")+ bpy.ops.render.render(write_still=True)+ result["images"].append(f"view_{tag}.png")+ shutil.copy(os.path.join(renders_dir, "view_00.png"), os.path.join(renders_dir, "thumb.png"))+ result["images"].append("thumb.png")+ _write(result_path, result)+++main()diff --git a/toolkits/3dcode_cli/threedcode/runners/freecad_exec.py b/toolkits/3dcode_cli/threedcode/runners/freecad_exec.pynew file mode 100644index 00000000..39061e05--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/runners/freecad_exec.py@@ -0,0 +1,71 @@+"""Run a FreeCAD Python project inside freecadcmd and report geometry / export STL.++Invoked: FC_CODE=<user.py> FC_OUT=<out.json> [FC_STL=<stl_out>] freecadcmd freecad_exec.py+(args go via env because freecadcmd treats every positional arg as another script to run).+Writes {status, error, solids, volume} to FC_OUT; if FC_STL is set, tessellates the+largest-volume shape to STL for rendering. status: ok | no_geometry | error.+"""++import json+import os+import traceback+++def main():+ code_path = os.environ["FC_CODE"]+ out_path = os.environ["FC_OUT"]+ stl_out = os.environ.get("FC_STL", "")+ result = {"status": "ok", "error": "", "solids": 0, "volume": 0.0}++ import FreeCAD as App # provided by freecadcmd+ ns = {"__name__": "__main__", "App": App, "FreeCAD": App}+ try:+ import Part+ ns["Part"] = Part+ except Exception:+ pass+ try:+ with open(code_path) as fh:+ exec(compile(fh.read(), code_path, "exec"), ns)+ except BaseException:+ tb = traceback.format_exc().strip().splitlines()+ result["status"] = "error"+ result["error"] = (tb[-1] if tb else "error")[:300]+ json.dump(result, open(out_path, "w"))+ return++ # collect shapes with positive volume across all open documents+ shapes = []+ for doc in App.listDocuments().values():+ for obj in doc.Objects:+ shp = getattr(obj, "Shape", None)+ if shp is None:+ continue+ try:+ v = shp.Volume+ if v and v > 1e-9:+ shapes.append((v, shp))+ except Exception:+ continue+ if not shapes:+ result["status"] = "no_geometry"+ json.dump(result, open(out_path, "w"))+ return++ shapes.sort(key=lambda x: -x[0])+ result["solids"] = len(shapes)+ result["volume"] = round(shapes[0][0], 3)+ if stl_out:+ try:+ import MeshPart+ shp = shapes[0][1]+ diag = getattr(shp.BoundBox, "DiagonalLength", 0) or 10.0+ lin = max(diag * 0.002, 1e-3) # ~0.2% of size → curves stay smooth at any scale+ mesh = MeshPart.meshFromShape(Shape=shp, LinearDeflection=lin, AngularDeflection=0.2)+ mesh.write(stl_out)+ except Exception as e:+ result["stl_error"] = str(e)[:200]+ json.dump(result, open(out_path, "w"))+++main()diff --git a/toolkits/3dcode_cli/threedcode/schema.py b/toolkits/3dcode_cli/threedcode/schema.pynew file mode 100644index 00000000..273660b9--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/schema.py@@ -0,0 +1,134 @@+"""Project layout, meta.json schema, validation, and anomaly checks.++A *project* is one independent asset: its code + reference images / prompt / video /+derived renders+glb + a meta.json. A *source* folder holds many projects.+"""++from __future__ import annotations++import json+from datetime import datetime, timezone+from pathlib import Path++META_NAME = "meta.json"++# fields a fresh build must NOT clobber — carried over from an existing meta.json+PRESERVE = ("exec", "license", "provenance", "title", "owner")+++def merge_preserved(d: Path, meta: dict) -> dict:+ """Carry over user-set / previously-computed fields (exec, license, …) from disk."""+ f = d / META_NAME+ if f.exists():+ try:+ old = json.loads(f.read_text())+ for k in PRESERVE:+ if old.get(k):+ meta[k] = old[k]+ except Exception:+ pass+ return meta++# code dialect by file extension (overridable with --dialect)+DIALECT_BY_EXT = {+ ".py": "blender_python", # default for .py here; pass --dialect cadquery if it's CadQuery+ ".scad": "openscad",+ ".glsl": "shader_glsl", ".frag": "shader_glsl", ".vert": "shader_glsl",+ ".js": "jscad", ".fs": "featurescript",+}+CODE_EXTS = set(DIALECT_BY_EXT)++IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".webp"}+MESH_EXTS = {".glb", ".gltf", ".obj", ".ply", ".stl"}++# anomaly thresholds (warnings, not hard failures)+MAX_CODE_LINES = 5000+MAX_CODE_BYTES = 1_000_000+++def _now() -> str:+ return datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")+++def is_project(d: Path) -> bool:+ """A directory is a project if it has a meta.json or a top-level code file."""+ return (d / META_NAME).exists() or any(+ c.suffix.lower() in CODE_EXTS for c in d.iterdir() if c.is_file()+ )+++def find_projects(root: Path) -> list[Path]:+ """`root` is itself a project, else each immediate project subdir of it."""+ root = root.resolve()+ if is_project(root):+ return [root]+ return [d for d in sorted(root.iterdir()) if d.is_dir() and is_project(d)]+++def _code_file(d: Path) -> Path | None:+ files = [c for c in sorted(d.iterdir()) if c.is_file() and c.suffix.lower() in CODE_EXTS]+ # prefer the textured/full code over a *_geo variant if both exist+ files.sort(key=lambda p: ("_geo" in p.stem, p.name))+ return files[0] if files else None+++def validate_project(d: Path, source: str) -> tuple[list[str], list[str], dict | None]:+ """Return (errors, warnings, meta-or-None). Errors block upload; warnings don't."""+ errors: list[str] = []+ warnings: list[str] = []++ code = _code_file(d)+ if code is None:+ errors.append("no code file (.py/.scad/.glsl/...) found")+ return errors, warnings, None++ text = code.read_text(errors="replace")+ lines = text.count("\n") + 1+ if lines > MAX_CODE_LINES:+ warnings.append(f"code is {lines} lines (> {MAX_CODE_LINES} — possibly degenerate)")+ if len(text) > MAX_CODE_BYTES:+ warnings.append(f"code is {len(text)} bytes (> {MAX_CODE_BYTES})")++ has_ref = any(c.suffix.lower() in IMAGE_EXTS for c in d.rglob("*") if c.is_file())+ has_prompt = (d / "prompt.txt").exists() or (d / "prompt.json").exists()+ if not (has_ref or has_prompt):+ warnings.append("no reference image and no prompt — the (input -> code) pair is ungrounded")++ # structure convention: renders + mesh belong in renders/, not loose at the top level+ top_assets = [c.name for c in d.iterdir()+ if c.is_file() and c.suffix.lower() in (IMAGE_EXTS | MESH_EXTS)]+ if top_assets:+ warnings.append(f"{len(top_assets)} render/mesh file(s) at top level — convention is a renders/ folder")++ meta = build_meta(d, source, code, lines)+ return errors, warnings, meta+++def build_meta(d: Path, source: str, code: Path, lines: int, dialect: str | None = None) -> dict:+ """Construct (or refresh) the project's meta.json body. Hashes filled in later."""+ project = d.name+ dialect = dialect or DIALECT_BY_EXT.get(code.suffix.lower(), "unknown")+ modality = ["code"]+ if any(c.suffix.lower() in IMAGE_EXTS for c in d.rglob("*") if c.is_file()):+ modality.append("reference_images")+ if (d / "prompt.txt").exists() or (d / "prompt.json").exists():+ modality.append("prompt")+ if any(c.suffix.lower() in MESH_EXTS for c in d.rglob("*") if c.is_file()):+ modality.append("glb")+ return {+ "id": f"{source}/{project}",+ "source": source,+ "project": project,+ "title": project,+ "dialect": dialect,+ "modality": modality,+ "code": {"file": code.name, "lines": lines},+ "license": "",+ "provenance": {},+ "owner": "",+ "contributor": "",+ "dedup": {},+ "status": "pending",+ "created_at": _now(),+ "updated_at": _now(),+ }diff --git a/toolkits/3dcode_cli/threedcode/storage.py b/toolkits/3dcode_cli/threedcode/storage.pynew file mode 100644index 00000000..d80512fc--- /dev/null+++ b/toolkits/3dcode_cli/threedcode/storage.py@@ -0,0 +1,88 @@+"""R2 (S3-compatible) object storage — thin boto3 wrapper used by `3dcode`.++Contributors upload straight from their own machine to the staging bucket; the admin+side pulls/lists/deletes the same way. Keys are ``<source>/<project>/<relpath>``.+"""++from __future__ import annotations++import mimetypes+from dataclasses import dataclass+from pathlib import Path++import boto3+from botocore.config import Config as BotoConfig++from .config import Config+++@dataclass+class Uploaded:+ files: int+ bytes: int+++class R2:+ def __init__(self, cfg: Config):+ cfg.require_r2()+ self.bucket = cfg.bucket+ self._s3 = boto3.client(+ "s3",+ endpoint_url=cfg.endpoint,+ aws_access_key_id=cfg.access_key_id,+ aws_secret_access_key=cfg.secret_access_key,+ region_name="auto",+ config=BotoConfig(signature_version="s3v4", retries={"max_attempts": 5}),+ )++ def put_file(self, local: Path, key: str) -> int:+ ctype = mimetypes.guess_type(str(local))[0] or "application/octet-stream"+ self._s3.upload_file(str(local), self.bucket, key, ExtraArgs={"ContentType": ctype})+ return local.stat().st_size++ def upload_tree(self, local_dir: Path, key_prefix: str) -> Uploaded:+ """Upload every file under ``local_dir`` to ``key_prefix/<relpath>``."""+ files = bytes_ = 0+ for path in sorted(local_dir.rglob("*")):+ if path.is_file():+ rel = path.relative_to(local_dir).as_posix()+ bytes_ += self.put_file(path, f"{key_prefix.rstrip('/')}/{rel}")+ files += 1+ return Uploaded(files, bytes_)++ def download_tree(self, prefix: str, dest_dir: Path) -> Uploaded:+ """Download every object under ``prefix`` into ``dest_dir/<relpath>`` (zero egress on R2)."""+ prefix = prefix.rstrip("/") + "/"+ files = bytes_ = 0+ for key in self.list(prefix):+ rel = key[len(prefix):]+ if not rel:+ continue+ out = dest_dir / rel+ out.parent.mkdir(parents=True, exist_ok=True)+ self._s3.download_file(self.bucket, key, str(out))+ bytes_ += out.stat().st_size+ files += 1+ return Uploaded(files, bytes_)++ def list(self, prefix: str = "") -> list[str]:+ keys, token = [], None+ while True:+ kw = {"Bucket": self.bucket, "Prefix": prefix}+ if token:+ kw["ContinuationToken"] = token+ r = self._s3.list_objects_v2(**kw)+ keys += [o["Key"] for o in r.get("Contents", [])]+ if not r.get("IsTruncated"):+ return keys+ token = r["NextContinuationToken"]++ def get_text(self, key: str) -> str:+ return self._s3.get_object(Bucket=self.bucket, Key=key)["Body"].read().decode()++ def delete_prefix(self, prefix: str) -> int:+ keys = self.list(prefix)+ for i in range(0, len(keys), 1000):+ batch = [{"Key": k} for k in keys[i:i + 1000]]+ self._s3.delete_objects(Bucket=self.bucket, Delete={"Objects": batch})+ return len(keys)diff --git a/toolkits/README.md b/toolkits/README.mdindex 5248089e..f4aed154 100644--- a/toolkits/README.md+++ b/toolkits/README.md@@ -11,13 +11,20 @@ contributor's project ──▶ curation ──▶ 3DCodeVerse on the Hub ──| folder | stage | what it does ||---|---|---|+| [`3dcode_cli/`](3dcode_cli/) | contributor → corpus | the installable `3dcode` CLI: validate, fingerprint/dedupe, execute, render and push a project to the staging bucket. Per-dialect modules for Blender-Python, CadQuery, build123d, FreeCAD and OpenSCAD || [`curation/`](curation/) | raw → corpus | per-source curation: convert a source's native format to runnable projects, execute/render them, compute ground-truth meshes, dedupe, pack to tar+parquet, upload to the Hub || [`llamafactory/`](llamafactory/) | corpus → training data | turn every corpus subdirectory into a LLaMA-Factory dataset, verify it with the real compilers/runtimes, flatten multi-file samples, build multimodal (render + instruction) variants, and sample training mixes |-The contributor-facing CLI (`3dcode validate / check / exec / render / push`) lives in its own installable-package, **[gaoypeng/3dcode_toolkit](https://github.com/gaoypeng/3dcode_toolkit)**, and is intentionally *not*-vendored here — it is `pipx install`-ed and would drift if copied. `curation/` holds the per-source scripts from-that repo, which are not part of the package and would otherwise have no home.+`3dcode_cli/` is a complete copy of **[gaoypeng/3dcode_toolkit](https://github.com/gaoypeng/3dcode_toolkit)**+(74 files, byte-for-byte apart from `.git`), kept here so the whole data toolchain lives in one place. It is still+`pipx install`-able from either location:++```bash+pipx install "git+https://github.com/gaoypeng/3dcode_toolkit" # upstream+pipx install ./toolkits/3dcode_cli # this copy+```++If both are edited they will drift — pick one as canonical and mirror the other.---@@ -85,3 +92,11 @@ python build_mm_dataset.py --views 4 --out mm/Results produced with these tools: [`finetune/llm_finetune_exps.md`](../finetune/llm_finetune_exps.md) and[`finetune/docs/REPORT.md`](../finetune/docs/REPORT.md).++---++## Layout note++Nothing outside this folder hardcodes the name `toolkits/`: the scripts take their input and output paths as+arguments, and the only references are the links in this file, `../README.md` and `../finetune/README.md`.+Renaming the folder is therefore a `git mv` plus those three links.