Person Detailer:
PersonDetailer refines faces or other selected regions in an image while keeping the rest of the picture in place. It works through a batch one image at a time, finds the regions assigned to each enabled reference, and inpaints those regions with that reference’s own prompt and optional LoRA. It can also handle faces or detected body parts that were not assigned to a reference, depending on how the generic pass is configured. Each refined region is blended back into the working image, so later passes build on earlier ones. This makes the node useful when several people need different details or when you want to improve a head, hair, body region, or detected part without regenerating the entire image. You can review both the finished images and previews of the regions that were refined.
Person Detailer Input Parameters:
images
Required IMAGE. The image batch to refine; the node processes each image separately. If an image has more than three channels, the node removes channels after RGB, including alpha, before processing and returning the batch. No default, minimum, or maximum image dimensions are specified here.
person_data
Required PERSON_DATA. Supplies the reference assignments and region masks used to decide what to detail in each image. Connect the result from Person Selector Multi. The available masks and assignments determine whether a reference slot finds a region and whether generic detailing has anything to process; auxiliary body-part detailing also requires auxiliary mask data. No default is specified.
model
Required MODEL. The base image-generation model used for each inpaint pass. When you select a LoRA for a slot, the node prepares a patched model for that slot rather than changing this base model directly. No default is specified.
clip
Required CLIP. Encodes slot prompts into guidance for inpainting and is also used when the node must create empty or text-based negative conditioning. A selected LoRA can be applied to the CLIP model used to encode that slot’s nonempty prompt. No default is specified.
vae
Required VAE. Supplies the image encoding and decoding used by the inpaint pipeline. Connect a VAE appropriate for your model and workflow. No default is specified.
seed
Required INT; default 0; minimum 0; maximum 18446744073709551615. The same seed is passed to every slot and batch item. Keeping it fixed helps you compare changes to settings, although different masks and prompts can still produce different results.
steps
Required INT; default 4; minimum 1; maximum 100. Sets the number of sampling steps passed to each inpaint operation. More steps mean more sampling work for every region being detailed, so the effect on processing time grows when you have many slots, faces, parts, or images.
denoise
Required FLOAT; default 0.52; minimum 0.0; maximum 1.0; step 0.01. Controls how strongly an inpaint pass changes its source region. Lower values preserve more of the original detail; higher values permit a stronger redraw. Use a lower value when you want to retain a person’s existing appearance.
sampler_name
Required COMBO[STRING]. Selects the sampling algorithm from the sampler names available in your ComfyUI installation. It is passed to each inpaint operation. The supplied source does not specify a default or a fixed option list.
scheduler
Required COMBO[STRING]. Selects the noise schedule from the scheduler names available in your ComfyUI installation. It is passed to each inpaint operation. The supplied source does not specify a default or a fixed option list.
detail_daemon_enabled
Required BOOLEAN; default true; options true or false. Globally enables Detail Daemon’s detail-preservation adjustment for slots whose per-slot configuration also permits it. Turning this off prevents that adjustment for all slots, regardless of their individual setting.
detail_amount
Required FLOAT; default 0.20; minimum -5.0; maximum 5.0; step 0.01. Sets Detail Daemon strength when it is enabled for a slot. Positive values aim for more detail, negative values favor a smoother result, and 0 turns the strength off.
dd_smooth
Required BOOLEAN; default true; options true or false. Smooths the Detail Daemon adjustment curve to help avoid artifacts. It is passed to the inpaint pipeline along with the other Detail Daemon settings.
mask_blend_pixels
Required INT; default 32; minimum 0; maximum 128; step 1. Sets the feather radius around a mask edge in sampling pixels, relative to the target crop size. The pipeline converts that radius to image pixels for the final blend, so the transition covers the corresponding area of the picture. The Inpaint Options feather direction determines which side of the edge receives the transition; with the default “both” direction, a large radius can extend into a thin masked feature.
mask_expand_pixels
Required INT; default 0; minimum 0; maximum 64; step 1. Expands the mask outward by this many original-image pixels before the crop region is calculated and before feathering. Increase it when a mask clips the edge of the feature you want to refine, but remember that expansion can also include nearby features, such as part of a face beside a hair mask. It is unaffected by feather direction.
target_width
Required INT; default 800; minimum 64; maximum 4096; step 8. Sets the width to which a region crop is resized for sampling. It is a sampling-frame setting, not a command to resize the entire output image, and it also affects how the sampling-pixel blend radius maps back onto the image.
target_height
Required INT; default 1200; minimum 64; maximum 4096; step 8. Sets the height to which a region crop is resized for sampling. Like target_width, it controls the working crop rather than the dimensions of the completed image.
reference_1_enabled
Required BOOLEAN; default true; options true or false. Enables detailing for the first reference in person_data. If that reference is absent or its selected mask is empty, the node skips its pass.
reference_1_lora
Required COMBO[STRING]. Chooses a LoRA for the first reference, or “None” to use the base model and CLIP without a slot LoRA. The menu consists of “None” and the LoRA filenames available in your installation; no default selection is specified in the source.
reference_1_lora_strength
Required FLOAT; default 1.0; minimum 0.0; maximum 2.0; step 0.05. Sets the strength of reference 1’s selected LoRA on both the model and CLIP. At 0.0, the node skips applying that LoRA.
reference_1_prompt
Required STRING; default empty text. Supplies positive prompt text for reference 1 and is encoded using that slot’s CLIP, including its LoRA when applicable. If left empty or containing only spaces, the node uses positive_base when connected; otherwise it encodes an empty prompt.
reference_2_enabled
Required BOOLEAN; default false; options true or false. Enables detailing for the second reference in person_data. Enabling it does not create a second reference: the node skips the pass if the reference or a usable selected mask is absent.
reference_2_lora
Required COMBO[STRING]. Chooses a LoRA for reference 2, or “None” for no slot LoRA. Options are “None” plus the available LoRA filenames; no default selection is specified.
reference_2_lora_strength
Required FLOAT; default 1.0; minimum 0.0; maximum 2.0; step 0.05. Controls how strongly reference 2’s selected LoRA is applied to its model and CLIP. A value of 0.0 skips the LoRA.
reference_2_prompt
Required STRING; default empty text. Guides reference 2’s inpaint pass. An empty or whitespace-only prompt falls back to connected positive_base, or to an encoded empty prompt if positive_base is absent.
reference_3_enabled
Required BOOLEAN; default false; options true or false. Enables a separate detailing pass for the third reference in person_data. The pass is skipped if that reference is unavailable or its selected region has no usable mask.
reference_3_lora
Required COMBO[STRING]. Chooses reference 3’s LoRA from “None” and the available LoRA filenames. Select “None” when this reference does not need a separate LoRA; the source does not specify a default selection.
reference_3_lora_strength
Required FLOAT; default 1.0; minimum 0.0; maximum 2.0; step 0.05. Sets reference 3’s LoRA strength for both model and CLIP. Setting it to 0.0 skips application of the selected LoRA.
reference_3_prompt
Required STRING; default empty text. Supplies reference 3’s positive prompt. When it is empty or whitespace-only, the node uses positive_base if connected and otherwise encodes an empty prompt.
reference_4_enabled
Required BOOLEAN; default false; options true or false. Enables detailing for the fourth reference. The node checks that reference 4 exists and has a nonempty mask for the selected region before inpainting it.
reference_4_lora
Required COMBO[STRING]. Selects a LoRA for reference 4, or “None” to leave its model and CLIP unpatched by a slot LoRA. The other choices are available LoRA filenames; no default selection is specified.
reference_4_lora_strength
Required FLOAT; default 1.0; minimum 0.0; maximum 2.0; step 0.05. Controls the selected LoRA’s strength on reference 4’s model and CLIP. At 0.0, that LoRA is not applied.
reference_4_prompt
Required STRING; default empty text. Provides positive guidance for reference 4’s region. Leaving it empty uses connected positive_base, or an encoded empty prompt when no base conditioning is connected.
reference_5_enabled
Required BOOLEAN; default false; options true or false. Enables detailing for the fifth reference. As with the other slots, an absent reference or empty selected mask causes the node to skip that pass.
reference_5_lora
Required COMBO[STRING]. Selects reference 5’s LoRA from “None” and the installed LoRA filenames. “None” means no slot LoRA; the source does not specify a default selection.
reference_5_lora_strength
Required FLOAT; default 1.0; minimum 0.0; maximum 2.0; step 0.05. Sets how strongly reference 5’s selected LoRA affects its model and CLIP. A strength of 0.0 skips the LoRA.
reference_5_prompt
Required STRING; default empty text. Supplies reference 5’s positive prompt. Empty or whitespace-only text uses connected positive_base when available and otherwise becomes an encoded empty prompt.
generic_enabled
Required BOOLEAN; default false; options true or false. Enables a pass for eligible faces or auxiliary parts not handled by the reference passes. Its exact coverage depends on generic_catch_unprocessed, the generic mask type configured through inpaint_options, and the mask data in person_data.
generic_catch_unprocessed
Required BOOLEAN; default true; options true or false. When true, generic detailing can also catch regions left unprocessed by active reference slots, including faces assigned to disabled slots; in auxiliary mode, it can include parts assigned to references whose active slots do not use auxiliary masks. When false, it is limited to genuinely unassigned faces or auxiliary hits. This setting matters only when generic_enabled is true.
generic_lora
Required COMBO[STRING]. Selects the LoRA used for eligible generic regions, or “None” for no generic LoRA. The choices are “None” and the available LoRA filenames; the source does not specify a default selection.
generic_lora_strength
Required FLOAT; default 1.0; minimum 0.0; maximum 2.0; step 0.05. Sets generic LoRA strength on both model and CLIP. At 0.0, the node skips applying that LoRA.
generic_prompt
Required STRING; default empty text. Provides positive guidance for generic detailing. If empty or whitespace-only, it uses connected positive_base, or an encoded empty prompt if positive_base is not connected.
positive_base
Optional CONDITIONING; default not connected. Provides fallback positive conditioning when an enabled reference or generic slot has no nonempty prompt. A slot with its own prompt instead encodes that text for its pass.
negative
Optional CONDITIONING; default not connected. Supplies negative conditioning for the inpaint passes. With no connection and no negative prompt in inpaint_options, the node encodes an empty negative prompt; if Inpaint Options supplies negative-prompt text, the node encodes it and, when negative is connected, appends that conditioning to the connected negative conditioning.
dd_options
Optional DD_OPTIONS; default not connected. Passes advanced Detail Daemon parameters to the inpaint pipeline, typically from a Detail Daemon Options node. These settings work alongside the global Detail Daemon controls and each slot’s permission to use Detail Daemon.
inpaint_options
Optional INPAINT_OPTIONS; default not connected. Supplies advanced inpaint settings and per-slot overrides, including the region mask type, number of rounds, and whether a slot uses Detail Daemon. It can also provide settings such as CFG, feather direction, crop context, and negative-prompt text. Without a connection, the node uses its built-in inpaint defaults; the complete values of those defaults are not shown in the supplied class.
Person Detailer Output Parameters:
images
IMAGE, output 1. The completed image batch, in its original batch order, after enabled reference passes and then eligible generic passes have been stitched into each image. This is the output to use for the finished pictures. If the input contained channels beyond RGB, those channels are not retained.
refined
IMAGE, output 2. A batch of previews returned by all successful refinement passes, including reference and generic passes. These show the regions worked on, rather than replacing the full-image result. Auxiliary parts from one slot can appear together as a tiled preview. The number of preview images can differ from the number of input images; if there are no previews, this output is a single black 64 × 64 RGB placeholder.
refined_references
IMAGE, output 3. Contains only refinement previews produced by the enabled reference slots. Use it to inspect reference-assigned work separately from generic work. It can include tiled auxiliary-part previews, and it becomes a single black 64 × 64 RGB placeholder if no reference previews were produced.
refined_generic
IMAGE, output 4. Contains only previews produced by the generic pass, making it easier to check what happened to eligible unassigned or unprocessed regions. It can include tiled auxiliary-part previews, and it becomes a single black 64 × 64 RGB placeholder if no generic previews were produced.
Person Detailer Usage Tips:
- Start with Person Selector Multi connected to person_data and keep only the reference slots you need enabled. Match each slot number to the intended reference before assigning its prompt and LoRA; reference 1 is enabled by default, while references 2 through 5 are disabled by default.
- For a controlled first test, leave seed fixed at its default of 0, use the default 4 steps and 0.52 denoise, and inspect both images and refined_references. Adjust denoise downward if the region changes too much, or upward if it changes too little.
- Use a short, specific prompt for a reference that needs its own treatment. Leave its prompt empty when you deliberately want positive_base to guide it; without positive_base, an empty slot prompt supplies no written positive description.
- Set a slot’s LoRA to “None,” or its strength to 0.0, when you want to test the prompt without that LoRA. The node reuses prepared model and conditioning for slots with the same LoRA, strength, and prompt combination within an execution.
- Enable generic_enabled when the reference passes leave faces or parts you still want detailed. Keep generic_catch_unprocessed true to cover eligible regions left by disabled or non-auxiliary reference slots; turn it off when generic work should be restricted to unassigned regions.
- Select the desired mask type for each slot through Inpaint Options. For detected body parts, choose “aux” and ensure Person Selector Multi has auxiliary detector data. Auxiliary parts are detailed individually; if you need both head and body-part passes, chain two PersonDetailer nodes as described by the node.
- Keep mask_expand_pixels at 0 unless segmentation visibly cuts off a feature. Increase it cautiously, especially near faces. If a feathered edge weakens a narrow mask, reduce mask_blend_pixels or adjust feather_direction through Inpaint Options.
- Each additional image, eligible region, auxiliary part, or configured repeat can add inpaint work. For a faster trial, test a small batch with only the necessary slots enabled before raising crop dimensions or steps.
Person Detailer Common Errors and Solutions:
“RefN — no reference connected, skip”
- Explanation: An enabled reference slot has a higher slot number than the number of references reported in person_data. The node skips that slot; “N” is its slot number.
- Solution: Add the intended reference in Person Selector Multi, or disable the unused slot.
“RefN — no match, skip”
- Explanation: The selected mask for that reference and image is empty, so there is no region for the slot to inpaint.
- Solution: Check the reference assignment and selected mask type in Person Selector Multi and Inpaint Options. Confirm that the intended region is detected in that batch image.
“RefN — aux: no detector connected to Person Selector Multi, skip”
- Explanation: The slot is configured for auxiliary body-part detailing, but person_data does not contain auxiliary masks.
- Solution: Supply auxiliary detector data to Person Selector Multi, or change the slot’s mask type to one supported by the masks you already have.
“RefN — aux: no body parts assigned, skip”
- Explanation: Auxiliary mask data exists, but no body-part region is assigned to this reference in the current image.
- Solution: Check the detector’s results and the reference assignment for that image. Disable the slot if there is no part to detail.
“Generic — aux: no detector connected to Person Selector Multi, skip”
- Explanation: Generic detailing is set to auxiliary mode, but person_data lacks auxiliary mask data.
- Solution: Connect auxiliary detector data to Person Selector Multi, or select a non-auxiliary generic mask type in Inpaint Options.
“Generic — aux: no unassigned body parts”
- Explanation: The generic auxiliary pass found no eligible parts. With generic_catch_unprocessed off, parts already assigned to a reference are excluded even when that reference does not detail them.
- Solution: If you want generic to handle parts left by reference slots that do not use “aux,” turn generic_catch_unprocessed on. Otherwise, verify that the detector found unassigned parts.
“Generic — no unmatched faces”
- Explanation: No face qualifies for the generic pass under the current assignments and generic_catch_unprocessed setting. This can be an expected status, not a failure.
- Solution: Check face detection and assignments. Turn generic_catch_unprocessed on if you also want eligible faces left by disabled reference slots, or leave the settings unchanged when all intended faces are already handled.
“Warning: invalid generic mask_type '…', falling back to 'head'”
- Explanation: The generic mask type supplied through Inpaint Options is not recognized, so the node uses a head mask instead.
- Solution: Recheck the generic mask-type setting in Inpaint Options and choose a supported value; recreate an outdated options node if its choices no longer match the installed node.
“RefN — invalid mask_type '…', falling back to 'head'. (Recreate Inpaint Options node to fix.)”
- Explanation: A reference slot has an unrecognized mask type. The node continues with head detailing, which may not be the region you intended.
- Solution: Recreate the Inpaint Options node as the message suggests, then set the reference slot’s mask type again.
“Warning: invalid lora value …, skipping”
- Explanation: A slot’s LoRA value is neither a valid filename string nor a valid index into the available LoRA list. The node continues without applying that LoRA.
- Solution: Reselect the LoRA from the slot’s menu, or choose “None.” If the workflow came from another installation, confirm that the LoRA is installed and available in the menu.
LoRA file lookup or loading fails
- Explanation: A selected LoRA may no longer exist at its listed path, or it may fail to load. The exact exception text depends on the file and the loading operation.
- Solution: Confirm that the selected file exists in your ComfyUI LoRA location, then reselect it. Try “None” to check whether the workflow otherwise runs.
Missing mask data or an incompatible person_data structure
- Explanation: The node reads reference counts and named masks from person_data. If the connected data lacks a mask it needs, execution may stop with a missing-key or indexing exception rather than a friendly skip message.
- Solution: Connect PERSON_DATA from the compatible Person Selector Multi workflow and check that its generated masks correspond to the selected mask types and image batch.
Black 64 × 64 image on a refinement output
- Explanation: This is the node’s placeholder when that particular preview output has no refinement crops; it does not by itself mean the completed images output failed.
- Solution: Inspect images and the node’s status text, then check whether any slots were enabled and found eligible nonempty masks.
