Metadata-Version: 2.4
Name: socbag-manager
Version: 0.0.2
Summary: 单帧 soc bag 目录的发现与路径解析，仅返回路径信息，不提供文件读写
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=5.4.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# socbag-manager

单帧 soc bag 目录的**发现与路径解析**库，仅返回路径信息，不读取/写入文件内容。

## 目录约定

- **bag 目录**: `{base_path}/{bag_path}/`，需同时存在 `camera/` 与 `lidar/` 子目录
- **相机图像**: `{base}/{bag_path}/camera/{camera_name}/data/{sequence}.png`
- **雷达点云**: `{base}/{bag_path}/lidar/{lidar_name}/pcd/{sequence}.pcd`

## 安装

```bash
pip install socbag-manager
```

## 统一设置

所有 API 基于 `SocbagManagerSettings`，可从代码构造或 YAML 加载（兼容 C03 `base_paths`/`priority_base_path` 与 C04 `data_dirs`/`default_main_dir`）：

```python
from socbag_manager import SocbagManagerSettings

settings = SocbagManagerSettings(
    base_paths={"pandar": "/data/pandar", "at128": "/data/at128"},
    priority_source="pandar",
    bag_name_pattern="*_soc*",
)
# 或
settings = SocbagManagerSettings.from_yaml("/path/to/config.yaml")
```

## 主要 API

- **发现**: `get_ordered_base_paths`, `discover_bags`, `discover_bags_from_scan_root`, `discover_cameras`, `discover_lidars`, `discover_sequences`
- **路径解析**: `resolve_camera_paths`, `resolve_lidar_paths`, `resolve_frame_paths`
- **候选枚举**: `list_frame_candidates`, `choose_one_candidate`（`CandidatePath`）
- **目录树**: `TreeNode`, `build_folder_tree(settings, scope="roots"|"bags"|"sequences", ...)`

## 使用示例

```python
from socbag_manager import (
    SocbagManagerSettings,
    discover_bags,
    discover_sequences,
    resolve_frame_paths,
    build_folder_tree,
)

settings = SocbagManagerSettings.from_yaml("config.yaml")
bag_names = discover_bags(settings)
sequences = discover_sequences(settings, bag_names[0])
paths = resolve_frame_paths(settings, bag_names[0], sequences[0])
# paths["images"], paths["pcds"]

tree_roots = build_folder_tree(settings, scope="bags")
for root in tree_roots:
    for bag in root.children:
        print(bag.name, bag.path)
```

## 约束

- 所有接口**仅返回路径**（字符串或树节点中的 path），不读取/解析图像或点云文件。
- 依赖：Python >=3.10，PyYAML。

## 开发与测试

```bash
pip install -e ".[dev]"
python -m pytest tests/ -v
```
