Metadata-Version: 2.4
Name: tftree-manager
Version: 0.1.1
Summary: TF 树梳理与变换管理：YAML/JSON 外参加载、图路径与环检测、直接关系重写、局部求逆、可嵌入 TF 树可视化与操作底座、变换矩阵计算
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20.0
Requires-Dist: PyYAML>=5.4.0
Requires-Dist: Flask>=2.0.0
Requires-Dist: mdrive4-json>=0.0.2
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: ui
Requires-Dist: PySide6; extra == "ui"
Requires-Dist: matplotlib; extra == "ui"
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"

# tftree-manager

**当前版本：0.1.1**

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

## 安装

```bash
pip install tftree-manager
```

## 推荐入口

V0.1.1 延续 `TFTreeWorkspace + services` 主入口：

```python
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：

```python
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.1 更新说明与迁移方向。
- `plan/`：长期架构调整计划、验收矩阵和执行记录。
