adameyes 0.1.1
Plug-and-play perception brain for robots
License: MIT
Requires Python: >=3.8

# AdamEyes

### Plug-and-play perception library for robotics (v0.1.1)

<p> AdamEyes is a lightweight Python perception library that provides a modular vision pipeline for robots using a single RGB camera.
It bundles object detection, monocular depth estimation, visual odometry, mapping, and grid-based planning into a simple, ROS-free API.

AdamEyes focuses on clarity, modularity, and correctness, making it suitable for research, learning, prototyping, and early-stage robotic systems.
</p>

## What AdamEyes Provides (v0.1.1)

AdamEyes can:

Capture live frames from a camera

Detect objects using YOLO

Estimate relative depth from a single RGB camera

Track relative motion using visual odometry (SLAM-lite)

Generate a 2D occupancy grid

Plan paths on the grid using A*

Visualize perception and maps for debugging

AdamEyes is a perception library, not a full robot controller.
It does not issue motor commands or make behavior decisions.

## Design Philosophy

ROS-free, pure Python

Single entry point (AdamEyes)

Blackboard-style shared state

Config-driven behavior

Visualization is optional and for humans

AdamEyes computes machine-readable signals that higher-level robotic systems can consume to make decisions.

## Installation
### Requirements

Python 3.8+

USB camera or compatible video source

OpenCV-compatible system (Windows, Linux, macOS)

### Install from PyPI
```bash
pip install adameyes
```

### Development install
```bash
git clone https://github.com/yourusername/adameyes.git
cd adameyes
pip install -e .
```

### Quick Start
```python
from adameyes import AdamEyes
import cv2

eyes = AdamEyes()

while True:
    state = eyes.update()
    eyes.draw()

    if state.objects:
        print(f"Detected {len(state.objects)} objects")

    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

eyes.close()
```

This runs:

live camera capture

object detection

depth estimation

mapping

visualization

## Core API
### AdamEyes

```python
AdamEyes(
    config=None,
    **override
)
```

config: path to a YAML configuration file

override: keyword overrides for configuration values

### Main Methods
Method	Description
update()	Run one perception cycle and update state
plan(goal)	Compute a path on the occupancy grid
draw()	Visualize camera feed and map
close()	Release camera and close windows

## State Object (Primary Output)

update() returns a State object containing all perception results.

```python
state.frame        # RGB camera frame (numpy array)
state.fps          # Frames per second
state.objects      # List of detected objects
state.depth_map    # Relative depth map
state.pose         # Relative pose (x, y, yaw)
state.grid         # Occupancy grid (0 = free, 1 = obstacle)
state.path         # Planned path (if any)
```

### Detected Object Format
```python
{
    "label": "person",
    "confidence": 0.87,
    "bbox": (x1, y1, x2, y2)
}
```

All values are machine-readable and intended for higher-level decision logic.

## Usage Examples

### Example 1: Object Detection Only

```python
from adameyes import AdamEyes

eyes = AdamEyes()

while True:
    state = eyes.update()

    for obj in state.objects:
        print(f"{obj['label']} (conf: {obj['confidence']:.2f})")
```

### Example 2: Path Planning on Occupancy Grid
```python
from adameyes import AdamEyes
import cv2

eyes = AdamEyes()
goal = (200, 300)

while True:
    state = eyes.update()
    path = eyes.plan(goal)

    if path:
        next_waypoint = path[0]
        # Send waypoint to your robot controller

    eyes.draw()

    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

eyes.close()
```
### Example 3: Custom Configuration

```python
from adameyes import AdamEyes

eyes = AdamEyes(
    config="config.yaml",
    logging={"save": True, "level": "INFO"}
)

state = eyes.update()
print("Pose:", state.pose)

if state.grid is not None:
    print("Grid shape:", state.grid.shape)

if state.depth_map is not None:
    print("Depth shape:", state.depth_map.shape)
```

## ⚙️ Configuration (v0.1.1)

AdamEyes is configured using YAML or keyword overrides.

### Supported Configuration

```yaml
camera:
  index: 0
  resolution: [640, 480]

detection:
  model: "yolov8n.pt"
  conf: 0.5

depth:
  model: "midas_small"

slam:
  features: 2000

logging:
  level: "INFO"
  save: false
  folder: "logs"
```

### Load configuration

```python
eyes = AdamEyes(config="config.yaml")
```

### Override parameters

```python
eyes = AdamEyes(
    camera={"resolution": [320, 240]},
    detection={"conf": 0.3}
)
```
### Visualization Notes

draw() uses OpenCV GUI windows

Visualization is optional

Headless systems should not call draw()

### Performance Notes

Depth estimation is computationally expensive on CPU

FPS may range from 3–10 FPS on CPU systems

GPU acceleration (if available) improves performance significantly

Lowering camera resolution improves FPS

AdamEyes prioritizes correctness and clarity over raw speed in v0.1.0.

## 📁 Project Structure
```graphql
adameyes/
├── core/        # Brain and shared state
├── modules/     # Camera, detection, depth, SLAM, mapping, planning
├── utils/       # Configuration and logging
├── viz/         # Visualization helpers
```

### Basic Smoke Test

```python
from adameyes import AdamEyes

eyes = AdamEyes()
state = eyes.update()

assert state.frame is not None
print("AdamEyes v0.1.0 working correctly")

eyes.close()
```
### Roadmap

Planned for future releases:

Module enable/disable flags

Metric depth scaling

Improved SLAM backend

Costmap-based planning

ROS 2 integration

Simulation / no-camera mode

### License

MIT License.
See LICENSE for details.

### Acknowledgments

YOLO – Object detection

MiDaS – Monocular depth estimation

OpenCV – Computer vision

<div align="center"> <b>AdamEyes v0.1.1</b><br> A clean, modular perception library for robotics. </div>