How qwenlm/qwen-image-layered works
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: app.py Decompose UI · combine_layers.py Combine Layers · edit_rgba_image.py Edit Layer · test_images Test Images
Components 15
Interactive UIs
Standalone Gradio entry points for decomposition, editing, and recomposition.
- Decompose UI · Main launch path for uploading an image and generating layered RGBA outputs.
src/app.py - Edit Layer · Interactive utility for editing individual RGBA layers.
src/tool/edit_rgba_image.py - Combine Layers · Utility for recomposing multiple RGBA layers into one image.
src/tool/combine_layers.py - Local Runtime · 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 · Diffusers-backed Qwen-Image-Layered inference pipeline used for image decomposition.
- Edit Model · Qwen-Image-Edit boundary used to modify isolated RGBA layers.
Layer I/O
Layered image artifacts, exports, and sample inputs.
- Input Image · Source image provided to the decomposition workflow.
- RGBA Layers · Ordered transparent layers produced by decomposition and consumed by editing and recomposition.
- Layer Preview · Interactive inspection of individual layers and their ordering.
- Layer Export · Packaged layered outputs prepared for downstream use.
- PPTX · Presentation-format export preserving layered content.
- ZIP · Compressed export of layer assets and metadata.
- PSD · Photoshop-format layered export for external editing tools.
- Test Images · Built-in sample inputs for demos and development.
assets/test_images - Bottom-to-Top · Architectural constraint required when recombining layers.
Connections 18
- 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.