# Orbbec_Astra_Pro_Plus

**Repository Path**: myx_2024/Orbbec_Astra_Pro_Plus

## Basic Information

- **Project Name**: Orbbec_Astra_Pro_Plus
- **Description**: 奥比中光 Orbbec_Astra_Pro_Plus
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-19
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Orbbec Astra Pro Plus - MJPEG 流媒体服务器

## 目录

- [项目架构](#项目架构)
- [系统架构图](#系统架构图)
- [功能特性](#功能特性)
- [文件结构](#文件结构)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [API 端点](#api-端点)
- [配置参数](#配置参数)
- [版本信息](#版本信息)

---

基于 Python 的 Orbbec Astra Pro Plus 深度摄像头 MJPEG 实时流媒体服务器，跨平台兼容 Windows / Linux，通过 HTTP 在局域网内提供摄像头实时画面，适用于 Docker 容器内无 X11 显示环境。

## 项目架构

项目采用 **单进程多线程** 架构，自上而下分为三层：

```
┌─────────────────────────────────────────────┐
│              浏览器客户端 (Client)             │
│          http://<本机IP>:8080                │
└──────────────────┬──────────────────────────┘
                   │  HTTP GET / | /stream
                   ▼
┌─────────────────────────────────────────────┐
│           ThreadedHTTPServer (:8080)         │
│  多线程 HTTP 服务器，每个请求一个线程处理        │
│  ┌───────────────┐  ┌───────────────┐       │
│  │  MJPEGHandler │  │  MJPEGHandler │  ...  │
│  │   (Thread-1)  │  │   (Thread-2)  │       │
│  └───────┬───────┘  └───────┬───────┘       │
│          │ 共享 camera_cap    │               │
└──────────┼──────────────────┼───────────────┘
           │                  │
           ▼                  ▼
┌─────────────────────────────────────────────┐
│        cv2.VideoCapture（跨平台后端）         │
│   Linux: V4L2  |  Windows: DSHOW→MSMF→默认   │
│          Orbbec Astra Pro Plus               │
└─────────────────────────────────────────────┘
```

- **表示层** — `MJPEGHandler`: 处理 HTTP 请求，返回 HTML 页面或 MJPEG 视频流
- **服务层** — `ThreadedHTTPServer`: 基于 `ThreadingMixIn` 的多线程服务器，所有 handler 共享同一摄像头实例
- **设备层** — `cv2.VideoCapture`: 跨平台后端回退策略，自动适配驱动 Orbbec 摄像头

## 系统架构图

```mermaid
flowchart TB
    subgraph Client["客户端"]
        Browser["浏览器"]
    end

    subgraph Server["HTTP 服务器 (Port 8080)"]
        Main["main() 入口"]
        IP["_get_local_ip() 获取本机IP"]
        HTTPServer["ThreadedHTTPServer"]
        Handler1["MJPEGHandler\nThread-1"]
        Handler2["MJPEGHandler\nThread-2"]
    end

    subgraph Camera["摄像头层（跨平台）"]
        OpenCV["cv2.VideoCapture\nLinux: V4L2\nWindows: DSHOW→MSMF→默认"]
        Device["Orbbec Astra Pro Plus\n/dev/video* | 摄像头索引"]
    end

    Main -->|"_open_camera()"| OpenCV
    Main -->|"获取本机IP"| IP
    Main -->|"创建绑定 camera_cap + host_ip"| HTTPServer
    HTTPServer -->|"每个请求新建线程"| Handler1
    HTTPServer -->|"每个请求新建线程"| Handler2
    Handler1 -->|"共享 camera_cap"| OpenCV
    Handler2 -->|"共享 camera_cap"| OpenCV
    OpenCV -->|"读取帧"| Device

    Browser -->|"GET /"| Handler1
    Browser -->|"GET /stream"| Handler2
    Handler1 -->|"HTML 页面（动态IP）"| Browser
    Handler2 -->|"MJPEG 流"| Browser
```

## 功能特性

- **跨平台兼容**: 自动检测操作系统，Linux 用 V4L2，Windows 用 DSHOW → MSMF → 默认三级回退
- **动态 IP 检测**: 自动获取本机局域网 IP，HTML 页面和启动提示均动态显示
- **MJPEG HTTP 流**: 通过浏览器即可查看摄像头实时画面，无需额外客户端
- **多线程支持**: 基于 `ThreadingMixIn`，支持多客户端并发访问
- **自动设备检测**: 自动枚举摄像头设备索引，找到第一个可用设备并打开
- **Docker 友好**: 无 GUI 依赖，适合在 Docker 容器中运行

## 文件结构

```
Orbbec_Astra_Pro_Plus/
├── README.md
├── SKILL.md
└── scripts/
    └── cmake_build/
        └── camera_stream_server.py    # MJPEG 流媒体服务器主程序
```

### camera_stream_server.py 内部结构

| 组件 | 类型 | 说明 |
|------|------|------|
| `STREAM_HTML` | 常量 | HTML 页面模板（动态替换本机 IP） |
| `MJPEGHandler` | 类 | HTTP 请求处理器，负责页面渲染和流推送 |
| `ThreadedHTTPServer` | 类 | 多线程 HTTP 服务器 |
| `_open_camera()` | 函数 | 跨平台摄像头初始化（多后端回退） |
| `_get_local_ip()` | 函数 | 获取本机局域网 IP 地址 |
| `main()` | 函数 | 程序入口，启动服务 |

## 环境要求

- **Python**: 3.8+
- **OpenCV**: `opencv-python`
- **操作系统**: Windows / Linux
- **硬件**: Orbbec Astra Pro Plus 摄像头（USB 连接）

## 快速开始

### 1. 安装依赖

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

### 2. 运行服务器

```bash
# Windows / Linux 通用
python3 scripts/cmake_build/camera_stream_server.py
```

启动后会自动检测平台并打印流媒体地址。

### 3. 查看实时画面

在浏览器中打开启动日志提示的地址，例如 `http://172.70.101.208:8080`。

### 4. 端口被占用时

```bash
# 查看占用进程
fuser -v 8080/tcp        # Linux
netstat -ano | findstr :8080   # Windows

# 释放端口后重新运行
```

## API 端点

| 路径 | 方法 | 说明 |
|------|------|------|
| `/` | GET | 返回包含实时画面的 HTML 页面（动态显示本机 IP） |
| `/stream` | GET | 返回 MJPEG 原始视频流 |

## 配置参数

可在代码中调整以下参数：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| 监听端口 | `8080` | HTTP 服务器端口 |
| 目标分辨率 | `1280×720` | 摄像头采集分辨率 |
| 目标帧率 | `30fps` | 摄像头采集帧率 |
| JPEG 质量 | `70` | 压缩质量（0-100），平衡画质与带宽 |
| Linux 设备枚举 | `/dev/video0` ~ `/dev/video2` | V4L2 设备路径 |
| Windows 设备枚举 | 索引 `0` ~ `4` | DSHOW/MSMF 摄像头索引 |
| Windows 后端优先级 | DSHOW → MSMF → 默认 | 三级回退策略 |

## 版本信息

- **版本**: V1.1.0.0
- **最后更新**: 2026-06-29
- **作者**: M-Robot 研发团队 - 异构机器人协同项目组