mirror of
https://github.com/sipeed/sipeed_wiki.git
synced 2026-11-09 17:44:31 -06:00
docs(d640): split into 7 pages with GUI guide, accuracy curves, and FAQ
Structure: - maixsense-d640.md: product overview, specs, platform compatibility - quick-start.md: unbox, connect, preview with UVC/GUI/SDK - gui.md: full GUI walkthrough (preview, filters, exposure, OTA, calibration) - sdk.md: C API guide with code examples - firmware.md: three update methods (GUI/CLI/SSH), calibration management - accuracy.md: test data + error curves for both baselines - faq.md: troubleshooting (connection, depth, macOS, bandwidth) Key additions: - macOS: UVC works for preview, NCM needed for vendor control - IR format: MJPEG only (raw YUV exceeds USB 2.0 bandwidth) - Accuracy chart for short baseline (0.3-2m, avg 1.0%) and long baseline (0.5-3m, avg 1.1%) - GUI firmware/calibration upload instructions
This commit is contained in:
lxowalle
@@ -463,6 +463,19 @@ items:
|
||||
file: maixsense/maixsense-a075v/maixsense-a075v.md
|
||||
- label: MaixSense-D640
|
||||
file: maixsense/maixsense-d640/maixsense-d640.md
|
||||
items:
|
||||
- label: Quick Start
|
||||
file: maixsense/maixsense-d640/quick-start.md
|
||||
- label: GUI Guide
|
||||
file: maixsense/maixsense-d640/gui.md
|
||||
- label: SDK Guide
|
||||
file: maixsense/maixsense-d640/sdk.md
|
||||
- label: Firmware
|
||||
file: maixsense/maixsense-d640/firmware.md
|
||||
- label: Accuracy
|
||||
file: maixsense/maixsense-d640/accuracy.md
|
||||
- label: FAQ
|
||||
file: maixsense/maixsense-d640/faq.md
|
||||
- label: SLogic
|
||||
items:
|
||||
- label: SLogic with an AI Agent
|
||||
|
||||
82
docs/hardware/zh/maixsense/maixsense-d640/accuracy.md
Normal file
82
docs/hardware/zh/maixsense/maixsense-d640/accuracy.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# 测量精度
|
||||
|
||||
## 测试条件
|
||||
|
||||
- 镜头：70° FOV，双通滤波片
|
||||
- 传感器：SC035HGS 黑白全局快门
|
||||
- 目标：漫反射平面（避免镜面反光）
|
||||
- 方法：对准已知距离目标，读取中心区域深度均值
|
||||
|
||||
## 精度曲线
|
||||
|
||||
|
||||
|
||||
## 短基线版 (~50mm)
|
||||
|
||||
有效范围：**0.3m ~ 2.0m**
|
||||
|
||||
| 目标距离 (mm) | 测量值 (mm) | 误差 |
|
||||
| :---: | :---: | :---: |
|
||||
| 300 | 296 | -1.33% |
|
||||
| 400 | 398 | -0.50% |
|
||||
| 500 | 507 | +1.40% |
|
||||
| 600 | 598 | -0.33% |
|
||||
| 700 | 699 | -0.14% |
|
||||
| 800 | 818 | +2.25% |
|
||||
| 900 | 901 | +0.11% |
|
||||
| 1000 | 1009 | +0.90% |
|
||||
| 1100 | 1115 | +1.36% |
|
||||
| 1200 | 1196 | -0.33% |
|
||||
| 1300 | 1300 | +0.00% |
|
||||
| 1400 | 1412 | +0.86% |
|
||||
| 1500 | 1485 | -1.00% |
|
||||
| 1600 | 1595 | -0.31% |
|
||||
| 1700 | 1727 | +1.59% |
|
||||
| 1800 | 1784 | -0.89% |
|
||||
| 1900 | 1871 | -1.53% |
|
||||
| 2000 | 2063 | +3.15% |
|
||||
|
||||
**统计：** 平均绝对误差 1.00%，最大误差 3.15%（2000mm 处）
|
||||
|
||||
## 长基线版 (~100mm)
|
||||
|
||||
有效范围：**0.5m ~ 3.0m**
|
||||
|
||||
| 目标距离 (mm) | 测量值 (mm) | 误差 |
|
||||
| :---: | :---: | :---: |
|
||||
| 500 | 502 | +0.40% |
|
||||
| 600 | 601 | +0.17% |
|
||||
| 700 | 703 | +0.43% |
|
||||
| 800 | 803 | +0.38% |
|
||||
| 900 | 904 | +0.44% |
|
||||
| 1000 | 1012 | +1.20% |
|
||||
| 1100 | 1109 | +0.82% |
|
||||
| 1200 | 1213 | +1.08% |
|
||||
| 1300 | 1314 | +1.08% |
|
||||
| 1400 | 1421 | +1.50% |
|
||||
| 1500 | 1533 | +2.20% |
|
||||
| 1600 | 1618 | +1.12% |
|
||||
| 1700 | 1714 | +0.82% |
|
||||
| 1800 | 1838 | +2.11% |
|
||||
| 1900 | 1948 | +2.53% |
|
||||
| 2000 | 2014 | +0.70% |
|
||||
| 2100 | 2107 | +0.33% |
|
||||
| 2200 | 2209 | +0.41% |
|
||||
| 2300 | 2299 | -0.04% |
|
||||
| 2400 | 2421 | +0.88% |
|
||||
| 2500 | 2581 | +3.24% |
|
||||
| 2600 | 2616 | +0.62% |
|
||||
| 2700 | 2752 | +1.93% |
|
||||
| 2800 | 2829 | +1.04% |
|
||||
| 2900 | 2936 | +1.24% |
|
||||
| 3000 | 3043 | +1.43% |
|
||||
|
||||
**统计：** 平均绝对误差 1.08%，最大误差 3.24%（2500mm 处）
|
||||
|
||||
## 精度特性
|
||||
|
||||
- 两个版本在有效范围内误差均 **≤3%**，典型 **~1%**
|
||||
- 误差随距离增大略有增长（双目视差精度与距离的平方成反比）
|
||||
- 长基线版在远距离更稳定（3m 处误差 1.43%），短基线版近距离更精细（0.3m 可测）
|
||||
- 镜面反光表面会显著降低精度，建议使用漫反射目标测试
|
||||
- 深度值的 Z 轴噪声（帧间抖动）通常 ≤1%，可通过空间滤波和时间平均进一步降低
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 156 KiB |
103
docs/hardware/zh/maixsense/maixsense-d640/faq.md
Normal file
103
docs/hardware/zh/maixsense/maixsense-d640/faq.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# 常见问题
|
||||
|
||||
## 连接问题
|
||||
|
||||
### 连接后没有识别到设备
|
||||
|
||||
1. 确认使用的是**数据线**而非充电线
|
||||
2. 设备上电后需要约 **10 秒**完成初始化
|
||||
3. Linux 下运行 `lsusb` 确认设备出现
|
||||
4. Windows 检查设备管理器 → "照相机"是否有 4 个 UVC 设备
|
||||
5. 尝试更换 USB 端口（建议使用主板直连端口，避免 Hub）
|
||||
|
||||
### SSH 连接不上设备
|
||||
|
||||
- 确认 USB NCM 网络接口已获取到 IP
|
||||
- Linux：`ip addr` 查看 `usb0` 或 `enx*` 接口
|
||||
- Windows：设备管理器 → "网络适配器" 查看 NCM/RNDIS 设备
|
||||
- 设备默认 IP `10.253.24.1`，密码 `sipeed`
|
||||
- 如果 IP 不通，尝试 `ping` 或检查子网配置
|
||||
|
||||
### macOS 无法使用深度滤波/曝光控制
|
||||
|
||||
macOS 的 UVC 驱动不支持本设备的厂商扩展描述符。这些功能通过 NCM 网络通道实现：
|
||||
|
||||
- GUI：设置 → 连接方式 → 选择 NCM
|
||||
- SDK：`MSD_CAPTURE_TRANSPORT=ncm` 环境变量
|
||||
- UVC 预览（QuickTime/VLC）不受影响
|
||||
|
||||
## 深度图像问题
|
||||
|
||||
### 深度图帧率只有 12fps
|
||||
|
||||
这是正常的。深度帧率由 NPU 推理速度决定（AX620Q 800MHz NPU，约 75ms/帧），设备描述符声明 12fps。IR 流可独立达到 30fps。
|
||||
|
||||
### 深度图有黑色区域
|
||||
|
||||
黑色像素表示深度无效（像素值 = 0），常见原因：
|
||||
|
||||
- **物体反光或透明**：玻璃、镜面金属、光滑塑料会导致双目匹配失败
|
||||
- **超出测量范围**：短基线 >2m 或长基线 >3m 时精度下降，低置信度像素被过滤
|
||||
- **遮挡区域**：物体边缘因两个摄像头视角不同产生的遮挡带
|
||||
- **纹理不足**：纯色、无纹理的平面区域难以进行立体匹配
|
||||
|
||||
**优化建议**：
|
||||
- 降低置信度阈值（GUI 或 SDK 中设置，例如从 0.5 降到 0.3）
|
||||
- 增加场景纹理（投射结构光或纹理图案）
|
||||
- 确保 IR 补光灯正常工作
|
||||
|
||||
### 深度值如何转换为毫米
|
||||
|
||||
使用 Z16 格式打开 Raw Depth 流时，每个像素是 `uint16_t` 类型，**单位直接就是毫米**。值为 0 表示无效像素。
|
||||
|
||||
### IR 流能否输出 Raw YUV
|
||||
|
||||
目前 IR 流仅支持 MJPEG 格式。Raw YUV (NV12) 在 USB 2.0 带宽下不可行：
|
||||
|
||||
- 单目 NV12 640×480@30fps = 110 Mbps
|
||||
- 双目 = 220 Mbps
|
||||
- 加上深度流 = 266 Mbps
|
||||
- USB 2.0 HS ISO 可用带宽仅 ~280 Mbps
|
||||
|
||||
如需 Raw 灰度数据，可通过 MJPEG 解码获取（JPEG quality 70，压缩比约 12:1）。
|
||||
|
||||
## 固件问题
|
||||
|
||||
### 标定数据丢失
|
||||
|
||||
标定数据独立于固件存储，固件更新不会覆盖它。如需恢复：
|
||||
|
||||
```bash
|
||||
# 下载当前标定（备份）
|
||||
./msd-upload fetch-calibration backup.tar.gz
|
||||
|
||||
# 上传标定
|
||||
./msd-upload calibration new_calib.tar.gz --restart
|
||||
```
|
||||
|
||||
也可在 GUI 中操作：设备菜单 → "标定管理"。
|
||||
|
||||
### 固件更新后无法启动
|
||||
|
||||
1. SSH 登录设备：`ssh root@10.253.24.1`
|
||||
2. 查看日志：`cat /run/log/maixsense-d640/current.log`
|
||||
3. 检查服务状态：`systemctl status maixsense-d640`
|
||||
4. 手动重启：`systemctl restart maixsense-d640`
|
||||
|
||||
### 设备发热
|
||||
|
||||
AX620Q SoC 在持续运行 NPU 推理时会有一定发热，属于正常现象。典型功耗约 1.5W。建议：
|
||||
- 保持通风良好
|
||||
- 避免密封环境长时间运行
|
||||
- 环境温度 0°C ~ 50°C
|
||||
|
||||
## 性能问题
|
||||
|
||||
### 延迟太高
|
||||
|
||||
当前设备侧延迟约 126ms（NPU 推理 75ms + 后处理 18ms + 其他开销），加上 USB 传输 27ms，端到端约 153ms。这是 USB 2.0 + AX620Q NPU 的硬件极限。
|
||||
|
||||
如需更低延迟：
|
||||
- 确认使用的是 800MHz NPU 固件（可查看 `cat /proc/ax_proc/npu/clk`）
|
||||
- 减少 USB Hub 层级（直连主板端口）
|
||||
- 考虑使用支持 USB 3.0 的未来硬件版本
|
||||
141
docs/hardware/zh/maixsense/maixsense-d640/firmware.md
Normal file
141
docs/hardware/zh/maixsense/maixsense-d640/firmware.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# 固件与标定管理
|
||||
|
||||
## 固件更新
|
||||
|
||||
MaixSense-D640 支持三种固件更新方式：
|
||||
|
||||
### 方式一：GUI 更新（推荐）
|
||||
|
||||
1. 打开 GUI 应用，连接设备
|
||||
2. 点击设备菜单 → "固件更新"
|
||||
3. 选择固件包 (`maixsense_d640-*.tar.gz`)
|
||||
4. 等待上传进度完成
|
||||
5. 设备自动重启
|
||||
|
||||
### 方式二：命令行工具
|
||||
|
||||
```bash
|
||||
# 使用 SDK 工具
|
||||
./msd-upload firmware maixsense_d640-v1.0.tar.gz --restart
|
||||
```
|
||||
|
||||
通过 USB 批量传输直接写入设备，无需网络连接。
|
||||
|
||||
### 方式三：SSH 手动部署
|
||||
|
||||
```bash
|
||||
# 登录设备
|
||||
ssh root@10.253.24.1 # 密码: sipeed
|
||||
|
||||
# 停止服务
|
||||
systemctl stop maixsense-d640
|
||||
|
||||
# 上传新固件
|
||||
scp maixsense_d640_live root@10.253.24.1:/opt/maixsense-d640/
|
||||
|
||||
# 重启服务
|
||||
systemctl restart maixsense-d640
|
||||
```
|
||||
|
||||
### 固件更新说明
|
||||
|
||||
- 固件更新**不会覆盖**标定数据 (`calibration/` 目录被跳过)
|
||||
- 更新前设备会自动验证包的 SHA256 校验和
|
||||
- 失败时自动回滚，不会导致设备变砖
|
||||
|
||||
## 标定文件管理
|
||||
|
||||
标定数据决定深度精度，每台设备出厂时已预置标定。
|
||||
|
||||
### 上传新标定
|
||||
|
||||
**GUI 方式：**
|
||||
1. 设备菜单 → "上传标定"
|
||||
2. 选择标定目录或包文件
|
||||
3. 设备自动备份旧标定并应用新数据
|
||||
4. 重启后生效
|
||||
|
||||
**命令行方式：**
|
||||
```bash
|
||||
./msd-upload calibration calib.tar.gz --restart
|
||||
```
|
||||
|
||||
**SSH 方式：**
|
||||
```bash
|
||||
scp -r calibration/ root@10.253.24.1:/opt/maixsense-d640/calibration/
|
||||
ssh root@10.253.24.1 "systemctl restart maixsense-d640"
|
||||
```
|
||||
|
||||
### 下载当前标定
|
||||
|
||||
```bash
|
||||
# 命令行
|
||||
./msd-upload fetch-calibration current_calib.tar.gz
|
||||
|
||||
# SSH
|
||||
ssh root@10.253.24.1 "tar czf - -C /opt/maixsense-d640 calibration" > calib_backup.tar.gz
|
||||
```
|
||||
|
||||
### 恢复历史标定
|
||||
|
||||
GUI 方式：设备菜单 → "标定管理" → 选择历史备份版本
|
||||
|
||||
命令行方式：
|
||||
```bash
|
||||
# 在设备上查看备份
|
||||
ssh root@10.253.24.1 "ls /opt/maixsense-d640/calibration.bak-*"
|
||||
|
||||
# 恢复指定备份
|
||||
ssh root@10.253.24.1 "
|
||||
mv /opt/maixsense-d640/calibration /opt/maixsense-d640/calibration.current
|
||||
mv /opt/maixsense-d640/calibration.bak-20261023 /opt/maixsense-d640/calibration
|
||||
systemctl restart maixsense-d640
|
||||
"
|
||||
```
|
||||
|
||||
### 标定文件格式
|
||||
|
||||
标定包需包含以下文件：
|
||||
|
||||
```
|
||||
calibration/
|
||||
├── stereo_calib.ini # INI 格式，必须含 [P1] [P2] [Q] 段
|
||||
├── stereo_calib_left_mesh.bin # 左目 GDC 校正网格 (9504 bytes)
|
||||
└── stereo_calib_right_mesh.bin # 右目 GDC 校正网格 (9504 bytes)
|
||||
```
|
||||
|
||||
## 设备目录结构
|
||||
|
||||
```
|
||||
/opt/maixsense-d640/
|
||||
├── maixsense_d640_live # 主固件二进制
|
||||
├── VERSION # 版本号
|
||||
├── manifest.sha256 # 文件校验和
|
||||
├── bin/msd_file_service # USB 文件传输守护进程
|
||||
├── lib/ # 运行时库
|
||||
├── models/620E.axmodel # 深度 NPU 模型
|
||||
├── calibration/ # 标定数据（更新时保留）
|
||||
└── scripts/
|
||||
├── maixsense-d640-start.sh
|
||||
├── maixsense-d640-stop.sh
|
||||
├── maixsense-d640-uvc-gadget.sh
|
||||
└── maixsense-d640.service
|
||||
```
|
||||
|
||||
## systemd 服务
|
||||
|
||||
```bash
|
||||
# 查看状态
|
||||
systemctl status maixsense-d640
|
||||
|
||||
# 重启
|
||||
systemctl restart maixsense-d640
|
||||
|
||||
# 查看日志（日志在 tmpfs，断电后丢失）
|
||||
cat /run/log/maixsense-d640/current.log
|
||||
|
||||
# 查看上一次运行日志
|
||||
cat /run/log/maixsense-d640/previous.log
|
||||
```
|
||||
|
||||
> 日志存放在 `/run/log/maixsense-d640/`（tmpfs），不占用 NAND Flash，重启后清空。最大 4MB 自动轮转。
|
||||
129
docs/hardware/zh/maixsense/maixsense-d640/gui.md
Normal file
129
docs/hardware/zh/maixsense/maixsense-d640/gui.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# GUI 使用指南
|
||||
|
||||
MaixSense-D640 配套桌面 GUI 应用（基于 Tauri + React），提供实时预览、参数调整、固件管理等功能。
|
||||
|
||||
## 安装
|
||||
|
||||
从 [GitHub Releases](https://github.com/sipeed/MaixSense-D640-SDK) 下载对应平台的安装包：
|
||||
|
||||
| 平台 | 文件 |
|
||||
| :--- | :--- |
|
||||
| Windows | `MaixSense-D640-Setup-x.x.x.exe` |
|
||||
| Linux | `maixsense-d640_x.x.x_amd64.deb` |
|
||||
| macOS | `MaixSense-D640-x.x.x.dmg` |
|
||||
|
||||
## 主界面
|
||||
|
||||
启动 GUI 后，连接 D640 设备，应用会自动发现并显示设备信息。
|
||||
|
||||
主界面分为以下区域：
|
||||
|
||||
### 设备栏（左侧）
|
||||
|
||||
- 显示已连接的 D640 设备列表
|
||||
- 设备名称、固件版本、连接状态
|
||||
- 点击设备进入预览
|
||||
|
||||
### 预览区（中央）
|
||||
|
||||
实时显示四路视频流：
|
||||
|
||||
- **深度图**（伪彩）：彩色编码的深度信息，近处暖色（红/橙），远处冷色（蓝/青）
|
||||
- **左 IR / 右 IR**：双目红外灰度图像
|
||||
- **点云**（可选）：3D 点云可视化，支持鼠标旋转/缩放
|
||||
|
||||
### 检查器面板（右侧）
|
||||
|
||||
#### 设备信息
|
||||
|
||||
显示固件版本、标定状态、设备序列号等。
|
||||
|
||||
#### 深度滤波配置
|
||||
|
||||
可实时调整的深度参数：
|
||||
|
||||
- **置信度阈值**：过滤低置信度像素（0~1，越高越严格）
|
||||
- **最小深度 / 最大深度 (mm)**：有效测量范围裁剪
|
||||
- **空间滤波强度**：3×3 边缘保持中值滤波（0=关闭）
|
||||
|
||||
修改后点击"应用"立即生效，无需重启设备。
|
||||
|
||||
#### 曝光控制
|
||||
|
||||
- **自动曝光**：默认开启，设备自动调整
|
||||
- **手动曝光**：设置固定的快门时间和增益
|
||||
- 左右目联动（主从模式），保证双目一致性
|
||||
|
||||
## 功能操作
|
||||
|
||||
### 实时预览
|
||||
|
||||
1. 连接设备后，点击左侧设备栏中的设备
|
||||
2. 预览区自动显示深度伪彩和 IR 流
|
||||
3. 可通过顶部工具栏切换显示模式
|
||||
|
||||
### 抓图/录像
|
||||
|
||||
- **抓图**：点击工具栏"拍照"按钮，保存当前帧（包含深度原始数据 + IR + 伪彩）
|
||||
- **录像**：点击"录制"按钮开始，再次点击停止。录像包含带时间戳的原始深度序列
|
||||
|
||||
### 点云查看
|
||||
|
||||
- 点击"点云"模式切换到 3D 视图
|
||||
- 鼠标左键拖拽旋转，滚轮缩放
|
||||
- 可导出 `.pcd` 格式点云文件
|
||||
|
||||
### 固件更新
|
||||
|
||||
1. 点击设备菜单（设备名右侧 ⋯ 按钮）
|
||||
2. 选择"固件更新"
|
||||
3. 选择固件包文件 (`maixsense_d640-*.tar.gz`)
|
||||
4. 等待上传和验证完成
|
||||
5. 设备自动重启并加载新固件
|
||||
|
||||
> 固件更新**不会覆盖**标定数据。
|
||||
|
||||
### 标定文件管理
|
||||
|
||||
**上传新标定：**
|
||||
1. 设备菜单 → "上传标定"
|
||||
2. 选择标定包（含 `stereo_calib.ini` + `*_mesh.bin`）
|
||||
3. 设备自动备份旧标定并应用新标定
|
||||
|
||||
**恢复历史标定：**
|
||||
1. 设备菜单 → "标定管理"
|
||||
2. 查看历史备份列表
|
||||
3. 选择要恢复的版本
|
||||
|
||||
**下载当前标定：**
|
||||
1. 设备菜单 → "下载标定"
|
||||
2. 保存为 `.tar.gz` 文件
|
||||
|
||||
### 精度测试
|
||||
|
||||
GUI 内置精度探测工具：
|
||||
1. 将设备对准已知距离的平面目标
|
||||
2. 工具栏 → "精度测试"
|
||||
3. 自动采集多帧并统计中心区域深度值的均值和标准差
|
||||
|
||||
### 连接模式选择
|
||||
|
||||
GUI 支持两种连接方式：
|
||||
|
||||
- **USB（默认）**：UVC 取流 + 厂商控制，Windows/Linux 推荐
|
||||
- **NCM 网络**：通过 USB 网络连接，macOS 推荐（厂商控制需要此通道）
|
||||
|
||||
可在设置中切换，或设置环境变量：
|
||||
```bash
|
||||
MSD_CAPTURE_TRANSPORT=ncm ./maixsense-d640-gui
|
||||
```
|
||||
|
||||
## 故障排查
|
||||
|
||||
| 问题 | 解决 |
|
||||
| :--- | :--- |
|
||||
| 设备列表为空 | 检查 USB 线、重新插拔、确认驱动（Windows） |
|
||||
| 预览黑屏 | 等待 10 秒设备初始化完成；检查镜头是否被遮挡 |
|
||||
| 深度图全黑 | 调低置信度阈值；确认测量距离在有效范围内 |
|
||||
| macOS 无法调参 | 切换到 NCM 模式：设置 → 连接方式 → NCM |
|
||||
| 固件更新失败 | 确认包文件完整；重启设备后重试 |
|
||||
@@ -6,311 +6,72 @@
|
||||
|
||||
## 产品概述
|
||||
|
||||
**MaixSense-D640** 是 Sipeed 推出的双目立体深度相机模组，基于 AX620Q 视觉 SoC，搭载两颗 SC035HGS 全局快门传感器，通过 NPU 实时推理输出密集视差/深度图。
|
||||
**MaixSense-D640** 是 Sipeed 推出的双目立体深度相机模组，基于爱芯元智 AX620Q 视觉 SoC，搭载两颗思特威 SC035HGS 全局快门传感器，通过 NPU 实时推理输出 640×384 密集深度图。USB 即插即用，标准 UVC 协议，无需安装驱动。
|
||||
|
||||
### 主要特性
|
||||
### 产品亮点
|
||||
|
||||
- **分辨率**：深度图 640×384 @12fps（NPU 实时推理），双目 IR 640×480 @30fps
|
||||
- **接口**：USB 2.0 Type-C（UVC 即插即用，免驱）
|
||||
- **输出格式**：
|
||||
- Raw Depth（Z16/D16/Y16，毫米级 16bit 深度）
|
||||
- 伪彩深度（MJPEG，可视化）
|
||||
- 左/右 IR 灰度（MJPEG）
|
||||
- **测量范围**：0.2m ~ 5m（取决于基线和标定）
|
||||
- **SoC**：爱芯元智 AX620Q（双核 Cortex-A7 + 3.2TOPS NPU）
|
||||
- **传感器**：2× 思特威 SC035HGS（全局快门，850nm IR 优化）
|
||||
- **基线**：长基线 ~99mm / 短基线 ~32mm（不同硬件版本）
|
||||
- **即插即用**：标准 UVC 协议，Windows/Linux/macOS 免驱
|
||||
- **实时深度**：640×384 @12fps 密集深度图，NPU 硬件加速
|
||||
- **四路并发输出**：Raw 深度 + 伪彩深度 + 左右 IR 灰度
|
||||
- **毫米级精度**：有效范围内误差 ≤3%
|
||||
- **开放 SDK**：C/C++ API，支持二次开发
|
||||
|
||||
### 资料汇总
|
||||
## 硬件版本
|
||||
|
||||
| 资料 | 链接 |
|
||||
| :--- | :--- |
|
||||
| SDK 下载 | [GitHub](https://github.com/sipeed/MaixSense-D640-SDK) |
|
||||
| 硬件资料 | [下载站](https://dl.sipeed.com/shareURL/MaixSense/MaixSense_D640) |
|
||||
MaixSense-D640 提供两种基线版本，适用于不同场景：
|
||||
|
||||
## 快速上手
|
||||
|
||||
### 准备工作
|
||||
|
||||
- MaixSense-D640 模组 × 1
|
||||
- USB Type-C 数据线 × 1（建议使用高质量线材）
|
||||
- Windows 10/11 或 Linux PC × 1
|
||||
|
||||
### 连接设备
|
||||
|
||||
1. 使用 USB-C 线将 D640 连接到电脑
|
||||
2. 设备上电后自动启动固件，约 10 秒后完成初始化
|
||||
3. 系统会识别到 4 个 UVC 视频设备：
|
||||
|
||||
| 设备节点 (Linux) | 流 | 格式 | 分辨率 | 帧率 |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| /dev/video0 | Raw Depth | Z16/D16/Y16 | 640×384 | 12fps |
|
||||
| /dev/video1 | 伪彩深度 | MJPEG | 640×384 | 12fps |
|
||||
| /dev/video2 | 左 IR | MJPEG | 640×480 | 30fps |
|
||||
| /dev/video3 | 右 IR | MJPEG | 640×480 | 30fps |
|
||||
|
||||
> **Windows 用户**：设备免驱，即插即用。在"相机"应用或任意 UVC 查看工具中可看到 4 个视频源。
|
||||
>
|
||||
> **Linux 用户**：通过 `v4l2-ctl --list-devices` 可列出所有设备节点。
|
||||
|
||||
### 快速预览
|
||||
|
||||
#### 方法一：使用任意 UVC 查看工具
|
||||
|
||||
D640 是标准 UVC 设备，可使用以下工具直接查看：
|
||||
|
||||
- **Windows**：[PotPlayer](https://potplayer.daum.net/)、VLC、系统相机应用
|
||||
- **Linux**：`guvcview`、`vlc`、`ffplay`
|
||||
- **macOS**：QuickTime Player、VLC
|
||||
|
||||
```bash
|
||||
# Linux 快速查看伪彩深度流
|
||||
ffplay /dev/video1
|
||||
|
||||
# 查看 IR 流
|
||||
ffplay /dev/video2
|
||||
```
|
||||
|
||||
#### 方法二：使用 SDK 测量延迟和查看深度数据
|
||||
|
||||
```bash
|
||||
# 编译 SDK
|
||||
cd sdk && mkdir build && cd build
|
||||
cmake .. -DCMAKE_BUILD_TYPE=Release
|
||||
make -j$(nproc)
|
||||
|
||||
# 查看深度延迟
|
||||
./msd-latency depth 10
|
||||
|
||||
# 查看 IR 延迟
|
||||
./msd-latency left 10
|
||||
```
|
||||
|
||||
## SDK 开发指南
|
||||
|
||||
### 安装 SDK
|
||||
|
||||
```bash
|
||||
git clone https://github.com/sipeed/MaixSense-D640-SDK.git
|
||||
cd MaixSense-D640-SDK
|
||||
mkdir build && cd build
|
||||
cmake .. -DCMAKE_BUILD_TYPE=Release
|
||||
make -j$(nproc)
|
||||
```
|
||||
|
||||
依赖：`libusb-1.0-dev`、`libuvc-dev`（Linux）或 WinUSB（Windows）。
|
||||
|
||||
### 核心 API
|
||||
|
||||
SDK 提供 C API（`msd_` 前缀），头文件 `#include <maix_stereo_depth/sdk.h>`。
|
||||
|
||||
#### 打开设备
|
||||
|
||||
```c
|
||||
#include <maix_stereo_depth/sdk.h>
|
||||
|
||||
msd_context *ctx = NULL;
|
||||
msd_context_create(&ctx);
|
||||
|
||||
msd_device *device = NULL;
|
||||
msd_status status = msd_device_open(ctx, NULL, &device); // NULL = 自动查找
|
||||
if (status != MSD_STATUS_OK) {
|
||||
printf("打开设备失败: %s\n", msd_status_string(status));
|
||||
return -1;
|
||||
}
|
||||
|
||||
// 获取固件信息
|
||||
msd_firmware_info info;
|
||||
msd_device_get_firmware_info(device, &info);
|
||||
printf("固件版本: %s\n", info.version);
|
||||
```
|
||||
|
||||
#### 获取深度帧
|
||||
|
||||
```c
|
||||
msd_stream *stream = NULL;
|
||||
msd_stream_config config = {
|
||||
.type = MSD_STREAM_DEPTH,
|
||||
.format = MSD_PIXEL_FORMAT_Z16,
|
||||
};
|
||||
msd_stream_open(device, &config, &stream);
|
||||
msd_stream_start(stream);
|
||||
|
||||
while (running) {
|
||||
msd_frame frame;
|
||||
status = msd_stream_read(stream, &frame, 1000); // 1000ms 超时
|
||||
if (status == MSD_STATUS_OK) {
|
||||
// frame.data 指向 640×384 的 uint16_t 深度数据（单位：毫米）
|
||||
uint16_t *depth = (uint16_t *)frame.data;
|
||||
printf("中心点深度: %u mm\n", depth[192 * 640 + 320]);
|
||||
msd_frame_release(&frame);
|
||||
}
|
||||
}
|
||||
|
||||
msd_stream_stop(stream);
|
||||
msd_stream_close(stream);
|
||||
```
|
||||
|
||||
#### 获取 IR 灰度帧
|
||||
|
||||
```c
|
||||
msd_stream_config ir_config = {
|
||||
.type = MSD_STREAM_LEFT_IR,
|
||||
.format = MSD_PIXEL_FORMAT_MJPEG,
|
||||
};
|
||||
msd_stream_open(device, &ir_config, &ir_stream);
|
||||
```
|
||||
|
||||
#### 获取设备时钟（延迟测量）
|
||||
|
||||
```c
|
||||
msd_device_clock clock;
|
||||
msd_device_get_clock(device, &clock);
|
||||
printf("设备 PTS: %lu us, 设备 monotonic: %lu us\n",
|
||||
clock.device_pts_us, clock.device_monotonic_us);
|
||||
// 可用于对齐设备帧时间戳与主机时钟，计算端到端延迟
|
||||
```
|
||||
|
||||
#### 上传固件/标定
|
||||
|
||||
```c
|
||||
// 上传固件包
|
||||
msd_device_upload_file(device, MSD_UPLOAD_FIRMWARE_PACKAGE,
|
||||
"maixsense_d640-v1.0.tar.gz", 0, NULL, NULL);
|
||||
|
||||
// 上传标定文件
|
||||
msd_device_upload_file(device, MSD_UPLOAD_CALIBRATION_PACKAGE,
|
||||
"calibration.tar.gz", 0, NULL, NULL);
|
||||
|
||||
// 下载当前标定
|
||||
msd_device_download_file(device, MSD_DOWNLOAD_CALIBRATION,
|
||||
"current_calib.tar.gz", NULL, NULL);
|
||||
```
|
||||
|
||||
### 编译选项
|
||||
|
||||
| CMake 选项 | 默认 | 说明 |
|
||||
| | 短基线版 (~50mm) | 长基线版 (~100mm) |
|
||||
| :--- | :--- | :--- |
|
||||
| `BUILD_EXAMPLES` | ON | 编译示例程序 |
|
||||
| `BUILD_SHARED_LIBS` | ON | 编译为动态库 |
|
||||
| 有效测量范围 | 0.3m ~ 2.0m | 0.5m ~ 3.0m |
|
||||
| 最佳应用 | 近距离精密测量、桌面级 | 中远距离、机器人导航 |
|
||||
| 平均误差 | ~1.0% | ~1.1% |
|
||||
|
||||
### 示例程序
|
||||
|
||||
| 程序 | 说明 |
|
||||
| :--- | :--- |
|
||||
| `msd-latency` | 延迟测量工具（支持 depth/left/right 流） |
|
||||
| `msd-upload` | 固件和标定文件上传工具 |
|
||||
|
||||
## 固件更新
|
||||
|
||||
### 通过 USB 上传（推荐）
|
||||
|
||||
```bash
|
||||
# 使用 SDK 工具
|
||||
./msd-upload firmware maixsense_d640-v1.0.tar.gz --restart
|
||||
```
|
||||
|
||||
设备会自动完成：解压 → 校验 SHA256 → 替换文件 → 重启服务。固件更新**不会覆盖标定数据**。
|
||||
|
||||
### 通过 SSH（开发调试）
|
||||
|
||||
设备通过 USB 建立 NCM 网络连接（IP 默认 `10.253.24.1`，密码 `sipeed`）：
|
||||
|
||||
```bash
|
||||
ssh root@10.253.24.1
|
||||
|
||||
# 手动部署
|
||||
scp maixsense_d640_live root@10.253.24.1:/opt/maixsense-d640/
|
||||
ssh root@10.253.24.1 "systemctl restart maixsense-d640"
|
||||
```
|
||||
|
||||
### 固件目录结构
|
||||
|
||||
```
|
||||
/opt/maixsense-d640/
|
||||
├── maixsense_d640_live # 主固件
|
||||
├── VERSION # 版本号
|
||||
├── models/620E.axmodel # 深度 NPU 模型
|
||||
├── calibration/ # 标定数据（固件更新不覆盖）
|
||||
│ ├── stereo_calib.ini # 内参与投影矩阵
|
||||
│ ├── stereo_calib_left_mesh.bin
|
||||
│ └── stereo_calib_right_mesh.bin
|
||||
├── scripts/
|
||||
│ ├── maixsense-d640-start.sh # 启动脚本
|
||||
│ ├── maixsense-d640-stop.sh # 停止脚本
|
||||
│ └── maixsense-d640.service # systemd 服务单元
|
||||
└── lib/ # 运行时库
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 连接后没有识别到设备
|
||||
|
||||
1. 确认 USB 线是数据线而非充电线
|
||||
2. 设备上电后需要约 10 秒完成初始化
|
||||
3. Linux 下运行 `lsusb` 确认设备出现（Vendor ID: Sipeed）
|
||||
4. 检查 `dmesg` 中是否有 USB 枚举错误
|
||||
|
||||
### 深度图帧率只有 12fps
|
||||
|
||||
这是正常的。深度帧率由 NPU 推理速度决定（AX620Q 800MHz NPU 约 75ms/帧 ≈ 13fps），描述符声明 12fps。IR 流可达 30fps。
|
||||
|
||||
### 深度图有黑色区域
|
||||
|
||||
黑色像素表示该区域深度值无效（置信度低或超出测量范围），常见原因：
|
||||
- 物体表面反光或透明
|
||||
- 距离超出测量范围
|
||||
- 双目遮挡区域（靠近基线边缘）
|
||||
|
||||
### 如何获取毫米级深度值
|
||||
|
||||
使用 Z16 格式打开 Raw Depth 流，每个像素是 `uint16_t` 类型，单位为毫米。值为 0 表示无效。
|
||||
|
||||
### SSH 连接不上设备
|
||||
|
||||
- 确认 USB NCM 网络接口已获取到 IP 地址
|
||||
- Linux：`ip addr` 查看是否有 `usb0` 或 `enx*` 接口
|
||||
- Windows：设备管理器中查看"网络适配器"是否出现 RNDIS/NCM 设备
|
||||
- 设备 IP 默认为 `10.253.24.1`，密码 `sipeed`
|
||||
|
||||
### 标定数据丢失或需要重新标定
|
||||
|
||||
```bash
|
||||
# 从设备下载当前标定
|
||||
./msd-upload fetch-calibration current_calib.tar.gz
|
||||
|
||||
# 上传新标定
|
||||
./msd-upload calibration new_calib.tar.gz --restart
|
||||
```
|
||||
|
||||
标定数据在固件更新时不会被覆盖。
|
||||
|
||||
### 设备发热正常吗
|
||||
|
||||
AX620Q SoC 在持续运行 NPU 推理时会有一定发热，属于正常现象。建议保持通风良好，避免密封环境长时间运行。
|
||||
> 两个版本使用相同的固件和 SDK，仅标定数据不同。
|
||||
|
||||
## 技术规格
|
||||
|
||||
| 参数 | 规格 |
|
||||
| :--- | :--- |
|
||||
| SoC | 爱芯元智 AX620Q (2× Cortex-A7 + 3.2 TOPS NPU) |
|
||||
| 传感器 | 2× 思特威 SC035HGS (全局快门, 640×480) |
|
||||
| 传感器 | 2× 思特威 SC035HGS (全局快门, 640×480, 850nm IR 优化) |
|
||||
| 深度分辨率 | 640×384 |
|
||||
| 深度帧率 | 12fps (NPU bound) |
|
||||
| IR 帧率 | 30fps |
|
||||
| 测量范围 | 0.2m ~ 5m |
|
||||
| IR 帧率 | 30fps (MJPEG) |
|
||||
| 测量范围 | 0.3m~2.0m (短基线) / 0.5m~3.0m (长基线) |
|
||||
| 测量精度 | 有效范围内 ≤3%，典型 ~1% |
|
||||
| 接口 | USB 2.0 Type-C (UVC + NCM) |
|
||||
| 输出协议 | UVC (即插即用，免驱) |
|
||||
| 供电 | USB 5V, 典型功耗 ~1.5W |
|
||||
| 基线 | 长基线 ~99mm / 短基线 ~32mm |
|
||||
| 视场角 | ~70°(H) × 50°(V) (取决于镜头) |
|
||||
| 供电 | USB 5V |
|
||||
| 视场角 | ~70°(H) × 50°(V) |
|
||||
| 工作温度 | 0°C ~ 50°C |
|
||||
|
||||
## 延迟指标
|
||||
## UVC 输出流
|
||||
|
||||
| 指标 | 典型值 |
|
||||
| :--- | :--- |
|
||||
| 设备侧延迟 (capture→send) | 126ms avg, 98ms min |
|
||||
| USB 传输延迟 | 27ms avg |
|
||||
| 端到端延迟 (capture→host receive) | 153ms avg |
|
||||
| IR 端到端延迟 | 50ms avg |
|
||||
设备连接后会出现 4 个 UVC 视频设备：
|
||||
|
||||
| 设备 | 流 | 格式 | 分辨率 | 帧率 | 说明 |
|
||||
| :--- | :--- | :--- | :--- | :--- | :--- |
|
||||
| video0 | Raw Depth | Z16/D16/Y16 | 640×384 | 12fps | 16bit 毫米深度值 |
|
||||
| video1 | 伪彩深度 | MJPEG | 640×384 | 12fps | 彩色可视化 |
|
||||
| video2 | 左 IR | MJPEG | 640×480 | 30fps | 左目灰度图 |
|
||||
| video3 | 右 IR | MJPEG | 640×480 | 30fps | 右目灰度图 |
|
||||
|
||||
> **关于 IR 格式**：IR 流目前仅支持 MJPEG。Raw YUV (NV12) 在 USB 2.0 带宽下不可行——单目 640×480@30fps 的 NV12 需要 110Mbps，双目加深度将超出 USB 2.0 HS 的 280Mbps 可用带宽。
|
||||
|
||||
### 平台兼容性
|
||||
|
||||
| 平台 | UVC 预览 | SDK 完整功能 | GUI | 说明 |
|
||||
| :--- | :---: | :---: | :---: | :--- |
|
||||
| Windows 10/11 | ✅ | ✅ | ✅ | 免驱即插即用 |
|
||||
| Linux | ✅ | ✅ | ✅ | 免驱 |
|
||||
| macOS | ✅ | ✅ (NCM) | ✅ | UVC 可预览；SDK 厂商控制走 NCM 网络通道 |
|
||||
|
||||
> macOS 的 UVC 可直接查看 IR 和伪彩流。深度滤波配置、曝光控制等厂商扩展功能通过 NCM 网络连接实现，SDK 会自动选择。
|
||||
|
||||
## 更多文档
|
||||
|
||||
- [快速上手](./quick-start.md) — 开箱连接和预览
|
||||
- [GUI 使用指南](./gui.md) — 桌面应用操作说明
|
||||
- [SDK 开发指南](./sdk.md) — C/C++ API 接口和示例代码
|
||||
- [固件与标定管理](./firmware.md) — 固件更新、标定上传/下载
|
||||
- [测量精度](./accuracy.md) — 实测精度数据和误差曲线
|
||||
- [常见问题](./faq.md) — 故障排查
|
||||
|
||||
83
docs/hardware/zh/maixsense/maixsense-d640/quick-start.md
Normal file
83
docs/hardware/zh/maixsense/maixsense-d640/quick-start.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# 快速上手
|
||||
|
||||
## 开箱准备
|
||||
|
||||
- MaixSense-D640 模组 × 1
|
||||
- USB Type-C 数据线 × 1（需要数据线，非充电线）
|
||||
- 电脑 × 1（Windows / Linux / macOS）
|
||||
|
||||
## 连接设备
|
||||
|
||||
1. 使用 USB-C 线将 D640 连接到电脑
|
||||
2. 等待约 10 秒，设备自动初始化
|
||||
3. 系统会识别到 4 个视频设备
|
||||
|
||||
**Linux 确认设备：**
|
||||
```bash
|
||||
v4l2-ctl --list-devices
|
||||
# 应显示 4 个 /dev/videoN 节点
|
||||
```
|
||||
|
||||
**Windows 确认设备：** 打开"设备管理器" → "照相机"，应看到 4 个 UVC 设备。
|
||||
|
||||
## 快速预览
|
||||
|
||||
### 方法一：系统自带工具
|
||||
|
||||
D640 是标准 UVC 设备，可用任意视频查看工具：
|
||||
|
||||
**Windows：**
|
||||
- 打开"相机"应用，切换到 D640 的伪彩深度流
|
||||
- 或使用 [PotPlayer](https://potplayer.daum.net/) 打开任意一路流
|
||||
|
||||
**Linux：**
|
||||
```bash
|
||||
# 查看伪彩深度
|
||||
ffplay /dev/video1
|
||||
|
||||
# 查看左 IR
|
||||
ffplay /dev/video2
|
||||
|
||||
# 使用 guvcview
|
||||
guvcview -d /dev/video1
|
||||
```
|
||||
|
||||
**macOS：**
|
||||
- QuickTime Player → 文件 → 新建影片录制 → 选择 D640 设备
|
||||
- 或使用 VLC
|
||||
|
||||
### 方法二：使用 GUI 应用（推荐）
|
||||
|
||||
GUI 提供完整的预览、配置和管理功能，详见 [GUI 使用指南](./gui.md)。
|
||||
|
||||
### 方法三：使用 SDK 命令行
|
||||
|
||||
```bash
|
||||
# 编译 SDK
|
||||
cd sdk && mkdir build && cd build
|
||||
cmake .. -DCMAKE_BUILD_TYPE=Release
|
||||
make -j$(nproc)
|
||||
|
||||
# 测量深度延迟
|
||||
./msd-latency depth 10
|
||||
|
||||
# 测量 IR 延迟
|
||||
./msd-latency left 10
|
||||
```
|
||||
|
||||
## SSH 登录设备
|
||||
|
||||
D640 通过 USB 同时建立 NCM 网络连接，可 SSH 登录进行调试：
|
||||
|
||||
```bash
|
||||
# Linux/macOS
|
||||
ssh root@10.253.24.1
|
||||
# 密码: sipeed
|
||||
```
|
||||
|
||||
> Windows 用户需确认 NCM/RNDIS 网络适配器已正常识别。IP 地址取决于板子配置，常见为 `10.253.24.1`。
|
||||
|
||||
## 下一步
|
||||
|
||||
- [GUI 使用指南](./gui.md) — 桌面应用完整操作
|
||||
- [SDK 开发指南](./sdk.md) — 集成深度数据到你的应用
|
||||
220
docs/hardware/zh/maixsense/maixsense-d640/sdk.md
Normal file
220
docs/hardware/zh/maixsense/maixsense-d640/sdk.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# SDK 开发指南
|
||||
|
||||
MaixSense-D640 SDK 提供 C/C++ API，用于将深度数据集成到你的应用中。
|
||||
|
||||
## 安装
|
||||
|
||||
### 依赖
|
||||
|
||||
| 平台 | 依赖 |
|
||||
| :--- | :--- |
|
||||
| Linux (Ubuntu/Debian) | `sudo apt install libusb-1.0-0-dev libuvc-dev cmake build-essential` |
|
||||
| Windows | CMake + Visual Studio，WinUSB 自动安装 |
|
||||
| macOS | `brew install libusb cmake` |
|
||||
|
||||
### 编译
|
||||
|
||||
```bash
|
||||
git clone https://github.com/sipeed/MaixSense-D640-SDK.git
|
||||
cd MaixSense-D640-SDK
|
||||
mkdir build && cd build
|
||||
cmake .. -DCMAKE_BUILD_TYPE=Release
|
||||
make -j$(nproc)
|
||||
```
|
||||
|
||||
编译产物：
|
||||
- `libmaix_stereo_depth.so` — 动态库
|
||||
- `msd-latency` — 延迟测量工具
|
||||
- `msd-upload` — 固件/标定上传工具
|
||||
|
||||
## API 概览
|
||||
|
||||
所有公开函数使用 `msd_` 前缀，头文件位于 `include/maix_stereo_depth/sdk.h`。
|
||||
|
||||
### 设备发现与打开
|
||||
|
||||
```c
|
||||
#include <maix_stereo_depth/sdk.h>
|
||||
|
||||
// 创建上下文
|
||||
msd_context *ctx = NULL;
|
||||
msd_context_create(&ctx);
|
||||
|
||||
// 打开设备（NULL = 自动查找第一个）
|
||||
msd_device *device = NULL;
|
||||
msd_status status = msd_device_open(ctx, NULL, &device);
|
||||
if (status != MSD_STATUS_OK) {
|
||||
printf("error: %s\n", msd_status_string(status));
|
||||
return -1;
|
||||
}
|
||||
|
||||
// 获取固件信息
|
||||
msd_firmware_info info;
|
||||
msd_device_get_firmware_info(device, &info);
|
||||
printf("firmware: %s\n", info.version);
|
||||
```
|
||||
|
||||
### 获取深度帧
|
||||
|
||||
```c
|
||||
msd_stream *stream = NULL;
|
||||
msd_stream_config config = {
|
||||
.type = MSD_STREAM_DEPTH,
|
||||
.format = MSD_PIXEL_FORMAT_Z16, // 16bit 毫米深度
|
||||
};
|
||||
msd_stream_open(device, &config, &stream);
|
||||
msd_stream_start(stream);
|
||||
|
||||
while (running) {
|
||||
msd_frame frame;
|
||||
status = msd_stream_read(stream, &frame, 1000); // 1000ms 超时
|
||||
if (status == MSD_STATUS_OK) {
|
||||
uint16_t *depth = (uint16_t *)frame.data;
|
||||
// depth[y * 640 + x] = 距离(mm)，0 表示无效
|
||||
printf("center depth: %u mm\n", depth[192 * 640 + 320]);
|
||||
msd_frame_release(&frame);
|
||||
}
|
||||
}
|
||||
|
||||
msd_stream_stop(stream);
|
||||
msd_stream_close(stream);
|
||||
```
|
||||
|
||||
### 获取 IR 灰度帧
|
||||
|
||||
```c
|
||||
msd_stream_config ir_config = {
|
||||
.type = MSD_STREAM_LEFT_IR, // 或 MSD_STREAM_RIGHT_IR
|
||||
.format = MSD_PIXEL_FORMAT_MJPEG,
|
||||
};
|
||||
msd_stream *ir = NULL;
|
||||
msd_stream_open(device, &ir_config, &ir);
|
||||
msd_stream_start(ir);
|
||||
|
||||
msd_frame frame;
|
||||
if (msd_stream_read(ir, &frame, 1000) == MSD_STATUS_OK) {
|
||||
// frame.data = JPEG 数据, frame.size = 字节数
|
||||
save_jpeg("ir_left.jpg", frame.data, frame.size);
|
||||
msd_frame_release(&frame);
|
||||
}
|
||||
```
|
||||
|
||||
### 深度滤波配置
|
||||
|
||||
```c
|
||||
msd_depth_filter_config filter = {
|
||||
.confidence_threshold = 0.5f, // 置信度阈值 [0,1]
|
||||
.min_depth_mm = 300.0f, // 最小深度 300mm
|
||||
.max_depth_mm = 2000.0f, // 最大深度 2000mm
|
||||
.spatial_filter_delta_q4 = 0, // 空间滤波（0=关闭）
|
||||
};
|
||||
msd_device_set_depth_filters(device, &filter);
|
||||
```
|
||||
|
||||
### 曝光控制
|
||||
|
||||
```c
|
||||
// 读取当前曝光
|
||||
msd_exposure_state exposure;
|
||||
msd_device_read_exposure(device, &exposure);
|
||||
printf("shutter: %u us, gain: %.2fx\n", exposure.shutter_us, exposure.analog_gain);
|
||||
|
||||
// 设为手动曝光
|
||||
msd_exposure_config manual = {
|
||||
.mode = MSD_EXPOSURE_MANUAL,
|
||||
.shutter_us = 5000,
|
||||
.analog_gain = 1.0f,
|
||||
};
|
||||
msd_device_apply_exposure(device, &manual);
|
||||
|
||||
// 恢复自动曝光
|
||||
msd_exposure_config auto_exp = { .mode = MSD_EXPOSURE_AUTO };
|
||||
msd_device_apply_exposure(device, &auto_exp);
|
||||
```
|
||||
|
||||
### 设备时钟（延迟测量）
|
||||
|
||||
```c
|
||||
msd_device_clock clock;
|
||||
msd_device_get_clock(device, &clock);
|
||||
// clock.device_pts_us — 设备 AX PTS 时钟（微秒）
|
||||
// clock.device_monotonic_us — 设备 CLOCK_MONOTONIC（微秒）
|
||||
// clock.host_before_ns / host_after_ns — 主机请求前后时间戳
|
||||
// 用于对齐帧 PTS 和主机时钟，计算端到端延迟
|
||||
```
|
||||
|
||||
### 固件/标定上传
|
||||
|
||||
```c
|
||||
// 上传固件
|
||||
msd_device_upload_file(device, MSD_UPLOAD_FIRMWARE_PACKAGE,
|
||||
"maixsense_d640-v1.0.tar.gz", 0, NULL, NULL);
|
||||
|
||||
// 上传标定
|
||||
msd_device_upload_file(device, MSD_UPLOAD_CALIBRATION_PACKAGE,
|
||||
"calibration.tar.gz", 0, NULL, NULL);
|
||||
|
||||
// 下载标定
|
||||
msd_device_download_file(device, MSD_DOWNLOAD_CALIBRATION,
|
||||
"current_calib.tar.gz", NULL, NULL);
|
||||
```
|
||||
|
||||
### 清理
|
||||
|
||||
```c
|
||||
msd_device_close(device);
|
||||
msd_context_destroy(ctx);
|
||||
```
|
||||
|
||||
## 命令行工具
|
||||
|
||||
### msd-latency
|
||||
|
||||
测量帧延迟：
|
||||
|
||||
```bash
|
||||
# 测深度流延迟（采集 10 秒）
|
||||
./msd-latency depth 10
|
||||
|
||||
# 测 IR 延迟
|
||||
./msd-latency left 10
|
||||
|
||||
# 逐帧详情
|
||||
./msd-latency depth 10 --per-frame
|
||||
```
|
||||
|
||||
输出示例：
|
||||
```
|
||||
device min 98 avg 126 p95 148 max 222 ms
|
||||
transfer min 22 avg 27 p95 33 max 35 ms
|
||||
total min 123 avg 153 p95 176 max 255 ms
|
||||
```
|
||||
|
||||
### msd-upload
|
||||
|
||||
固件和标定文件管理：
|
||||
|
||||
```bash
|
||||
# 上传固件
|
||||
./msd-upload firmware maixsense_d640-v1.0.tar.gz --restart
|
||||
|
||||
# 上传标定
|
||||
./msd-upload calibration calib.tar.gz --restart
|
||||
|
||||
# 下载当前标定
|
||||
./msd-upload fetch-calibration output.tar.gz
|
||||
```
|
||||
|
||||
## 延迟指标
|
||||
|
||||
| 指标 | 深度流 | IR 流 |
|
||||
| :--- | :--- | :--- |
|
||||
| 设备侧延迟 | 126ms avg, 98ms min | 40ms avg |
|
||||
| USB 传输 | 27ms avg | 11ms avg |
|
||||
| 端到端 | 153ms avg | 50ms avg |
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 同一设备同时只能有一个进程打开（UVC 设备独占）
|
||||
- 深度帧率由 NPU 决定（~12fps），无法通过 SDK 调整
|
||||
- macOS 上厂商控制（滤波/曝光/时钟）走 NCM 网络通道，需要 USB 网络连接可用
|
||||
@@ -461,6 +461,19 @@ items:
|
||||
file: maixsense/maixsense-a075v/maixsense-a075v.md
|
||||
- label: MaixSense-D640
|
||||
file: maixsense/maixsense-d640/maixsense-d640.md
|
||||
items:
|
||||
- label: 快速上手
|
||||
file: maixsense/maixsense-d640/quick-start.md
|
||||
- label: GUI 使用指南
|
||||
file: maixsense/maixsense-d640/gui.md
|
||||
- label: SDK 开发指南
|
||||
file: maixsense/maixsense-d640/sdk.md
|
||||
- label: 固件与标定
|
||||
file: maixsense/maixsense-d640/firmware.md
|
||||
- label: 测量精度
|
||||
file: maixsense/maixsense-d640/accuracy.md
|
||||
- label: 常见问题
|
||||
file: maixsense/maixsense-d640/faq.md
|
||||
- label: SLogic
|
||||
items:
|
||||
- label: SLogic Combo 8
|
||||
|
||||
Reference in New Issue
Block a user