H3 Face Stitch Back:
H3FaceStitch places refined face crops back into their original video frames. It uses the face-tracking information created earlier in the workflow to align each crop with its source frame, including positions between whole pixels, which helps avoid small placement jumps across a moving shot. By default, it blends only the face area rather than the entire crop: the wider crop gives the refinement process visual context, while the surrounding hair, clothing, and background can remain unchanged. You can control the softness of the edge, match the refined face’s colour to the frame, reduce the strength of the refinement, and decide what appears when a face was not detected.
H3 Face Stitch Back Input Parameters:
base_images
The original frames that receive the refined faces. This required IMAGE input also supplies the pixels preserved outside each paste area. The output begins as a copy of these frames, so source frames without a corresponding refined crop remain unchanged. The node uses the first three image channels. There is no numeric minimum, maximum, or default; connect the source-frame sequence that corresponds to the tracking information.
refined_crops
The refined face crops to place back into the source frames. This required IMAGE input should be the result of processing the crops associated with the supplied transform, in the same crop order. The node aligns each crop to its recorded position and uses its first three channels. A missing crop cannot be composited; if there are fewer crops than recorded boxes, processing stops at the available count. There is no numeric minimum, maximum, or default.
transform
The required H3FACEXFORM tracking data that tells the node where each crop belongs. It provides crop boxes, canvas and source dimensions, and may also provide source-frame indices, face rectangles, and detection information. This lets the node place a crop into the correct frame even when crops are not present for every source frame. Use the transform produced for the same crop sequence and original frames; a transform from another clip or crop run can cause incorrect placement or processing errors. There is no numeric minimum, maximum, or default.
paste_region
Chooses how much of a refined crop is pasted. Options are face_only (default), face_ellipse, and full_crop. face_only blends a rectangular area around the detected face; face_ellipse uses an oval area; and full_crop blends the whole crop, including any altered hair, shoulders, or background. The first two options generally preserve more of the original frame. If face-rectangle data is unavailable, the face-area options use a central region of the crop instead. An optional masks connection overrides this setting.
mask_dilation
Expands the paste area before its edge is softened, helping the blend cover the face without fading into its features. Its default is 16, minimum 0, maximum 256, and control step 2. A larger value reaches farther beyond the face or supplied mask; a smaller value confines changes more tightly. Although the control describes dilation in canvas pixels, the expansion is applied to the paste mask before that mask is mapped back onto the source frame.
feather
Controls how softly the paste mask fades into the original frame. Its default is 6, minimum 0, maximum 256, and control step 2. With the default scaling behaviour, the requested width is interpreted in source-frame pixels and converted for use on the crop canvas; the conversion is calculated per processing chunk. Larger values make a broader, softer transition, while smaller values keep the refined area more tightly defined. A value of 0 removes Gaussian softening from face-area and supplied masks; full_crop also has its own edge-feathering behaviour.
colour_match
Sets how strongly the refined crop’s colour and contrast are adjusted toward the original region it replaces. Its default is 1.0, minimum 0.0, maximum 1.0, and control step 0.05. At 0.0, no colour matching is applied; at 1.0, the node applies the full per-channel mean and contrast adjustment; intermediate values apply part of that adjustment. This can reduce an obvious brightness or tint difference between an independently refined face and its source frame.
blend
Sets the overall strength of the refined result within the paste area. Its default is 1.0, minimum 0.0, maximum 1.0, and control step 0.05. At 1.0, the refined crop contributes at full strength wherever the paste mask allows; at 0.0, the original pixels remain. Values between them mix the refined result with the original, which can help when a face looks over-sharpened. Detection-based weighting, when enabled, can reduce the effective strength further on particular frames.
undetected_frames
Controls whether refined crops are pasted on frames where tracking reports that no face was detected. Options are fade_out (default), skip, and composite_anyway. fade_out uses weights from the transform to reduce the pasted result across a detection gap; skip keeps the original pixels on frames marked undetected; and composite_anyway pastes regardless of detection, which can produce an unwanted face on an occluded or turned-away subject. This setting controls compositing, not whether the upstream refinement processes a frame. Its behaviour depends on the detection or weight data available in the transform.
feather_scales_with_crop
An optional BOOLEAN setting with a default of False; its options are False and True. Leave it False to interpret feather relative to the source frame, helping the visible blend width remain more consistent as the tracked face changes size. Set it True to use the older canvas-relative behaviour, where a fixed feather setting can appear narrower or wider in the source frame as crop magnification changes.
masks
An optional MASK input for per-crop paste masks in crop-canvas space. When connected, these masks determine where the refined result is visible and override paste_region. The node resizes a mask to the transform’s canvas dimensions when necessary, then applies mask_dilation and feather before mapping it into the source frame. A face-shaped mask can follow the jaw or hairline more closely than a rectangular face box. Supply masks in the same order as the refined crops; there is no numeric minimum, maximum, or default mask value.
H3 Face Stitch Back Output Parameters:
images
The resulting IMAGE sequence, in the same source-frame order as base_images. Each processed frame contains its aligned refined crop blended into the original according to the paste mask, colour matching, blend strength, and detection setting. Areas outside the mask retain their original appearance, and source frames that receive no crop remain unchanged. The output contains the first three image channels rather than preserving additional channels from the input frames.
H3 Face Stitch Back Usage Tips:
- Start with
paste_regionset toface_onlyandfeather_scales_with_cropset toFalse. This keeps the wider crop available as refinement context without automatically replacing its surrounding background. - If you see a rectangular boundary, try a suitable face-shaped
masksinput orface_ellipse. Adjustmask_dilationto cover the full face, then increasefeatherenough to soften the boundary without unnecessarily blending distant areas. - With a well-aligned face-shaped mask, try a relatively small
feathervalue, such as4to8. A rectangular paste area may need a broader transition. Inspect both small and large faces in the same shot before settling on a value. - Keep
colour_matchnear its default when the refined face has a different tint or brightness from the frame. Lower it if the correction changes the look of the refinement more than you intend. - Reduce
blendbelow1.0when the refinement appears too sharp or prominent. This changes its overall contribution without requiring another refinement pass. - Use
undetected_framesset tofade_outfor a smoother transition through tracking gaps. Chooseskipwhen retaining the exact original pixels on undetected frames matters more than a gradual transition; usecomposite_anywayonly after checking turned-away and occluded frames. - Keep
base_images,refined_crops,transform, and anymasksfrom the same ordered workflow. The transform can map crops to a subset of source frames, but mixing outputs from different runs can place a convincing-looking face in the wrong location.
H3 Face Stitch Back Common Errors and Solutions:
KeyError: 'boxes', KeyError: 'canvas', or KeyError: 'src_size'
- Explanation: The transform is missing required placement or size information. These keys are read directly by the node.
- Solution: Connect a valid
H3FACEXFORMfrom the tracking or crop stage used for these frames. Do not substitute unrelated transform data.
ZeroDivisionError: float division by zero
- Explanation: A crop box has a width or height of zero, so the node cannot calculate how to map the crop back onto the source frame.
- Solution: Inspect the upstream face tracking and crop generation for invalid boxes. Regenerate the affected transform after correcting the tracking result.
RuntimeError: CUDA out of memory or another device out-of-memory message
- Explanation: Warping and blending several full-resolution frames at once can exceed available device memory, despite the node’s internal chunking.
- Solution: Process fewer or smaller frames per run, reduce source resolution where acceptable, or free device memory used by other workflows before retrying.
IndexError: index ... is out of bounds or a mask batch-size error
- Explanation: The supplied
maskssequence may have fewer entries than the crops being processed, or its dimensions may not match the expected per-crop mask layout. - Solution: Provide one compatible mask per refined crop in the same order, or disconnect
masksand usepaste_regioninstead.
IndexError: index ... is out of bounds when placing a crop
- Explanation: A source-frame index in the transform may point outside the
base_imagessequence. - Solution: Reconnect the original frame sequence associated with the transform and check that no frames were removed or reordered after tracking.
RuntimeError mentioning tensor shapes, sizes, or devices
- Explanation: The frames, refined crops, masks, or transform may not form a compatible set. For example, the transform’s recorded source size may differ from the actual source frames.
- Solution: Use the original frames and crop outputs from the same run, check their frame counts and dimensions, and regenerate the transform if the source video was resized or reordered.
[H3FaceRefine] frame count mismatch: base=... refined=... transform=... -> using ...
- Explanation: This is a printed diagnostic, not necessarily an error. The source-frame, refined-crop, and transform-box counts differ; the node reports how many crops it will process.
- Solution: If the difference is unexpected, check for dropped, duplicated, or reordered frames and reconnect matching workflow outputs. If tracking intentionally produced fewer crops than source frames, verify the resulting video rather than assuming every frame should be changed.
[H3FaceRefine] compositing ... refined frame(s) into ... source frame(s)
- Explanation: This is an informational message indicating that the transform maps a crop sequence into a source sequence with a different frame count.
- Solution: No action is needed when the tracked subject is intentionally absent from some frames. If faces appear on incorrect frames, confirm that the transform and source frames came from the same clip in the same order.
The refined face has a hard edge or looks pasted on
- Explanation: The paste area may be too tight, its edge too sharp, or the refined crop’s brightness and colour may differ from the original frame.
- Solution: Increase
mask_dilationenough to cover the face, adjustfeatherfor a softer transition, and trycolour_matchnear1.0. For an irregular boundary, use an aligned face-shapedmasksinput.
A face appears during an occlusion or after the subject turns away
- Explanation:
composite_anywayignores detection status, and other modes depend on the detection information stored in the transform. - Solution: Select
fade_outorskipand check that the upstream transform correctly identifies undetected frames.
