🌊 MaskFlow: Precise, Consistent and Seamless Regional Image Editing

Overview

🌊 Models: This repository is the official implementation for paper "MaskFlow: Precise, Consistent and Seamless Regional Image Editing", including:

• Pipelines
• Schedulers
• DataModule
• Trainers
• Evaluators
• Editor

🎨 Dataset: MaskEdit-10k is available on 🤗 Hugging Face.

💜 Local Editor: Editor is relsead for pratical user-specified and freeform masks designing, the editor can be deployed on the local and server.

🩵 Demo (Comming soon): MaskFlow is integrated into LightX2V for an accessible inference workflow.

⭐️ Please leave your star if these can help you to create attractive artworks ⭐️

• Overview
• Introduction
• Editor
• Quick Start
  • 1. Set up the environment
  • 2. Prepare the inputs
  • 3. Choose a checkpoint
  • 4. Run standard 50-step inference
• Visualization
• License
• Citation

MaskFlow is a mask-aware 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.

We release the image editor for convenient usage, supporting:

• Freeform Mask: User can draw masks on the source image with any shapes to identify the editable region. The masks can also be saved for future use!
• Online Inference: The editor can be deployed on the server to share the convenience to more people.

After environment is ready, just run uv run python -m editor, and this editor will deployed on http://127.0.0.1:7890 on the local by default.

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

git clone https://github.com/ReyChiaro/MaskFlow.git
cd MaskFlow

# Install uv if it is not already available.
python -m pip install uv

# Reproduce the locked Python 3.12 environment.
uv python install 3.12
uv sync

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Prepare a source RGB image and a spatially aligned mask. White pixels in the mask indicate the region to edit; black pixels indicate the region to preserve. If a prompt comes from MaskEdit-10k and contains [MASK_AREA], replace the placeholder with a natural referring phrase before inference.

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.

The LoRA adapters are hosted in ReyChiaro/MaskFlow. Diffusers downloads and caches the selected files automatically.

S denotes training on the scene split, while SEC denotes training on all scene and infographic splits. A distilled LoRA is a residual adapter: it must be used with its matching standard SFT LoRA (S with S, or SEC with SEC). The SFT adapter is loaded as maskflow, and the distilled adapter is loaded as dmd.

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, use checkpoint.sft_weight_name=latest-I.safetensors with the same command.

The base model defaults to Qwen/Qwen-Image-Edit-2511, and the output directory is created automatically.

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.

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.

MaskFlow code and adapter weights are released under the MIT License. Use of the Qwen base model and third-party datasets remains subject to their respective licenses and terms.

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