baoshi-measure-cargo

# 货物高度测量服务（baoshi-measure-cargo）

本项目基于 Orbbec 深度相机 + FastAPI，用于在固定 ROI（感兴趣区域）内计算最近距离，并通过中位数输出稳定的高度测量结果。

1. 项目功能

• 提供 HTTP 接口 /height，返回毫米级测量结果。
• 支持深度帧预处理（阈值过滤、中值滤波、形态学开运算、时间滤波）。
• 支持自动保存本次测量的彩色图与深度标注图。
• 内置请求日志中间件，记录接口耗时与响应摘要。

2. 目录结构

• api.py：FastAPI 服务入口与路由定义。
• main.py：命令行启动入口。
• api_config.py：配置对象与环境变量读取。
• cargo_service.py：测高核心服务（采样、统计、图片保存）。
• depth_common.py：深度处理通用逻辑（ROI、滤波、最近点等）。
• cargo_height_measure.py：本地可视化调试脚本。
• request_logging.py：请求日志中间件。
• utils.py：彩色帧格式转换工具。
• examples/：SDK 使用示例脚本。

3. 环境准备

3.1 Python 依赖

pip install -r requirements.txt

说明：请确保本机已正确安装并可使用 Orbbec SDK（pyorbbecsdk）。

3.2 硬件要求

• 已连接并可被系统识别的 Orbbec 深度相机。
• 建议固定相机姿态，保证测量区域稳定。

4. 启动方式

4.1 启动 API 服务

python main.py

默认监听地址：127.0.0.1:8080

4.2 本地窗口调试

python cargo_height_measure.py

按 q 或 ESC 退出。

4.3 示例脚本

python examples/quick_start.py
python examples/save_image_to_disk.py

5. 接口说明

5.1 健康检查

• 路径：GET /health

• 返回示例：

  {"status": "ok"}
  

5.2 高度测量

• 路径：GET /height

• 成功返回示例：

  {
  "height_mm": 1234,
  "samples": [1231, 1235, 1234, 1232, 1236],
  "unit": "mm",
  "sample_count": 5,
  "image_paths": {
  "color": "/sample_images/color_640x480_20260227_133000_123.png",
  "depth": "/sample_images/depth_annotated_640x480_20260227_133000_123.png"
  }
  }
  

• 失败返回：当有效样本不足时返回 503。

6. 关键环境变量

• SAMPLE_COUNT：单次测量采样数量（默认 10）。
• FRAME_TIMEOUT_MS：每帧等待超时毫秒数（默认 200）。
• SAMPLE_TIMEOUT_SEC：单次测量总超时秒数（默认 8）。
• MAX_SAVED_IMAGES：最多保留图片数量（默认 1000）。
• REQUEST_LOG_MAX_LEN：日志中响应体最大长度（默认 1000）。
• REQUEST_LOG_MAX_BYTES：单个日志文件最大字节（默认 20MB）。
• REQUEST_LOG_BACKUP_COUNT：日志轮转保留份数（默认 10）。
• API_HOST：服务监听地址（默认 127.0.0.1）。
• API_PORT：服务端口（默认 8080）。
• MIN_DEPTH：有效最小深度（cm，默认 50）。
• MAX_DEPTH：有效最大深度（cm，默认 400）。
• ROI_WIDTH_CM：ROI 宽度（cm，默认 10）。
• ROI_HEIGHT_CM：ROI 高度（cm，默认 12）。

7. 日志与输出

• 请求日志目录：Log/request.log
• 测量图片目录：sample_images/
• 示例脚本输出目录：
  • color_images/
  • depth_images/

8. 常见问题

• 如果 /height 返回 503：
  • 检查相机是否正常连接；
  • 检查当前场景是否在有效深度区间内；
  • 适当增大 SAMPLE_TIMEOUT_SEC 或降低 SAMPLE_COUNT。
• 如果没有彩色图：
  • 设备可能不支持彩色传感器，或彩色流未成功启用。

9. 开发建议

• 优先在 cargo_height_measure.py 中观察 ROI 与最近点标注效果，再调整环境变量。
• 对线上接口调用，建议同时监控 request.log 与保存的 sample_images 进行问题定位。