# box-trace-orbbec-reid

**Repository Path**: tunmx/box-trace-orbbec-reid

## Basic Information

- **Project Name**: box-trace-orbbec-reid
- **Description**: 111111111222222222222
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-13
- **Last Updated**: 2025-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# 项目介绍
该项目集成奥比中光的3D深度相机和yolo算法的python项目，由于型号DaBai DCW2 不支持原厂的python接口，所以python接口是从c++接口封装而来

### 开发信息
+ C++ SDK版本： OrbbecSDK-1.10.22 
+ 已验证支持相机 ：DaBai DCW2，Gemini 336L
+ 深度相机深度检测截断 5120 mm（超过该距离只会输出5120）
+ 目前只支持一台设备上运行一台深度相机，多设备请联系开发

### 1.  环境配置

#### ubantu 开启usb 相机权限配置
```bash
    cd ./orbbec/Script
    sudo chmod +x ./install_udev_rules.sh
    sudo ./install_udev_rules.sh
    sudo udevadm control --reload-rules && udevadm trigger
```

#### python 开发环境配置
```bash
    conda conda env create -f environment.yml -n your_env_name
```

### 2. 使用方法

#### 调用方法
```python
    import sys
    from loguru import logger
    from Tracking.track import Track
    from Tracking.logger import setup_logger
    
    # 1. 导入相机sdk库
    try:
        lib_path = "./orbbec/lib"
        sys.path.insert(0, lib_path)
        logger.info(f"尝试从路径导入: {lib_path}")
        import scvOrbbec
    
        logger.info("scvOrbbec模块导入成功")
    except ImportError as e:
        logger.exception("请先编译并安装scvOrbbec模块")
        logger.error(f"导入错误: {e}")
        logger.error(f"Python路径: {sys.path}")
        sys.exit(1)
    
    # 2. 初始化日志和追踪算法
    
    logger = setup_logger()
    track = Track()
    
    # 3. 流式读取追踪结果
    for people in track.stream_processing(is_show=True):
        logger.info(f"peoples: {people.tracking_people.track_id}")
        # people 的数据类型: TrackingBox
```
#### 数据类型
```python

class BoxXXYY:
    x1: int
    y1: int
    x2: int
    y2: int

class TrackingBox:
    box: BoxXXYY
    track_id: int
    distance: int
```

#### 日志错误码信息
```c++
typedef enum {
    SUCCESS = 0,                        // 成功获取图像
    ERROR_INIT_FAILED = -1,             // 初始化失败
    ERROR_DEVICE_NOT_FOUND = -2,        // 未查到设备
    ERROR_STREAM_NOT_AVAILABLE = -3,    // 相机数据流不可用
    ERROR_INVALID_PARAMETER = -4,       // 不可用相机参数
    ERROR_TIMEOUT = -5,                 //  获取帧超时
    ERROR_DEVICE_DISCONNECTED = -6      // 设备链接断开 
} SCVErrorCode;
```

### 3. ReID 目标锁定（保留 ByteTrack）

- 功能：在保持 ByteTrack 的连续视频流跟踪基础上，加入行人 ReID 外观特征，实现“只跟这个人”。
- 模型位置：`./asserts/baseline_R50_2.onnx`
- 依赖：`onnxruntime`（已加入 `Tracking/requirements.txt`）
- 跟踪器：默认强制使用 ByteTrack（`ultralytics/cfg/trackers/bytetrack.yaml`）。

#### 用法示例

1) 锁定已知 id：
```python
from Tracking.track import Track

t = Track()
# 锁定指定 id（例如 42），相似度阈值可调（0~1，越大越严格）
t.start_lock(target_id=42, similarity_threshold=0.8)

for people in t.stream_processing(is_show=True):
    print("locked:", people.tracking_people.track_id)
```

2) 锁定第一个出现的人（负数 id 进入“待选期”，自动锁定首个出现的 id）：
```python
from Tracking.track.py import Track

t = Track()
t.start_lock(target_id=-1, similarity_threshold=0.8)

for people in t.stream_processing(is_show=True):
    print("locked-first:", people.tracking_people.track_id)
```

3) 取消锁定，恢复常规：
```python
t.stop_lock()
```

#### 行为说明
- 锁定开启后：仅输出被锁定的目标；如果当前帧中出现该 id，则优先使用它并更新模板特征。
- 丢失时：使用 ReID 余弦相似度与模板比对进行重识别，若相似度 ≥ 阈值即“认回”。
- 负数 id：进入“待选期”，当画面出现任意行人时锁定其 id 并提取模板。

#### 可调参数
- `similarity_threshold`：默认 0.7（推荐 0.7~0.9）。
- 模板动量 `lock_feat_momentum`：默认 0.9（越大越稳，越小适应越快）。
- ByteTrack 的 `track_buffer` 可在 `ultralytics/cfg/trackers/bytetrack.yaml` 中适当提高（如 60~90）增强遮挡后的回归窗口。

#### 性能建议
- ReID 在 CPU 上有额外开销；本实现仅在锁定/刷新/丢失重识别时进行特征提取，已做基础优化。
- 若性能紧张，可提高阈值、降低分辨率、或减少提特征频率。

#### 故障排查
- “ReID 模型加载失败”：检查 `./asserts/baseline_R50_2.onnx` 路径是否存在，或安装 `onnxruntime`。