Metadata-Version: 2.2
Name: wheelchair_planning
Version: 0.4.0
Summary: Wheelchair planning module
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Project-URL: Homepage, https://github.com/H-tr/Wheel-Chair-Planning
Project-URL: Repository, https://github.com/H-tr/Wheel-Chair-Planning
Project-URL: Issues, https://github.com/H-tr/Wheel-Chair-Planning/issues
Requires-Python: >=3.12
Requires-Dist: numpy>=2
Requires-Dist: scipy
Requires-Dist: casadi
Provides-Extra: kinematics
Requires-Dist: pin>=3.3; extra == "kinematics"
Requires-Dist: pin-pink; extra == "kinematics"
Requires-Dist: osqp; extra == "kinematics"
Provides-Extra: examples
Requires-Dist: fire; extra == "examples"
Requires-Dist: matplotlib; extra == "examples"
Requires-Dist: pybullet; extra == "examples"
Requires-Dist: xmltodict; extra == "examples"
Provides-Extra: dev
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: trimesh>=4.0; extra == "dev"
Description-Content-Type: text/markdown

# Wheel-Chair-Planning

<div align="center">

[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue?style=for-the-badge&logo=materialformkdocs)](https://h-tr.github.io/Wheel-Chair-Planning/)
[![Build Docs](https://img.shields.io/github/actions/workflow/status/H-tr/Wheel-Chair-Planning/docs.yml?branch=main&style=for-the-badge&label=docs%20build&logo=github)](https://github.com/H-tr/Wheel-Chair-Planning/actions/workflows/docs.yml)
[![CI](https://img.shields.io/github/actions/workflow/status/H-tr/Wheel-Chair-Planning/ci.yml?branch=main&style=for-the-badge&label=CI&logo=github)](https://github.com/H-tr/Wheel-Chair-Planning/actions/workflows/ci.yml)

</div>

A planning library for the **wheelchair-mounted xArm7** robot
([`wheelchair_xarm_description`](https://github.com/soibkhon/wheelchair_xarm_description)).
It provides inverse kinematics (TRAC-IK and Pink), motion planning
([VAMP](https://github.com/KavrakiLab/vamp) + [OMPL](https://ompl.kavrakilab.org/)),
and collision-aware planning through a unified Python interface.

The architecture mirrors [AdaCompNUS/Autolife-Planning](https://github.com/AdaCompNUS/Autolife-Planning);
only the robot has been swapped — from the 24-DOF Autolife humanoid to a 10-DOF
mobile manipulator (a 3-DOF planar wheelchair base + a 7-DOF xArm7 arm).

## Features

- **Inverse Kinematics** — TRAC-IK (unconstrained) and Pink (QP-based constrained) solvers with self-collision avoidance and camera/orientation stabilization
- **Motion Planning** — VAMP-based planner with collision checking, path validation, and subgroup planning (arm-only, base-only, and whole-body)
- **Time Parameterization** — TOPP-RA; converts planned paths into executable trajectories with velocity/acceleration limits
- **Kinodynamic Planning** — FLASK (flatness-based kinodynamic RRT-Connect) plans time-parameterised trajectories directly, with joint/base velocity and acceleration limits and an exactly nonholonomic diff-drive base
- **Collision Geometry** — Spherized URDF representations for efficient collision detection, with pointcloud obstacle support

## Robot

| | |
|---|---|
| Description | [`soibkhon/wheelchair_xarm_description`](https://github.com/soibkhon/wheelchair_xarm_description) (vendored at `assets/wheelchair_xarm_description`) |
| Arm | UFACTORY xArm7 (7 DOF), end-effector `link_tcp` |
| Base | Wheelchair platform, modeled as a 3-DOF planar virtual joint (x, y, yaw) |
| Planning groups | `wheelchair_arm` (7), `wheelchair_base` (3), `wheelchair_whole_body` (10) |

## Quick Start

**Platform**: Linux x86_64 (AVX2), Python 3.12–3.14.

For inference — running the planners and IK solvers — pip install:

```bash
git clone --recursive https://github.com/H-tr/Wheel-Chair-Planning.git
cd Wheel-Chair-Planning
pip install -e ".[kinematics]"   # core deps: numpy, scipy, casadi
```

The `kinematics` extra adds `pin` + `pin-pink` for the IK solvers; drop it
if you only need motion planning and time parameterization.

For development — rebuilding URDFs, regenerating FK headers, running the C++
toolchain end-to-end — use the setup script, which installs pixi and the
conda-forge deps (pinocchio, orocos-kdl, eigen, boost, ...):

```bash
bash scripts/setup.sh
```

## Usage

```bash
# Inverse kinematics
pixi run python examples/ik/basic.py
pixi run -e dev python examples/ik/basic_vis.py           # PyBullet visualization

# Motion planning
pixi run python examples/planning/motion.py
pixi run python examples/planning/subgroup.py

# Time parameterization
pixi run python examples/planning/time_parameterization.py

# Kinodynamic planning (FLASK): drive to a table, then reach over it
pixi run python examples/planning/kinodynamic.py

# Tests
pixi run -e dev test
```

### Rebuilding the robot description

The planning URDFs, spherized collision geometry, and the FK header are generated
from the vendored robot description:

```bash
pixi run build-robot        # preprocess URDF + meshes + SRDF + virtual base
pixi run decompose-robot    # CoACD convex decomposition
pixi run spherize-robot     # FOAM spherization -> wheelchair_spherized.urdf
pixi run generate-fk        # cricket -> ext/ompl_vamp/robot/wheelchair.hh
pixi run build-pkg          # compile the C++ extensions
```

## Project Structure

```
wheelchair_planning/   # Core Python package
  kinematics/          # TRAC-IK + Pink IK, FK, collision checking
  planning/            # VAMP motion planning, cost + constrained planners
  trajectory/          # TOPP-RA time parameterization
  envs/                # Simulation environments (PyBullet)
  types/               # Shared dataclasses (Pose, JointState, ...)
  resources/           # Packaged URDFs and asset loaders
third_party/
  vamp/                # SIMD-accelerated motion planning (submodule)
  ompl/                # Open Motion Planning Library (submodule)
  cricket/             # FK code generator (submodule)
  foam/                # Collision geometry / spherization (submodule)
  toppra/              # Time-optimal path parameterization (submodule)
ext/                   # C++ extensions (ompl_vamp, trac_ik)
assets/
  wheelchair_xarm_description/   # Raw robot description (submodule)
examples/              # IK, planning, demos
tests/                 # Pytest suite (CI)
scripts/               # Setup, build, spherize, FK codegen
docs/                  # MkDocs site sources (GitHub Pages)
```

## Acknowledgements

This project builds on several outstanding open-source libraries and on the
[AdaCompNUS/Autolife-Planning](https://github.com/AdaCompNUS/Autolife-Planning)
architecture:

- **[VAMP](https://github.com/KavrakiLab/vamp)** — SIMD-accelerated motion planning and collision checking (KavrakiLab, Rice University).
- **[OMPL](https://ompl.kavrakilab.org/)** — The Open Motion Planning Library (KavrakiLab, Rice University).
- **[TOPP-RA](https://github.com/hungpham2511/toppra)** — Reachability-analysis-based time-optimal path parameterization, used for time parameterization.
- **[TRAC-IK](https://traclabs.com/projects/trac-ik/)** — Inverse kinematics solver (TRACLabs).
- **[wheelchair_xarm_description](https://github.com/soibkhon/wheelchair_xarm_description)** — The robot description (URDF + meshes).
```
