✋ Hand Tracking:
HandTracking uses MediaPipe to locate hands in an image and mark detected hand positions. It is intended for workflows where you want a visual guide to hand placement or position data for later processing. The node also includes gesture labels and settings described as WAN and T2I-Adapter compatibility features. In this implementation, however, gesture labels are randomly selected rather than recognized from hand poses, and some compatibility settings are limited to changes within this node. Treat the landmark positions as the meaningful tracking result and the gesture labels as placeholders.
✋ Hand Tracking Input Parameters:
image
The image to analyze. This required input must be a PyTorch image tensor; other input types trigger an error that the node catches. If you provide a batch of images, the node processes only the first image. For a useful result, provide an image in the expected image-tensor format with a clearly visible hand. No default, minimum, or maximum is specified.
max_hands
The requested maximum number of hands to detect. The default is 2, with a minimum of 1 and a maximum of 4. Choosing a lower value can keep the result focused when you only need one or two hands. In wan_2.1 mode, the code limits this setting to at most two hands; in wan_2.2 mode, it uses your selected value. This is a requested limit, not a guarantee that the node will detect that many hands.
detection_confidence
A setting used to calculate the hand-detection threshold. The default is 0.5, with a minimum of 0.1 and a maximum of 1.0. A higher threshold is intended to make detection more selective, while a lower one is intended to allow less certain detections. The code adjusts this value according to the selected WAN mode before attempting detection, so the value used during processing may differ from the value you enter.
enable_gestures
Controls whether the node adds gesture text for detected hands. The default is True; the available values are True and False. When enabled, the node chooses a label from open_hand, fist, pointing, peace, and thumbs_up and draws it on the image. These labels are selected randomly in the supplied implementation, so they do not describe the actual hand pose. Disable this setting when you need an image without potentially misleading gesture text.
smoothing
A setting exposed for smoothing, with a default of 0.5, a minimum of 0.0, and a maximum of 1.0. The supplied processing code does not use this value. Changing it therefore has no demonstrated effect on landmark positions, image annotations, or other results in this implementation.
wan_version
Selects the node’s WAN-related detection settings. The options are wan_2.1, wan_2.2, and auto; the default is auto. The wan_2.1 path adjusts the detection threshold and caps the requested hand count at two, while wan_2.2 applies a different threshold adjustment and uses the selected max_hands value. In auto mode, the code chooses a path using image-tensor dimensions; its dimension check is not a reliable way to identify a WAN model version. Select a mode explicitly if you need predictable handling of the hand-count setting.
enable_t2i_adapter
Controls whether an additional value is appended to each hand landmark. The default is True; the available values are True and False. When enabled, each landmark has a fourth value set to 1.0, described in the code as an adapter-compatibility flag. When disabled, each landmark has only its position values. This changes the shape of the landmark data; the supplied code does not itself send that data to a T2I-Adapter.
cache_results
A setting exposed for result caching. The default is True; the available values are True and False. Although the node creates a cache manager, the supplied processing method does not read from or write to it. Changing this setting has no demonstrated effect on processing speed or results in this implementation.
✋ Hand Tracking Output Parameters:
hand_landmarks
A list of detected hands, with 21 landmark entries per hand. Each entry contains horizontal and vertical image positions in pixels plus a depth value from the hand detector. If enable_t2i_adapter is on, each entry also contains a fourth value of 1.0. An empty list means no landmark data was returned; it can also be the node’s fallback result after an error. Downstream tools should account for both the empty case and the possible three- or four-value landmark format.
annotated_image
The image returned with a small green dot drawn at each detected landmark position. When gesture labels are enabled, the node also draws their text near the top of the image. The result is an image tensor suitable for previewing or passing to another image node. If processing fails, the node returns a blank image instead, which is a useful sign to check alongside the other outputs.
gestures
A comma-separated text label for detected hands when enable_gestures is on; otherwise, the value is none. It is also none when no gestures are added or when the node returns its fallback result. The labels in this implementation are randomly selected, not inferred from the landmarks, so do not use this output to make decisions about what gesture a person actually made.
confidence
A numeric output that is 0.8 when one or more hands have been processed successfully and 0.0 when none are returned or processing fails. The code adds a fixed placeholder value for each hand and averages it; this is not MediaPipe’s measured detection confidence. It should not be interpreted as a calibrated accuracy score or confused with the detection_confidence input.
✋ Hand Tracking Usage Tips:
- Start with
max_handsset to1for a single-hand image or2for two hands. Raise it only when you need more hands, and usewan_2.2if you need the node to request more than two. - Keep
detection_confidenceat its default of0.5initially. If visible hands are missed, try a lower value; if unwanted detections appear, try a higher value. Review the annotated image after each change rather than relying on theconfidenceoutput, which is a placeholder. - Turn off
enable_gestureswhen producing a clean landmark overlay or when downstream work requires trustworthy pose labels. The landmark dots can still be drawn without the randomly selected gesture text. - Check whether the next node expects three values or four values per landmark. Set
enable_t2i_adaptertoFalsefor three-value landmarks, or leave it on when the next step is designed to accept the added flag. - Feed one image at a time when every image matters. If you supply a batch, this implementation analyzes only its first image.
- Do not rely on
smoothingorcache_resultsto improve a sequence: neither setting is used in the supplied processing method.
✋ Hand Tracking Common Errors and Solutions:
Error in hand tracking: Input image must be a torch.Tensor
- Explanation: The node received an input that was not a PyTorch image tensor. It logs the error and returns empty landmarks, a blank image,
none, and0.0. - Solution: Connect a compatible
IMAGEoutput rather than passing a file path, text value, or other unsupported object directly to the node.
Error in hand tracking: 'NoneType' object is not iterable
- Explanation: When no hands are found, MediaPipe may provide no hand-landmark list. The supplied code attempts to loop over that missing list, causing an error and the fallback outputs.
- Solution: Try an image with a clearly visible, unobstructed hand and adjust
detection_confidence. If you maintain the node code, guard the landmark loop so it runs only when a landmark list exists.
Error in hand tracking: OpenCV color-conversion error
- Explanation: The node passes its converted image to OpenCV for color conversion. An image with an unexpected shape or number of color channels can fail at this step; the exact OpenCV message depends on the image supplied.
- Solution: Use a standard color image from a compatible
IMAGEnode. Avoid feeding an unconverted grayscale image or a tensor with an unusual channel layout.
Error in hand tracking: Tensor conversion or device error
- Explanation: Converting the supplied tensor to a NumPy image can fail if its contents or structure are incompatible with the processing steps. The node catches the underlying exception, logs it with the prefix
Error in hand tracking:, and returns fallback outputs. - Solution: Check that the connected node supplies a valid image tensor, then test with one ordinary color image to isolate the problem.
Blank annotated_image with empty hand_landmarks
- Explanation: A blank image together with an empty list,
none, and0.0is the node’s fallback result after a caught exception. These outputs alone do not identify which processing step failed. - Solution: Check the application log for the message beginning
Error in hand tracking:. Use its remaining text to identify the cause, then retry with a compatible single image.
gestures shows a label that does not match the hand
- Explanation: This is a limitation of the supplied implementation, not evidence of a poorly posed hand. The node selects gesture names randomly.
- Solution: Set
enable_gesturestoFalseif the labels would be misleading. Use a separate gesture-classification step if your workflow needs labels based on the actual pose.
confidence stays at 0.8
- Explanation: The output uses a fixed placeholder value for each processed hand. It does not report how certain the detector was.
- Solution: Judge the result by inspecting
annotated_imageandhand_landmarks. Do not use this output as a threshold for measured detection quality.
