Jakkanna QWEN Detailer:
VNCCS_QWEN_Detailer finds regions of interest in an image, generates a revised version of each region with a Qwen-compatible image-editing workflow, and places the results back into the full image. It can refine detected regions with segmentation, use additional images as references, match generated colors to the original, and blend the boundaries where edits meet untouched areas. Its square-processing option is intended to reduce shape drift while editing rectangular regions. The node works on one image at a time; if no usable regions are found, it returns the original image unchanged.
Jakkanna QWEN Detailer Input Parameters:
image
Required IMAGE. The source image to inspect and detail. Detected regions are cropped from this image, and generated edits are placed back into it. Supply a single image, not a batch.
bbox_detector
Required BBOX_DETECTOR. Finds candidate regions for editing. The node calls this detector with the detection threshold, dilation, a fixed crop factor of 1.0, and the minimum detection size. Its detections determine which areas can be changed.
model
Required MODEL. The image-generation model used to sample a revised version of each detected region. Use a model compatible with the connected Qwen conditioning and latent workflow.
clip
Required CLIP. Processes the text instruction and image references into conditioning for generation. This workflow calls image-aware tokenization, so the connected encoder must support the Qwen-style operations used here.
vae
Required VAE. Encodes image references into latents and decodes generated latents into visible images. The same VAE participates in preparing each region and producing its edited result.
prompt
Required STRING; multiline and dynamic prompts are enabled. Describe the change you want within the detected regions. The text is combined with image references and the node’s instruction text; in inpaint mode, it is also preceded by the inpaint prompt.
threshold
Required FLOAT; default 0.5, minimum 0.0, maximum 1.0, step 0.01. Passed to the bounding-box detector and, when connected, the segmentation detector. It controls their detection filtering; the precise meaning of a score depends on the detector you connect. Raise it when detections are too permissive, or lower it when intended subjects are missed.
dilation
Required INT; default 0, minimum -512, maximum 512, step 1. Passed to detection and also applied to the returned crop coordinates. Positive values can expand the area available for editing, while negative values can shrink it. A crop that becomes smaller than 10 pixels in either dimension is skipped.
drop_size
Required INT; default 10, minimum 1, maximum MAX_RESOLUTION, step 1. Passed to the bounding-box detector and optional segmentation detector to filter small detections. The exact filtering behavior depends on those detectors. Separately, this node rejects adjusted crop regions narrower or shorter than 10 pixels.
feather
Required INT; default 0, minimum 0, maximum 300, step 1. Controls smoothing of the paste mask at an edited region’s boundary when standard pasting is used. Increasing it can soften a visible transition, but may also mix more of the generated result with the original. When Poisson blending succeeds, that blending path takes precedence over the standard feathered paste.
steps
Required INT; default 4, minimum 1, maximum 10000. The number of sampling steps used to generate each edited region. More steps require more sampling work; they do not guarantee a better result.
cfg
Required FLOAT; default 1.0, minimum 0.0, maximum 100.0. Passed to the sampler as its guidance setting. It affects how strongly sampling follows the supplied conditioning; the useful value depends on the connected model and workflow.
seed
Required INT; default 0, minimum 0, maximum 18446744073709551615. Passed to the sampler for every detected region. Keep it fixed when comparing settings so you can better isolate the effect of a change, subject to the sampler’s reproducibility.
sampler_name
Required COMBO of STRING values supplied by SAMPLER_NAMES. Selects the sampling algorithm used for each region. The available options depend on the installed ComfyUI environment; the provided node source does not list them or specify a menu default.
scheduler
Required COMBO of STRING values supplied by SCHEDULER_NAMES. Selects the sampling schedule used with the sampler. Its available options depend on the installed ComfyUI environment; the provided node source does not list them or specify a menu default.
denoise
Required FLOAT; default 1.0, minimum 0.01, maximum 1.0, step 0.01. Sets the sampler’s denoising strength for the region’s starting latent. Lower values are useful when you want to retain more of the source region; higher values allow a larger change.
tiled_vae_decode
Required BOOLEAN; default False. When enabled, decodes generated latents in tiles instead of using the VAE’s ordinary decode call. This may be useful when ordinary decoding exceeds available memory, although its effect depends on the VAE.
tile_size
Required INT; default 512, minimum 64, maximum 2048, step 64. Sets both horizontal and vertical tile dimensions for tiled VAE decoding. It has no effect when tiled_vae_decode is off. Smaller tiles may reduce decoding memory demands at the cost of more tiled work.
controlnet_image
Optional IMAGE. Supplies a second image reference for each detected region; despite the socket name, this source passes it to the Qwen image encoder and does not show a separate ControlNet application. Its full-image dimensions are resized to match image if necessary. In inpaint mode, part of it is also used to construct the region reference. Supply a single image, not a batch.
image2
Optional IMAGE. Supplies an additional image reference to the Qwen conditioning workflow. Unlike controlnet_image, it is passed as a whole reference image rather than cropped to each detected region. Supply a single image, not a batch.
sam_model_opt
Optional SAM_MODEL. Refines bounding-box detections with a SAM-generated mask. When this input is connected, it takes priority over segm_detector_opt; the segmentation detector is not used in that case.
segm_detector_opt
Optional SEGM_DETECTOR. Refines bounding-box detections by intersecting them with a mask produced by a segmentation detector. It is used only when sam_model_opt is not connected.
sam_detection_hint
Optional COMBO; default center-1. Options: center-1, horizontal-2, vertical-2, rect-4, diamond-4, mask-area, mask-points, mask-point-bbox, and none. Passed to SAM mask creation to choose how hints are supplied for refinement. It matters only when sam_model_opt is connected.
sam_dilation
Optional INT; default 0, minimum -512, maximum 512, step 1. Passed to SAM mask creation to adjust its refinement area. It is separate from dilation, which also affects detection and the final crop. It has no effect without sam_model_opt.
sam_threshold
Optional FLOAT; default 0.93, minimum 0.0, maximum 1.0, step 0.01. Passed to SAM mask creation as its threshold setting. Adjust it when SAM refinement is excluding too much or retaining too much, according to the behavior of the connected SAM implementation.
sam_bbox_expansion
Optional INT; default 0, minimum 0, maximum 1000, step 1. Passed to SAM mask creation to expand the bounding-box area considered during refinement. It has no effect without sam_model_opt.
sam_mask_hint_threshold
Optional FLOAT; default 0.7, minimum 0.0, maximum 1.0, step 0.01. Passed to SAM mask creation as a mask-hint threshold. Its visible effect depends on the selected hint mode and connected SAM implementation.
sam_mask_hint_use_negative
Optional COMBO; default False. Options: False, Small, and Outter. Passed to SAM mask creation to select its negative-hint behavior. The option Outter is spelled exactly that way in the node interface. It has no effect without sam_model_opt.
target_size
Optional COMBO of INT values; default 1024. Options: 1024, 1344, 1536, 2048, 768, and 512. Sets the square processing size when distortion_fix is enabled and is also passed into the Qwen encoding routine. In the shown encoding implementation, the latter does not directly resize the non-square input to this value. Larger square sizes require processing more pixels.
upscale_method
Optional COMBO. Options: nearest-exact, bilinear, area, bicubic, and lanczos. Selects the resizing method used while preparing images for vision-language conditioning and VAE reference encoding. No menu default is specified in the interface; the method’s function signature uses lanczos when no value is supplied.
crop_method
Optional COMBO. Options: disabled and center. Passed to image preparation when resizing vision-language images and VAE references. No menu default is specified in the interface; the method’s function signature uses center when no value is supplied.
instruction
Optional multiline STRING. Its default asks the encoder to describe the input image’s features, explain the requested modification, and generate a new image consistent with the original where appropriate. It supplies the system-level editing instruction; prompt supplies your particular edit request. An empty value falls back to the same instruction text in the encoding routine.
inpaint_mode
Optional BOOLEAN; default False. When enabled, the node blacks out the detected bounding-box area in its cropped working image and adds the inpaint prompt to the text sent for conditioning. This is a black-box editing workflow, not evidence of a separate native inpainting mask. Note that enabling distortion_fix subsequently rebuilds the square working image from the unblacked-out image, so the black-box treatment may not be retained in the main image reference.
inpaint_prompt
Optional multiline STRING; default [!!!IMPORTANT!!!] Inpaint mode: draw only inside black box. Used before prompt only when inpaint_mode is enabled. If passed as an empty string, the encoding routine substitutes (Fill black area with image) .
color_match_method
Optional COMBO; default kornia_reinhard. Options: disabled and kornia_reinhard. The latter adjusts the generated region’s LAB color statistics toward those of the original crop before pasting, using a fixed mixing strength of 0.8. It requires Kornia; if Kornia cannot be imported, the node prints a warning and leaves the generated colors unchanged.
seam_fix
Optional BOOLEAN; default True. When on, attempts OpenCV Poisson blending to integrate an edited crop with the surrounding image. When off, uses standard pasting with the available region mask and feather setting. If Poisson blending fails, the node prints a message and falls back to standard pasting.
qwen_2511
Optional BOOLEAN; default True. When enabled, the node attempts to set reference_latents_method to index_timestep_zero on positive and negative conditioning before sampling. The code silently continues if that adjustment fails, so enabling it does not guarantee that the conditioning change was applied.
distortion_fix
Optional BOOLEAN; default True. When enabled, prepares a square reference around each detected crop, resizes it to target_size, then converts the generated result back to the original crop dimensions before pasting. This is intended to limit distortion or drift when working with rectangular detections. Disable it to use the unsquared crop workflow.
Jakkanna QWEN Detailer Output Parameters:
image
IMAGE. The full-size image after each valid detected region has been generated and pasted back in sequence. Areas outside the pasted regions remain based on the source image, subject to the chosen blending method. If there are no valid detections, this output is the original input image.
Jakkanna QWEN Detailer Usage Tips:
- Start with one image and a detector that identifies the subject you intend to edit. If the result looks unchanged, check the detector’s results and adjust
thresholdordrop_size; the node returns the original image when no valid regions remain. - Use
dilationto give a detected region more surrounding context, then check the result near image edges. Very small adjusted crops are skipped, and excessive expansion can include areas you did not intend to change. - Connect
sam_model_optorsegm_detector_optwhen a rectangular detection includes unwanted background. SAM takes priority if both are connected, so disconnect it when you want to test segmentation-detector refinement. - Begin with the displayed defaults for
steps,cfg, anddenoise, then change one setting at a time while keepingseedfixed. Lowerdenoisewhen preserving the source matters more than making a large edit. - Keep
distortion_fixon for rectangular subjects that change shape unexpectedly, and choose atarget_sizeappropriate for the detail you need and the resources available. For black-box inpainting, test withdistortion_fixoff because the square-processing path rebuilds the main reference from the original image. - If pasted regions have conspicuous borders, compare
seam_fixon and off. With standard pasting, try a modestfeathervalue or a refined segment mask; Poisson blending can produce a different appearance and may fall back if it fails. - Use
color_match_methodset tokornia_reinhardwhen an edited region’s colors depart from the original crop. Choosedisabledwhen the intended edit deliberately changes those colors or when you need to diagnose the generated image without correction. - Enable
tiled_vae_decodeif ordinary VAE decoding runs out of memory, and try a smallertile_sizeif needed. This setting affects decoding, not detector processing or sampling.
Jakkanna QWEN Detailer Common Errors and Solutions:
[Jakkanna QWEN Detailer] Image batches are not supported.
- Explanation:
imagecontains more than one image, but the node processes only one at a time. - Solution: Feed it a single image or process batch items separately upstream.
[Jakkanna QWEN Detailer] ControlNet image batches are not supported.
- Explanation: The optional
controlnet_imagecontains more than one image. - Solution: Supply one corresponding reference image per run, or disconnect this input while testing.
[Jakkanna QWEN Detailer] Reference image batches are not supported.
- Explanation: The optional
image2contains more than one image. - Solution: Supply a single additional reference image or process references separately.
[Jakkanna] ERROR: Failed to detect/refine segments: …
- Explanation: The bounding-box detector failed, or connected SAM or segmentation refinement failed. The text after the colon contains the underlying error.
- Solution: First test with only
bbox_detectorconnected. Confirm it is compatible with the input image, then reconnect one refinement option at a time and use the underlying error text to identify the failing component.
[Jakkanna] ERROR: Invalid segs format from bbox_detector. Expected tuple of length 2, got: …
- Explanation: The detector did not return the two-part segment structure this node expects.
- Solution: Use a compatible bounding-box detector that returns an image shape and segment collection in the expected format.
[Jakkanna] ERROR: Invalid segments list. Expected list or tuple, got: …
- Explanation: The detector returned a two-part result, but its segments were not provided as a list or tuple.
- Solution: Check the connected detector or any adapter between it and this node. It must provide a list or tuple of segments.
[Jakkanna] Warning: Kornia not found. Skipping color match. Install with 'pip install kornia'
- Explanation:
kornia_reinhardwas selected, but the Kornia dependency is unavailable. Processing continues without color matching. - Solution: Install Kornia in the environment running ComfyUI, or select
disabledforcolor_match_method.
[Jakkanna] Seam Fix (Poisson Blending) failed, falling back to standard paste: …
- Explanation: OpenCV could not complete Poisson blending for a region. The node continues using standard pasting.
- Solution: Inspect the region and its mask for unusual dimensions or coverage. Try
seam_fixoff, and usefeatheror a refined mask if the standard paste leaves a visible edge.
[Jakkanna] Auto-fixing deprecated color match method '…' to 'kornia_reinhard'
- Explanation: A saved workflow supplied a color-match value outside the current options. The node replaces it with
kornia_reinhard. - Solution: Re-select
disabledorkornia_reinhardin the node and save the workflow to remove the outdated value.
No error appears, but the image is unchanged
- Explanation: The detector may have found no regions, or all adjusted regions may have been smaller than 10 pixels in width or height. In that case, the node returns the original image.
- Solution: Check detector results, lower
thresholdordrop_sizewhere appropriate, and ensuredilationis not shrinking the desired crops too far.
Sampling or image encoding fails
- Explanation: This node calls Qwen-style image-aware CLIP tokenization and conditioning, VAE encoding, and ComfyUI sampling. An incompatible connected component can fail during one of those stages; the exact message comes from that component rather than from this node.
- Solution: Check the error’s failing stage and confirm that
model,clip, andvaebelong to a compatible workflow. Test with optional reference images disconnected to narrow down image-conditioning failures.
