Metadata-Version: 2.4
Name: fastsim-navigation
Version: 0.1.3
Summary: Native C++17 Hybrid A* SE(2) navigation for Python
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Project-URL: Documentation, https://pypi.org/project/fastsim-navigation/
Requires-Python: <3.13,>=3.12
Requires-Dist: numpy>=1.24
Description-Content-Type: text/markdown

# fastsim-navigation

FastSim 的独立 Hybrid A* SE(2) 导航包，提供 Python API 和 `fastsim-se2-plan` 命令行工具。

## 安装

发行版仅支持：

- CPython 3.12
- Linux x86-64
- glibc 2.35 及以上

本包只发布预编译 wheel，不发布源码包。所需的 OMPL、ODE、CCD 和 Boost 运行库都已封装在 wheel 中，用户不需要本地编译环境或系统级导航库。

```bash
python3.12 -m pip install --only-binary=:all: fastsim-navigation
```

如果 Python 版本或平台不匹配，pip 会直接报告无可用发行版，不会在用户机器上尝试编译。

## Python API

```python
import numpy as np
import fastsim_navigation as se2

cells = np.zeros((80, 80), dtype=np.uint8)
costmap = se2.Costmap(cells, 0.1, 0.0, 0.0)
planner = se2.HybridAStar(costmap)

request = se2.PlanRequest()
request.start = se2.Pose2D(1.0, 1.0, 0.0)
request.goal = se2.Pose2D(7.0, 7.0, 0.0)
request.footprint = se2.CircleFootprint(0.2)

config = se2.PlannerConfig()
config.minimum_turning_radius = 0.4
config.allow_reverse = True

result = planner.plan(request, config)
if result.status == se2.PlannerStatus.SUCCESS:
    print(result.path_array)       # shape: (N, 3), float64
    print(result.directions_array) # shape: (N,), int8
```

主要功能包括：

- Dubins / Reeds-Shepp 运动学与解析扩展
- 前进、倒车、方向切换和可选原地旋转
- 圆形、多边形和多多边形机器人足迹
- `uint8` 代价地图、未知区域策略与地图膨胀
- 障碍物启发式缓存、路径平滑、重采样与曲率校验
- 超时、节点上限、取消、诊断信息和版本透传
- CSV / PGM 地图输入，CSV / JSON 路径输出，SVG 路径绘图

## CLI

```bash
fastsim-se2-plan \
  --map map.csv --resolution 0.1 \
  --origin 0 0 \
  --start 0.25 0.25 0 \
  --goal 1.75 1.75 0 \
  --radius 0.08 \
  --path-csv path.csv \
  --result-json result.json \
  --svg plan.svg
```

`--help` 可查看全部参数。地图代价值中，`0` 为自由区域，`1..252` 为软代价，`253/254` 为障碍物，`255` 为未知区域。

第三方组件和许可证信息包含在 wheel 的 `fastsim_navigation/licenses/` 目录中。
