---
license: other
license_name: mixed-non-commercial-research
base_model: Qwen/Qwen3-8B
library_name: peft
tags:
- 3d-scene-layout
- indoor-scenes
- furniture-placement
- qwen3
- lora
---

# FastFill (v4, base): object-conditioned indoor room layout

FastFill lays out the furniture of one room in a **single forward pass**. Given:
- the room's floor polygon, doors and windows, and fixed objects;
- the list of objects to place, with categories and optional descriptions;
- optional constraints;

it predicts, for **every** object:
- a size `[depth, width, height]` in metres;
- a bottom-centre position `[x, y, z]` in metres;
- a yaw: the direction the object's front faces, counter-clockwise from +x.

This repository holds what you need beyond the base model:
- the LoRA adapter on Qwen3-8B;
- the geometry decoder and heads;
- the tokenizer;
- the exact FastFill code the model was trained with.

**Download `Qwen/Qwen3-8B` and run it.** Nothing else is needed.

## Use

```bash
pip install torch              # the build for your CUDA / platform
pip install -r requirements.txt
python predict.py example_condition.json                          # fetches Qwen/Qwen3-8B from the Hub
python predict.py example_condition.json --qwen /path/to/Qwen3-8B  # or a local copy
```

In Python:

```python
import json, predict
model, tokenizer, max_length = predict.load(qwen="Qwen/Qwen3-8B", device="cuda")
condition = json.load(open("example_condition.json"))
layout = predict.predict_layout(model, tokenizer, condition, max_length=max_length, device="cuda",
                                grid_decode="spread")
```

**Hardware:** the bf16 base model needs about 16 GB of GPU memory. One room takes well under a second on a GH200.

## Input and output

- **Input:** a `fastfill.v2` condition. See `example_condition.json` and `code/fastfill/v2/schema.py`.
  - `room`: `floor_polygon_xy_m`, `floor_z_m`, `height_m`, `openings` (doors and windows), `fixed_objects`.
  - `objects`: `id`, `category`, optional `description` and `support_parent`.
  - `constraints`: `against_wall`, `near`, `faces`, `between`, ...
- **Output:** `{"schema_version": "fastfill.v2", "objects": [{"id", "target_size_local_m", "bottom_center_m", "yaw_rad"}, ...]}`, one entry per requested object.

## Model

| | |
|---|---|
| Base model | Qwen3-8B, frozen, bf16 |
| Adapter | LoRA rank 8, alpha 16, on q/k/v/o projections |
| Decoder and heads | 2-layer object decoder (dim 128, 4 heads)<br>size head (log-space)<br>yaw: 12 bins plus a residual<br>position: 16×16 grid cell plus a residual |
| Training | `main4-cell05-v4fixed-e5-base`: 6,552 steps (5 epochs)<br>effective batch 24, lr 1e-4 with cosine schedule<br>max length 8,192 tokens, up to 256 objects per room |
| Data | FastFill v4 layout data (v2-fixed build)<br>indoor rooms from about 20 public sources |
| Code | `code/fastfill`: training commit `26939bc`<br>the model, batch, evaluate, io and schema modules are byte-identical to it |

`checkpoint/training_manifest.json` records the training run (data hashes, full configuration).

## Results (test300: 300 held-out rooms, stratified by source)

| Decoding | Position error (m) | Size error (log) | Yaw error (rad) | Out of bounds | Blocks a door | Collisions per room | Constraints met | Clean rooms |
|---|---|---|---|---|---|---|---|---|
| spread | 3.11 | **0.321** | 0.593 | 10.0% | 11.7% | 3.65 | 37.7% | 11.1% |

**Read the raw output as a draft. It is not a guaranteed-valid layout.** Sizes are the model's strongest output, and they are what our downstream workflow uses. Positions often collide, block doors or break constraints. Pair the model with a geometric checker or repair step before using a layout in simulation.

## Limitations

- **One room at a time.** The model reads furniture boxes only, not meshes or appearance.
- **No validity guarantee.** Collisions, out-of-bounds objects and blocked doors occur, as shown in the table above.
- **Licence.** The training data mixes sources released for non-commercial research; use this model under the same terms. The base model, Qwen3-8B, is Apache-2.0.