Metadata-Version: 2.4
Name: teleop-cursor
Version: 1.0.0
Summary: Desktop cursor teleoperation node for ROS 2 mobile robots
Home-page: https://github.com/gaminization/teleop-cursor
Author: Garv Arora
Author-email: Garv Arora <66058398+gaminization@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/gaminization/teleop-cursor
Project-URL: Repository, https://github.com/gaminization/teleop-cursor
Project-URL: Issues, https://github.com/gaminization/teleop-cursor/issues
Keywords: ros2,robotics,teleoperation,cursor,mobile-robot
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Scientific/Engineering
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyautogui>=0.9.50
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

<div align="center">

# 🖱️ teleop-cursor

### Intuitive Desktop Cursor Teleoperation for ROS 2 Mobile Robots

[![ROS 2](https://img.shields.io/badge/ROS2-Humble%20%7C%20Jazzy%20%7C%20Rolling-blue?style=for-the-badge&logo=ros&logoColor=white)](https://docs.ros.org/)
[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
[![pip](https://img.shields.io/badge/pip%20install-teleop--cursor-orange?style=for-the-badge&logo=pypi&logoColor=white)](https://github.com/gaminization/teleop-cursor)

<p align="center">
  <b>Transform real-time desktop mouse cursor movements into canonical ROS 2 velocity commands (<code>geometry_msgs/msg/Twist</code>) for physical and simulated mobile robots.</b>
</p>

[Quickstart](#-quickstart) • [Architecture](#-architecture) • [Control Mapping](#-control-mapping) • [Simulation](#-gazebo-simulation) • [Documentation](#-documentation)

---

</div>

## 📌 Overview

**teleop-cursor** provides an ultra-lightweight, zero-hardware teleoperation node for ROS 2 (`rclpy`). Instead of requiring dedicated joysticks or cumbersome keyboard combinations, `teleop-cursor` tracks your screen cursor position relative to display center, translating cursor displacement vectors into smooth linear ($v_x$) and angular ($\omega_z$) velocity commands published directly to the `/cmd_vel` topic.

Whether you are testing autonomous mobile robots (AMRs), validating navigation pipelines in Gazebo, or demonstrating robot movements, `teleop-cursor` turns any standard workstation display into a responsive teleoperation interface.

---

## ⚡ Key Features

- **🚀 Instant Teleoperation**: Zero hardware joysticks required—teleoperate directly using your mouse or trackpad.
- **🔄 Dominant Axis Switching**: Automatically calculates magnitude deltas ($\Delta X, \Delta Y$) to distinguish between turning and driving forward/backward.
- **🤖 ROS 2 Native**: Built on `rclpy` and standard `geometry_msgs/msg/Twist` payloads, ensuring 100% compatibility with TurtleBot3, Nav2, and custom robot controllers.
- **🎯 Dynamic Resolution Handling**: Dynamically queries monitor dimensions using `pyautogui`, auto-centering controls on any resolution (1080p, 4K, ultrawide).
- **⏱️ Real-Time Stream**: Operates at a steady 10 Hz control callback frequency with minimal CPU overhead.

---

## 🏗️ Architecture

The diagram below demonstrates how host screen cursor events flow through the system to actuate simulated or physical ROS 2 robots:

```mermaid
graph LR
    A[Host Display Cursor] -->|X, Y Coordinates| B[PyAutoGUI Interface]
    B -->|Screen Offset ΔX, ΔY| C[CursorFollowNode]
    
    subgraph Signal Processing Loop 10Hz
        C --> D{Dominant Axis?}
        D -->|"abs(ΔX) > abs(ΔY)"| E[Compute Angular Yaw Speed ωz]
        D -->|"abs(ΔY) >= abs(ΔX)"| F[Compute Linear Speed vx]
        E --> G[Construct Twist Message]
        F --> G
    end

    G -->|Publish| H((/cmd_vel Topic))
    H --> I[TurtleBot3 Gazebo Sim]
    H --> J[Physical Mobile Robot]
```

*For complete mathematical details and signal transformations, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).*

---

## 🎮 Control Mapping

The host display is divided into four primary directional control regions anchored to screen center $(X_c, Y_c)$:

```text
                  ▲  FORWARD (+vx = 0.2 m/s)
                  │  [|ΔY| >= |ΔX|]
                  │
   LEFT ◄─────────┼─────────► RIGHT
(ωz = +1.0 rad/s) │         (ωz = -1.0 rad/s)
 [|ΔX| > |ΔY|]    │          [|ΔX| > |ΔY|]
                  │
                  ▼  BACKWARD (-vx = -0.2 m/s)
                     [|ΔY| >= |ΔX|]
```

### Motion Decision Matrix

| Cursor Displacement | Robot Action | `linear.x` (m/s) | `angular.z` (rad/s) |
| :--- | :--- | :---: | :---: |
| **Top Half** ($|\Delta Y| \ge |\Delta X|, \Delta Y > 0$) | Drive Forward | `+0.2` | `0.0` |
| **Bottom Half** ($|\Delta Y| \ge |\Delta X|, \Delta Y < 0$) | Drive Backward | `-0.2` | `0.0` |
| **Left Side** ($|\Delta X| > |\Delta Y|, \Delta X < 0$) | Rotate Left (CCW) | `0.0` | `+1.0` |
| **Right Side** ($|\Delta X| > |\Delta Y|, \Delta X > 0$) | Rotate Right (CW) | `0.0` | `-1.0` |

---

## 🚀 Quickstart

### Prerequisites

Ensure you have a working installation of ROS 2 (Humble, Iron, Jazzy, or Rolling) and Python 3.10+:

```bash
# Source your ROS 2 environment
source /opt/ros/$ROS_DISTRO/setup.bash
```

### Option A — Pip Install (Recommended)

```bash
# Install directly from the repo (adds 'teleop-cursor' CLI to PATH)
pip install git+https://github.com/gaminization/teleop-cursor.git

# Then simply run:
teleop-cursor
```

### Option B — Local Editable Install

```bash
git clone https://github.com/gaminization/teleop-cursor.git
cd teleop-cursor
pip install -e .

# Run the CLI
teleop-cursor
```

### Option C — ROS 2 `colcon` Workspace Build

```bash
mkdir -p ~/ros2_ws/src && cd ~/ros2_ws/src
git clone https://github.com/gaminization/teleop-cursor.git
cd ~/ros2_ws && colcon build --packages-select teleop_cursor
source install/setup.bash

# Run via ros2 run
ros2 run teleop_cursor teleop-cursor
```

### Option D — Direct Script

```bash
git clone https://github.com/gaminization/teleop-cursor.git
cd teleop-cursor
python3 cursor.py
```

3. Move your mouse across your screen to stream velocity commands to your robot!

---

## 🧪 Gazebo Simulation

To test `teleop-cursor` with TurtleBot3 inside Gazebo:

```bash
# Terminal 1: Launch Gazebo Simulation World
export TURTLEBOT3_MODEL=waffle
ros2 launch turtlebot3_gazebo turtlebot3_world.launch.py

# Terminal 2: Run via pip CLI
teleop-cursor

# Or via ros2 run (after colcon build)
ros2 run teleop_cursor teleop-cursor
```

*For complete simulation launching and debugging guides, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).*

---

## ⚙️ Configuration & Parameters

The node parameters in [cursor.py](cursor.py) can be easily tuned:

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `max_linear_speed` | `float` | `0.2` | Maximum linear speed limit ($v_x$) in meters/second |
| `max_angular_speed` | `float` | `1.0` | Maximum angular speed limit ($\omega_z$) in radians/second |
| `timer` frequency | `float` | `0.1` (10 Hz) | Publish rate period in seconds |

---

## 📂 Repository Structure

```text
teleop-cursor/
├── teleop_cursor/        # Pip-installable Python package
│   ├── __init__.py       # Package initialisation & exports
│   └── cursor.py         # CursorFollowNode ROS 2 node implementation
├── resource/             # ROS 2 ament_index resource marker
│   └── teleop_cursor
├── cursor.py             # Backward-compatible script wrapper
├── package.xml           # ROS 2 ament_python package manifest
├── pyproject.toml        # PEP 517/518 build system & metadata
├── setup.py              # Setuptools config (colcon + pip)
├── LICENSE               # MIT Open Source License
├── README.md             # Primary repository landing page
├── CHANGELOG.md          # Version history & release notes
├── CONTRIBUTING.md       # Open-source contribution & PR guide
├── TIMELINE.md           # Project roadmap & release milestones
├── SECURITY.md           # Security & physical robot safety policies
└── docs/
    ├── ARCHITECTURE.md   # Deep-dive architecture & transformation math
    └── DEVELOPMENT.md    # Developer setup, testing & simulation guide
```

---

## 📖 Documentation Directory

- 📐 **[Technical Architecture](docs/ARCHITECTURE.md)**: Deep dive into signal processing math, coordinate frame transformations, sequence diagrams, and message definitions.
- 💻 **[Developer Guide](docs/DEVELOPMENT.md)**: Workspace setup, colcon building, linting rules (`black`/`flake8`), and ROS 2 debugging utilities.
- 🤝 **[Contributing Guidelines](CONTRIBUTING.md)**: Standard PR workflows, Conventional Commit requirements, and issue reporting.
- 🗺️ **[Project Timeline & Roadmap](TIMELINE.md)**: Milestone progression, release history, and feature roadmap (proportional control, deadband overlay).
- 📜 **[Changelog](CHANGELOG.md)**: Formal release logs adhering to Keep a Changelog.
- 🔒 **[Security Policy](SECURITY.md)**: Safety standards for teleoperating physical mobile hardware.

---

## 📄 License

This project is open-source software licensed under the [MIT License](LICENSE).

---

<div align="center">
  <sub>Built with ❤️ for the ROS 2 Robotics Community by <a href="https://github.com/gaminization">Garv Arora</a></sub>
</div>
