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-FVMtools > Person Detailer

ComfyUI Node: Person Detailer

Class Name

PersonDetailer

Category
FVM Tools/Face
Author
ping1979ping (Account age: 285days)
Extension
comfyui-FVMtools
Latest Updated
2026-10-26
Github Stars
0.0K

How to Install comfyui-FVMtools

Install this extension via the ComfyUI Manager by searching for comfyui-FVMtools
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter comfyui-FVMtools 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

Person Detailer Description

Inpaints faces and body regions with per-person prompts and LoRAs while preserving the rest of the image.

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.

Person Detailer Related Nodes

Go back to the extension to check out more related nodes.
comfyui-FVMtools
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.

Person Detailer