# stitch

**Repository Path**: mgdh/stitch

## Basic Information

- **Project Name**: stitch
- **Description**: 实现jetson适配的拼接代码
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GPU 多路相机拼接

本应用接收异步相机码流，进行硬件解码，按时间戳匹配帧，使用 CUDA 拼接 NV12
画面，并通过 Qt/OpenGL 显示结果。

## 架构

```text
CameraSource（当前为 FFmpeg，Jetson 计划使用 GStreamer）
    -> toolkit::media::Frame + 引用计数 surface
    -> toolkit::media::FrameSynchronizer（兼容别名 InputCache）
    -> StitchConsumer
    -> toolkit::ops::cuda NV12 合成器
    -> toolkit::common::BoundedQueue
    -> Qt/OpenGL 或输出适配器
```

热路径在队列和同步器中不拷贝像素。`Frame` 持有一个类型擦除、引用计数的
surface。当前 FFmpeg 在该句柄中存放 `AVFrame`；Orin 源可以存放
`NvBufSurface` 而无需改动 `InputCache`。

可复用的队列、帧模型、同步器以及 CUDA NV12 算子位于同级
[`toolkit`](../../toolkit) 项目中。stitch 仅保留旧名称的薄别名，以及
FFmpeg/CUDA 的应用适配器。

关于组件边界、同步行为以及 Orin/ROS 2 集成规划，请参阅
[docs/architecture.md](docs/architecture.md)。

## 环境要求

- Linux
- NVIDIA 驱动与 CUDA
- FFmpeg 开发包（`libavcodec`、`libavformat`、`libavutil`、`libswscale`）
- 可执行文件需要 Qt 5 Widgets 与 OpenGL
- spdlog 与 nlohmann-json
- CMake 3.18 或更新版本

随附的容器镜像仍是复现原始开发环境的最简便方式：

```bash
make stitch_env
make build
```

使用已拷贝到构建目录的默认配置运行：

```bash
cd build
./stitch_app --config resource/hk5.json
```

`STITCH_CONFIG=/path/to/config.json` 同样受支持，命令行选项的优先级更高。

## 同步配置

```json
"synchronization": {
  "cache_depth": 3,
  "tolerance_ms": 20,
  "max_wait_ms": 80
}
```

- `cache_depth` 是每路相机保留的最大已解码 surface 引用数。旧帧会被丢弃，
  但不会拷贝像素。
- `tolerance_ms` 是成组输出帧集合的最大时间戳跨度。
- `max_wait_ms` 限制一个不完整的帧集合最多可拖延整条管线的时长。

FFmpeg 适配器将每路流的 PTS 映射到本地单调时钟。这只提供近似的网络相机
对齐，并非同时曝光。当拼接缝隙处的运动需要真正的相机同步时，请使用 PTP、
硬件触发或统一的采集时钟。

## 拼接配置

`stitch.mode` 可以是 `raw`（水平拼接）或 `homography`（单应变换）。
单应模式需要每路相机各一个 3x3 逆矩阵和一个四角输出区域。这些值现在是
配置数据，而非 CUDA 源码中的常量。NV12 输出尺寸应为偶数。

## 测试

与平台无关的同步器测试可以不依赖 CUDA 或 FFmpeg 进行构建：

```bash
g++ -std=c++17 -I ../../toolkit/include -I core/utils/include \
  tests/input_cache_test.cpp -o input_cache_test
./input_cache_test
```

完整的应用验证必须在 Linux/Jetson 环境下进行，因为它需要 NVIDIA 硬件解码、
CUDA、FFmpeg 以及 Qt。