# HomoMotion

**Repository Path**: PolarisF/HomoMotion

## Basic Information

- **Project Name**: HomoMotion
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-09
- **Last Updated**: 2025-12-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HomoMotion

一个使用单应性变换从视频中提取运动信息的 Python 库。

## 特性

- 🎯 使用 ORB、SIFT 等算法进行特征提取
- 🚀 **CUDA 加速 SIFT** (可选，15-21 倍加速)
- 🔗 稳健的特征匹配和单应性估计
- 🎬 基于地理空间中帧间差异的运动检测
- 🐛 中间结果可视化调试模式
- 🎛️ 简单直观的 API

## 安装

```bash
pip install -r requirements.txt
pip install -e .
```

### 可选：CUDA 加速 (推荐)

如果你有 NVIDIA GPU，可以启用 CUDA 加速的 SIFT，获得 **15-21 倍** 的性能提升：

```bash
# 1. 克隆 E-Sift 到 3rdparty 目录
cd 3rdparty
git clone -b rtx4090 https://github.com/Polaris-F/E-Sift.git esift
# 注意：rtx4090 分支适用于 RTX 4090 (sm_89)
# 其他 GPU 请使用 jetson-dev3 分支并修改 CMakeLists.txt 中的 sm_XX

# 2. 编译
cd esift
mkdir build && cd build
cmake -DBUILD_PYTHON_BINDINGS=ON ..
make -j

# 3. 运行时设置环境变量
export LD_LIBRARY_PATH=/path/to/HomoMotion/3rdparty/esift/build:$LD_LIBRARY_PATH
```

## 快速入门

```python
from homomotion import MotionDetector
import cv2

# 初始化检测器
detector = MotionDetector(
    feature_type='SIFT',      # 或 'CUDA_SIFT' (需要 E-Sift)
    num_frames=3,
    frame_interval=1,
    diff_mode='mean',
    nfeatures=2000,
    debug=True
)

# 加载图像
img1 = cv2.imread('frame_t-2.jpg')
img2 = cv2.imread('frame_t-1.jpg')
img3 = cv2.imread('frame_t.jpg')

# 处理
result = detector.process([img1, img2, img3])

# 访问结果
print(result.homography_matrices)
cv2.imshow('Motion Map', result.motion_map)
cv2.imshow('Valid Mask', result.valid_mask)
```

### 使用 CUDA 加速

```python
# 只需将 feature_type 改为 'CUDA_SIFT'
detector = MotionDetector(
    feature_type='CUDA_SIFT',  # 使用 GPU 加速
    nfeatures=2000
)
```

**性能对比 (1920x1080, 3帧):**

| 方法 | 耗时 | FPS |
|------|------|-----|
| SIFT (CPU) | ~1500 ms | 0.6 |
| CUDA_SIFT (GPU) | ~75-100 ms | 10-14 |

## 核心概念

### 帧差计算

该库通过以下步骤计算运动：
1. 提取连续帧的特征
2. 计算单应性矩阵以将帧对齐到参考帧（通常是最后一帧）
3. 将前一帧转换到参考坐标系
4. 仅在有效重叠区域内计算帧差

### 参数

- `num_frames`: 使用的总帧数（包括参考帧）
- `frame_interval`: 帧间隔（例如，1 表示连续帧）
- `diff_mode`: 
  - `'add'`: 差异的平均值（适用于一般运动）
  - `'subtract'`: 差异的差异（减少远距离物体的重影）

## 要求

- Python >= 3.7
- OpenCV >= 4.5.0
- NumPy >= 1.20.0
- Matplotlib >= 3.3.0

## 许可证

MIT License

## 贡献

欢迎贡献！请随时提交 Pull Request。

## 批量处理工具（生产级）

```bash
python tools/batch_process_directional_motion.py \
    --input_dir "path/to/sequence" \
    --output_root "output/dir"
```