Merge pull request #3 from YanjieZe/main

[add hand isActive state]

Author: zhigenzhao

CLAUDE.md

@@ -0,0 +1,108 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This project provides Python bindings for the XRoboToolkit PC Service SDK, enabling Python applications to extract XR state data including controller poses, hand tracking, and body motion capture from XR devices (primarily PICO headsets).
+
+## Architecture
+
+The project consists of:
+
+- **Core C++ Bindings** (`bindings/py_bindings.cpp`): Pybind11-based C++ module that wraps the PXREARobotSDK
+- **SDK Integration**: Uses the XRoboToolkit-PC-Service SDK (cloned from external repository)
+- **Build System**: CMake-based build with Python setuptools integration
+- **Multi-platform Support**: Linux (x86_64/aarch64) and Windows
+
+Key components:
+- `PXREARobotSDK.h`: Main SDK header providing device connectivity and data parsing
+- `py_bindings.cpp`: Thread-safe C++ wrapper with mutex-protected global state variables
+- JSON parsing using nlohmann/json for device state data
+- Callback-based data updates from the SDK
+
+## Build Commands
+
+### Ubuntu/Linux Setup and Build
+```bash
+# Full setup (downloads dependencies and builds)
+bash setup_ubuntu.sh
+
+# Manual build after setup
+python setup.py install
+
+# Clean build artifacts
+python setup.py clean
+```
+
+### Windows Setup and Build
+```batch
+# Full setup (downloads dependencies and builds)
+setup_windows.bat
+
+# Manual build after setup
+python setup.py install
+```
+
+### Development Commands
+```bash
+# Uninstall existing package
+pip uninstall -y xrobotoolkit_sdk
+
+# Install pybind11 dependency
+conda install -c conda-forge pybind11
+# or
+pip install pybind11
+
+# Build and install
+python setup.py install
+```
+
+## Data Flow and Threading
+
+The SDK uses a callback-based architecture:
+- `OnPXREAClientCallback`: Main callback function that receives JSON data from connected devices
+- Global state variables (poses, button states, etc.) are updated in real-time
+- Thread-safe access via mutex locks for each data category
+- Data parsing from comma-separated pose strings to arrays
+
+## Key Functions and Data Types
+
+### Controller Data
+- Poses: `std::array<double, 7>` (x,y,z,qx,qy,qz,qw)
+- Buttons: Menu, Primary, Secondary, Axis Click
+- Analog: Trigger, Grip, Axis (x,y)
+
+### Hand Tracking
+- 26 joints per hand with 7 values each (position + quaternion)
+- Hand scale factor
+
+### Body Tracking
+- 24 body joints with pose, velocity, acceleration data
+- IMU timestamps for each joint
+- Availability flag for body tracking system
+
+## Dependencies
+
+### Required
+- pybind11 (Python binding framework)
+- CMake (build system)
+- XRoboToolkit-PC-Service SDK (automatically downloaded during setup)
+
+### Platform-specific Libraries
+- Linux: `libPXREARobotSDK.so`
+- Windows: `PXREARobotSDK.dll` and `PXREARobotSDK.lib`
+
+## Testing
+
+No formal test suite is included. Test functionality using the example scripts in `examples/`:
+- `example.py`: Basic controller and headset pose testing
+- `example_body_tracking.py`: Body tracking functionality
+- `run_binding_continuous.py`: Continuous data capture
+
+## Important Notes
+
+- The SDK requires active XR device connection (PICO headset)
+- Body tracking requires at least two Pico Swift devices
+- All data access is thread-safe but real-time dependent on device connectivity
+- The project builds a Python extension module that must be installed to site-packages

README.md

@@ -102,10 +102,19 @@ xrt.init()
 # Left Hand State
 left_hand_tracking_state = xrt.get_left_hand_tracking_state()
 print(f"Left Hand State: {left_hand_tracking_state}")
+
+# Left Hand isActive
+left_hand_is_active = xrt.get_left_hand_is_active()
+print(f"Left Hand isActive: {left_hand_is_active}")
+
 # Right Hand State
 right_hand_tracking_state = xrt.get_right_hand_tracking_state()
 print(f"Right Hand State: {right_hand_tracking_state}")
 
+# Right Hand isActive
+right_hand_is_active = xrt.get_right_hand_is_active()
+print(f"Right Hand isActive: {right_hand_is_active}")
+
 xrt.close()
 ```
 

bindings/py_bindings.cpp

@@ -17,8 +17,10 @@ std::array<double, 7> HeadsetPose;
 
 std::array<std::array<double, 7>, 26> LeftHandTrackingState;
 double LeftHandScale = 1.0;
+int LeftHandIsActive = 0;
 std::array<std::array<double, 7>, 26> RightHandTrackingState;
 double RightHandScale = 1.0;
+int RightHandIsActive = 0;
 
 // Whole body motion data - 24 joints for body tracking
 std::array<std::array<double, 7>, 24> BodyJointsPose;  // Position and rotation for each joint
@@ -148,6 +150,7 @@ void OnPXREAClientCallback(void* context, PXREAClientCallbackType type, int stat
                         std::lock_guard<std::mutex> lock(leftHandMutex);
 
                         LeftHandScale = leftHand["scale"].get<double>();
+                        LeftHandIsActive = leftHand["isActive"].get<int>();
                         for (int i = 0; i < 26; i++) {
                             LeftHandTrackingState[i] = stringToPoseArray(leftHand["HandJointLocations"][i]["p"].get<std::string>());
                         }
@@ -158,6 +161,7 @@ void OnPXREAClientCallback(void* context, PXREAClientCallbackType type, int stat
                     {
                         std::lock_guard<std::mutex> lock(rightHandMutex);
                         RightHandScale = rightHand["scale"].get<double>();
+                        RightHandIsActive = rightHand["isActive"].get<int>();
                         for (int i = 0; i < 26; i++) {
                             RightHandTrackingState[i] = stringToPoseArray(rightHand["HandJointLocations"][i]["p"].get<std::string>());
                         }
@@ -324,6 +328,11 @@ int getLeftHandScale() {
     return LeftHandScale;
 }
 
+int getLeftHandIsActive() {
+    std::lock_guard<std::mutex> lock(leftHandMutex);
+    return LeftHandIsActive;
+}
+
 std::array<std::array<double, 7>, 26> getRightHandTrackingState() {
     std::lock_guard<std::mutex> lock(rightHandMutex);
     return RightHandTrackingState;
@@ -334,6 +343,11 @@ int getRightHandScale() {
     return RightHandScale;
 }
 
+int getRightHandIsActive() {
+    std::lock_guard<std::mutex> lock(rightHandMutex);
+    return RightHandIsActive;
+}
+
 // Body tracking functions
 bool isBodyDataAvailable() {
     std::lock_guard<std::mutex> lock(bodyMutex);
@@ -388,6 +402,8 @@ PYBIND11_MODULE(xrobotoolkit_sdk, m) {
     m.def("get_time_stamp_ns", &getTimeStampNs, "Get the timestamp in nanoseconds.");
     m.def("get_left_hand_tracking_state", &getLeftHandTrackingState, "Get the left hand state.");
     m.def("get_right_hand_tracking_state", &getRightHandTrackingState, "Get the right hand state.");
+    m.def("get_left_hand_is_active", &getLeftHandIsActive, "Get the left hand tracking quality (0 = low, 1 = high).");
+    m.def("get_right_hand_is_active", &getRightHandIsActive, "Get the right hand tracking quality (0 = low, 1 = high).");
 
     // Body tracking functions
     m.def("is_body_data_available", &isBodyDataAvailable, "Check if body tracking data is available.");

examples/test_hand_isactive.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""
+Test script for hand tracking isActive functionality.
+
+This script demonstrates how to use the new isActive functions to check
+hand tracking quality for both left and right hands.
+"""
+
+import xrobotoolkit_sdk as xrt
+import time
+
+def main():
+    try:
+        # Initialize the SDK
+        print("Initializing XRoboToolkit SDK...")
+        xrt.init()
+        
+        print("Testing hand tracking isActive functionality...")
+        print("isActive values: 0 = low quality, 1 = high quality")
+        print("Press Ctrl+C to stop\n")
+        
+        while True:
+            # Get hand tracking states
+            left_hand_state = xrt.get_left_hand_tracking_state()
+            right_hand_state = xrt.get_right_hand_tracking_state()
+            
+            # Get hand tracking quality (isActive)
+            left_hand_active = xrt.get_left_hand_is_active()
+            right_hand_active = xrt.get_right_hand_is_active()
+            
+            
+            print(f"Left Hand:  isActive={left_hand_active}")
+            print(f"Right Hand: isActive={right_hand_active}")
+            
+            # Show hand tracking quality status
+            left_quality = "HIGH" if left_hand_active == 1 else "LOW"
+            right_quality = "HIGH" if right_hand_active == 1 else "LOW"
+            
+            print(f"Left Hand Quality: {left_quality}")
+            print(f"Right Hand Quality: {right_quality}")
+            
+            # Example of first joint position for reference
+            if len(left_hand_state) > 0:
+                left_wrist_pos = left_hand_state[0][:3]  # x, y, z
+                print(f"Left Wrist Position: ({left_wrist_pos[0]:.3f}, {left_wrist_pos[1]:.3f}, {left_wrist_pos[2]:.3f})")
+            
+            if len(right_hand_state) > 0:
+                right_wrist_pos = right_hand_state[0][:3]  # x, y, z
+                print(f"Right Wrist Position: ({right_wrist_pos[0]:.3f}, {right_wrist_pos[1]:.3f}, {right_wrist_pos[2]:.3f})")
+            
+            print("-" * 50)
+            time.sleep(1)
+            
+    except KeyboardInterrupt:
+        print("\nStopping hand tracking test...")
+    except Exception as e:
+        print(f"Error: {e}")
+    finally:
+        print("Closing SDK...")
+        xrt.close()
+
+if __name__ == "__main__":
+    main()