# qwenlm/qwen-image-layered architecture

> Architecture diagram of the GitHub repository qwenlm/qwen-image-layered, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qwenlm/qwen-image-layered
- Repository: https://github.com/qwenlm/qwen-image-layered

## Overview

This repository is a lightweight application/demo wrapper around the **Qwen-Image-Layered** model. It is focused on **inference, interactive decomposition, layer editing, and recomposition**, not training or model implementation.

1. **Primary purpose**
   The core job is to take an input image, decompose it into a variable number of **RGBA layers**, and let a user inspect, export, edit, and recombine those layers. The architecture is centered on a layered-image workflow rather than a conventional app backend.

2. **Main entry point**
   `src/app.py` is the main launch path for the decomposition UI. Based on the README, this starts a **Gradio-based** interface for uploading an image, running the model, and producing layer outputs plus exportable artifacts.

3. **Model boundary**
   The actual decomposition is performed by the external **Diffusers** implementation of `QwenImageLayeredPipeline`, loaded from Hugging Face. This repository does not contain the model weights or core inference code; it acts as a client of that pipeline. The model is used as an image-to-multi-RGBA decomposer, with optional prompt/caption guidance.

4. **Input/output flow for decomposition**
   The typical flow is:
   - user uploads an input image
   - the app passes it to the Qwen-Image-Layered pipeline
   - the pipeline returns an ordered set of RGBA layers
   - the UI exposes those layers for viewing and export
   This is the central data path in the repo.

5. **Layer export subsystem**
   The decomposition app can export the result into **PPTX, ZIP, and PSD** formats. That means the repo includes a packaging boundary between the model output and downstream editing tools that understand layered documents. These exports are important because they preserve layer order and transparency for external use.

6. **Layer editing tool**
   `src/tool/edit_rgba_image.py` is a separate Gradio-based utility for editing individual transparent layers. The README says it uses **Qwen-Image-Edit** for edits on RGBA images, which implies a second model boundary: the decomposed layer is treated as an isolated asset, edited independently, then reinserted into the layered workflow.

7. **Layer recomposition tool**
   `src/tool/combine_layers.py` is the recomposition step. It takes multiple RGBA layers and merges them back into a single image. The repo explicitly requires the layers to be uploaded **from bottom to top**, so layer ordering is a key architectural constraint.

8. **Assets and test data**
   `assets/test_images` provides sample images for development and demos. This is a small but important fixture layer: it supports reproducible testing of the decomposition and editing pipeline without needing external data sources.

9. **Runtime and dependencies that shape the architecture**
   The repo depends on:
   - **Python**
   - **Diffusers** for model inference
   - **Transformers >= 4.51.3**
   - **PyTorch** for execution/device placement
   - **Gradio** for the interactive UIs
   - **python-pptx** and **psd-tools** for export interoperability
   These dependencies indicate a local, GPU-oriented inference application with document-format interoperability.

10. **Deployment model**
   The repository is designed to be run as standalone local tools rather than a distributed service. Each script launches its own interface, which keeps the system modular: decomposition, layer editing, and layer recombination are separate user-facing entry points.

11. **Important architectural boundary: layered editability**
   The central concept is that the image is converted into physically separated layers so that later edits remain localized. That boundary between “composited image” and “independent RGBA layers” is the main architectural idea in the repo and should be the focus of any diagram.

12. **What is not in the repo**
   There is no visible training pipeline, dataset ingestion pipeline, or server-side orchestration layer in the tree. The repository is primarily a **front-end/inference utility layer** around externally hosted model artifacts and supporting document/export tools.

Main entry points: [`src/app.py`](https://github.com/qwenlm/qwen-image-layered/blob/main/src/app.py) (Decompose UI), [`src/tool/combine_layers.py`](https://github.com/qwenlm/qwen-image-layered/blob/main/src/tool/combine_layers.py) (Combine Layers), [`src/tool/edit_rgba_image.py`](https://github.com/qwenlm/qwen-image-layered/blob/main/src/tool/edit_rgba_image.py) (Edit Layer), [`assets/test_images`](https://github.com/qwenlm/qwen-image-layered/tree/main/assets/test_images) (Test Images)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Interactive UIs"]
  node_app["Decompose UI<br/>gradio app<br/>[app.py]"]
  node_edit_tool["Edit Layer<br/>gradio tool<br/>[edit_rgba_image.py]"]
  node_combine_tool["Combine Layers<br/>gradio tool<br/>[combine_layers.py]"]
  node_local_runtime(("Local Runtime<br/>python app"))
end

subgraph group_model["Model Boundary"]
  node_qwen_pipeline[("Layered Pipeline<br/>external model")]
  node_qwen_edit[("Edit Model<br/>external model")]
end

subgraph group_io["Layer I/O"]
  node_uploaded_image["Input Image<br/>user asset"]
  node_rgba_layers["RGBA Layers<br/>layer set"]
  node_layer_view["Layer Preview<br/>ui artifact"]
  node_layer_export["Layer Export<br/>export bundle"]
  node_pptx_export["PPTX<br/>document export"]
  node_zip_export["ZIP<br/>archive export"]
  node_psd_export["PSD<br/>document export"]
  node_sample_images["Test Images<br/>fixture set"]
  node_layer_order{{"Bottom-to-Top<br/>ordering rule"}}
end

node_app -->|"accepts"| node_uploaded_image
node_app -->|"runs"| node_qwen_pipeline
node_qwen_pipeline -->|"produces"| node_rgba_layers
node_app -->|"shows"| node_layer_view
node_app -->|"packages"| node_layer_export
node_layer_export -->|"includes"| node_pptx_export
node_layer_export -->|"includes"| node_zip_export
node_layer_export -->|"includes"| node_psd_export
node_edit_tool -->|"edits"| node_rgba_layers
node_edit_tool -->|"uses"| node_qwen_edit
node_combine_tool -->|"consumes"| node_rgba_layers
node_combine_tool -->|"requires"| node_layer_order
node_combine_tool -->|"merges"| node_uploaded_image
node_sample_images -.->|"feeds"| node_app
node_sample_images -.->|"feeds"| node_edit_tool
node_local_runtime -->|"launches"| node_app
node_local_runtime -->|"launches"| node_edit_tool
node_local_runtime -->|"launches"| node_combine_tool

click node_app "https://github.com/qwenlm/qwen-image-layered/blob/main/src/app.py"
click node_edit_tool "https://github.com/qwenlm/qwen-image-layered/blob/main/src/tool/edit_rgba_image.py"
click node_combine_tool "https://github.com/qwenlm/qwen-image-layered/blob/main/src/tool/combine_layers.py"
click node_sample_images "https://github.com/qwenlm/qwen-image-layered/tree/main/assets/test_images"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_edit_tool,node_combine_tool,node_local_runtime toneBlue
class node_qwen_pipeline,node_qwen_edit toneAmber
class node_uploaded_image,node_rgba_layers,node_layer_view,node_layer_export,node_pptx_export,node_zip_export,node_psd_export,node_sample_images,node_layer_order toneMint
```

## Components

### Interactive UIs

Standalone Gradio entry points for decomposition, editing, and recomposition.

- [Decompose UI](https://github.com/qwenlm/qwen-image-layered/blob/main/src/app.py): gradio app · Main launch path for uploading an image and generating layered RGBA outputs. · `src/app.py`
- [Edit Layer](https://github.com/qwenlm/qwen-image-layered/blob/main/src/tool/edit_rgba_image.py): gradio tool · Interactive utility for editing individual RGBA layers. · `src/tool/edit_rgba_image.py`
- [Combine Layers](https://github.com/qwenlm/qwen-image-layered/blob/main/src/tool/combine_layers.py): gradio tool · Utility for recomposing multiple RGBA layers into one image. · `src/tool/combine_layers.py`
- **Local Runtime**: python app · Standalone execution model used by each script entry point.

### Model Boundary

External inference pipelines used by the repo as clients, not implemented here.

- **Layered Pipeline**: external model · Diffusers-backed Qwen-Image-Layered inference pipeline used for image decomposition.
- **Edit Model**: external model · Qwen-Image-Edit boundary used to modify isolated RGBA layers.

### Layer I/O

Layered image artifacts, exports, and sample inputs.

- **Input Image**: user asset · Source image provided to the decomposition workflow.
- **RGBA Layers**: layer set · Ordered transparent layers produced by decomposition and consumed by editing and recomposition.
- **Layer Preview**: ui artifact · Interactive inspection of individual layers and their ordering.
- **Layer Export**: export bundle · Packaged layered outputs prepared for downstream use.
- **PPTX**: document export · Presentation-format export preserving layered content.
- **ZIP**: archive export · Compressed export of layer assets and metadata.
- **PSD**: document export · Photoshop-format layered export for external editing tools.
- [Test Images](https://github.com/qwenlm/qwen-image-layered/tree/main/assets/test_images): fixture set · Built-in sample inputs for demos and development. · `assets/test_images`
- **Bottom-to-Top**: ordering rule · Architectural constraint required when recombining layers.

## Connections

- Decompose UI → Input Image: accepts · The decomposition UI starts from a user-supplied image.
- Decompose UI → Layered Pipeline: runs · Hands the image to the layered decomposition pipeline.
- Layered Pipeline → RGBA Layers: produces · Returns an ordered set of RGBA layers.
- Decompose UI → Layer Preview: shows · Exposes generated layers for inspection.
- Decompose UI → Layer Export: packages · Prepares layered outputs for external tools.
- Layer Export → PPTX: includes · One export target is PowerPoint.
- Layer Export → ZIP: includes · One export target is a ZIP archive.
- Layer Export → PSD: includes · One export target is Photoshop format.
- Edit Layer → RGBA Layers: edits · Operates on a single isolated layer at a time.
- Edit Layer → Edit Model: uses · Delegates layer modification to the edit model.
- Combine Layers → RGBA Layers: consumes · Takes multiple layers as inputs.
- Combine Layers → Bottom-to-Top: requires · Layers must be uploaded from bottom to top.
- Combine Layers → Input Image: merges · Produces a recomposed composite image.
- Test Images → Decompose UI: feeds · Provides ready-made inputs for the decomposition demo.
- Test Images → Edit Layer: feeds · Supports local testing of layer editing flows.
- Local Runtime → Decompose UI: launches · Each script is intended to run as a standalone local UI.
- Local Runtime → Edit Layer: launches · The edit utility is also a standalone entry point.
- Local Runtime → Combine Layers: launches · The recomposition utility runs independently.
