Metadata-Version: 2.4
Name: pb-calibration
Version: 0.1.5
Summary: PB 车辆配置/标定文件（vehicle_config.proto）反序列化校验、解析为 YAML、从 YAML 保真优先地组装为 .pb.txt。V0.1.5：支持未知字段警告、未修改原文保真、浮点标准化输出、YAML 全量字符串化。
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Requires-Dist: protobuf>=4.21.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# pb-calibration

**当前版本：0.1.5**

基于 **vehicle_config.proto**（与 **mdrive** `master` 对齐，依赖 **`modules/message/common/geometry.proto`**）的 PB 车辆配置/标定文件（`.pb.txt`）反序列化校验、解析为 YAML、从 YAML 保真优先地组装为 `.pb.txt`。  
V0.1.5：新增“未修改原文保真”重组、未知字段警告与尽量保留、浮点标准化输出、YAML 全量双引号字符串化。  
V0.1.4：`vehicle_config.proto` 与上游 mdrive 一致，`Transform` 使用 `mdrive.message.common.Point3D` / `Quaternion`；`VehicleLidarConfig.enable_ids` 为 `uint32`（与此前本地单文件内嵌 `int32` 的实验性定义不同）。  
V0.1.3：在 V0.1.2 基础上为 `VehicleConfig` 增加 `vehicle_lidar_config`（`enable_ids`），兼容 mdrive_conf 新标定。  
V0.1.2：VehicleInfo 新增字段 `color`、`manufacturer` 等；此前版本曾将 Point3D/Quaternion 内嵌在单文件内。

## 环境与安装

推荐使用 **Conda** 环境 `py310`，并在该环境中安装本包及依赖：

```bash
conda activate py310
pip install -e .   # 开发安装
# 或
pip install .      # 普通安装
```

若仅安装不开发，也可：

```bash
pip install pb-calibration
```

## 功能

1. **反序列化检查**：检查 `pb.txt` 是否存在格式问题（能否正常解析）。
2. **解析为 YAML**：将 `pb.txt` 解析为每个单独的 yaml 文件，输出到**指定目录**；该目录与后续「组合」时使用的目录一致。
3. **从 YAML 组装**：按顺序将指定目录中的单独 yaml 文件组装成 `pb.txt`（输入目录与解析输出目录一致，可指定）。
4. **保真优先重组**：如果输入 PB 解析后未修改对应 YAML，重组时优先复用原始 PB 文本块，避免 `0` 被删、`1` 变 `1.0`、科学计数法改写、长小数截断等无意义 diff。
5. **未知字段警告**：如果输入 PB 含当前 proto 未识别字段，`parse` 会给出 warning，并在未修改对应块时尽量原样保留；修改该块后会再次警告这些字段可能丢失。
6. **统一输出规范**：新建或修改后的 `float/double` 字段统一输出为十进制、不使用科学计数法、最多 8 位小数、四舍五入、`0.0` 不省略；空内容不写。
7. **YAML 全量字符串化**：所有 YAML 标量值均以双引号字符串输出，避免隐式类型转换。
8. **YamlConfigManager**：类，存储默认 YAML 路径；**不缓存 YAML 内容**，每次从默认路径读取，保证多程序共同维护时数据为最新。支持 `read_yaml` / `update_yaml`、`read_order_manifest` / `update_order_manifest`、`rescan` / `get_cached` / `get`。
9. **函数式 API**：`read_yaml`、`update_yaml`、`read_order_manifest`、`update_order_manifest`（显式传路径，无状态）。

## 命令行

```bash
# 1. 检查 pb.txt 格式
pb-calibration check -i /path/to/vehicle_config.pb.txt

# 2. 解析 pb.txt 为 yaml，输出到指定目录（该目录即后续 build 的输入）
pb-calibration parse -i /path/to/vehicle_config.pb.txt -o /path/to/yaml_dir

# 3. 从指定目录按顺序组装为 pb.txt（目录与 parse 的 -o 一致）
pb-calibration build -i /path/to/yaml_dir -o /path/to/vehicle_config_out.pb.txt
```

## 测试

在本版本目录（V0.1.5）下执行：

```bash
conda activate py310
pip install -e .[dev]
pytest test/ -v
python -m build
```

或单独运行：`pytest test/test_v015_features.py -v`、`pytest test/test_roundtrip.py -v`、`pytest test/test_api.py -v`、`pytest test/test_yaml_manager.py -v`。

## 从 proto 重新生成 `*_pb2.py`（维护者）

在包根目录下，需同时生成 `geometry.proto` 与 `vehicle_config.proto`（若系统无 `protoc`，可用 `grpcio-tools`）：

```bash
conda activate py310
python -m grpc_tools.protoc --proto_path=pb_calibration/protobuf --python_out=pb_calibration/protobuf \
  pb_calibration/protobuf/modules/message/common/geometry.proto \
  pb_calibration/protobuf/vehicle_config.proto
```

生成后请将 `vehicle_config_pb2.py` 中对 `geometry_pb2` 的导入改为相对导入：  
`from .modules.message.common import geometry_pb2 as ...`，以便打包安装后可解析。

## 依赖

- Python >= 3.10（推荐在 conda 环境 `py310` 下使用）
- PyYAML >= 6.0
- protobuf >= 4.21.0

## License

MIT
