# oyjmove

**Repository Path**: ou-yangjie/oyjmove

## Basic Information

- **Project Name**: oyjmove
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-04
- **Last Updated**: 2026-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 运动轨迹记录仪 (Motion Trajectory Recorder)

基于 C++ 和 OpenCV 的实时视觉追踪工具。通过 HSV 颜色空间提取特定颜色的运动物体，实时绘制其运动轨迹，并支持卡尔曼滤波平滑防抖。

## 功能特性

- **实时颜色追踪**：基于 HSV 颜色空间的颜色提取，默认追踪亮绿色物体（可在 `main.cpp` 宏中修改追踪颜色）
- **卡尔曼滤波平滑**：使用匀速运动模型的卡尔曼滤波器，有效抑制手抖和噪声
- **动态轨迹拖尾**：保留最近 N 秒的轨迹，自动清除过期点，带颜色渐变效果
- **画中画调试窗**：主窗口右下角嵌入 HSV 二值化掩膜预览，方便调试颜色阈值
- **按键交互**：
  - `S` — 保存当前画面为 JPG 图片（带时间戳文件名）
  - `C` — 清除轨迹并重置追踪器
  - `ESC` — 退出程序

## 运行环境

| 组件 | 要求 |
|------|------|
| 操作系统 | Ubuntu Linux 20.04+ |
| 编译器 | GCC 7+ / Clang 7+ |
| C++ 标准 | C++11 或更高 |
| OpenCV | 4.x |
| CMake | 3.10+ |
| 摄像头 | 内置/外接 USB 摄像头 |

## 安装依赖

```bash
# 安装 OpenCV 4.x（如果尚未安装）
sudo apt update
sudo apt install libopencv-dev cmake g++

# 验证安装
pkg-config --modversion opencv4
```

## 编译运行

```bash
# 进入项目目录
cd motion_tracker/

# 配置并编译
cmake -B build
cmake --build build

# 运行
./build/motion_tracker
```

## 项目结构

```
motion_tracker/
├── CMakeLists.txt           # CMake 构建文件
├── config.json              # 参数配置文件（运行时参考）
├── src/
│   └── main.cpp             # 主程序源代码
├── docs/
│   ├── README.md            # 本文件
│   ├── AI对话记录.md         # AI 对话记录
│   └── 项目设计说明书.md      # 项目设计说明书
└── build/                   # 构建输出目录（自动生成）
```

## 修改追踪颜色

编辑 `src/main.cpp`，修改以下宏定义：

```cpp
// --- 追踪颜色: 亮绿色（默认）---
#define H_LOW   35      // 色相下限
#define H_HIGH  85      // 色相上限
#define S_LOW   100     // 饱和度下限
#define V_LOW   100     // 明度下限

// 改为追踪红色示例:
// #define H_LOW   0
// #define H_HIGH  10
// #define S_LOW   100
// #define V_LOW   100
```

OpenCV 中 HSV 各通道范围：
- **H (Hue/色相)**: 0 ~ 180（标准 0°~360° 压缩到一半）
- **S (Saturation/饱和度)**: 0 ~ 255
- **V (Value/明度)**: 0 ~ 255

修改后重新编译即可生效。

## 配置文件说明

`config.json` 包含所有运行参数的说明，方便查阅。**注意**：实际运行时参数由 `main.cpp` 中的宏定义控制，`config.json` 仅作为文档参考。修改参数后需重新编译。

## 轨迹存储数据结构

使用 **`std::deque<TrajectoryPoint>`** 存储轨迹点：

| 容器 | 尾部插入 | 头部删除 | 随机遍历 | 适用性 |
|------|---------|---------|---------|--------|
| `std::vector` | O(1) | O(n) | O(1) | 头部删除效率低 |
| `std::queue` | O(1) | O(1) | 不支持 | 无法遍历绘制轨迹线 |
| `std::deque` | O(1) | O(1) | O(1) | **三个操作均最优** |

`std::deque` 在过期点清除（`pop_front`）、新点添加（`push_back`）和轨迹线遍历绘制三个核心操作上均为 O(1)，是最佳选择。

## 按键操作

| 按键 | 功能 |
|:---:|------|
| `S` | 保存当前画面为 `trajectory_YYYYMMDD_HHMMSS.jpg` |
| `C` | 清除所有轨迹，重新初始化卡尔曼滤波器 |
| `ESC` | 安全退出程序 |

## 常见问题

**Q: 摄像头无法打开？**
A: 检查摄像头是否被其他程序占用，或尝试修改 `init_camera(n)` 中的设备 ID（0, 1, 2...）。

**Q: 追踪不到我的物体？**
A: 运行程序，观察右下角画中画窗口的二值化掩膜。如果目标物体没有显示为白色，说明 HSV 阈值不匹配，请在 `main.cpp` 中调整 `H_LOW/H_HIGH/S_LOW/V_LOW`。可使用 OpenCV 的 HSV 调色工具辅助确定阈值。

**Q: 轨迹线抖动很大？**
A: 确保 `SMOOTH_MODE` 设置为 `"KALMAN"`（默认），卡尔曼滤波比移动平均效果更好。也可以适当调大 `GAUSS_KERNEL_SIZE`。

## 许可证

本项目仅供学习和研究使用。