update comment

example1_basic.py

@@ -1,42 +1,130 @@
+"""
+示例 1: 基础用法 - 单传感器同步处理
+
+本示例演示 OrisysSensor 的基本使用流程：
+1. 初始化传感器（视频文件或摄像头）
+2. 循环获取图像并计算形变
+3. 读取各类传感器数据
+4. 可视化显示
+
+适用场景：单传感器、简单应用、学习入门
+"""
+
 import os
-os.environ["OPENCV_VIDEOIO_MSMF_ENABLE_HW_TRANSFORMS"] = "0"
+os.environ["OPENCV_VIDEOIO_MSMF_ENABLE_HW_TRANSFORMS"] = "0"  # Windows 下禁用硬件加速，避免兼容性问题
+
 import cv2
 import orisys
 
+
 def main():
+    # =========================================================================
+    # 1. 初始化传感器
+    # =========================================================================
+    # 参数说明：
+    #   vid_src:  视频源，可以是文件路径（如 "./s1.mp4"）或摄像头索引（如 0）
+    #   isstitch: 是否启用复眼拼接模式（多单元传感器需要开启）
+    #   cuda:     是否使用 CUDA GPU 加速（需要 CuPy 和 CUDA 支持）
+    #   verbose:  是否打印详细初始化日志
+    
+    # 方式1: 从视频文件读取
+    sensor = orisys.Sensor("./s1.mp4", isstitch=True, cuda=True, verbose=True)
+    
+    # 方式2: 从摄像头读取（取消注释使用）
+    # sensor = orisys.Sensor(0, isstitch=True, cuda=True, verbose=True)
 
-    # 打开视频
-    sensor1 = orisys.Sensor("./s1.mp4",isstitch=True,cuda = True,verbose = True)
-    # 打开摄像头
-    # sensor1 = Sensor(0,isstitch=True,cuda = True,verbose = True)
-
+    print("\n按 'q' 退出程序，按 'r' 重置光流追踪器")
 
+    # =========================================================================
+    # 2. 主循环：获取图像 → 计算形变 → 读取数据 → 显示
+    # =========================================================================
     while True:
-        sensor1.get_img() # 提取并拼接复眼图像
-        sensor1.compute_deformation() # 计算形变和分解
-        # 提取信息：
-        # 向量场: VRAW, VNORMAL, VSHEAR: 原始，法向，切向 
-        # 帧率，时间戳: FPS, TIMESTAMP
-        # 变形量总和: FNORMAL , FSHEARX, FSHEARY : 法向，切向（X)，切向（Y)
-        # 深度图: DEPTH
-        fps, fn, fx, fy, flow, depth = sensor1.read_info(sensor1.info.FPS, sensor1.info.FNORMAL, sensor1.info.FSHEARX, sensor1.info.FSHEARY, sensor1.info.VRAW, sensor1.info.DEPTH)
-        print(fps,fn,fx,fy)
-        # 显示向量场
-        arrows = orisys.util.draw_arrows(sensor1.img, flow, threshold=5, grid_spacing=40, arrow_scale=1.0)
-        cv2.imshow("Deformation", arrows)
+        # 步骤 2.1: 获取并拼接图像
+        # get_img() 完成以下操作：
+        #   - 从视频源读取一帧
+        #   - 转换为灰度图
+        #   - 提取各个视觉单元并拼接
+        #   - 应用时域滤波降噪
+        sensor.get_img()
+        
+        # 步骤 2.2: 计算形变场
+        # compute_deformation() 完成以下操作：
+        #   - 计算光流（追踪像素位移）
+        #   - HHD 分解（分离法向和切向分量）
+        #   - 计算力的大小
+        #   - 计算深度图
+        sensor.compute_deformation()
+        
+        # 步骤 2.3: 读取传感器数据
+        # read_info() 支持以下数据类型：
+        #   向量场数据：
+        #     - VRAW:    原始光流场 (H, W, 2) 的 numpy 数组
+        #     - VNORMAL: 法向分量场
+        #     - VSHEAR:  切向分量场
+        #   标量数据：
+        #     - FNORMAL: 法向力总和（正压力）
+        #     - FSHEARX: X方向切向力
+        #     - FSHEARY: Y方向切向力
+        #   其他：
+        #     - FPS:       当前帧率
+        #     - TIMESTAMP: 时间戳字符串
+        #     - DEPTH:     深度图（归一化 0-1）
+        fps, fn, fx, fy, flow, depth = sensor.read_info(
+            sensor.info.FPS,
+            sensor.info.FNORMAL,
+            sensor.info.FSHEARX,
+            sensor.info.FSHEARY,
+            sensor.info.VRAW,
+            sensor.info.DEPTH
+        )
+        
+        # 打印力的数值
+        print(f"FPS: {fps:5.1f}, 法向力: {fn:8.2f}, 切向力X: {fx:8.2f}, 切向力Y: {fy:8.2f}")
+        
+        # =====================================================================
+        # 3. 可视化显示
+        # =====================================================================
+        # 绘制光流箭头图
+        # 参数说明：
+        #   img:          背景图像
+        #   flow:         光流场
+        #   threshold:    显示阈值（小于此值的箭头不显示）
+        #   grid_spacing: 箭头网格间距（像素）
+        #   arrow_scale:  箭头缩放比例
+        arrows = orisys.util.draw_arrows(
+            sensor.img.copy(),  # 使用 copy() 避免修改原图
+            flow,
+            threshold=5,
+            grid_spacing=40,
+            arrow_scale=1.0
+        )
+        cv2.imshow("形变场 Deformation", arrows)
 
-        depth_img = cv2.applyColorMap((depth*1* 255.0).astype('uint8'), cv2.COLORMAP_HOT)
-        cv2.imshow('depth', depth_img)
+        # 绘制深度图（热力图）
+        depth_img = cv2.applyColorMap(
+            (depth * 255.0).astype('uint8'),
+            cv2.COLORMAP_HOT
+        )
+        cv2.imshow("深度图 Depth", depth_img)
 
-        key = cv2.waitKey(1)
-        if key & 0xFF == ord("q"):
-            print("\n 停止程序")
+        # =====================================================================
+        # 4. 键盘控制
+        # =====================================================================
+        key = cv2.waitKey(1) & 0xFF
+        if key == ord("q"):
+            print("\n退出程序...")
             break
-        if key & 0xFF == ord("r"):
-            sensor1.reset()
-    
-    sensor1.disconnect() # 断开传感器连接
+        if key == ord("r"):
+            # 重置光流追踪器（当追踪漂移时使用）
+            sensor.reset()
+            print("光流追踪器已重置")
     
+    # =========================================================================
+    # 5. 清理资源
+    # =========================================================================
+    sensor.disconnect()  # 释放视频源和相关资源
+    cv2.destroyAllWindows()
+
 
 if __name__ == '__main__':
     main()