ComfyUI-MosaicRestore Introduction
A preview of ComfyUI-MosaicRestore
ComfyUI-MosaicRestore is a ComfyUI custom node that finds mosaic or pixelated areas in an image and attempts to restore them. You can connect a single image or a batch of frames; the node chooses the appropriate processing path automatically. It also produces a mask showing the areas it detected, which you can use elsewhere in your workflow.
The extension is based on the restoration pipeline used by lada. It is useful when you want to try restoring a pixelated region without manually drawing a mask for each image or frame. Restoration has limits, though: if the mosaic has removed too much visual information, no setting can reliably recover the original detail. Treat the output as an attempted reconstruction, not a record of what was originally underneath.
How ComfyUI-MosaicRestore Works
Think of the node as having two jobs: find the mosaic, then rebuild the detected area. A detection model identifies regions that appear pixelated. A separate restoration model processes those regions, while the node outputs a mask that marks where mosaics were found.
The node handles still images and frame batches differently:
- Single image: A still image has no motion for the restoration model to learn from. The node makes five slightly shifted views of the detected region, processes them like a short sequence, and combines the results into one image.
- Multiple frames: The node detects mosaics in each frame, links overlapping detections across frames, and processes the resulting sequence together. This lets the restoration model use changes between frames when rebuilding a region.
You do not need to select a still-image or frame-batch mode. The node decides based on the images you provide.
ComfyUI-MosaicRestore Features
The Mosaic Restore node appears in ComfyUI’s image/restoration category. Its controls let you adjust detection, restoration, and how the models run:
| Input | Default | What it means |
|---|---|---|
image | Required | The image or batch of frames to process. |
detection_model | v4-fast | Chooses the model that locates mosaic regions. An accurate model may find regions a faster model misses, but can take longer. |
restoration_model | basicvsrpp-v1.2 | Chooses the model that rebuilds detected regions. Start with the default for general use. |
device | auto | Chooses where processing runs: auto, cuda, mps, or cpu. Leave it on auto unless you need to select a device explicitly. |
fp16 | true | Uses half-precision processing on a GPU. Turn it off when using a CPU or if the output looks broken. |
detect_face_mosaics | false | Also processes mosaics classified as faces or heads. Enable it when those regions are the ones you intend to restore. |
debug | false | Replaces the normal image output with a four-panel diagnostic view: input, output, detections, and a change heatmap. Use it to see what the node found and where it changed the image. |
keep_loaded | false | Keeps models in video memory between runs, making repeated use faster while continuing to occupy that memory. |
The node has two outputs:
| Output | What you receive |
|---|---|
image | The restored image or frames. With debug enabled, this becomes the four-panel diagnostic view rather than the normal result. |
mask | A mask for each frame: 1.0 inside detected mosaic regions and 0 elsewhere. You can reuse it in later nodes that accept a mask. |
Model weights download when you first select them. They are stored in ComfyUI/models/mosaic_restore/; the extension does not bundle them.
ComfyUI-MosaicRestore Models
Detection models decide where the node should work. All four choices are YOLO11 segmentation detectors:
| Model | Approximate size | When to try it |
|---|---|---|
v3.1-fast | 6 MB | An older fast detector, useful for comparison. |
v3.1-accurate | 21 MB | An older detector that prioritizes accuracy over speed. |
v4-fast | 6 MB | Default. A starting point for balancing speed and detection accuracy. |
v4-accurate | 45 MB | The largest detector. Try it if the default misses mosaic regions; it is slower but may find more of them. |
Restoration models decide how detected areas are rebuilt:
| Model | Approximate size | When to try it |
|---|---|---|
basicvsrpp-v1.2 | 78 MB | Default. The recommended general-purpose choice. |
basicvsrpp-v1.1 | 78 MB | An older general-purpose model from lada, retained for comparison. |
deepmosaics | 102 MB | A legacy DeepMosaics model used as a comparison baseline. It usually produces worse results than the default. Its weights are downloaded from Google Drive. |
A practical first test is to keep both defaults. If the mask misses an area, try v4-accurate: that changes what is detected. If the mask is correct but the rebuilt area is unsatisfying, compare restoration models: that changes what is produced inside the detected area.
ComfyUI-MosaicRestore Troubleshooting
The node does not change the area you expected
- Turn on
debugand run the image again. - Look at the detections panel and the
maskoutput to check whether the area was found. - If it was missed, try
v4-accurate. - If the area is a mosaic classified as a face or head, enable
detect_face_mosaics.
The restored area looks inaccurate or lacks detail
- Check the debug view to confirm the correct region was detected.
- Try
basicvsrpp-v1.2if you selected a different restoration model. - Bear in mind that heavy mosaics can destroy detail the model cannot recover. For a different approach, the author points to DiffusionCreamPy, which uses diffusion-based restoration and generally produces stronger results on heavier mosaics, at the cost of more computation per image.
The image output shows four panels instead of one restored image
Turn off debug. That setting deliberately replaces the normal image output with a diagnostic grid.
The output looks broken when using fp16
Turn off fp16 and run the image again. The original guidance also recommends disabling it when processing on a CPU.
Repeated runs are slow
If you have enough video memory available, enable keep_loaded so the models remain loaded between runs. Turn it off again if you need that memory for other parts of your workflow.
Frequently Asked Questions
Do I need to switch modes for a single image and a batch of frames?
No. The node selects its processing path automatically.
Does the mask show the restored pixels?
No. It marks the regions detected as mosaics. The restored result appears in the image output when debug is off.
Can restoration reveal exactly what was beneath a mosaic?
No. The model attempts to reconstruct missing detail, but the original information may have been destroyed by pixelation.
Why does the first use of a model take extra time?
Model weights are downloaded the first time you select that model.
ComfyUI-MosaicRestore Learn More
- lada — the project whose inference pipeline this node follows. Its video approach provides context for the frame-batch behavior.
- DiffusionCreamPy — an alternative to consider when this node’s restoration is not strong enough, especially for heavier mosaics.
- The extension’s
LICENSEfile — details of its AGPL-3.0 license. The project reuses code from lada and DeepMosaics.
