HunyuanImage-3.0 Tiled Refine:
HunyuanImage3TiledRefine prepares HunyuanImage-3.0 for a tiled refinement pass on an enlarged image that would be too large to process comfortably in one pass. Rather than asking the model to work on the entire canvas at once, it processes overlapping sections at every denoising step and combines their predictions using softly feathered blending, a technique described in the implementation as MultiDiffusion. This blending reduces abrupt transitions between neighboring sections while allowing the canvas to extend beyond the approximately 2048 × 2048 size described as manageable by a single sequence. It is intended for image-to-image refinement, where an existing enlarged image provides the overall composition and the model refines its appearance with partial denoising. The node does not enlarge or render an image by itself; it changes how the model operates during a subsequent sampling pass.
HunyuanImage-3.0 Tiled Refine Input Parameters:
model
The required MODEL connection supplies the model that you want to prepare for tiled refinement. In the intended workflow, this is your HunyuanImage-3.0 model. The node clones the supplied model and applies the tiled-denoising behavior to that clone, leaving the incoming model object unchanged by this operation. During subsequent sampling, the modified model processes overlapping portions of the latent image—the compressed image representation used during denoising—instead of handling the entire enlarged canvas in a single model call. This parameter has no numeric range or default value; you must connect a compatible model from your workflow. The supplied source does not establish compatibility with unrelated model families.
tile_width
The required INT parameter sets the width of each processing tile in image-space pixels. Its default is 1024, minimum is 256, maximum is 2048, and adjustment step is 16. Internally, the node converts this width into the corresponding latent-space width using the model's VAE spatial factor. Wider tiles let each model call see more horizontal context, which can help features remain coherent across a larger region, but generally require more working memory per call. Narrower tiles reduce the size of each individual model call but may require more tiles to cover the same canvas. This setting controls processing regions, not the final image width; the enlarged latent supplied to the sampler determines the canvas size. Encode your prompt conditioning for the chosen tile width and height rather than for the full enlarged canvas.
tile_height
The required INT parameter sets the height of each processing tile in image-space pixels. Its default is 1024, minimum is 256, maximum is 2048, and adjustment step is 16. Like the width, this value is converted to latent-space units before tiled processing begins. Taller tiles provide more vertical context within each model call, while shorter tiles reduce the area processed at once and can help when memory is limited. Width and height work together to determine the area of each tile, so increasing both can substantially increase the memory needed for an individual call. You can choose rectangular tiles when appropriate, but the prompt conditioning should be encoded for those same dimensions. This setting does not resize your image or define its final height.
overlap
The required INT parameter specifies the amount of overlap between neighboring tiles in image-space pixels. Its default is 256, minimum is 0, maximum is 1024, and adjustment step is 16. The node converts this distance into latent-space units, and the refinement implementation blends tile predictions with cosine-shaped feathering weights that soften their edges. Overlap gives adjacent processing regions shared image content and a shared area in which their predictions can be blended, helping reduce visible boundaries. Increasing overlap generally increases repeated processing and can make sampling slower; reducing it reduces that extra work but gives neighboring tiles less shared context. A value of 0 requests no overlap, so there is no shared region for blending neighboring predictions. Keep overlap smaller than both tile dimensions as a practical configuration safeguard; the exposed numeric range does not itself guarantee that every combination is suitable.
HunyuanImage-3.0 Tiled Refine Output Parameters:
MODEL
The MODEL output is the cloned model with tiled-denoising behavior installed. Connect it to the model input of the sampler that performs your refinement pass. At each denoising step, the attached behavior runs the model over overlapping latent tiles and blends their predictions into a result for the larger canvas. This output is not a finished image, an enlarged image, or a latent; it is a model prepared to process an enlarged latent through tiled sampling. To obtain the refined image, you still need prompt conditioning, an upscaled latent, a sampling pass with denoise below 1, and the usual decoding stage. The original incoming model remains available for other workflow branches without this node's modification.
HunyuanImage-3.0 Tiled Refine Usage Tips:
- Build the refinement stage around an existing enlarged image: prepare an upscaled latent, connect this node's MODEL output to your sampler, supply the conditioning, and decode the sampled latent afterward. This node does not perform the enlargement itself.
- Start with the defaults of 1024 × 1024 tiles and 256 overlap. They provide a straightforward baseline before you adjust memory use, processing time, or blending behavior.
- Encode the prompt at the tile dimensions, not the full canvas dimensions. For example, when refining a 3072 × 3072 latent with 1024 × 1024 tiles, use 1024 × 1024 as the conditioning geometry while keeping the sampler's latent at the enlarged canvas size.
- Set the sampler's denoise below 1, as specified by the node's intended workflow. Lower denoise generally preserves more of the enlarged source image, while higher values allow greater changes. Denoise is configured on the sampler, not on this node.
- If GPU memory is insufficient, reduce the tile dimensions in increments of 16 and re-encode the conditioning for the new dimensions. Smaller tiles reduce the spatial workload of each model call, although the model and other workflow components still require memory.
- If tile boundaries remain visible, try increasing overlap while keeping it smaller than both tile dimensions. More overlap gives the feathered blending a wider shared region, but does not guarantee that all differences between tiles will disappear.
- When processing is too slow, consider reducing overlap cautiously. Larger tiles can reduce the number of regions needed to cover a canvas, but may increase memory requirements, so test changes on a representative image.
- Check other model-patching nodes in your workflow. This node installs a model-function wrapper; the supplied code does not demonstrate that it composes with other wrappers, so test combinations carefully rather than assuming every patch remains active.
HunyuanImage-3.0 Tiled Refine Common Errors and Solutions:
Required input missing or invalid parameter value
- Explanation: ComfyUI may reject the workflow before sampling if the model connection is missing or a numeric setting falls outside the declared input limits. The exact validation message depends on your ComfyUI version; the supplied node code does not define a custom message.
- Solution: Connect a compatible HunyuanImage-3.0 MODEL, keep tile_width and tile_height between 256 and 2048, and keep overlap between 0 and 1024. Use the exposed controls, which adjust in steps of 16.
CUDA out of memory
- Explanation: This is a possible GPU runtime error rather than a custom error from this node. Tiling reduces the spatial area processed per model call, but large tiles, the model itself, and other workflow components can still exceed available GPU memory.
- Solution: Reduce tile_width and tile_height, update the conditioning dimensions to match, and close other GPU-heavy applications. If the error occurs during image decoding rather than sampling, address that stage separately, for example with a compatible tiled decoding workflow.
Tensor-size or shape-mismatch error during sampling
- Explanation: The exact message varies. In this workflow, conditioning encoded for the full enlarged canvas instead of the tile size is an important configuration issue to check, although incompatible models or other patches can also cause shape errors.
- Solution: Re-encode your conditioning for the selected tile_width and tile_height, confirm that you are using HunyuanImage-3.0 components, and test without additional model patches. Keep the upscaled latent at the intended final canvas size.
Unsuitable overlap relative to tile size
- Explanation: This is a configuration warning, not a verified exception string. The interface permits combinations such as a 256-pixel tile with 1024-pixel overlap, but the supplied node code does not validate the relationship between these settings or establish how every such combination behaves.
- Solution: Keep overlap smaller than both tile dimensions. If you suspect an overlap-related failure, return to 1024 × 1024 tiles with 256 overlap and test again.
Visible seams or inconsistent detail between tiles
- Explanation: This is a visual symptom rather than a runtime error. Too little shared area can make transitions between independently processed regions more noticeable, and feathered blending cannot guarantee perfect consistency.
- Solution: Increase overlap within a sensible range, verify that the conditioning matches the tile dimensions, and consider lowering denoise to retain more of the original image's structure. If memory permits, test larger tiles to give each call more context.
The refinement changes the image too much
- Explanation: This is a sampling-setting issue rather than a node exception. The intended workflow uses denoise below 1; excessive denoising can alter the composition or appearance more than you want from a refinement pass.
- Solution: Lower the sampler's denoise value and compare results while keeping the source image and prompt unchanged. Confirm that the sampler receives your enlarged source latent rather than a fresh empty latent.
The node produces no image or the refinement appears inactive
- Explanation: This node outputs only a modified MODEL. It does not execute sampling or decoding, and its effect will not be used if the sampler is still connected to the original model.
- Solution: Connect the MODEL output from this node to the refinement sampler, provide the upscaled latent and matching conditioning, then decode the sampler's latent output. Check that another patch later in the model chain has not replaced the tiled wrapper.
Sampling is unexpectedly slow
- Explanation: This is usually a performance symptom rather than an error. Every denoising step processes multiple tiles, and overlapping areas require repeated work. Large canvases, small tiles, and substantial overlap can increase the workload.
- Solution: Test a smaller canvas first, reduce overlap cautiously, or increase tile dimensions if memory allows. Balance speed against boundary quality, and remember that tiling enables larger-canvas processing rather than guaranteeing faster sampling.
