README.md

---
title: Open-World Object Intelligence Platform
emoji: 👁️
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: 4.44.1
app_file: app.py
pinned: false
license: mit
hardware: gpu
---

# Open-World Object Intelligence Platform

[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **Complete System Architecture, Product Specification, ML Pipelines, Live Testing, Downloads, Guides, API, Database, and Hugging Face Deployment Plan**

---

## 🌟 Key Features

1. **Known Object Detection (RT-DETR)**: Fast, predictable object detection for standard COCO classes using RT-DETR.
2. **Open-Vocabulary Discovery (YOLO-World)**: Zero-shot visual concept detection driven by dynamic text prompts without detector retraining.
3. **Specific Object Recognition (Visual Embeddings)**: Deep PyTorch vision feature extractor + cosine similarity search to teach and recognize specific physical objects (*e.g. My Cup* vs generic *cups*).
4. **🔒 Lock Mode Target Filtering**: Restricts output bounding boxes so that **ONLY** objects matching your lock target (*e.g., 'My Cup', 'red backpack'*) are displayed on the live feed. Non-matching objects are completely suppressed.
5. **Result Fusion Engine**: Smart Non-Maximum Suppression (NMS) and IoU deduplication that prioritizes specific taught object identities over generic category labels.
6. **Hugging Face Spaces & Gradio Web App**: Sleek glassmorphic web interface built with Gradio and FastAPI ready for 1-click Hugging Face Spaces deployment.
7. **Python SDK & OpenCV Examples**: Clean client SDK (`object_intelligence`) with ready-to-run OpenCV webcam scripts.
8. **Portable Custom Object Database**: Portable SQLite database with ZIP import/export capabilities for taught object libraries.

---

## 🏗️ System Architecture

```
                 OBJECT INTELLIGENCE PLATFORM
                              |
      +-----------------------+-----------------------+
      |                       |                       |
      v                       v                       v
 KNOWN OBJECTS          OPEN VOCABULARY        SPECIFIC OBJECTS
    RT-DETR               YOLO-World             Embeddings
      |                       |                       |
      +-----------------------+-----------------------+
                              |
                              v
                        RESULT FUSION
                              |
                     +--------+--------+
                     |                 |
                     v                 v
                NORMAL MODE        LOCK MODE
                     |                 |
                     |           Target matching
                     |                 |
                     |                 v
                     |          Only target boxes
                     |                 |
                     +--------+--------+
                              |
                              v
                     OBJECT KNOWLEDGE DB
```

---

## 🚀 Quick Start

### 1. Installation

```bash
git clone https://github.com/user/Object-Intelligence.git
cd Object-Intelligence
pip install -r requirements.txt
```

### 2. Run Application Locally

```bash
python app.py
```
Open your browser at `http://localhost:7860`.

---

## 🐍 Python SDK Usage

```python
from object_intelligence import ObjectDetector
import cv2

# Initialize detector client
detector = ObjectDetector()

# Select mode ('combined', 'known', 'open_vocabulary', 'specific')
detector.set_mode("combined")

# Enable Lock Mode for a specific target
detector.lock("My Cup")

# Process frame
frame = cv2.imread("sample.jpg")
annotated_frame, detections = detector.detect_and_draw(frame)

# Save result
cv2.imwrite("output.jpg", annotated_frame)
```

---

## 🧠 Teaching Custom Objects

Teach the system new physical objects using reference photos:

```python
from object_intelligence import ObjectDetector

detector = ObjectDetector()
detector.add_object(
    name="My Cup",
    images=["cup_front.jpg", "cup_back.jpg", "cup_side.jpg"],
    category="Drinkware",
    description="Personal blue mug with handle"
)
```

---

## 🌐 Deploying to Hugging Face Spaces

1. Create a new **Gradio** Space on Hugging Face.
2. Upload this repository (`app.py`, `requirements.txt`, `backend/`, `object_intelligence/`, `docs/`, `examples/`).
3. Hugging Face Spaces will automatically install dependencies and run `app.py`!

---

## 📄 License

Distributed under the MIT License. See `LICENSE` for details.