# ar_antidizzy

**Repository Path**: captainwilson/ar_antidizzy

## Basic Information

- **Project Name**: ar_antidizzy
- **Description**: ar第一人称视角没有imu降噪时防抖方法的探索
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-20
- **Last Updated**: 2026-01-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Anti-Dizzy Video Stabilization Tools

一套专门针对跑步/第一人称视频的抗眩晕防抖工具集。

## 工具列表

### 1. `jogging_stabilize.py` - 跑步视频防抖

专为跑步/慢跑视频优化的防抖算法，包含：
- **背景优先稳像**：自动排除前景/近景干扰
- **非对称 X/Y 滤波**：Y轴（垂直）更强抑制，减少弹跳感
- **软水平锁**：限制roll角度和角速度
- **步频陷波滤波**：可选，抑制2-3Hz跑步弹跳
- **动态裁切**：根据抖动程度自动调整
- **暗角/边框**：提供稳定参考系

**用法：**
```bash
# 标准模式
python3 jogging_stabilize.py --input video.mp4 --output stable.mp4

# 抗眩晕模式（最强）
python3 jogging_stabilize.py --input video.mp4 --output stable.mp4 --config antidizzy

# 预览 + 调试信息
python3 jogging_stabilize.py --input video.mp4 --output stable.mp4 --display --debug

# 快速处理（降低质量）
python3 jogging_stabilize.py --input video.mp4 --output stable.mp4 --me-scale 0.3 --max-features 600
```

**配置模式：**
- `gentle` - 轻度防抖，裁切最小
- `standard` - 平衡模式（默认）
- `antidizzy` - 最强抗眩晕，包含步频滤波

**输出：** 自动生成左右对比视频（原始 | 稳定）

---

### 2. `realtime_stream_stabilize.py` - 实时流防抖（快、可上云）

实时拉流（RTSP/HTTP 等）→ 稳像 → RTMP 或 HLS 推流。支持 H.264/H.265 输入，使用稀疏光流（LK）或 ORB 做运动估计，可选 GPU 做 warp/vignette。

**用法：**
```bash
# 从项目根目录运行（或 cd ar_antidizzy）
python3 ar_antidizzy/realtime_stream_stabilize.py \
  --input "rtsp://camera/stream" \
  --output-rtmp "rtmp://server/live/out"

# 输出 HLS 到目录
python3 ar_antidizzy/realtime_stream_stabilize.py \
  --input "http://example.com/stream.m3u8" \
  --output-hls /tmp/hls_out

# 使用 ORB、指定 GPU、不自动重连
python3 ar_antidizzy/realtime_stream_stabilize.py \
  --input "rtsp://..." --output-rtmp "rtmp://..." \
  --motion orb --device cuda --no-reconnect
```

**参数：**
- `--input` - 输入流 URL（RTSP/SRT/HTTP）
- `--output-rtmp` - 输出 RTMP URL
- `--output-hls` - 输出 HLS 目录（生成 playlist.m3u8）
- `--config` - gentle / standard / antidizzy
- `--motion` - sparse_flow（默认，更快）或 orb
- `--device` - auto / cuda / cpu（warp/vignette 用 GPU 时需安装 torch）

**API 服务（可选）：**
```bash
# 安装 API 依赖
pip install -r ar_antidizzy/requirements-stream.txt

# 启动 FastAPI
python3 ar_antidizzy/stream_service.py
# 或: uvicorn ar_antidizzy.stream_service:app --host 0.0.0.0 --port 8000

# 启动稳像任务
curl -X POST http://localhost:8000/v1/stream \
  -H "Content-Type: application/json" \
  -d '{"stream_url":"rtsp://...","output":{"type":"rtmp","url":"rtmp://..."}}'

# 停止
curl -X POST http://localhost:8000/v1/stream/{session_id}/stop
```

---

### 3. `add_fixation_overlay.py` - 视觉锚点叠加

添加固定视觉锚点，减少运动眩晕：
- **中心大十字**：占分辨率10%，提供中心锚点
- **四角小十字**：淡绿色，提供外围参考系

**布局：**
```
+               +      ← 四角小十字 (淡绿色)
    
        +              ← 中心大十字 (白色, 10%分辨率)
    
+               +
```

**用法：**
```bash
# 基本用法
python3 add_fixation_overlay.py -i video.mp4 -o video_fix.mp4

# 自定义大小
python3 add_fixation_overlay.py -i video.mp4 -o video_fix.mp4 \
    --center-ratio 0.15 --corner-size 20

# 预览
python3 add_fixation_overlay.py -i video.mp4 -o video_fix.mp4 --display
```

**参数：**
- `--center-ratio` - 中心十字占分辨率比例（默认0.10 = 10%）
- `--corner-size` - 角落十字大小（默认14px）
- `--corner-color` - 角落十字颜色（默认144,238,144 = 淡绿色）
- `--center-color` - 中心十字颜色（默认255,255,255 = 白色）

---

### 4. `anti_dizzy_stabilize.py` - 通用防抖

通用的在线防抖脚本，支持三种模式：
- `normal` - 低延迟，轻度稳像
- `ultra` - 更强稳像
- `anti` - 抗眩晕优先

**用法：**
```bash
python3 anti_dizzy_stabilize.py --input video.mp4 --output stable.mp4 --mode anti
```

---

## 推荐工作流

### 方案1：防抖 + 锚点（推荐）
```bash
# 1. 先防抖
python3 jogging_stabilize.py --input raw.mp4 --output stable.mp4 --config antidizzy

# 2. 再叠加锚点
python3 add_fixation_overlay.py -i stable.mp4 -o final.mp4
```

### 方案2：仅防抖
```bash
python3 jogging_stabilize.py --input raw.mp4 --output stable.mp4 --config standard
```

### 方案3：仅锚点（最快）
```bash
python3 add_fixation_overlay.py -i raw.mp4 -o final.mp4
```

---

## 性能优化

如果处理速度慢，可以：

1. **降低运动估计分辨率**
   ```bash
   --me-scale 0.3  # 默认0.5，越小越快
   ```

2. **减少特征点数量**
   ```bash
   --max-features 600  # 默认1500
   ```

3. **使用轻量模式**
   ```bash
   --config gentle  # 最轻防抖
   ```

---

## 依赖

```bash
pip install opencv-python numpy
```

---

## 注意事项

- 防抖会裁切部分画面（通常5-20%）
- 输出视频宽度是输入的2倍（左右对比）
- 处理速度取决于视频分辨率和硬件
- 建议先用 `--display` 预览效果

---

## 技术原理

### 防抖算法
- 运动估计：ORB特征点 + RANSAC
- 轨迹平滑：One Euro Filter + 速度/加速度限制
- 背景优先：mask + 运动一致性过滤
- 步频抑制：IIR陷波滤波器（2-3Hz）

### 视觉锚点
- 中心十字：提供中央注视点，减少眼球运动
- 外围十字：提供稳定参考系，减少前庭冲突

---

## License

MIT