mi-ripple

Mi-Ripple

AI Skill — start here

Open skills/mi-ripple/SKILL.md →

AI coding agents should read this skill first. It contains the complete workflow for installing Mi-Ripple, processing an image, inspecting the generated evidence, requesting permission before paid regeneration, and returning the actual result. The skill never authorizes paid regeneration on the user's behalf.

Install it from the canonical repository:

https://github.com/miyang-ai/Mi-Ripple

Direct skill URL:

https://raw.githubusercontent.com/miyang-ai/Mi-Ripple/main/skills/mi-ripple/SKILL.md

Reference implementation of Mi-Ripple, MIYANG's diagnosis-guided workflow for restoring grid-like and scale-like artifacts introduced by iterative, reference-conditioned AI image editing.

Try Mi-Ripple on the MIYANG Lab website →

Experience Mi-Ripple with Alice →

Visit the MIYANG official website →

Mi-Ripple does not apply one aggressive filter to every image. It first separates:

• Periodic lattice artifacts: isolated spectral peaks that can be selectively notched with low measured distortion.
• Granular artifacts in unstructured regions: 3–8 px texture that can be reduced behind a structure-protection mask.
• Content-entangled artifacts: repeated texture overlapping hair, foliage, fabric, or other legitimate detail. These require human review or optional regeneration from a cleaned reference.

[!IMPORTANT] This is a research implementation, not a universal artifact detector. Automatic scores are triage signals. Review the generated heat maps and comparison boards before accepting an output.

Before / after

These are the five comparisons currently used by the MIYANG Lab tool. Open an image to inspect it at native resolution.

Night hair · Image 2.5

The images share the same source composition but come from separate experimental branches: direct regeneration versus cleaned-reference regeneration followed by selective lattice notching. Regeneration is not pixel-aligned restoration and can change fine semantic details.

Moss gorge · Image 2.5

Moss gorge · Image 2.0

Rainforest path · Image 2.0

Ice cave · Image 2.0

Installation

Python 3.11 or newer is required.

git clone https://github.com/miyang-ai/Mi-Ripple.git
cd Mi-Ripple
python -m venv .venv
source .venv/bin/activate
pip install -e .

OpenCV-based face protection is optional:

pip install -e ".[face]"

For development:

pip install -e ".[dev]"
pytest

Quick start

Local deterministic processing is the default:

mi-ripple input.png output/

The output directory contains:

• a diagnosis JSON and visual inspection boards;
• intermediate masks and processed candidates;
• a machine-readable XML decision trace;
• a final image when the deterministic route can deliver one;
• a sidecar containing hashes, parameters, measurements, and the final outcome.

If artifacts overlap image content, the default route stops with needs_human_decision. Optional regeneration requires explicit permission and a MIYANG API key:

export MIYANG_API_KEY=...
mi-ripple input.png output/ --allow-regen --max-regen 1

Regeneration may change image content, dimensions, and color. Its output remains a candidate until a person accepts it.

Python API

from pathlib import Path

from mi_ripple.pipeline import run

result = run(Path("input.png"), Path("output"))
print(result["outcome"], result["final"])

Individual measurement and processing modules are also public:

• mi_ripple.diagnosis
• mi_ripple.scale_index
• mi_ripple.notch
• mi_ripple.spatial
• mi_ripple.reference
• mi_ripple.verify

Method and evidence

The accompanying paper is:

Yicheng Xu, Jiayin Chen, and Muting Wang. Mi-Ripple: Restoring Images Degraded by Iterative AI Editing. MIYANG Technology (Shanghai) Co., Ltd., 2026.

The LaTeX manuscript, references, and publication figures are included in paper/.

Paper figures

Selective notch versus broad spectral suppression

[![Residual comparison for selective notch and soft clipping](https://raw.githubu