Metadata-Version: 2.4
Name: lidar-image-pick-core
Version: 0.0.1
Summary: 图像缩放坐标映射、LiDAR 投影点选点与像素/点云导航核心算法库
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20
Provides-Extra: pcd
Requires-Dist: open3d>=0.17; extra == "pcd"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# lidar-image-pick-core

纯算法库，不绑定 Qt。用于把“图像缩放坐标映射、LiDAR 投影点选点、像素模式/点云模式方向导航”沉淀为稳定能力。

## 功能

- 图像画布坐标与原图像素坐标互转
- 一个像素下多个 LiDAR 投影点的完整候选返回
- 像素模式方向移动
  - 先按原图像素 `u/v +/- step`
  - 若该像素无投影点，再最近邻吸附到真实点云像素
- LiDAR 模式方向移动
  - 有 `ring/count` 时优先按 `ring + count` 导航
  - 缺 `ring` 或缺可达目标时，自动降级为方向最近邻导航
- PCD 输入支持
  - `DATA ascii` 直接解析
  - `DATA binary` / `binary_compressed` 需要安装 `open3d`

## 安装

```bash
pip install lidar-image-pick-core
```

需要 PCD 二进制读取时：

```bash
pip install "lidar-image-pick-core[pcd]"
```

## 快速开始

```python
from lidar_image_pick_core import (
    CanvasTransform,
    PickIndex,
    ProjectedPointRecord,
    move_lidar,
    move_pixel,
    resolve_pixel,
)

points = [
    ProjectedPointRecord(point_id="p0", xyz=(1.0, 0.0, 10.0), pixel=(100, 50), ring=0, count=0),
    ProjectedPointRecord(point_id="p1", xyz=(1.2, 0.1, 10.0), pixel=(101, 50), ring=0, count=1),
    ProjectedPointRecord(point_id="p2", xyz=(1.0, 0.0, 11.0), pixel=(100, 50), ring=1, count=0),
]

index = PickIndex.build(points, image_size=(1920, 1080))

result = resolve_pixel(index, 100, 50)
print(result.points_at_resolved_pixel)   # 同像素下全部点

pixel_move = move_pixel(index, (100, 50), "left", step=1, snap=True)
print(pixel_move.requested_pixel, pixel_move.resolved_pixel)

lidar_move = move_lidar(index, "p1", "left")
print(lidar_move.active_point.point_id)  # p0

transform = CanvasTransform(
    image_width=1920,
    image_height=1080,
    canvas_width=1280,
    canvas_height=720,
    zoom_factor=2.0,
    pan_offset_x=0,
    pan_offset_y=0,
)
canvas_pt = transform.image_to_canvas(100, 50)
image_pt = transform.canvas_to_image(*canvas_pt)
```

## 主要接口

- `CanvasTransform`
- `ProjectedPointRecord`
- `PickIndex.build(projected_points, image_size)`
- `load_structured_points_from_pcd(path)`
- `project_points_with_callable(structured_points, project_xyz_to_pixel, image_size)`
- `get_points_at_pixel(index, px, py)`
- `find_nearest_projected_pixel(index, px, py, directional=None)`
- `resolve_pixel(index, px, py, snap="exact_then_nearest")`
- `move_pixel(index, current_pixel, direction, step=1, snap=True)`
- `move_lidar(index, active_point_id, direction)`
- `get_capabilities(index)`

## 设计约束

- 本库不依赖 D05 / D07，但接口兼容它们的常见数据形态
- 本库不负责 UI 事件，只负责算法与结果结构
- 缺 `ring` / `count` 时不崩溃，自动降级并返回 `status/message`

## License

MIT
