Articraft Setup, Generation, and Local Viewer Workflow

Articraft's Articulated 3D Asset Use Case

Articraft addresses the gap between text or image descriptions and reusable 3D assets that contain articulated parts. Its target audience includes researchers, graphics engineers, model creators, and developers who need objects such as hinged lamps or adjustable fans rather than a single static mesh. A prompt can specify a weighted base, two hinged arms, and an adjustable head, giving the generation system explicit mechanical and visual requirements.

The repository is positioned as reference code for the Articraft paper and includes generation code, a viewer, an SDK, and command line tools. It also connects to a separately released public dataset in `mattzh72/articraft-data`. This division matters because generated records are stored locally under a data root rather than being bundled directly into the Python package.

This is not a general-purpose CAD authoring interface exposed as a polished desktop application. The documented workflow centers on AI generation, command line inspection, local record management, and a web viewer. That makes Articraft most relevant to experimental pipelines, paper reproduction, and technical evaluation of agentic articulated asset generation. It is a poorer fit for an artist who primarily needs manual parametric modeling and expects a conventional CAD user interface.

Generation, Python Records, and Compiled Assets

The documented generation path starts with `articraft generate`, passes a natural-language prompt to the configured model provider, and produces an asset record under the selected data root. Provider keys in `.env`, together with `ARTICRAFT_MODEL` and `ARTICRAFT_THINKING_LEVEL`, control which backend and generation settings are used. The README also links to separate image-conditioned generation documentation, so the system is not limited to text prompts.

Records contain a `model.py` file. Articraft compiles and inspects those generated records by executing their Python code. That mechanism explains why the project can work with articulated descriptions and model-specific construction logic, but it also creates its largest security boundary. A record is executable code, not an inert data file. Generated records and model scripts should only be opened or compiled when their source is trusted.

The package dependencies indicate the geometry and validation side of the workflow. `cadquery`, `trimesh`, `manifold3d`, and `numpy` support 3D construction and representation. `python-fcl`, `networkx`, `scipy`, and `rtree` are consistent with collision, graph, numerical, and spatial operations. `fastapi` and `uvicorn` support the local viewer API, while `websockets` supports interactive communication. The repository layout separates these concerns among `agent/`, `articraft/`, `cli/`, `storage/`, `viewer/`, and `sdk/`.

Articraft stores generated assets in a gitignored data directory, `<repo-root>/data` by default. A manifest and library commands support listing, checking, categorization, and rebuilding that index. This local-first storage model keeps generated records separate from source code, but it also means a checkout alone does not provide a complete asset library unless the dataset or generated records are also present.

Legacy Checkout Status and Supported Python Versions

This checkout is no longer the center of Articraft development. Its README marks it as superseded and directs users to `articraftresearch/Articraft`, which it describes as the current project maintained by a volunteer group of researchers and engineers. The release named `legacy-final` carries the same message: Articraft development has moved. The last push to this repository was on 2026-07-30.

That status changes the adoption decision. The code remains relevant as reference implementation and paper-associated source, but adopting this exact repository as the foundation of a new internal tool carries migration risk. Documentation, CLI behavior, record structure, and dependencies may evolve at the successor repository. The `pyproject.toml` already limits the package to Python `>=3.11,<3.13`, so Python 3.13 and newer are outside the declared support range.

The package identifies itself as version `0.1.0` and classifies its development status as alpha. That classification does not prove instability, but it is an explicit signal that this is early software. The setup also depends on `uv` and `just`. `npm` is optional, but it is required for the local viewer frontend and frontend hooks. For the successor repository, first compare its Python range, setup command, data format, and viewer commands rather than assuming this README remains accurate.

The repository code is licensed under Apache-2.0. The README separately states that contributed Articraft data is released under CC BY 4.0 and may be distributed publicly for building, evaluating, and improving machine learning models. Code and dataset rights therefore need to be tracked separately. This is a licensing distinction to verify in project records, not legal advice about a particular deployment.

Installing mattzh72/articraft and Preparing Its Data

git clone https://github.com/mattzh72/articraft-data.git ../articraft-data
export ARTICRAFT_DATA_DIR="$(cd ../articraft-data && pwd)"
uv run articraft status
uv run articraft library check --require-records

The README says Articraft normally uses `<repo-root>/data`, while `--data-dir` can point to another folder. If setup reports that `npm` is unavailable, that is expected for the Python package but means the local React frontend has not been installed.

First Desk Lamp Generation and Viewer Launch

just viewer

The generated desk lamp should then be browsable through the viewer's object library and joint controls. The repository includes a viewer demonstration image, but the README does not define geometry tolerances, generation success rates, output fidelity, or provider latency, so those qualities cannot be inferred from the example prompt.

Record Forking and Local Library Maintenance

uv run articraft library list
uv run articraft library rebuild-manifest
uv run articraft library check --require-records
uv run articraft library set-category <record_id> <category_slug>

These commands favor inspection over opaque storage. A failed `library check` can therefore be used as an explicit validation gate, while `rebuild-manifest` repairs or regenerates library indexing after records change. The README does not document rollback, transactional behavior during generation, or recovery after an interrupted write. Avoid treating fork history or manifest rebuilds as a documented backup system without checking the successor project.

Security, Trust, and the Limits of Local Operation

The clearest limitation is Articraft's execution of generated `model.py` files. Local-first storage does not make the content harmless. A malicious or compromised record can execute Python when Articraft compiles or inspects it. Dataset provenance therefore matters more than it would for a viewer that only parses inert scene files.

The README warns to run generated records and scripts only from trusted sources. That warning applies to direct imports, agent-created scripts, shared folders, and externally obtained records. A separate viewer does not eliminate the issue if opening a record triggers compilation or inspection. Production adoption should require a controlled ingestion process or an isolated environment, but the available documentation does not specify a sandbox command, container image, or permission model.

Articraft is also the wrong tool when only a static mesh is needed, when assets must remain non-executable, or when Python 3.13 support is mandatory. Its declared dependency set is substantial, and local generation may depend on external model providers or a separately configured coding agent. A conventional CAD workflow offers direct manual control over dimensions and constraints. An agentic generation workflow instead exchanges that direct manipulation for prompt-driven creation and executable model records.

Articraft Versus Direct CAD and Inert Asset Viewers

The closest alternative is direct use of a conventional CAD system rather than Articraft's prompt-driven workflow. That approach gives predictable manual editing and does not require a language model merely to specify each revision. It is the better choice when an engineer already knows the dimensions and needs deterministic authorship rather than experimental asset generation.

An inert mesh viewer is another alternative when the requirement is limited to inspecting static geometry. Such a viewer can consume a non-executable asset format and provide orbit or selection controls without compiling Python records. It avoids Articraft's `model.py` execution boundary, but it does not reproduce Articraft's prompt generation, articulated record structure, fork history, local library workflow, or model inspection features.

Articraft occupies the space between those approaches. Its value is the integrated path from a natural-language description to an articulated record that can be browsed and forked. Its cost is added infrastructure: provider credentials, `uv`, `just`, Python geometry dependencies, a React viewer, a separate data root, and strict trust boundaries. Engineers should choose it when experimental generation and articulation are central, not simply because a 3D viewer is also needed.

Editorial conclusion

Researchers reproducing the Articraft paper or maintaining its released dataset should use this legacy repository, while new development work belongs in articraftresearch/Articraft. Before adopting either checkout for production asset work, verify Python 3.11 or 3.12 compatibility, provider access, trust in generated model.py files, and whether the successor repository has changed the CLI or record format.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. mattzh72/articraft on GitHub
3. Project website
4. README
5. Releases