Insta360 云台控制服务

这是一个基于FastAPI的云台控制服务，支持视频流处理、图像捕获和全景图生成。

功能特性

• 🎮 云台控制（pan/tilt）
• 📹 实时视频流
• 📸 图像捕获
• 🖼️ 全景图生成
• 🌐 Web界面

环境变量配置

VIDEO_DEVICE

视频设备路径，默认为 /dev/video7

快速开始

1. 构建Docker镜像

# 构建镜像
sudo docker build -t insta360-driver .

2. 运行容器

# 推荐运行命令（使用--device挂载特定设备）
sudo docker run --rm -it \
  --device=/dev/video7:/dev/video7 \
  -e VIDEO_DEVICE=/dev/video7 \
  -p 8800:8000 \
  insta360-driver

参数说明：

• --device=/dev/video7:/dev/video7: 直接挂载特定视频设备
• -e VIDEO_DEVICE=/dev/video7: 设置环境变量指定视频设备
• -p 8800:8000: 端口映射（主机8800端口映射到容器8000端口）
• --rm: 容器停止后自动删除
• -it: 交互模式运行

3. 访问服务

• API文档: http://localhost:8800/docs
• Web界面: http://localhost:8800/view
• 健康检查: http://localhost:8800/status

API 接口详细说明

基础状态接口

获取云台状态

curl http://localhost:8800/status

响应示例：

{
  "status": "ok",
  "current_pan": "0",
  "current_tilt": "0",
  "state": {
    "pan": 0,
    "tilt": 0,
    "step": 36000
  }
}

截图接口

curl http://localhost:8800/capture

返回JPEG格式的图像数据

云台控制接口

向左旋转

curl -X POST http://localhost:8800/pan-left

向右旋转

curl -X POST http://localhost:8800/pan-right

向上倾斜

curl -X POST http://localhost:8800/tilt-up

向下倾斜

curl -X POST http://localhost:8800/tilt-down

移动到指定位置

# 移动到指定pan和tilt位置
curl -X POST "http://localhost:8800/move-to-position" \
     -H "Content-Type: application/json" \
     -d '{"pan": 360000, "tilt": 180000}'

# 回到原点
curl -X POST "http://localhost:8800/move-to-position" \
     -H "Content-Type: application/json" \
     -d '{"pan": 0, "tilt": 0}'

参数说明：

• pan: 水平旋转角度（范围：-522000 到 522000）
• tilt: 垂直倾斜角度（范围：-522000 到 522000）

响应示例：

{
  "status": "ok",
  "message": "Moved to position pan=360000, tilt=180000",
  "pan": 360000,
  "tilt": 180000
}

全景图生成接口

生成全景图

curl -X POST http://localhost:8800/generate-panorama

功能说明：

• 自动控制云台从-522000到522000度，每次移动36000度
• 在每个位置拍摄一张图片
• 使用OpenCV拼接所有图片生成全景图
• 保存到panorama_YYYYMMDD_HHMMSS.jpg文件

响应示例：

{
  "status": "ok",
  "panorama": "panorama_20241219_143022.jpg",
  "source_images": ["captured_images/pan_-522000.jpg", ...],
  "total_captured": 30,
  "successful_stitching": 30
}

部署方式

1. Docker 直接运行

# 构建镜像
sudo docker build -t insta360-driver .

# 运行容器（指定视频设备）
sudo docker run --rm -it \
  --device=/dev/video7:/dev/video7 \
  -e VIDEO_DEVICE=/dev/video7 \
  -p 8800:8000 \
  insta360-driver

2. Docker Compose

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

3. Kubernetes 部署

准备工作

1. 给有视频设备的节点打标签：

kubectl label nodes <node-name> hardware=camera

2. 确保节点上有视频设备：

# 在节点上检查
ls -la /dev/video*

部署应用

# 应用配置
kubectl apply -f k8s-deployment.yaml

# 查看部署状态
kubectl get pods -l app=insta360-driver

# 查看服务
kubectl get svc insta360-service

修改视频设备

如果需要修改视频设备路径：

# 编辑ConfigMap
kubectl edit configmap insta360-config

# 或者重新应用配置
kubectl apply -f k8s-deployment.yaml

# 重启Pod
kubectl rollout restart deployment insta360-driver

故障排除

视频设备访问问题

1. 检查设备是否存在：

ls -la /dev/video*

2. 检查设备权限：

sudo chmod 666 /dev/video7

3. 检查v4l2-ctl工具：

v4l2-ctl --list-devices

4. 测试设备是否可用：

v4l2-ctl -d /dev/video7 --list-formats-ext

Docker 运行问题

1. 确保使用正确的设备挂载方式：

# 推荐方式
sudo docker run --device=/dev/video7:/dev/video7 ...

# 或者使用特权模式（不推荐）
sudo docker run --privileged -v /dev:/dev ...

2. 检查端口映射：

# 确保端口没有被占用
netstat -tlnp | grep 8800

Kubernetes 部署问题

1. 检查Pod状态：

kubectl describe pod <pod-name>

2. 查看Pod日志：

kubectl logs <pod-name>

3. 检查节点标签：

kubectl get nodes --show-labels | grep camera

注意事项

1. 设备权限: 确保视频设备有正确的读写权限
2. 端口映射: 注意Docker运行时的端口映射（8800:8000）
3. 设备挂载: 推荐使用--device参数而不是--privileged
4. 资源限制: 全景图生成需要较多内存和CPU资源
5. 网络访问: 确保防火墙允许对应端口访问

开发说明

环境变量

• VIDEO_DEVICE: 视频设备路径（默认：/dev/video7）
• PYTHONPATH: Python路径（默认：/app）

文件结构

driver/
├── main.py              # 主应用文件
├── requirements.txt     # Python依赖
├── Dockerfile          # Docker构建文件
├── docker-compose.yml  # Docker Compose配置
├── k8s-deployment.yaml # Kubernetes部署配置
├── README.md           # 说明文档
└── captured_images/    # 截图保存目录

技术栈

• Web框架: FastAPI
• 图像处理: OpenCV
• 视频控制: v4l2-ctl
• 容器化: Docker
• 编排: Kubernetes