🌊 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

Use latest.safetensors for general scenes and latest-I.safetensors for infographics. These are standard SFT LoRA adapters; load one as maskflow. The older S/SEC checkpoints remain available for their matching distilled adapters. Do not substitute a latest adapter for the SFT adapter required by an older distilled checkpoint.

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=latest.safetensors \
  runtime.num_inference_steps=50 \
  runtime.text_cfg_scale=4.0 \
  output.path=outputs/result.png

For infographics, change the standard command to checkpoint.sft_weight_name=latest-I.safetensors.

Distillation inference (older S/SEC checkpoints): 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-tcfg4-step8.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.

Visualization

General scene editing: object removal

The first comparison from Appendix E.1.4 shows removal within the masked region. The masked source is shown first and MaskFlow appears in the final panel.

Infographic editing: object replacement

The first comparison from Appendix E.2.3 shows replacement of a selected element in an infographic. The comparison includes the masked source, baseline outputs, and MaskFlow in the final panel.

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