ComfyUI-MosaicRestore

A ComfyUI custom node that detects and restores mosaic / pixelated regions in images and image batches. Based on the inference pipeline of ladaapp/lada.

Features

• Single image, batch, or video frames — automatic. Connect one image or many; the node figures out which mode to run. No toggle to flip.
• Auto-downloads its own models from HuggingFace into ComfyUI/models/mosaic_restore/ the first time you pick one. Nothing bundled with the repo.
• Mask output showing what the detector found, so you can re-use it downstream.
• Debug toggle that returns a 4-panel preview (input / output / detections / change heatmap) for diagnosing bad results.
• Multiple model choices — pick the YOLO detector and the restoration model from dropdowns.

Not happy with the result?

Mosaic restoration is fundamentally limited by how much information the censoring destroyed. This node mirrors the original lada implementation as closely as possible, so the output quality is the same as lada's own app — sometimes that's enough, sometimes it isn't.

If you need stronger restoration, take a look at Schwi-AI/DiffusionCreamPy. It uses a diffusion model instead of a deterministic restorer and generally produces noticeably better results, especially on heavier mosaics. It costs more compute per image, but it's the better tool when this node isn't getting you there.

Installation

1. Drop this folder into ComfyUI/custom_nodes/.
2. Restart ComfyUI. The first run will pip-install ultralytics if you don't have it.
3. Add the Mosaic Restore node from the image/restoration category and pick your models — the weights are pulled on first use.

Inputs

Input	Type	Default	Notes
image	IMAGE	—	Single image or a batch of frames. Multi-frame input is auto-detected.
detection_model	enum	v4-fast	Which YOLO detector to use. See table below.
restoration_model	enum	basicvsrpp-v1.2	Which restoration model to use. See table below.
device	enum	auto	auto / cuda / mps / cpu.
fp16	BOOLEAN	true	Half precision on GPU. Disable on CPU or if outputs look broken.
detect_face_mosaics	BOOLEAN	false	Also restore mosaics the detector classifies as faces / heads.
debug	BOOLEAN	false	Replace the image output with a 4-panel debug grid.
keep_loaded	BOOLEAN	false	Keep models in VRAM between runs for faster re-use.

Outputs

Output	Type	Notes
image	IMAGE	Restored frames. Becomes the 4-panel debug grid when debug is enabled.
mask	MASK	Detection mask per frame (1.0 inside mosaic regions, 0 elsewhere).

Models

Detection (detection_model) — YOLO11 segmentation:

Name	Size	Notes
v3.1-fast	~6 MB	Older, fast.
v3.1-accurate	~21 MB	Older, more accurate.
v4-fast	~6 MB	Default. Good balance of speed/accuracy.
v4-accurate	~45 MB	Largest detector. Slower but a bit more recall.

Restoration (restoration_model):

Name	Size	Notes
basicvsrpp-v1.2	~78 MB	Default. Best general-purpose quality.
basicvsrpp-v1.1	~78 MB	Older generic model from lada. Kept for comparison.
deepmosaics	~102 MB	Legacy DeepMosaics model (downloaded from Google Drive). Comparison baseline — usually worse output.

How it works

The node has two paths and picks one automatically based on how many frames you give it.

Single image. Feeding the model a still gives it nothing to track. To work around this, the node makes 5 tiny pan-shifted copies of the detected region, runs them through BasicVSR++ as if they were a short video, then averages the results back into one image. This noticeably beats the obvious "send the same frame 5 times" approach.

Multi-frame batch. Each frame is detected, overlapping detections are linked across frames into a clip, and the whole clip goes through BasicVSR++ in one pass so the model can use the real motion between frames. This matches what lada's own app does for videos.

License

This project re-uses code from ladaapp/lada (AGPL-3.0) and DeepMosaics (GPL-3.0). The combined work is distributed under AGPL-3.0. See LICENSE for details.