Save 4 hours! We auto-setup your workflow! Free!

Drop your workflow.json — we handle every dependency, custom node, and model. Just open the link and run.

Auto-Setup Workflow Json (Free) Now!
ComfyUI > Nodes > ComfyUI-MosaicRestore > Mosaic Restore

ComfyUI Node: Mosaic Restore

Class Name

MosaicRestore

Category
image/restoration
Author
l33chking (Account age: 3119days)
Extension
ComfyUI-MosaicRestore
Latest Updated
2026-06-29
Github Stars
0.0K

How to Install ComfyUI-MosaicRestore

Install this extension via the ComfyUI Manager by searching for ComfyUI-MosaicRestore
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter ComfyUI-MosaicRestore in the search bar
After installation, click the Restart button to restart ComfyUI. Then, manually refresh your browser to clear the cache and access the updated list of nodes.

Visit ComfyUI Online for ready-to-use ComfyUI environment

  • Free trial available
  • 16GB VRAM to 80GB VRAM GPU machines
  • 400+ preloaded models/nodes
  • Freedom to upload custom models/nodes
  • 200+ ready-to-run workflows
  • 100% private workspace with up to 200GB storage
  • Dedicated Support

Run ComfyUI Online

Mosaic Restore Description

Detects and restores mosaic regions in images or video frames, with matching detection masks.

Mosaic Restore:

MosaicRestore detects mosaic or pixelated regions and applies a restoration model to them. It is designed for both still images and batches of frames: a single image uses a motion-simulating approach to support restoration, while a batch of two or more frames is treated as video so the model can use information across frames. This can help produce more consistent results through a sequence. Restoration estimates missing visual detail; it cannot guarantee recovery of what was originally behind the mosaic.

Mosaic Restore Input Parameters:

image

The image or batch you want to process. It must be a ComfyUI IMAGE with three RGB color channels. A single image is processed in still-image mode; a batch of two or more images is processed in video mode, so use a sequential frame batch when you want the node to draw on information across frames. No minimum or maximum image dimensions or batch length are specified by the node, and there is no default value. Images smaller than two pixels in either dimension cannot produce the usual debug grid, though the source does not establish whether the restoration models can process them.

detection_model

Selects the model that finds candidate mosaic regions before restoration. This choice affects which areas the node attempts to restore and which areas appear in the detection mask. The default is v4-fast. The available options come from the installed detection-model registry and are not enumerated in the provided source, so no complete option list or numeric minimum and maximum can be stated.

restoration_model

Selects the model used to generate restored detail in detected regions. Different available models may produce different results, but the provided source does not establish a quality or speed ranking. The default is basicvsrpp-v1.2. Options come from the installed restoration-model registry; the complete list and numeric limits are not specified here.

device

Chooses where the models run. Options are auto (default), cuda, mps, and cpu. With auto, the node chooses CUDA if available, then Apple MPS if available, and otherwise CPU. If you explicitly select unavailable CUDA or MPS, it logs a warning and falls back to CPU. This setting can affect processing speed and available memory, but does not change which regions you ask the node to detect. There is no numeric minimum or maximum.

fp16

Controls whether eligible processing uses half-precision calculations, which can reduce GPU memory use and improve speed. Options are true (default) and false. In this implementation, the setting takes effect only when the selected device resolves to CUDA; selecting it on MPS or CPU does not enable half precision. Disable it if you encounter unstable results such as NaN values. There is no numeric minimum or maximum.

detect_face_mosaics

Controls whether mosaics classified as faces or heads are also eligible for restoration. Options are false (default) and true. Leave it off for the node’s default NSFW-only detection behavior, or turn it on when you also want to process mosaic-covered faces or heads. Enabling it changes the regions considered for restoration; it does not guarantee every face mosaic will be detected. There is no numeric minimum or maximum.

debug

Controls whether the image result becomes a diagnostic comparison instead of the normal restored image. Options are false (default) and true. When enabled, each frame is displayed as a 2×2 grid: source at top left, restored result at top right, detected regions tinted red at bottom left, and a pixel-difference heatmap at bottom right. The grid retains the source dimensions, so each panel is smaller than the original frame. There is no numeric minimum or maximum.

keep_loaded

Controls whether the detection and restoration models remain cached after processing. Options are false (default) and true. Enable it when you expect to run the node repeatedly and have enough GPU memory; keeping the models loaded can make later runs faster. Leave it off when memory is limited or you only need one run: the node unloads its cached models when it finishes. There is no numeric minimum or maximum.

Mosaic Restore Output Parameters:

image

A ComfyUI IMAGE containing one result for each input image or frame, in the same order. Normally this is the restored result. With debug enabled, it is instead the diagnostic 2×2 grid for each frame, not an image to treat as the final restoration. If restoration fails for a single image, the node logs the failure and passes that image through unchanged; a failed video run first falls back to processing its frames individually.

mask

A ComfyUI MASK containing one detection mask per input image or frame, in matching order. It represents the mosaic regions identified during processing, with mask values scaled from 0 to 1 for use in a ComfyUI workflow. An all-zero mask is returned when single-image processing fails or an individual frame fails during video fallback. An empty mask therefore does not, by itself, prove that the source contains no mosaic.

Mosaic Restore Usage Tips:

  • Start with the default models and device set to auto. Change models only after comparing results on the same source, since the available model choices depend on your installation.
  • Pass sequential frames together as one batch when processing a clip. A batch of two or more frames activates video processing; one frame uses still-image processing.
  • Turn on debug to inspect where detection occurred and how much the restored result differs from the source. Turn it off before using the image result as your final full-frame output.
  • Enable detect_face_mosaics when covered faces or heads are part of what you intend to process. If an expected region is missed, inspect the debug detection panel and the mask output before changing restoration settings.
  • On CUDA, try the default fp16 setting for speed and memory efficiency. Turn it off if results are unstable. On CPU or MPS, this node does not enable half precision.
  • Set keep_loaded to true for repeated runs when GPU memory permits. Keep it false if other workflow nodes need that memory after restoration.

Mosaic Restore Common Errors and Solutions:

Expected (B, H, W, 3) IMAGE tensor, got shape ...

  • Explanation: The supplied image does not have the four-dimensional batch, height, width, and three-color-channel shape expected by the node. This validation error occurs before its restoration fallback.
  • Solution: Connect a standard three-channel ComfyUI IMAGE output. If your source has another channel arrangement, convert it to RGB before connecting it.

CUDA requested but unavailable; falling back to CPU.

  • Explanation: device is set to cuda, but CUDA is not available to this installation. Processing continues on CPU and may be slower.
  • Solution: Set device to auto or cpu, or check that your CUDA-capable hardware and PyTorch installation are available to ComfyUI.

MPS requested but unavailable; falling back to CPU.

  • Explanation: device is set to mps, but Apple MPS is not available. Processing continues on CPU.
  • Solution: Set device to auto or cpu, or check MPS availability in the environment running ComfyUI.

Video-mode restoration failed; falling back to per-frame still mode.

  • Explanation: Processing the batch together failed. The node logs the underlying error and retries each frame separately, so the results may lack the consistency provided by video processing.
  • Solution: Inspect the accompanying log for the underlying cause. Try a shorter frame batch or a different available model, and ensure your selected device has sufficient resources.

Still fallback failed for frame ...

  • Explanation: After video processing failed, restoration also failed for the indicated frame. The node returns that frame unchanged with an all-zero mask.
  • Solution: Check the full logged error, then test the affected frame on its own. Confirm that the selected models are available and try a smaller image or a device with sufficient memory if the log indicates a resource problem.

Single-image restoration failed; passing through.

  • Explanation: Restoration failed for a single image. The node logs the underlying error and returns the original image with an all-zero mask rather than a restored result.
  • Solution: Read the accompanying error details. Confirm the model choices, allow any first-use model download to complete, and check device memory if the log reports a loading or allocation failure.

IndexError: list index out of range

  • Explanation: An empty image batch can leave the node with no first image to process. The code accesses the first frame in single-image mode without an explicit empty-batch check.
  • Solution: Ensure the connected IMAGE contains at least one image before running MosaicRestore.

Mosaic Restore Related Nodes

Go back to the extension to check out more related nodes.
ComfyUI-MosaicRestore
RunComfy
Copyright 2025 RunComfy. All Rights Reserved.

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

Mosaic Restore