| --- |
| 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. |
|
|
