Skip to content

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/.gitignore
new file mode 100644
index 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
+.env
diff --git a/toolkits/3dcode_cli/CLAUDE.md b/toolkits/3dcode_cli/CLAUDE.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.example
new file mode 100644
index 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.md
new file mode 100644
index 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.toml
new file mode 100644
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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")
+
+
+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.py
new file mode 100644
index 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_PATH
diff --git a/toolkits/3dcode_cli/threedcode/dialects/__init__.py b/toolkits/3dcode_cli/threedcode/dialects/__init__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 out
diff --git a/toolkits/3dcode_cli/threedcode/registry.py b/toolkits/3dcode_cli/threedcode/registry.py
new file mode 100644
index 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 hits
diff --git a/toolkits/3dcode_cli/threedcode/runners/__init__.py b/toolkits/3dcode_cli/threedcode/runners/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/toolkits/3dcode_cli/threedcode/runners/blender_exec.py b/toolkits/3dcode_cli/threedcode/runners/blender_exec.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.md
index 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.