tftree-manager 0.1.0

TF 树梳理与变换管理：YAML/JSON 外参加载、图路径与环检测、直接关系重写、局部求逆、可嵌入 TF 树可视化与操作底座、变换矩阵计算

tftree-manager

当前版本：0.1.0

tftree-manager 是 D03 的 TF/外参领域服务库，用于加载、查询、诊断和更新 YAML / mdrive4 JSON / PB 派生外参工作区。它不是底层矩阵小工具，也不是端到端应用工作流；项目侧仍应负责 UI 状态、车辆/任务上下文、临时目录、业务保存策略和标定算法编排。

安装

pip install tftree-manager

推荐入口

V0.1.0 的新代码应优先使用 TFTreeWorkspace + services：

from tftree_manager import (
    TFTreeWorkspace,
    TransformOperationService,
    TransformQueryService,
    TopologyService,
)

workspace = TFTreeWorkspace.load_yaml("/path/to/yaml_dir")
query = TransformQueryService(workspace)
topology = TopologyService(workspace)
ops = TransformOperationService(workspace)

frames = workspace.frames()
cycles = topology.detect_cycles()

# 默认 compute，用于标定文件、尺寸链、保存和 JSON/PB/YAML 写回。
T_compute = query.get_transform("lidar", "camera")

# projection 用于 lidar2cam 显示、PnP 和图像投影。
T_projection = query.get_transform("lidar", "camera", output_mode="projection")

# 如果外部输入矩阵来自投影链路，D03 在 API 边界归一为 compute 后存储。
ops.upsert_direct_transform(
    "lidar",
    "camera",
    T_projection,
    input_mode="projection",
    save=False,
)

服务边界

D03 库内负责沉淀稳定的领域能力：

• workspace 加载/保存：TFTreeWorkspace.load_yaml()、load_mdrive4_json()、save_yaml()。
• transform 查询：TransformQueryService.get_transform()、compute_all_from_root()、convert_transform_mode()。
• 路径和拓扑诊断：TopologyService 的路径、环检测、边查询。
• 通用外参更新原语：TransformOperationService 的 direct relation、标定链路替换、相邻边求逆和 direct transform upsert。
• 格式边界：YAML、mdrive4 JSON、PB 派生 YAML 与可视化数据模型。

项目侧应保留业务状态和编排逻辑，包括当前 lidar/camera 选择、GUI 状态、车辆/任务上下文、临时目录策略、业务保存策略、标定算法输入输出组织。

compute / projection 合同

• compute 是默认模式，用于标定文件、尺寸链、direct/manual link 存储、PB/YAML/JSON 写回。
• projection 用于 lidar2cam 显示、PnP 和图像投影。
• graph 内部只保存 compute；projection 只在 get_transform(..., output_mode="projection")、convert_transform_mode(...) 或 input_mode="projection" 的 D03 API 边界派生/归一。
• mdrive4 JSON camera 的 compute 轴系为 FLU，projection 轴系为 OpenCV/RDF。
• PB/YAML 无 order_manifest.yaml.frame_axes metadata 时，D03 不推测相机轴系，compute 与 projection 返回一致。
• JSON 写回必须走 D03 的 compute -> JSON FLU 序列化，业务侧不要自行拼 camera JSON RPY/translation。

兼容层

TFTreeManager 在 V0.1.0 中仅作为 deprecated compat wrapper 保留，用于旧项目平滑运行；新文档、新示例和后续 C 项目接入应以 TFTreeWorkspace + services 为主入口。

C01~C08 当前只作为需求采样来源，不要求、不强制立即迁移。后续迁移应逐项按项目节奏接入稳定 facade 或 services。

面向 C 项目的 facade

重复的矩阵查询、路径查询、JSON root edge 更新和图数据构建可优先使用稳定 facade：

from tftree_manager import GraphViewModelBuilder, JsonRootEdgeUpdater, PathLookup, TransformLookup

matrix = TransformLookup.from_yaml("/path/to/yaml_dir").matrix("lidar", "camera")
path_edges = PathLookup.from_yaml("/path/to/yaml_dir").edge_keys("lidar", "camera")
view_model = GraphViewModelBuilder.from_yaml("/path/to/yaml_dir").build(
    source_frame="lidar",
    target_frame="camera",
)

updater = JsonRootEdgeUpdater.from_yaml("/path/to/yaml_dir", root_frame="vrf_ground")
updater.update_root_edge("lidar", "camera", matrix, save=False)

更多文档

• doc/README.md：完整功能说明和 CLI 示例。
• doc/API_USAGE.md：Flask 旧接口、Python API 和接入示例。
• doc/UPDATE.md：V0.1.0 更新说明与迁移方向。
• plan/：长期架构调整计划、验收矩阵和执行记录。