Metadata-Version: 2.4
Name: ilo_arena
Version: 1.0.2.post1
Summary: A computer vision and hardware streaming interface for education
Author-email: "intuition RT (SLB)" <contact@ilorobot.com>
Maintainer-email: "intuition RT (SLB)" <contact@ilorobot.com>
Project-URL: Homepage, https://ilorobot.com
Project-URL: Documentation, https://ilorobot.com
Keywords: python,education,robot,ilo,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Topic :: Education
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: ilo
Requires-Dist: pyserial
Requires-Dist: opencv-python
Requires-Dist: PySide6
Requires-Dist: numpy
Requires-Dist: torch
Requires-Dist: ultralytics

<p align="center">
  <img alt="Ilo robot" src="https://api.ilorobot.com/media/userfiles/ilo.png" height="200">
</p>
<p align="center">
  <img src="https://static.pepy.tech/personalized-badge/ilo?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=GREEN&left_text=downloads" alt="PyPI Downloads">
  <img src="https://img.shields.io/pypi/dm/ilo" alt="PyPI Downloads / Month">
</p>

# ilo_arena

**ilo_arena** is a computer vision and hardware streaming interface designed for education. It provides a powerful Python package to control **ilo**, the new educational robot, directly from your computer based on a video feed using AI to track the robot. 

It allows you to move the robot, read sensors, interact with LEDs, and create autonomous behaviors—all in just a few lines of Python.

---

## 🌟 Features

*   **Automatic Connection:** Seamlessly connect to robots detected in the camera's field of view.
*   **AI Element Detection:** Automatically detect and track elements (robots, boxes, etc.) using YOLO vision models.
*   **Intuitive Movement:** Move the robot in multiple directions using Python commands and create complex movement loops.
*   **LED Matrix Control:** Draw and animate using the robot's LED matrix.
*   **Real-time Play:** Interact with the robot in real time using your keyboard.
*   **Sensor Integration:** Control and read sensors wirelessly over Bluetooth.
*   **Built-in Studio UI:** Includes a graphical interface for training custom AI models and visualizing inference streams.

---

## ⚙️ Installation and Updates

**ilo_arena** requires Python 3.8 or higher. You can install it easily using `pip`.

### Install the package
```bash
pip install ilo_arena
```

### Update to the latest version
```bash
pip install ilo_arena --upgrade
```

---

## 🚀 How to Run

### 1. Launching the AI Training program
The package comes with a built-in graphical application that lets you train YOLO models.
To launch the UI, simply run the following command in your terminal:

```bash
ilo_train_ai
```

### 2. Running a Custom Robot Script
To control the robot programmatically, write your logic in a Python file and run it using Python:

```bash
python your_script.py
```

---

## 💻 Code Example

Here is a simple example to get you started. This script initializes the arena, finds detected elements, and commands the robot to perform a simple movement sequence.

```python
from ilo_arena import Robot, Arena, start_arena, Element

def my_robot_logic(arena: Arena):
    while True:
        try:
            # Fetch all items detected by the AI in the camera view
            elements: list[Element] = arena.get_all_elements()
            
            for element in elements:
                # Attempt to get the connected robot associated with this element
                robot: Robot | None = element.get_robot(element._id)
                
                if robot is not None:
                    # Move forward
                    robot.move("front", 45, 100)
                    arena.sleep(2.0)
                    
                    # Rotate 90 degrees
                    robot.rotation(90, finish_state=True)
                    
                    # Move backward
                    robot.move("back", 70, 100)
                    arena.sleep(2.0)
                    
                    # Stop the robot
                    robot.stop()
                    arena.sleep(1.0)
                    
        except Exception as e:
            print(f"Error encountered: {e}")
            
        # Yield time to the background thread
        arena.sleep(0.1)

if __name__ == "__main__":
    # Start the arena and run the logic in a background thread
    start_arena(my_robot_logic)
```

---

## 📚 Documentation

The physical control of the robot heavily depends on the underlying [`ilo` library](https://pypi.org/project/ilo/). For advanced hardware interactions, refer to the `ilo` documentation.

To have a list of all available function, you can use

```python
import ilo_arena

ilo_arena.list_function()
```


## 🤝 Contributing

Bug reports, patches, and suggestions are welcome! Questions? Contact us via [our website](https://ilorobot.com).

<p align="center">
  <a href="https://ilorobot.com">
    <img src="https://img.shields.io/badge/Powered_by-Intuition_RT-%234A75A0?style=for-the-badge&logo=python&logoColor=white" alt="Powered by Intuition RT">
  </a>
</p>
