{"id":50276935,"url":"https://github.com/dunknowcoding/ironengine-3dcreator","last_synced_at":"2026-05-27T21:02:58.124Z","repository":{"id":354771421,"uuid":"1223622794","full_name":"dunknowcoding/IronEngine-3DCreator","owner":"dunknowcoding","description":"Pure Pythonic light-weighted 3D point cloud generator using both local LLM and cloud LLM","archived":false,"fork":false,"pushed_at":"2026-04-30T01:19:45.000Z","size":455,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-30T02:26:51.197Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dunknowcoding.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-28T13:52:55.000Z","updated_at":"2026-04-30T01:19:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dunknowcoding/IronEngine-3DCreator","commit_stats":null,"previous_names":["dunknowcoding/ironengine-3dcreator"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/dunknowcoding/IronEngine-3DCreator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dunknowcoding%2FIronEngine-3DCreator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dunknowcoding%2FIronEngine-3DCreator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dunknowcoding%2FIronEngine-3DCreator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dunknowcoding%2FIronEngine-3DCreator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dunknowcoding","download_url":"https://codeload.github.com/dunknowcoding/IronEngine-3DCreator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dunknowcoding%2FIronEngine-3DCreator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33583399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-27T21:02:57.156Z","updated_at":"2026-05-27T21:02:58.115Z","avatar_url":"https://github.com/dunknowcoding.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# IronEngine 3D Creator\n\n### Prompt-to-3D desktop generator for structurally valid point clouds, live viewport preview, and local/cloud LLM workflows\n\n\u003cp\u003e\n  \u003ca href=\"https://pypi.org/project/ironengine-3d-creator/\"\u003e\u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/ironengine-3d-creator?logo=pypi\u0026logoColor=white\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"Python\" src=\"https://img.shields.io/pypi/pyversions/ironengine-3d-creator?logo=python\u0026logoColor=white\"\u003e\n  \u003cimg alt=\"UI\" src=\"https://img.shields.io/badge/UI-PySide6-41CD52?logo=qt\u0026logoColor=white\"\u003e\n  \u003cimg alt=\"Renderer\" src=\"https://img.shields.io/badge/rendering-OpenGL%20%2B%20Open3D-6E40C9\"\u003e\n  \u003cimg alt=\"LLM\" src=\"https://img.shields.io/badge/LLM-Ollama%20%7C%20OpenAI%20%7C%20Anthropic-111827\"\u003e\n  \u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-Apache%202.0-F59E0B\"\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://pypi.org/project/ironengine-3d-creator/\"\u003e\u003cimg alt=\"Install from PyPI\" src=\"https://img.shields.io/badge/install-pip%20install%20ironengine--3d--creator-2563EB\"\u003e\u003c/a\u003e\n  \u003ca href=\"docs/INSTALL.md\"\u003e\u003cimg alt=\"Installation Guide\" src=\"https://img.shields.io/badge/docs-installation%20guide-0F766E\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/dunknowcoding/IronEngine-3DCreator/issues\"\u003e\u003cimg alt=\"Support\" src=\"https://img.shields.io/badge/support-github%20issues-111827\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cimg alt=\"IronEngine 3D Creator banner\" src=\"docs/assets/readme/readme-banner.svg\" width=\"100%\"\u003e\n\nTurn natural-language prompts into editable 3D point clouds, repair common structural mistakes automatically, preview the result in a live Qt/OpenGL viewport, and export to formats that fit the wider IronEngine toolchain.\n\n**Now available on PyPI** as `ironengine-3d-creator`. Built and packaged by **NiusRobotLab**.\n\n\u003c/div\u003e\n\n\u003e **Best for:** makers, tool builders, and local-AI tinkerers who want a practical path from prompt -\u003e structured 3D output -\u003e editable result.\n\n**Jump to:** [Quick Start](#quick-start) | [Prompt-to-Result](#prompt-to-result) | [Screenshot Gallery](#screenshot-gallery) | [Installation](#installation) | [How To Use The App](#how-to-use-the-app) | [Packaging And Distribution](#packaging-and-distribution)\n\n---\n\n## Why this project exists\n\nMost LLM-to-3D experiments fail in the same places: legs float, supports intersect badly, repeated parts lose spacing, and tiny local models drift out of structure. `IronEngine 3D Creator` solves that by making the model choose a compact procedural recipe instead of drawing raw geometry directly.\n\nThe workflow is:\n\n```text\nPrompt -\u003e SOUL rules -\u003e LLM JSON spec -\u003e validator -\u003e integrity repair -\u003e point-cloud sampler -\u003e mesh reconstruction -\u003e preview/export\n```\n\nThat keeps generations fast, seedable, reproducible, and much easier to repair than arbitrary mesh output.\n\n## Quick start\n\n| Step | What to do | Command / action |\n|---|---|---|\n| 1 | Install from PyPI | `python -m pip install ironengine-3d-creator` |\n| 2 | Launch the desktop app | `ironengine-3d-creator` |\n| 3 | Start Ollama locally | `ollama serve` |\n| 4 | Pull a compact local model | `ollama pull qwen3.5:0.8b` |\n| 5 | Generate your first object | Set provider to `ollama`, select the model, enter a prompt, click **Generate** |\n\n## Prompt-to-result\n\n| Input | What the app does | Output |\n|---|---|---|\n| `A Chinese porcelain vase with cobalt blue painted bands and a polished ceramic finish` | The model emits a compact JSON spec, the integrity layer repairs structure, and the sampler reconstructs a dense point cloud for preview. | A vase you can inspect in points mode, switch to mesh mode, edit manually, and export to `PLY`, `PCD`, `GLB`, or `OBJ`. |\n\n## Why it feels different\n\n- **Local-first 3D generation**: pair the app with Ollama and lightweight `qwen3.5` models for a practical desktop workflow.\n- **Structure before geometry**: the model emits a compact `GenerationSpec`, then deterministic integrity repair fixes common support and alignment mistakes.\n- **Interactive editor, not a one-shot demo**: inspect the JSON spec, switch between point and mesh view, and make manual edits before export.\n- **Package + app together**: install it like a Python package, run it as a desktop tool, and still script or extend the underlying pipeline.\n\n## Screenshot gallery\n\n| Full UI | Point cloud viewport | Reconstructed mesh |\n|---|---|---|\n| ![IronEngine 3D Creator UI with local qwen3.5 model](docs/assets/readme/ui-window-qwen35.png) | ![Generated vase point cloud](docs/assets/readme/viewport-vase-qwen35.png) | ![Generated vase mesh preview](docs/assets/readme/viewport-vase-qwen35-mesh.png) |\n\nThe screenshots above were captured from the local app flow in the `IronEngineWorld` Conda environment using Ollama with `qwen3.5:0.8b` and a porcelain-vase prompt.\n\n## Highlights\n\n- **Structured generation**: the LLM returns a compact `GenerationSpec` of primitives, transforms, labels, and surface features.\n- **Deterministic integrity repair**: grounding, attachment, spacing, and framework repair happen after parsing so common structural failures are fixed automatically.\n- **Real desktop UI**: PySide6-based editor with prompt controls, streaming token view, live viewport, mesh mode, and editing tools.\n- **Multiple model backends**: Ollama and LM Studio locally, plus Anthropic and OpenAI in the cloud.\n- **Renderer API included**: offscreen render helpers let you create RGBA previews without opening the full app.\n- **Package-ready layout**: Conda environment file, wheel manifest, packaged prompt rules, contributor guide, and changelog are included.\n\n## At a glance\n\n| Area | What it does |\n|---|---|\n| Generation | Produces 3D point clouds from text prompts or auto templates |\n| Integrity | Repairs grounding, adjacency, symmetry, and framework alignment |\n| Geometry | Supports procedural primitives including `box`, `sphere`, `cylinder`, `capsule`, `cone`, `torus`, `ellipsoid`, `prism`, `helix`, and `plane` |\n| Surface detail | Applies features such as `scratch`, `curve_pattern`, `bump_field`, `dent`, `erosion`, `ridges`, `holes`, and `fur` |\n| Rendering | Shows points, mesh, or both with textured and plain color modes |\n| Export | Writes `PLY`, `PCD`, `GLB`, and `OBJ` |\n| Editing | Supports brush move, warp, paint, smooth, and undo/redo |\n| Performance | Uses NumPy by default and can accelerate with optional GPU backends |\n\n## Repository layout\n\n```text\nsrc/ironengine_3d_creator/\n  alignment/   # parsing, schema, defaults, validation, integrity repair\n  core/        # exporter, pipeline, resources, settings, session\n  generation/  # samplers, features, textures, reconstruction\n  llm/         # providers, prompts, model catalogs, thinking filters\n  rendering/   # offscreen rendering API\n  ui/          # Qt main window, panels, viewport, dialogs, workers\n\ndocs/\n  INSTALL.md\n  PROJECT_ANALYSIS.md\n  assets/readme/\n\ntools/\n  benchmark.py\n```\n\n## Installation\n\n### Fastest path: install from PyPI\n\n```powershell\npython -m pip install ironengine-3d-creator\nironengine-3d-creator\n```\n\n### Recommended for contributors: Conda with `IronEngineWorld`\n\n```powershell\nconda env create -f environment.yml\nconda activate IronEngineWorld\npython -m pip install -e .\n```\n\n### If `IronEngineWorld` already exists\n\n```powershell\nconda activate IronEngineWorld\npython -m pip install -e .\n```\n\n`open3d` is part of the base package requirements, so mesh reconstruction and export work out of the box after install.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eNeed a fuller setup path?\u003c/strong\u003e\u003c/summary\u003e\n\n- Use `docs/INSTALL.md` for the more detailed installation and smoke-test flow.\n- Prefer the editable install if you plan to modify the app or package metadata.\n- Keep GPU extras optional unless they match your machine, CUDA stack, and drivers.\n\n\u003c/details\u003e\n\n## Optional extras\n\nUse extras only for features you actually want:\n\n```powershell\npython -m pip install -e .[anthropic]\npython -m pip install -e .[openai]\npython -m pip install -e .[gpu_taichi]\npython -m pip install -e .[gpu_cupy]\npython -m pip install -e .[gpu_torch]\npython -m pip install -e .[nvidia]\npython -m pip install -e .[sim]\npython -m pip install -e .[all]\n```\n\n| Extra | Purpose |\n|---|---|\n| `gpu_taichi` | Cross-platform GPU fallback with Taichi |\n| `gpu_cupy` | CUDA array acceleration through CuPy |\n| `gpu_torch` | PyTorch-based GPU fallback |\n| `nvidia` | VRAM/resource monitoring via NVML |\n| `anthropic` | Anthropic provider support |\n| `openai` | OpenAI provider support |\n| `sim` | IronEngine Sim / viewer integration |\n| `all` | Installs all optional extras in one step |\n\n## Local Ollama setup\n\nThe default local path is Ollama. The project already works with available `qwen3.5` variants such as `qwen3.5:0.8b`, `qwen3.5:2b`, `qwen3.5:4b`, and `qwen3.5:9b` when those models are installed locally.\n\n```powershell\nollama serve\nollama pull qwen3.5:0.8b\n```\n\nThen in the app:\n\n1. Set **Provider** to `ollama`.\n2. Keep **Endpoint** as `http://localhost:11434`.\n3. Select a local `qwen3.5` model.\n4. Save the config.\n5. Enter your prompt and click **Generate**.\n\n## Run the application\n\n```powershell\nconda activate IronEngineWorld\npython -m ironengine_3d_creator\n```\n\nAfter installation, this also works:\n\n```powershell\nironengine-3d-creator\n```\n\n## How to use the app\n\n### 1. Configure the model\n\n- Choose a provider in the right-side **LLM configuration** panel.\n- For local usage, use `ollama` with a `qwen3.5` model.\n- Turn on **Reasoning / thinking mode** when you want better deliberation and can afford slower generation.\n- Leave **Code mode** off unless you specifically want sandboxed Python generation instead of structured JSON specs.\n\n### 2. Describe the object\n\nUse the left-side **Requirements** panel:\n\n- Pick a shape hint or leave it on auto.\n- Set the point budget.\n- Tune the approximate bounding box.\n- Add support counts when helpful.\n- Write a plain-language prompt with material, silhouette, and detail cues.\n\nExample prompts:\n\n- `A Chinese porcelain vase with cobalt blue painted bands and a polished ceramic finish`\n- `A weathered iron fence with evenly spaced bars and decorative finials`\n- `A low wooden stool with four legs and deep scratches across the seat`\n- `A stylized quadruped creature with a wide torso and short legs`\n\n### 3. Generate and inspect\n\n- Click **Generate** for LLM-driven output.\n- Click **Auto** to use built-in template generation without an LLM.\n- Watch the token stream while the provider emits reasoning or JSON.\n- Inspect the spec preview after generation.\n\n### 4. View the model\n\n- Use **Points**, **Mesh**, or **Points + Mesh** in the toolbar.\n- Toggle **Textured** or **Plain** color mode.\n- Use **Wireframe** when evaluating reconstructed meshes.\n- Press `F` to frame the cloud.\n\n### 5. Edit and export\n\n- Use brush, warp, paint, or smooth from the editing panel.\n- Export to `PLY`, `PCD`, `GLB`, or `OBJ`.\n- Use **Send to SceneEditor** to hand off to downstream IronEngine tools when available.\n\n## Keyboard shortcuts\n\n| Action | Shortcut |\n|---|---|\n| Generate | `Ctrl+G` |\n| Auto generate | `Ctrl+Shift+G` |\n| Save session | `Ctrl+S` |\n| Open session | `Ctrl+O` |\n| Export | `Ctrl+E` |\n| Undo | `Ctrl+Z` |\n| Redo | `Ctrl+Y` or `Ctrl+Shift+Z` |\n| User guide | `F1` |\n| Frame camera | `F` |\n| Points mode | `1` |\n| Mesh mode | `2` |\n| Points + mesh | `3` |\n\n## Packaging and distribution\n\nThis repository is prepared to be consumed as a Python package.\n\n### Build distributables\n\n```powershell\nconda activate IronEngineWorld\npython -m build\n```\n\n### Install the built wheel locally\n\n```powershell\nconda activate IronEngineWorld\npython -m pip install dist\\ironengine_3d_creator-0.2.0-py3-none-any.whl\n```\n\n### Important packaging notes\n\n- `SOUL.md` is bundled into the package so prompt rules still work from wheel installs.\n- `environment.yml` provides the recommended Conda-first setup.\n- `MANIFEST.in` includes the main docs and prompt assets in source distributions.\n- The repository is licensed under the Apache License 2.0.\n\n## Docs\n\n- [`docs/INSTALL.md`](docs/INSTALL.md) — installation and package smoke-test notes\n- [`docs/PROJECT_ANALYSIS.md`](docs/PROJECT_ANALYSIS.md) — architecture and repo-readiness audit summary\n- [`CONTRIBUTING.md`](CONTRIBUTING.md) — development workflow notes\n- [`CHANGELOG.md`](CHANGELOG.md) — tracked repository cleanup and packaging changes\n\n## Known practical notes\n\n- The best local experience comes from an already-running Ollama server.\n- Small `qwen3.5` models are fast and usable because the app asks for a compact JSON recipe instead of full geometry.\n- Mesh mode depends on point-cloud reconstruction quality, so very sparse generations may still look better in points mode.\n- GPU extras are optional and should only be installed when they match your machine and drivers.\n\n## License\n\nThis project is licensed under the Apache License 2.0. See [`LICENSE`](LICENSE) for the full text.\n\n## Screenshot provenance\n\nThe current README images were produced locally from the real application flow using:\n\n- Conda environment: `IronEngineWorld`\n- Provider: `ollama`\n- Model: `qwen3.5:0.8b`\n\nIf the UI or visual styling changes, refresh the embedded screenshots from a new local capture run before publishing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdunknowcoding%2Fironengine-3dcreator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdunknowcoding%2Fironengine-3dcreator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdunknowcoding%2Fironengine-3dcreator/lists"}