# artiscene

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python version](https://img.shields.io/badge/Python-3.11-blue)](https://www.python.org/)
[![artiscene MCP server](https://glama.ai/mcp/servers/JunjianChi/artiscene/badges/score.svg)](https://glama.ai/mcp/servers/JunjianChi/artiscene)

**A workflow of agents for simulation-ready articulated scenes.**

[Project Page](https://junjianchi.com/artiscene) | [Usage Guide](docs/usage.md)

artiscene turns a natural-language prompt into a simulation-ready USD scene
for NVIDIA Isaac Sim. Articulated furniture is retrieved from the
[Articraft](https://github.com/mattzh72/articraft) catalog and composed with
per-link friction, mass, and joint drives that PhysX consumes.

Manipulation policies train in simulation on scenes full of articulated
objects, but LLM-generated assets have lacked a validated pathway into a
physics simulator. artiscene is that pathway, from prompt to a scene that
loads, settles, and actuates in Isaac Sim.

![Thirty generated scenes, spanning offices, gyms, kitchens and labs, rendered from artiscene output](docs/assets/gallery_30.jpg)

## How it works

![Pipeline: shell plan, furniture placement, composed Isaac scene](docs/assets/pipeline.jpg)

The pipeline runs five stages. Shell, Furniture and Physics are LLM design
stages, each running a designer–critic–planner loop. SceneAuthor writes the
layered USD deterministically, and SceneReview scores the authored scene.

## Results

On a benchmark of 30 articulation-rich scenes, every scene passes `usdchecker`
and loads in Isaac Sim without fatal error, the mean stable fraction under a
gravity settle is 0.98, and 90.6% of finite joints actuate to 95% of their
catalog range. The [project page](https://junjianchi.com/artiscene)
reports the full tables.

---

## Quickstart

### 1. Prerequisites

- Python **3.11**
- [`uv`](https://docs.astral.sh/uv/) for Python package + venv management
- [`just`](https://github.com/casey/just) as the command runner
- An **OpenAI API key**
- A local [Articraft](https://github.com/mattzh72/articraft) checkout
- Optional: a **Meshy API key**, **Node.js 18+**

### 2. Setup

```bash
git clone git@github.com:JunjianChi/artiscene.git
cd artiscene
just setup-full
```

`just setup-full` installs Python dependencies, the three.js renderer, and
the CLIP texture index.

### 3. Furniture catalog

```bash
git clone https://github.com/mattzh72/articraft.git ../articraft
uv run artiscene articraft-status
```

The catalog is expected at `../articraft`. Set `ARTICRAFT_PATH` if it lives
elsewhere.

### 4. Add API keys

Create a `.env` at the repo root:

```bash
OPENAI_API_KEY=sk-...
MESHY_API_KEY=msy-...
```

`artiscene env` prints the resolved config and which keys are set.

### 5. Generate a scene

```bash
uv run artiscene generate "a cozy scandinavian home office with a desk, a filing cabinet and a bookshelf"
```

Each run writes a session under `data/sessions/`. The composed scene Isaac
Sim loads is `scene_isaac.usda` in the newest revision. On the 30-scene
benchmark a scene cost $3.22 on average with GPT-5.5.

### 6. Inspect the scene

```bash
uv run artiscene sessions
uv run artiscene view <hash>
uv run artiscene isaac <hash>
```

`view` opens the scene in a three.js browser viewer, and `isaac` prints the
Isaac Lab load snippet.

---

## MCP server

The pipeline is also exposed as an MCP server over stdio, so an LLM assistant
can browse the catalog and generate scenes directly.

```bash
uv sync --extra mcp
uv run artiscene-mcp
```

## Acknowledgements

This project uses [Articraft](https://github.com/mattzh72/articraft)
([Zhou et al., 2026](https://arxiv.org/abs/2605.15187)) as its articulated
furniture catalog. PBR textures come from [ambientCG](https://ambientcg.com).

This repository is licensed under the [Apache-2.0 License](LICENSE).