| --- |
| license: other |
| license_name: stabilityai-community |
| license_link: https://stability.ai/license |
| base_model: Qwen/Qwen-Image-Layered |
| library_name: peft |
| pipeline_tag: image-to-image |
| --- |
| |
| <h1 align="center">Stable Layers</h1> |
|
|
| <p align="center"> |
| <strong>Decomposing Images into Editable RGBA Layers</strong> |
| </p> |
|
|
| <p align="center"> |
| <img src="https://stability-ai.github.io/stable-layers.github.io/assets/images/teaser.png" alt="Stable Layers Teaser" width="100%" /> |
| </p> |
|
|
| <p align="center"> |
| <span><a href="https://arxiv.org/abs/2605.30257">Paper</a></span> |
| <span><a href="https://stability-ai.github.io/stable-layers.github.io/">Project Page</a></span> |
| <span><a href="https://huggingface.co/StabilityLabs/Stable-Layers">Model (Hugging Face)</a></span> |
| <span><a href="https://github.com/Stability-AI/Stable-Layers">Code</a></span> |
| </p> |
|
|
| ## About |
|
|
| **Stable Layers** decomposes a single RGB image into a small stack of back-to-front |
| RGBA layers (background plus object layers) suitable for compositing and editing. |
|
|
| This repository hosts the LoRA adapter over `Qwen/Qwen-Image-Layered`. This model |
| was trained using Qwen 3.5 9b as the VLM teacher. |
|
|
| ## Model Artifacts |
|
|
| This repository **is** the LoRA adapter (`adapter_config.json`, |
| `adapter_model.safetensors`). The base model is pulled from Hugging Face |
| automatically (`Qwen/Qwen-Image-Layered`). See the |
| [code repository](https://github.com/Stability-AI/Stable-Layers) for the inference |
| script. |
|
|
| ## Installation |
|
|
| ```bash |
| pip install torch diffusers transformers peft pillow numpy |
| ``` |
|
|
| Tested with `torch 2.11`, `diffusers 0.37`, `transformers 5.5`, `peft 0.18`. |
| Requires **one GPU** — the base model is ~40 GB in bf16, so an 80 GB-class card |
| (A100-80 / H100 / H200) is comfortable. |
|
|
| ## Recommended Inference Settings |
|
|
| > ### **Heun sampler · 50 steps · CFG 1.0 · 640 px · 4 layers** |
|
|
| | Setting | Value | Flag | |
| |---|---|---| |
| | **Sampler** | **Heun (2nd order)** | always used — not configurable | |
| | **Steps** | **50** | `--steps 50` | |
| | **CFG / guidance** | **1.0 (off)** | `--guidance-scale 1.0` | |
| | Resolution | 640 px (max dim) | `--size 640` | |
| | Layers | 4 | `--num-layers 4` | |
|
|
| **Note:** using a higher resolution, lower steps, or a non-Heun sampler will garble |
| the results. |
|
|
| ## Quickstart |
|
|
| ```bash |
| # single image |
| python decompose.py --input photo.png --output results/ |
| |
| # a directory of images |
| python decompose.py --input images/ --output results/ |
| |
| # RGBA layers with real alpha (for compositing / editors) |
| python decompose.py --input images/ --output results/ --transparent |
| |
| # explicit LoRA location |
| python decompose.py --input photo.png --output results/ --lora ./model |
| ``` |
|
|
| ## Outputs |
|
|
| ``` |
| results/<image_name>/ |
| source.png # input, resized |
| composite.png # layers recomposited — compare against source as a sanity check |
| layer_0.png # background (inpainted behind the removed objects) |
| layer_1.png # object layers, back-to-front |
| layer_2.png |
| layer_3.png |
| ``` |
|
|
| Layers are ordered back-to-front: `layer_0` is the background, higher indices sit |
| on top. Not every image needs all 4 — unused layers come out blank, which is |
| normal. |
|
|
| By default layers are composited onto **white** (easy to eyeball). Pass |
| `--transparent` to get **RGBA with real alpha**, which is what you want when |
| importing into an editor or compositing them yourself. |
|
|
| **Notes:** |
|
|
| - **Reproducible:** noise is seeded per image as `seed + image_index` |
| (`--seed 42` by default), so the same inputs give the same outputs. |
| - **Prompt:** decomposition is driven by the source image; the text prompt only |
| nudges guidance. The default (`"a clean, well composed image"`) is fine — |
| override with `--prompt` if you want. |
| - **Aspect ratio** is preserved; the longest side is scaled to `--size` and both |
| dimensions are rounded to multiples of 16. |
|
|
| ## License |
|
|
| This code and model usage are subject to Stability AI Community License terms. |
|
|
| For individuals or organizations generating annual revenue of USD 1,000,000 (or local |
| currency equivalent) or more, commercial usage requires an enterprise license from |
| Stability AI. |
|
|
| - License details: https://stability.ai/license |
| - Enterprise request: https://stability.ai/enterprise |
|
|
| ## Citation |
|
|
| ``` |
| @article{stablelayers2026, |
| author = {}, |
| title = {Stable Layers: Decomposing Images into Editable RGBA Layers}, |
| journal = {arXiv preprint arXiv:2605.30257}, |
| year = {2026} |
| } |
| ``` |
|
|
