H3 Face Transform Info:
H3FaceTransformInfo is a diagnostic node for checking face-tracking transform data before continuing with more expensive GPU processing. It reads the tracked face bounding boxes and creates a readable, frame-by-frame summary showing the video frame number, face position, face width and height, and a magnification value. It also reports the total number of frames, the transform canvas size, and the original source-image size. The summary is printed to the console and returned as text, making it useful for confirming that tracking is present, that face locations and sizes look reasonable, and that the crop or refinement process is likely to receive valid data. The node does not modify the transform data or perform face refinement; it is intended as a quick sanity check.
H3 Face Transform Info Input Parameters:
transform
This is the face-transform data that the node examines. It must be an H3FACEXFORM value containing the tracked frame information, canvas dimensions, source size, and per-frame face bounding boxes. Each bounding box is interpreted as x, y, w, and h: the horizontal and vertical position followed by the width and height of the tracked face region. The node uses this information to build the diagnostic table and calculates the displayed magnification as the canvas height divided by the face-box height. A valid transform is required for the node to run successfully. The interface does not define a default, minimum, or maximum value for this input; it must be supplied by a compatible upstream node.
max_rows
This integer controls the intended maximum number of transform rows to inspect in the diagnostic output. Its default value is 12, with a minimum of 1 and a maximum of 400. When the transform contains many frames, the node chooses a sampling interval so that it does not normally need to print every frame. Lower values create a shorter, easier-to-scan report, while higher values provide more detailed information across the sequence. The node always includes the header and may produce slightly more than the requested number of frame rows in some cases because its sampling interval is calculated using whole-number division. This setting does not change the transform, tracking, or image processing; it only affects how much frame information is displayed.
H3 Face Transform Info Output Parameters:
info
This string contains the transform inspection report. The first line shows the total frame count, the canvas dimensions, and the original source size in a format similar to frames=24 canvas=512x512 src=(1920, 1080). The next line labels the table columns: frame is the frame index, x and y are the face-box position, w and h are its width and height, and mag is the calculated magnification displayed with an x suffix. The report then lists sampled frames rather than necessarily every frame. Magnification is calculated as the canvas height divided by the face-box height, so a larger value generally indicates that the tracked face is represented by a smaller region relative to the output canvas. The same text is also printed to the console with an [H3FaceRefine] prefix, allowing you to inspect it without connecting the output elsewhere.
H3 Face Transform Info Usage Tips:
- Use this node immediately after the node that creates the
H3FACEXFORMvalue and before starting expensive face-refinement or generation steps. Check that the frame count and canvas size match the sequence you expect. - Keep
max_rowsat its default value of12for a quick overview of a long clip. Increase it toward400when you need to inspect tracking changes more closely, or reduce it toward1when you only need a compact diagnostic report. - Review the
x,y,w, andhvalues across the sampled frames. Large unexpected jumps can indicate unstable tracking, while a width or height that becomes extremely small may indicate that the face was not tracked reliably. - Pay attention to the
magcolumn. It is based on the canvas height divided by the tracked face height, so sudden or unusually large changes can reveal inconsistent face-box sizing before you spend time on GPU processing. - Connect
infoto a text-display or logging node if you want to keep the report visible in the workflow. The report is also printed in the console, where it appears after the[H3FaceRefine]label.
H3 Face Transform Info Common Errors and Solutions:
KeyError: 'boxes'
- Explanation: The supplied transform does not contain the
boxesdata required to read the per-frame face regions. This usually means the value is not the expectedH3FACEXFORMstructure or was created by an incompatible node. - Solution: Connect the transform output from the appropriate H3 face-tracking or face-refinement preparation node. Do not substitute an image, mask, or unrelated data type for the transform input.
KeyError: 'canvas'
- Explanation: The transform is missing its canvas dimensions. The node needs these dimensions to report the canvas size and calculate magnification.
- Solution: Ensure that the complete transform object is passed through the workflow and that the upstream transform-producing node finished successfully. Recreate the transform with the compatible H3 face-processing nodes if necessary.
KeyError: 'frames', KeyError: 'src_size'
- Explanation: The transform does not include one of the metadata fields used in the report.
framessupplies the frame count, whilesrc_sizesupplies the original source dimensions. - Solution: Use a fully formed
H3FACEXFORMoutput from the intended upstream node. Check for disconnected links, incompatible custom-node versions, or a transform generated before all tracking metadata was available.
ZeroDivisionError: float division by zero
- Explanation: At least one face bounding box has a height of zero, so the node cannot calculate
canvas height / face heightfor themagcolumn. - Solution: Inspect the upstream tracking result for invalid or empty face boxes. Re-run face detection or tracking, verify that a face is actually present, and use a transform-producing node or version that prevents zero-height boxes.
ValueError or an input validation error for max_rows
- Explanation: The supplied row limit is outside the permitted range. The node accepts integer values from
1through400. - Solution: Set
max_rowsto an integer within that range. The default value12is a suitable starting point for most diagnostics.
TypeError while reading transform data
- Explanation: The transform or one of its fields has an unexpected type or structure, such as a non-iterable box list or box values that cannot be unpacked into
x,y,w, andh. - Solution: Confirm that the input is connected to an
H3FACEXFORMoutput rather than manually constructed text or another data type. If the problem persists, regenerate the transform from the original tracking pipeline and make sure the related custom nodes are compatible.
