# 货物高度测量服务（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 依赖

```bash
pip install -r requirements.txt
```

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

### 3.2 硬件要求

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

## 4. 启动方式

### 4.1 启动 API 服务

```bash
python main.py
```

默认监听地址：`127.0.0.1:8080`

### 4.2 本地窗口调试

```bash
python cargo_height_measure.py
```

按 `q` 或 `ESC` 退出。

### 4.3 示例脚本

```bash
python examples/quick_start.py
python examples/save_image_to_disk.py
```

## 5. 接口说明

### 5.1 健康检查

- 路径：`GET /health`
- 返回示例：

```json
{"status": "ok"}
```

### 5.2 高度测量

- 路径：`GET /height`
- 成功返回示例：

```json
{
  "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` 进行问题定位。