StableI2I

Official implementation of StableI2I: Spotting Unintended Changes in Image-to-Image Transition (ICML 2026)

Questions: lijiayang.cs@gmail.com · looking forward to your ⭐

📌 TODOs

• release code
• release ckpt
• release pip-pkg (PyPI)
• release arxiv
• ICML version paper

Overview

Most image-to-image (I2I) evaluations focus on instruction following and perceptual quality. They rarely check whether the output still preserves the semantic correspondence and spatial structure of the input. StableI2I is a unified evaluation framework for content fidelity and pre–post consistency across editing and restoration, without requiring a reference image.

Evaluation prompts are bundled in the Python package. Callers only pass the input image, output image, and task prompt.

Install

pip install stablei2i

The runtime matches Qwen3-VL (transformers>=4.57.0). From source:

git clone https://github.com/Henry-Lee-real/StableI2I.git
cd StableI2I
pip install -e .

Checkpoints

StableI2I defaults to lijiayangCS/StableI2I_PLUS. You can also pass a local folder.

Quick Start

Load the judge once, then reuse it.

from stablei2i import StableI2I

judge = StableI2I(model="lijiayangCS/StableI2I_PLUS")  # or a local ckpt path

Images may be a file path, PIL.Image, numpy array, or torch.Tensor.

Single pair

result = judge.evaluate(
    input_image="before.png",
    output_image="after.png",
    prompt="Add a wooden bench along the path.",
    mode="cot",  # simple | cot | score, or a list of them
    dimensions="semantic,structure,lowlevel",
)
print(result["result"])

JSONL batch

Each line needs id, input_image, output_image. prompt is optional. Aliases before_image / after_image are accepted.

{"id":"case-1","input_image":"example/000155856.jpg","output_image":"example/000155856_dup2.png","prompt":"Add a wooden bench along the path."}

rows = judge.evaluate_jsonl(
    "test_jsonl/sample.jsonl",
    output_jsonl="outputs/results.jsonl",
    mode="cot",
)

Online evaluation / RL

Keep one StableI2I in the training process and score in-memory images. score mode returns 0–10; normalize=True maps it to [0, 1].

reward = judge.reward(src_image, gen_image, prompt, normalize=True)
reward_fn = judge.as_reward_fn(normalize=True)  # (input, output, prompt) -> float

# GRPO / custom loop
r = reward_fn(src_image, gen_image, task_prompt)

For training, disable forced CuDNN determinism:

judge = StableI2I(model="lijiayangCS/StableI2I_PLUS", deterministic=False, gpu_id=0)

CLI

# single pair
stablei2i \
  --input-image before.png \
  --output-image after.png \
  --prompt "Restore the image." \
  --mode score \
  --ckpt lijiayangCS/StableI2I_PLUS

# jsonl
stablei2i \
  --jsonl test_jsonl/sample.jsonl \
  --ckpt lijiayangCS/StableI2I_PLUS \
  --mode cot \
  --dimensions semantic,structure,lowlevel \
  --output-jsonl outputs/results.jsonl

python test.py ... is the same entry as stablei2i. Full flags, JSONL rules, and output schemas: infer.md.

Modes

Pass several modes at once (--mode simple,cot,score) to group results by mode name.

Web Demo

app.py starts a FastAPI UI (built-in examples, local path, upload).

export MODEL_PATH=path/to/ckpt
export GPU_ID=0
export HOST=127.0.0.1
export PORT=10004
python app.py

Then open http://127.0.0.1:10004

Training

• SFT: official Qwen3-VL finetuning
• GRPO / alignment: ms-swift, using StableI2I.as_reward_fn() as the online fidelity reward

Citation

@article{li2026stablei2i,
  title={StableI2I: Spotting Unintended Changes in Image-to-Image Transition},
  author={Li, Jiayang and Cao, Shuo and Li, Xiaohui and Zhang, Zhizhen and Zhu, Kaiwen and Duan, Yule and Qiao, Yu and Zhang, Jian and Liu, Yihao},
  journal={arXiv preprint arXiv:2605.04453},
  year={2026}
}