Skip to content

pyulog-compatibility.md

Latest commit

 

History

History
47 lines (36 loc) · 2.75 KB

pyulog-compatibility.md

File metadata and controls

47 lines (36 loc) · 2.75 KB
Raw

pyulog 兼容性说明

本项目以 PX4/pyulog 为行为基准，但实现方式保持 Go-native，不直接翻译 Python 源码。

上游基线

  • 上游仓库：https://github.com/PX4/pyulog
  • 当前参考提交：4379a77cc6d47b665c1c14d079b3dc890b7805af
  • 上游许可证：BSD-3-Clause
  • 本仓库许可证：GPL-3.0，保留第三方样例的 BSD-3-Clause 归属说明

兼容目标

pyulog 能力 Go 入口 V0 状态
ULog(...) 读取 .ulg ulogo.Read / ulogo.ReadFile / ulogo.Load 已用真实 pyulog oracle 做内容级解析对齐；支持不落盘 io.Reader 输入
appended data ulogo.Read 已按 appended offsets 分段读取
ulog_info cmd/ulog_info 已对齐 sample、sample_appended、sample_appended_multiple golden output
ulog_messages cmd/ulog_messages 已对齐 sample、sample_appended、sample_px4_events golden output
PX4 events ulogo.LoggedPX4Events 已支持日志内嵌 metadata 的离线解码
ulog_params cmd/ulog_params 初版 CSV/QGC/Octave 输出
ulog2csv cmd/ulog2csv 初版按 topic 输出 CSV
write_ulog 待设计 未实现
ulog2kml / ulog2rosbag 待设计 未实现
DB / migration 待设计 未实现

兼容性策略

  1. 上游 test/ 目录完整保留在 testdata/pyulog/，Python 测试文件作为兼容性参考快照。
  2. testdata/pyulog/oracle_summary.json 由真实 PX4/pyulog 生成，用来比较 Go 解析后的内容，而不是比较展示格式。当前覆盖 6 个样例日志、290 个 dataset、217964 行数据和 6085 个扁平字段哈希。
  3. 内容级 oracle 比较 header、flags、appended offsets、info/info_multiple、initial/default/changed parameters、formats、logging、dropouts，以及每个 topic 的行数、首尾 timestamp、逐字段小端字节 SHA256。
  4. Go 测试按 pyulog 测试分层启用：已启用解析 oracle、CLI info/messages/params/csv 和 PX4 events 样例；未实现的大块用 skipped contract test 标出。
  5. 每补一个 CLI 或 API 行为，都先添加 pyulog 样例级测试，确认 RED 后再补最小实现。
  6. Go API 保持稳定、清晰，不为了逐字复刻 Python 内部对象而牺牲类型边界。
  7. 对 pyulog 中依赖 NumPy/SQLite/ROS 生态的能力，先定义 Go 侧输出契约，再实现。

重新生成 oracle

需要本地安装 pyulog 及其 Python 依赖后执行：

python scripts/generate_pyulog_oracle.py \
  --testdata-dir testdata/pyulog \
  --output testdata/pyulog/oracle_summary.json

oracle_summary.json 是测试输入，不是手写 golden。Go 侧 TestParseMatchesPyulogOracleSummary 会读取它，并把当前解析结果转成同样的内容摘要后做精确比较。