Upload weights

.gitattributes

@@ -1,35 +1 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
 *.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chill
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MANIFEST.json

@@ -0,0 +1,82 @@
+{
+  "schema_version": 2,
+  "repository": "ReyChiaro/MaskFlow",
+  "base_model": "Qwen/Qwen-Image-Edit-2511",
+  "format": "diffusers-peft-lora-safetensors",
+  "adapter_names": {
+    "sft": "maskflow",
+    "dmd": "dmd"
+  },
+  "weights": [
+    {
+      "filename": "maskflow-S.safetensors",
+      "variant": "S",
+      "role": "sft",
+      "size_bytes": 1510070696,
+      "sha256": "abde09d33238e6b2133a4a7dd86b9830ef93a8d97978e5ba437d60675c75dafd",
+      "rank": 256,
+      "alpha": 256,
+      "recommended_num_inference_steps": 50,
+      "recommended_text_cfg_scale": 4.0
+    },
+    {
+      "filename": "maskflow-S-tcfg4-step8.safetensors",
+      "variant": "S distilled 8-step",
+      "role": "dmd",
+      "requires": "maskflow-S.safetensors",
+      "size_bytes": 1510070656,
+      "sha256": "109580b294c3993984303fa39cb1dc77dfc90fc892075e90d85d1afd079a49e7",
+      "rank": 256,
+      "alpha": 256,
+      "recommended_num_inference_steps": 8,
+      "recommended_text_cfg_scale": 4.0
+    },
+    {
+      "filename": "maskflow-S-tcfg4-step16.safetensors",
+      "variant": "S distilled 16-step",
+      "role": "dmd",
+      "requires": "maskflow-S.safetensors",
+      "size_bytes": 1510070656,
+      "sha256": "e9292a27cb68b8021d84cea8731ef656f2dcf0a8c66f57a577e7591dd03f0b10",
+      "rank": 256,
+      "alpha": 256,
+      "recommended_num_inference_steps": 16,
+      "recommended_text_cfg_scale": 4.0
+    },
+    {
+      "filename": "maskflow-SEC.safetensors",
+      "variant": "SEC",
+      "role": "sft",
+      "size_bytes": 1510070656,
+      "sha256": "972a2e54547474aaf3cb284f17395445bfba427b56da22b1efbbeea6dbc5fcdf",
+      "rank": 256,
+      "alpha": 256,
+      "recommended_num_inference_steps": 50,
+      "recommended_text_cfg_scale": 4.0
+    },
+    {
+      "filename": "maskflow-SEC-tcfg4-step16.safetensors",
+      "variant": "SEC distilled 16-step",
+      "role": "dmd",
+      "requires": "maskflow-SEC.safetensors",
+      "size_bytes": 1510070656,
+      "sha256": "4af5c87f43a892e5ac07c080e4bc67b3ee88e576371e6255c1132902ebf4646f",
+      "rank": 256,
+      "alpha": 256,
+      "recommended_num_inference_steps": 16,
+      "recommended_text_cfg_scale": 4.0
+    },
+    {
+      "filename": "maskflow-SEC-tcfg4-step8.safetensors",
+      "variant": "SEC distilled 8-step",
+      "role": "dmd",
+      "requires": "maskflow-SEC.safetensors",
+      "size_bytes": 1510070656,
+      "sha256": "157b9f869457b790160099cf3c5d4fbe44d5c46739a3ae49b1fb7abeda5fda1c",
+      "rank": 256,
+      "alpha": 256,
+      "recommended_num_inference_steps": 8,
+      "recommended_text_cfg_scale": 4.0
+    }
+  ]
+}

README.md

@@ -1,3 +1,167 @@
 ---
 license: mit
+library_name: diffusers
+pipeline_tag: image-to-image
+base_model: Qwen/Qwen-Image-Edit-2511
+datasets:
+  - ReyChiaro/MaskEdit-10k
+tags:
+  - image-editing
+  - regional-image-editing
+  - mask-guided-image-editing
+  - qwen-image
+  - lora
+  - diffusers
+inference: false
 ---
+
+<img src="https://raw.githubusercontent.com/ReyChiaro/MaskFlow/main/assets/readme/maskflow-header.svg" width="100%" alt="MaskFlow" />
+
+# 🌊 MaskFlow: Precise, Consistent and Seamless Regional Image Editing
+
+<p align="center">
+  <a href="https://reychiaro.github.io/MaskFlow"><img src="https://img.shields.io/badge/Project_Page-7C3AED?logo=googlechrome&amp;logoColor=white" alt="Project Page" /></a>
+  <a href="https://arxiv.org/abs/2608.06929"><img src="https://img.shields.io/badge/arXiv-Paper-751D38?logo=arxiv&amp;logoColor=white" alt="arXiv Paper" /></a>
+  <a href="https://github.com/ReyChiaro/MaskFlow"><img src="https://img.shields.io/badge/GitHub-Code-E38DA7?logo=github&amp;logoColor=white" alt="GitHub Code" /></a>
+  <a href="https://huggingface.co/ReyChiaro/MaskFlow"><img src="https://img.shields.io/badge/Hugging_Face-Model-EFD046?logo=huggingface&amp;logoColor=white" alt="Hugging Face Model" /></a>
+  <a href="https://huggingface.co/datasets/ReyChiaro/MaskEdit-10k"><img src="https://img.shields.io/badge/Hugging_Face-Dataset-EFD046?logo=huggingface&amp;logoColor=white" alt="Hugging Face Dataset" /></a>
+  <a href="https://github.com/ModelTC/LightX2V"><img src="https://img.shields.io/badge/LightX2V-Demo-67A7E8?logo=github&amp;logoColor=white" alt="LightX2V Demo" /></a>
+</p>
+
+MaskFlow is a mask-based framework for precise regional image editing. Given a source image, a spatial mask, and a text instruction, it edits the selected region while preserving the surrounding content. Its localized generation process and Soft-Poisson refinement improve regional control, background consistency, and boundary quality.
+
+These files are LoRA adapters for the base model [`Qwen/Qwen-Image-Edit-2511`](https://huggingface.co/Qwen/Qwen-Image-Edit-2511). The official MaskFlow pipeline is required for mask-conditioned editing and Soft-Poisson refinement, this model repository contains adapter weights rather than a standalone Diffusers pipeline.
+
+## Available weights
+
+| File | Variant | Steps | Text CFG | Intended use |
+|---|---|---:|---:|---|
+| `maskflow-S.safetensors` | S | 50 | 4.0 | Standard checkpoint trained with `scene` |
+| `maskflow-S-tcfg4-step8.safetensors` | S distilled | 8 | 4.0 | Faster inference |
+| `maskflow-S-tcfg4-step16.safetensors` | S distilled | 16 | 4.0 | Faster inference |
+| `maskflow-SEC.safetensors` | SEC | 50 | 4.0 | Standard checkpoint trained with `scene+infographics` |
+| `maskflow-SEC-tcfg4-step8.safetensors` | SEC distilled | 8 | 4.0 | Faster inference |
+| `maskflow-SEC-tcfg4-step16.safetensors` | SEC distilled | 16 | 4.0 | Faster inference |
+
+> NOTE:
+> - The variant `S` means that the model is trained with the `scene` split in [MaskEdit-10k](https://huggingface.co/datasets/ReyChiaro/MaskEdit-10k).
+> - The variant `SEC` means that the model is trained with all splits in [MaskEdit-10k](https://huggingface.co/datasets/ReyChiaro/MaskEdit-10k).
+> - A distilled LoRA is a residual adapter and must be used together with the matching standard SFT LoRA (`S` with `S`, or `SEC` with `SEC`). The SFT adapter is loaded as `maskflow`, while the distilled adapter is loaded as `dmd`.
+> - Although the student is distilled with teacher text classifier-free guidance, we recommend enabling CFG during student inference for better performance.
+
+<!-- The `S` and `SEC` identifiers follow the official release naming. All adapters use LoRA rank 256 and alpha 256. Exact file sizes and SHA-256 checksums are recorded in [`MANIFEST.json`](./MANIFEST.json). -->
+
+## Quick start
+
+### 1. Install the official code
+
+MaskFlow requires Python 3.12 or later. An NVIDIA GPU is recommended.
+
+```bash
+git clone https://github.com/ReyChiaro/MaskFlow.git
+cd MaskFlow
+python -m pip install uv
+uv python install 3.12
+uv sync
+```
+
+### 2. Prepare inputs
+
+Prepare a source image and a spatially aligned mask. White pixels in the mask indicate the edit region; black pixels indicate the area to preserve.
+
+### 3. Run inference
+
+No manual weight download is required. Diffusers downloads and caches the selected file on first use.
+
+**Standard usage:** Load the standard trained LoRA into model using the following scripts
+
+```bash
+uv run python inference.py \
+  input.source=/absolute/path/to/source.png \
+  input.mask=/absolute/path/to/mask.png \
+  'input.prompt=Replace the masked object with a red ceramic vase.' \
+  checkpoint.sft_path=ReyChiaro/MaskFlow \
+  checkpoint.sft_weight_name=maskflow-S.safetensors \
+  runtime.num_inference_steps=50 \
+  runtime.text_cfg_scale=4.0 \
+  output.path=outputs/result.png
+```
+
+**Distillation inference:** Load *both* SFT LoRA and distilled LoRA into model to enable less steps inference
+
+```bash
+uv run python inference.py \
+  input.source=/absolute/path/to/source.png \
+  input.mask=/absolute/path/to/mask.png \
+  'input.prompt=Replace the masked object with a red ceramic vase.' \
+  checkpoint.sft_path=ReyChiaro/MaskFlow \
+  checkpoint.sft_weight_name=maskflow-S.safetensors \
+  checkpoint.dmd_path=ReyChiaro/MaskFlow \
+  checkpoint.dmd_weight_name=maskflow-S.safetensors \
+  runtime.num_inference_steps=8 \
+  runtime.text_cfg_scale=4.0 \
+  output.path=outputs/result.png
+```
+
+> We recommand enable student classifier-free guidance in distillation version to get better performance.
+
+To use local files, pass each `.safetensors` path and leave its corresponding `weight_name` unset:
+
+```bash
+checkpoint.sft_path=/absolute/path/to/maskflow-S.safetensors \
+checkpoint.dmd_path=/absolute/path/to/maskflow-S-tcfg4-step8.safetensors
+```
+
+## Loading the LoRA adapter with Diffusers
+
+The following snippet only demonstrates adapter loading. Use the official MaskFlow pipeline above for actual mask-guided editing.
+
+```python
+import torch
+from diffusers import QwenImageTransformer2DModel
+
+transformer = QwenImageTransformer2DModel.from_pretrained(
+    "Qwen/Qwen-Image-Edit-2511",
+    subfolder="transformer",
+    torch_dtype=torch.bfloat16,
+)
+# Apply the standard SFT LoRA to the base transformer first.
+transformer.load_lora_adapter(
+    "ReyChiaro/MaskFlow",
+    weight_name="maskflow-SEC.safetensors",
+    prefix=None,
+    adapter_name="maskflow",
+)
+transformer.set_adapter("maskflow")
+transformer.fuse_lora(adapter_names=["maskflow"], safe_fusing=True)
+transformer.unload_lora()
+
+# The distilled LoRA is trained as a residual on top of the SFT model.
+transformer.load_lora_adapter(
+    "ReyChiaro/MaskFlow",
+    weight_name="maskflow-SEC-tcfg4-step8.safetensors",
+    prefix=None,
+    adapter_name="dmd",
+)
+transformer.set_adapter("dmd")
+```
+
+> More usage can refer to `inference.py`.
+
+## License
+
+The MaskFlow adapter weights and repository materials are released under the MIT License. See [`LICENSE`](./LICENSE). Use of the base model is also subject to its own license and terms.
+
+## Citation
+
+```bibtex
+@misc{xu2026maskflowpreciseconsistentseamless,
+  title={MaskFlow: Precise, Consistent and Seamless Regional Image Editing},
+  author={Rui Xu and Yang Yong and Shunzi Yang and Ruihao Gong and Chengtao Lv},
+  year={2026},
+  eprint={2608.06929},
+  archivePrefix={arXiv},
+  primaryClass={cs.CV},
+  url={https://arxiv.org/abs/2608.06929},
+}
+```

maskflow-S-tcfg4-step16.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e9292a27cb68b8021d84cea8731ef656f2dcf0a8c66f57a577e7591dd03f0b10
+size 1510070656

maskflow-S-tcfg4-step8.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:109580b294c3993984303fa39cb1dc77dfc90fc892075e90d85d1afd079a49e7
+size 1510070656

maskflow-S.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:abde09d33238e6b2133a4a7dd86b9830ef93a8d97978e5ba437d60675c75dafd
+size 1510070696

maskflow-SEC-tcfg4-step16.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4af5c87f43a892e5ac07c080e4bc67b3ee88e576371e6255c1132902ebf4646f
+size 1510070656

maskflow-SEC-tcfg4-step8.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:157b9f869457b790160099cf3c5d4fbe44d5c46739a3ae49b1fb7abeda5fda1c
+size 1510070656

maskflow-SEC.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:972a2e54547474aaf3cb284f17395445bfba427b56da22b1efbbeea6dbc5fcdf
+size 1510070656