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 > kanibus > ✋ Hand Tracking

ComfyUI Node: ✋ Hand Tracking

Class Name

HandTracking

Category
Kanibus
Author
kanibus (Account age: 1410days)
Extension
kanibus
Latest Updated
2025-08-04
Github Stars
0.01K

How to Install kanibus

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

✋ Hand Tracking Description

Uses MediaPipe to detect hand landmarks and return their positions with an annotated image.

✋ 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_hands set to 1 for a single-hand image or 2 for two hands. Raise it only when you need more hands, and use wan_2.2 if you need the node to request more than two.
  • Keep detection_confidence at its default of 0.5 initially. 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 the confidence output, which is a placeholder.
  • Turn off enable_gestures when 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_adapter to False for 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 smoothing or cache_results to 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, and 0.0.
  • Solution: Connect a compatible IMAGE output 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 IMAGE node. 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, and 0.0 is 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_gestures to False if 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_image and hand_landmarks. Do not use this output as a threshold for measured detection quality.

✋ Hand Tracking Related Nodes

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

✋ Hand Tracking