奥比 Gemini 305 局域网 MJPEG 推流

ljh_gemini_305 --- 奥比 Gemini 305 局域网 MJPEG 推流

在 同一局域网 内用浏览器或 VLC 查看 Gemini 305 彩色画面；访问方式与常见网络摄像头一致，例如 http://<主机IP>:8080/video.mjpeg。

作者： 算个文科生吧
联系方式： lijinghailjh@163.com

---

预览

硬件：Orbbec Gemini 305

双目结构光 / 深度相机，金属外壳，侧面 USB-C 供电与数据。

局域网 MJPEG 画面（推理 / 监控）

在 连接相机的电脑 上启动本服务后，局域网内其它设备浏览器打开（请将 IP 换成你的推流机地址，端口与 --port 一致，默认 8080）：

http://192.168.100.213:8080/video.mjpeg

下图为 上述地址实际截图（摄像头拍摄到的画面，可用于推理结果展示或远程监看）。

---

功能概览

能力	说明
默认 V4L2	OpenCV + CAP_V4L2，启动快，无需安装 Orbbec SDK 即可看图
可选 Orbbec SDK	--backend orbbec / auto，需 USB 权限与 pyorbbecsdk
/video.mjpeg	标准 MJPEG over HTTP （multipart/x-mixed-replace）
/stream	兼容旧路径，与 /video.mjpeg 同源流
Gemini305 适配	优先 MJPEG 节点、探测读超时、gemini 扫描顺序，减轻 YV12 误解码花屏 与 某路 /dev/video 卡死

---

快速开始

git clone <你的仓库地址>.git
cd ljh_gemini_305
pip3 install --user -r ljh_requirements.txt
python3 ljh_lan_mjpeg_server.py --host 0.0.0.0

浏览器打开：http://<运行上列命令的机器局域网IP>:8080/video.mjpeg

仅探测摄像头、不启动 HTTP（排查用）：

python3 ljh_lan_mjpeg_server.py --smoke-test

---

环境要求

项目	说明
操作系统	Linux （已在 NVIDIA Jetson + Gemini 305 环境验证）
Python	建议 3.10 （与常见 pyorbbecsdk2 预编译 wheel 对应）
用户组	需在 video 组以访问 V4L2；使用 SDK 时建议配置 udev（见下）
依赖	见 ljh_requirements.txt （numpy、opencv-python-headless）

---

安装

1）Python 依赖

pip3 install --user -r ljh_requirements.txt

2）（可选）Orbbec Python 封装

仅在 --backend orbbec 时需要。脚本含多镜像下载与超时设置：

chmod +x ljh_install_orbbec_python.sh
./ljh_install_orbbec_python.sh

安装失败时仍可 仅用 V4L2 看图。

3）（可选）USB 权限（SDK）

sudo cp udev/ljh_99-orbbec.rules /etc/udev/rules.d/ljh_99-orbbec.rules
sudo udevadm control --reload-rules && sudo udevadm trigger

然后 重新插拔 相机。

---

使用与访问

启动

python3 ljh_lan_mjpeg_server.py --host 0.0.0.0

• 0.0.0.0：监听所有网卡，便于局域网访问。
• 启动后终端会打印 网页首页 与 /video.mjpeg 的完整 URL。

访问地址

用途	URL
带简单预览页	http://<IP>:8080/
MJPEG 流（推荐）	http://<IP>:8080/video.mjpeg
兼容旧路径	http://<IP>:8080/stream

VLC、ffplay 等可直接打开 video.mjpeg ；请确保本机防火墙放行 8080（或你指定的端口）。

---

命令行参数

参数	说明
--host 0.0.0.0	绑定地址；仅本机调试可用 127.0.0.1
--port 8080	TCP 端口，默认 8080
--backend v4l2	默认，OpenCV 取流
--backend orbbec	使用 pyorbbecsdk
--backend auto	先试 SDK，失败再 V4L2（略多等待）
--device N	固定使用 /dev/videoN，跳过自动探测
--v4l2-fourcc auto	默认 ；尝试顺序：MJPG → 默认 → YUYV → YUY2
--v4l2-fourcc mjpg / yuyv / default	固定子集
--v4l2-scan gemini	默认 ；优先探测 2、4、6 等常见彩色节点
--v4l2-scan all	扫描 video0～video9（更慢）
--jpeg-quality 85	非硬件 MJPEG 时再编码 JPEG 的质量（1～100）
--smoke-test	只探测设备后退出

示例（固定某路 MJPEG，可选）：

python3 ljh_lan_mjpeg_server.py --host 0.0.0.0 --device 6 --v4l2-fourcc mjpg

---

故障排查

现象	建议
长时间无输出像卡住	已默认 V4L2 与快速探测；用 --smoke-test 看卡在哪一路
花屏、绿紫斜纹	多为 像素格式与缓冲区布局不符 ；保持 --v4l2-fourcc auto ，优先 MJPEG 节点
只有 640×480 等较低分辨率	部分机型 高清 V4L2 口布局异常 ；稳定看图用 MJPEG ；高分辨率可试 --backend orbbec
ljh_install_orbbec_python.sh 下载失败	换网络或手动下载 wheel 后 pip install；看图可不装 SDK
局域网打不开	检查 防火墙、IP 是否同网段、服务是否在本机已启动

---

实现原理（简要）

1. 采集 ：默认 cv2.VideoCapture + CAP_V4L2 ，枚举 /dev/video*。
2. 格式 ：优先 MJPEG 或驱动已解码的 BGR ；仅在缓冲区为规范 平面 YUV420 （(高+高/2)×宽 单平面）时才做平面解码，避免 把 YV12 与 H×W×3 误当 BGR。
3. 编码 ：非 JPEG 帧用 cv2.imencode('.jpg', ...) 生成 JPEG 字节。
4. 传输 ：ThreadingHTTPServer ，对 /video.mjpeg 返回 multipart/x-mixed-replace ，每帧 Content-Type: image/jpeg。

为何优先 MJPEG： 同一相机多路 V4L2 时，某路在 YUYV 请求下仍报 YV12 且 read() 得到 (800,1280,3) ，按 BGR 显示会花屏；另一路 FOURCC=MJPG 时解码稳定。故 auto 先试 MJPG ，并在探测评分中 提高 MJPEG/YUYV 权重、压低可疑 YV12 路，避免误选「分辨率高但不可用」的节点。

防阻塞： 在 open() 前 设置 CAP_PROP_READ_TIMEOUT_MSEC 等，减少 depth/IR 等节点 read() 永久阻塞 ；gemini 扫描先试 2、4、6，满足条件可跳过后续易卡节点。

SDK 路径： pyorbbecsdk Pipeline 取彩色帧；MJPEG 帧可直接推送 JPEG，其它格式经 ljh_orbbec_color.frame_to_bgr 再编码。

---

仓库结构

路径	说明
ljh_lan_mjpeg_server.py	主程序：HTTP 服务、V4L2 探测、MJPEG 推流
ljh_orbbec_color.py	SDK 彩色帧 → BGR（--backend orbbec）
ljh_requirements.txt	pip 依赖列表
ljh_install_orbbec_python.sh	可选安装 pyorbbecsdk2
udev/ljh_99-orbbec.rules	Orbbec USB 非 root 访问规则
images/	README 配图（相机外观、流画面截图），提交时请一并加入版本库
README.md	本说明（GitHub 首页）
Log/	SDK 运行可能产生的日志（未加 ljh_ 前缀，避免干扰 SDK）

---

源码地址

https://github.com/lijinghai/ljh_gemini_305

---

开源与许可

• 发布到 GitHub 前请在仓库根目录添加 LICENSE （如 MIT / Apache-2.0），并遵守 奥比中光 固件与 SDK 的许可条款。
• ljh_orbbec_color.py 中部分转换思路参考官方示例；二次分发时请保留相应说明并遵守厂商要求。

---