# lidar-manager

LiDAR 点云投影、颜色管理、降采样、缓存、距离/强度过滤，输出一张渲染后的图片。

## 安装

```bash
pip install lidar-manager
```

## 功能特性

- **lidar2cam 投影**：内参、外参、针孔/鱼眼畸变
- **颜色管理**：按距离/强度着色，内置多套配色（jet、viridis、rainbow 等），可直接选用
- **过滤管理**：按强度或距离阈值/范围过滤
- **降采样**：uniform / random / voxel / distance_based
- **缓存**：去畸变与点云投影缓存，减少重复计算
- **输出**：一张渲染后的图片（点云叠加在图像上）

版本更新与变更见 [version_update.md](version_update.md)。

## 输入与输出

- **输入**：点云、图像、内参、外参、颜色管理（配色方案）、过滤管理（可选：强度/距离范围）
- **输出**：一张渲染后的图片

## 快速开始

```python
import numpy as np
from lidar_manager import (
    ProjectionManager,
    ImageProcessor,
    get_default_color_scheme,
    list_default_scheme_names,
)

# 内置配色名称
print(list_default_scheme_names())  # ['jet', 'viridis', 'rainbow', ...]

# 获取默认配色（BGR 列表）
colors = get_default_color_scheme("jet")

# 构造投影管理器
K = np.eye(3)  # 3x3 内参
K[0, 0] = K[1, 1] = 1000
K[0, 2], K[1, 2] = 960, 540
T = np.eye(4)  # 4x4 外参 lidar2cam

pm = ProjectionManager(
    image_processor=ImageProcessor(K),
    initial_distance_range=(0, 100),
)
pm.update_intrinsic(K)
pm.update_extrinsic(T)

# 处理图像（去畸变）
image = np.zeros((1080, 1920, 3), dtype=np.uint8)  # 你的图像
proc_image, _ = pm.process_image(image)
pm.update_image_size(proc_image.shape[1], proc_image.shape[0])

# 更新配色
pm.update_color_scheme(colors)

# 点云 Nx3 或 Nx4 (x,y,z[, intensity])
points = np.random.randn(10000, 4).astype(np.float32)
points[:, 3] = np.clip(points[:, 3], 0, 255)  # intensity

# 投影并可选范围过滤
pm.project_points(
    points,
    color_type="distance",
    range_filter_params={"min_val": 5.0, "max_val": 80.0, "mode": "distance"},
)

# 输出：一张渲染后的图片
rendered = pm.render_to_image(proc_image, point_size=2, point_opacity=1.0)
# 保存或显示 rendered
```

## 接口说明

### 投影与渲染

- **project_points(points, color_type="distance", attr_range=None, color_filter_params=None, range_filter_params=None)**  
  唯一投影入口：将点云投影到当前图像并构建内部映射表。可传入 `range_filter_params`（如 `{"min_val": 5.0, "max_val": 80.0, "mode": "distance"}`）做全局距离/强度范围过滤；返回过滤后的映射表或 None。

- **render_to_image(image, point_size=2, point_opacity=1.0, use_background_mode=True)**  
  将当前映射表中的点云渲染到图像上，返回叠加后的图像。

### 按像素查询

- **find_nearest_point(px, py, search_radius=5)**  
  返回像素 (px, py) 处或邻域内**最近**的一个 3D 点（按 lidar 距离），返回 dict（含 pixel, xyz, cam_xyz, attr, normalized, color）；无点时返回 None。

- **get_lidar_3d_at_pixel(px, py, search_radius=5, distance_range=None, intensity_range=None, color_filter=None, return_attributes=False)**  
  按像素位置与可选的**距离/强度/颜色**过滤条件，筛选该位置附近的 lidar 3D 点列表。需先调用 `project_points`。  
  - `distance_range=(min_d, max_d)`：仅保留距离在 [min_d, max_d] 米内的点。  
  - `intensity_range=(min_i, max_i)`：仅保留强度在该区间内的点。  
  - `color_filter={"reference_color": [B,G,R], "threshold": float}`：仅保留与参考色 BGR 距离 ≤ threshold 的点。  
  - `return_attributes=False` 时返回 `List[Tuple[x,y,z]]`，`True` 时返回 `List[Dict]`（含 xyz、distance、intensity、pixel、color 等）。无点时返回 `[]`。

### 其它常用接口

- **update_intrinsic(K)** / **update_extrinsic(T)** / **update_image_size(width, height)**：更新内参、外参、图像尺寸。
- **update_color_scheme(colors)**：更新配色方案（BGR 列表）。
- **get_visible_points()**：返回当前可见点的数组（xyz + 当前属性）。
- **get_global_attr_range()**：返回归一化使用的全局属性范围 (min_val, max_val)。

## 依赖

- Python >= 3.10
- numpy, opencv-python, PyYAML, open3d

## License

MIT
