processor/app/processing/black_glove/README.md

Bundled black-glove processing

This directory contains the code and default model used by the black_glove_hand workflow module. It is intentionally inside Data Acquisition so the worker does not import the legacy repository-level black-glove demo.

Contents:

• glove_detector.py: YOLO-World box detection, RTMPose hand keypoints and temporal stabilization.
• glove_package/: local tracker and YOLO-World wrapper.
• d435_hands_demo.py: local RGB-D alignment/lifting helper used when a compatible depth stream is available.
• d435_tracking.py: local, NumPy-only depth jump gate and alpha-beta slot predictor. It is the production workflow's extracted v1.0 tracking logic; it does not import the standalone v1.0 project. The workflow adapter also keeps a slot-level depth-centre EMA, per-joint gate recovery, and label/2D geometry fallback when a detector track id is unavailable.
• hand_landmarker.task: MediaPipe model used by the RGB-D/Hand 3D helper.
• weights/yolov8m-worldv2.pt: default black-glove detector weight.

Before publishing a public repository, verify the redistribution terms for the bundled model files. If the model terms do not allow redistribution, keep the code layout and replace the files with a documented download step.

The Python dependencies are declared in the parent processor requirements.txt. RTMPose model assets may be downloaded by rtmlib on first use and cached by the Python environment; this is a package/runtime dependency, not a dependency on another repository directory.

Output semantics

The hand_3d/*.parquet artifact keeps both preview continuity and data quality explicit for each slot:

• real: current YOLO/RTMPose + depth observation accepted;
• propagated: bounded D435 alpha-beta prediction, for preview continuity;
• absent: no observation and no bounded prediction.

The RGB renderer hides detector rectangles, but the detector still uses its internal ROI. propagated frames are retained in this raw artifact for a continuous preview; they are excluded from the default training export.

The raw artifact keeps propagated rows so the 3D viewer can remain continuous. LeRobot/HDF5 training export filters state != "real" by default, so predicted points are not silently used as labels.

Future detector fine-tuning augmentation

The current repository has no detector-training command, so augmentation is not applied to inference code. When fine-tuning a glove-specific detector or 21-point pose model, build the training set from whole video sequences and add motion blur, random frame exposure, black-object/background swaps, partial occlusion, crop/scale jitter, and hand-edge truncation. Split validation by sequence/person, not by random frames, and keep a clean unaugmented test set.