为所有函数和类添加中文注释文档字符串

app/vision/frame_utils.py

@@ -9,6 +9,7 @@ TARGET_HEIGHT = 720
 
 
 def resize_to_target(image: np.ndarray, width: int = TARGET_WIDTH, height: int = TARGET_HEIGHT) -> np.ndarray:
+    """将图像缩放到目标尺寸（仅当尺寸不一致时）"""
     h, w = image.shape[:2]
     if w == width and h == height:
         return image
@@ -16,8 +17,10 @@ def resize_to_target(image: np.ndarray, width: int = TARGET_WIDTH, height: int =
 
 
 def bgr_to_rgba(bgr: np.ndarray) -> np.ndarray:
+    """将BGR格式图像转换为RGBA格式"""
     return cv2.cvtColor(bgr, cv2.COLOR_BGR2RGBA)
 
 
 def bgr_to_rgb(bgr: np.ndarray) -> np.ndarray:
+    """将BGR格式图像转换为RGB格式"""
     return cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB)

app/vision/pose_landmarker.py

@@ -14,8 +14,9 @@ PoseLandmarkerOptions = mp.tasks.vision.PoseLandmarkerOptions
 VisionRunningMode = mp.tasks.vision.RunningMode
 BaseOptions = mp.tasks.BaseOptions
 
-
 class PoseLandmarkerWrapper:
+    """MediaPipe姿态关键点检测器封装"""
+
     def __init__(
         self,
         *,
@@ -23,6 +24,7 @@ class PoseLandmarkerWrapper:
         prefer_gpu: bool = True,
         result_callback: Callable | None = None,
     ) -> None:
+        """初始化姿态检测器，优先尝试GPU委托，失败则回退到CPU"""
         self.model_path = model_path or DEFAULT_MODEL_PATH
 
         if prefer_gpu:
@@ -39,6 +41,7 @@ class PoseLandmarkerWrapper:
         logger.info("MediaPipe PoseLandmarker initialized with CPU delegate")
 
     def _create(self, delegate, result_callback=None):
+        """根据委托类型和回调创建PoseLandmarker实例"""
         options = PoseLandmarkerOptions(
             base_options=BaseOptions(model_asset_path=self.model_path, delegate=delegate),
             running_mode=VisionRunningMode.LIVE_STREAM,
@@ -51,7 +54,9 @@ class PoseLandmarkerWrapper:
         return PoseLandmarker.create_from_options(options)
 
     def detect_async(self, mp_image, timestamp_ms: int) -> None:
+        """异步执行姿态检测"""
         return self._landmarker.detect_async(mp_image, timestamp_ms)
 
     def close(self) -> None:
+        """释放MediaPipe资源"""
         self._landmarker.close()