🌊 MaskFlow: Precise, Consistent and Seamless Regional Image Editing

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. 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.
• The variant SEC means that the model is trained with all splits in 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.

Quick start

1. Install the official code

MaskFlow requires Python 3.12 or later. An NVIDIA GPU is recommended.

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

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

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:

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.

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. Use of the base model is also subject to its own license and terms.

Citation

@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},
}