diff --git a/docs/research/geonodes-translation-corpus.md b/docs/research/geonodes-translation-corpus.md new file mode 100644 index 0000000..d78175a --- /dev/null +++ b/docs/research/geonodes-translation-corpus.md @@ -0,0 +1,118 @@ +# Geometry Nodes Translation Corpus + +This note tracks public Geometry Nodes examples that are useful for learning how +to translate visual node graphs into Geometry Script. The goal is not to collect +cool files. The goal is to build a graded ladder from known node networks to +scripts we can generate, inspect, render, and revise. + +## Source Selection Rules + +- Prefer `.blend` files or repositories with real node groups over screenshot + and video-only tutorials. +- Prefer examples with clear visual outcomes and bounded mechanisms. +- Use Blender itself to inspect node groups before recreating anything. +- Translate one graph idiom at a time into Geometry Script. +- Verify each translation by generating a node group in Blender, inspecting its + node/link shape, and rendering when the visual result matters. +- Keep video-only sources as secondary explanation, not primary truth. + +## Complexity Ladder + +### Tier 1: Primitive Construction And Simple Fields + +Use these to learn Geometry Script signatures, result objects, chain syntax, +modifier sockets, and basic graph inspection. + +- `Shriinivas/geometrynodes` + - Source: https://github.com/Shriinivas/geometrynodes + - Candidate files: `cartesian.blend`, `paramnpolareq.blend`, + `piechart.blend`, `fieldvalue.blend` + - Why it matters: small mathematical graphs with clear output shapes. + - Translation value: curve generation, mesh primitives, math nodes, exposed + parameters, and field/value flow. + +### Tier 2: Scattering, Instancing, And Attribute Flow + +Use these after the primitive layer can be recreated without guessing. + +- Blender Guru beginner Geometry Nodes candy tutorial + - Source: https://www.blenderguru.com/tutorials/2025/9/10/blender-tutorial-geometry-nodes-for-beginners + - Candidate artifact: downloadable final `.blend` + - Why it matters: canonical beginner scatter workflow. + - Translation value: distribute points, instance on points, random rotation, + random scale, join geometry, and exposed controls. + +- Samuel Sullins demo file via BlenderNation + - Source: https://www.blendernation.com/2023/04/20/learn-geometry-nodes-with-this-demo-file/ + - Candidate artifact: free demo `.blend` with node comments and simple + scattering setups. + - Why it matters: likely built for learning and rebuilding. + - Translation value: comments may make node intent easier to map into prose + and Geometry Script. + +### Tier 3: Reusable Utility Node Groups + +Use these to learn how artists package node networks into inspectable tools. + +- `quellenform/blender-CurveToMeshUV` + - Source: https://github.com/quellenform/blender-CurveToMeshUV + - Candidate file: `Curve to Mesh UV v1.7.02.230213-FREE - Blender 3.4+.blend` + - Why it matters: a focused utility group with a clear contract. + - Translation value: curve-to-mesh workflows, UV attributes, face-corner + domain discipline, output attribute handling. + +- `Tams3d/T3D-GN-Presets` + - Source: https://github.com/Tams3d/T3D-GN-Presets + - Candidate file: `t3d_nodes.blend` + - Why it matters: a large preset library for Blender 4.4+ with many utility + node groups. + - Translation value: reusable group organization, socket naming, matrix and + deformation utilities. This is not a first target; it is a quarry. + +### Tier 4: Procedural Systems + +Use these only after the smaller idioms are reliable. + +- Blender Studio Geometry Nodes from Scratch files + - Source: https://studio.blender.org/training/geometry-nodes-from-scratch/chapter/files/ + - Candidate files: rock scattering, tree generator, grass tuft generator, + spaceship generator, geometry components demo. + - Why it matters: production-adjacent learning files with a broad concept + range. + - Translation value: progressive systems that combine distribution, + attributes, generated geometry, materials, and exposed controls. + +- `IRCSS/Trees-With-Geometry-Nodes-Blender` + - Source: https://github.com/IRCSS/Trees-With-Geometry-Nodes-Blender + - Candidate artifact: tree-generation node groups. + - Why it matters: procedural tree generation based on curves and instancing. + - Translation value: recursive-looking branch systems, curve distortion, + instance orientation, scale variation, and material variation. + +## First Translation Target + +Start with `Shriinivas/geometrynodes` because it is public, GitHub-hosted, MIT +licensed, and contains several bounded `.blend` examples. The first useful +translation is a tiny graph from `cartesian.blend` or `piechart.blend`, chosen +after node group inspection. + +## Extraction Workflow + +1. Download one source `.blend` into an ignored experiment folder. +2. Run Blender headlessly to list geometry node groups, group interface sockets, + node types, link counts, and exposed modifiers. +3. Pick one small node group and write a plain-language graph map: + inputs, generated geometry, fields/attributes, materials, outputs, and why + each stage belongs. +4. Recreate that group with Geometry Script using local generated 5.1 docs for + signatures. +5. Smoke-test generation in Blender and compare node types/link shape against + the source. +6. Render only after the graph structure is close enough to make visual review + meaningful. + +## Known Tooling Need + +We need a small Blender inspection script that can summarize node groups from a +`.blend` file into JSON. Without that, every example becomes manual archaeology +with better branding. diff --git a/notes/fresh-workspace-handoff.md b/notes/fresh-workspace-handoff.md index 8cf209e..8a8df91 100644 --- a/notes/fresh-workspace-handoff.md +++ b/notes/fresh-workspace-handoff.md @@ -23,11 +23,12 @@ git log --oneline -5 ## Current State VibeGeometry is an initial scaffold. It has persistence machinery, project -orientation docs, and helper tools, but no Blender builder library or artifact -schemas yet. +orientation docs, helper tools, and an initial Geometry Nodes translation corpus +note, but no Blender builder library or artifact schemas yet. -The current next action is to draft the scene brief and node graph manifest -schemas, then validate them against one tiny reference-driven example. +The current next action is to build the first Geometry Nodes translation corpus +entry by inspecting a small public `.blend` node group, mapping its graph in +prose, and recreating it with Geometry Script. ## Important Invariants @@ -47,6 +48,8 @@ schemas, then validate them against one tiny reference-driven example. - What exact JSON shape should the scene brief use for references, instructions, target traits, and acceptance criteria? - What should the first node graph manifest schema require versus merely allow? +- What node-group inspection JSON shape is most useful for translating public + `.blend` examples into Geometry Script? - Which Blender 5.0+ APIs and node construction helpers should become the first stable builder layer? - What is the smallest useful render-review artifact? diff --git a/notes/vibegeometry-implementation-plan.md b/notes/vibegeometry-implementation-plan.md index 43c266c..f333c4b 100644 --- a/notes/vibegeometry-implementation-plan.md +++ b/notes/vibegeometry-implementation-plan.md @@ -13,37 +13,46 @@ should not carry live next-action clutter. ## Near-Term Sequence -1. Define the scene brief contract. +1. Build the first Geometry Nodes translation corpus entry. + - Start from a small public `.blend` with inspectable node groups. + - Use Blender to summarize group sockets, node types, links, modifiers, and + graph shape before translating. + - Write a plain-language map of one source graph before scripting. + - Recreate the graph with Geometry Script using the local Blender 5.1 + generated Geometry Script docs for signatures. + - Smoke-test the generated node group in Blender before rendering. + +2. Define the scene brief contract. - Capture references, text instructions, target visual traits, constraints, camera/composition requirements, acceptance criteria, and known unknowns. - Preserve source paths or URLs for every reference image. - Separate visual target description from implementation strategy. -2. Define the node graph manifest contract. +3. Define the node graph manifest contract. - Describe node groups, sockets, exposed controls, modifiers, attribute names, field flow, materials, and dependencies. - Require enough naming and rationale for future agents to inspect the graph. - Keep graph contracts Blender 5.0+ oriented. -3. Build a minimal Python builder seam. +4. Build a minimal Python builder seam. - Start with one tiny scene that proves graph construction, material setup, camera, lighting, save, and render orchestration. - Prefer small composable helpers for node group creation and socket linking. - Avoid a giant builder abstraction until repeated graph idioms demand it. -4. Build render review artifacts. +5. Build render review artifacts. - Store render path, scene brief id, manifest id, script path, Blender version, review status, visual misses, graph issues, and next hypothesis. - Treat rendered output as the acceptance surface for visual claims. -5. Add geometry-node idiom notes and examples. +6. Add geometry-node idiom notes and examples. - Document established patterns for distribution, instancing, curve/surface generation, attributes, material variation, simulation zones, and exposed parameters. - Keep examples small enough to inspect. - Promote only graph patterns that survive review. -6. Generalize after the loop works. +7. Generalize after the loop works. - Add reference-image ingestion helpers. - Add headless batch rendering. - Add visual comparison or reviewer prompts. diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 76642fd..3f13213 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -1,3 +1,4 @@ {"ts":"2026-05-04T00:00:00+00:00","type":"scaffold","status":"accepted","note":"Initialized VibeGeometry with Epiphany-style persistence surfaces adapted to Blender 5.0+ geometry-node scene generation."} {"ts": "2026-05-04T11:52:15+00:00", "type": "research", "status": "ok", "note": "Geometry Script add-on is installed under Blender 5.1 and imports headlessly. A trivial cube node group built successfully in Blender 5.1.1; the documented grid().mesh_to_points() chain failed with NoneType callable, so Geometry Script should be treated as promising but each idiom must be smoke-tested against the installed Blender/add-on pair."} {"ts": "2026-05-04T11:55:00+00:00", "type": "research", "status": "ok", "note": "Local Geometry Script 5.1 generated docs are the authoritative node-signature source for this workspace. The prior grid().mesh_to_points() probe failed because grid() returns a result object with mesh and uv_map; the valid chain is grid(...).mesh.mesh_to_points(...)."} +{"ts": "2026-05-04T12:11:47+00:00", "type": "research", "status": "accepted", "note": "Public Geometry Nodes learning material is mostly screenshots, videos, and downloadable .blend files. VibeGeometry should build durable Geometry Script knowledge by inspecting source .blend node groups, mapping one graph at a time in prose, then recreating and smoke-testing with local Geometry Script 5.1 signatures."} diff --git a/state/map.yaml b/state/map.yaml index b1f9126..94e3704 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -77,4 +77,4 @@ data_flow: current_status: summary: VibeGeometry has an initial Epiphany-style persistence scaffold adapted for Blender geometry-node scene generation, with project-neutral state, handoff, architecture notes, and helper tools. - next_action: Draft the scene brief and node graph manifest schemas, then validate them against one tiny reference-driven example. + next_action: Build the first Geometry Nodes translation corpus entry by inspecting a small public `.blend` node group, mapping its graph in prose, and recreating it with Geometry Script.