Skip to content

Official Codebase of 3DCodeVerse

Python
2.7 KB
Raw Blame

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)

pipx install "git+https://github.com/gaoypeng/3dcode_toolkit"
# optional extras:
#   [dedup]    geometry + perceptual hashing (recommended)
#   [cadquery] CadQuery exec/render

3dcode-data 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-data`
  chair_02/
  ...

3. Workflow

3dcode-data validate ./yourname           # layout + anomaly checks
3dcode-data exec     ./yourname           # run the code locally, confirm it builds geometry
3dcode-data render   ./yourname           # (optional) render thumbnails into renders/
3dcode-data check    ./yourname           # flag duplicates against the existing corpus
3dcode-data 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-data 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-data check flags these).
  • Reasonable size — wildly over-long code is flagged by 3dcode-data anomalies.
  • A permissive, attributable license (set license/provenance in meta.json).