adameyes 0.1.1

Plug-and-play perception brain for robots

AdamEyes

Plug-and-play perception library for robotics (v0.1.1)

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.

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

pip install adameyes

Development install

git clone https://github.com/yourusername/adameyes.git
cd adameyes
pip install -e .

Quick Start

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

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.

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

{
    "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

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

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

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

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

eyes = AdamEyes(config="config.yaml")

Override parameters

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

adameyes/
├── core/        # Brain and shared state
├── modules/     # Camera, detection, depth, SLAM, mapping, planning
├── utils/       # Configuration and logging
├── viz/         # Visualization helpers

Basic Smoke Test

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

AdamEyes v0.1.1
A clean, modular perception library for robotics.