DOCUMENTATION .md

#  Smart Statue Detector API - Documentation

## Overview

REST API built with **FastAPI** + **YOLOv8** for detecting **persons** and **Egyptian statues** in images.

- 🟢 **Green box** → Person
- 🔴 **Red box** → Statue (with real name)

**Base URL:**
```
https://morefaat69-smart-statue-detector.hf.space
```

---

## Endpoints

### `GET /`
Health check - تأكد إن الـ API شغال.

**Response:**
```json
{
  "message": "AI API is running "
}
```

---

### `POST /predict-image`
Upload an image → get detections + annotated output image.

#### Request
| Field | Type | Description |
|-------|------|-------------|
| `file` | `multipart/form-data` | Image file (jpg, jpeg, png) |

#### Response
| Field | Type | Description |
|-------|------|-------------|
| `total_count` | `int` | Total detections (persons + statues) |
| `persons` | `int` | Number of persons detected |
| `statues` | `int` | Number of statues detected |
| `output_image_url` | `string` | URL of annotated image (temporary) |
| `output_image_base64` | `string` | Base64 encoded annotated image |
| `detections` | `array` | List of all detections |

#### Detection Object
| Field | Type | Description |
|-------|------|-------------|
| `type` | `string` | `"person"` or `"statue"` |
| `name` | `string` | `"Person"` or statue name (e.g. `"Hathor Capital"`) |
| `confidence` | `float` | Confidence score (0.0 → 1.0) |
| `bbox` | `array` | Bounding box `[x1, y1, x2, y2]` |

#### Example Response
```json
{
  "total_count": 2,
  "persons": 1,
  "statues": 1,
  "output_image_url": "https://morefaat69-smart-statue-detector.hf.space/uploads/output_test.jpeg",
  "output_image_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgAB...",
  "detections": [
    {
      "type": "person",
      "name": "Person",
      "confidence": 0.9128,
      "bbox": [56, 399, 577, 892]
    },
    {
      "type": "statue",
      "name": "Hathor Capital",
      "confidence": 0.3147,
      "bbox": [329, 0, 683, 721]
    }
  ]
}
```

---

## How to Connect (Integration Examples)

### cURL
```bash
curl -X POST "https://morefaat69-smart-statue-detector.hf.space/predict-image" \
  -H "accept: application/json" \
  -F "file=@your_image.jpg;type=image/jpeg"
```

---

### Python
```python
import requests
import base64
from PIL import Image
from io import BytesIO

url = "https://morefaat69-smart-statue-detector.hf.space/predict-image"

with open("your_image.jpg", "rb") as f:
    response = requests.post(url, files={"file": f})

data = response.json()

print(f"Persons: {data['persons']}")
print(f"Statues: {data['statues']}")

for d in data["detections"]:
    print(f"{d['type']} → {d['name']} ({d['confidence']:.2%})")

# عرض الصورة الناتجة
img_data = base64.b64decode(data["output_image_base64"].split(",")[1])
img = Image.open(BytesIO(img_data))
img.show()
```

---

### JavaScript / React
```javascript
const detectObjects = async (imageFile) => {
  const formData = new FormData();
  formData.append("file", imageFile);

  const response = await fetch(
    "https://morefaat69-smart-statue-detector.hf.space/predict-image",
    {
      method: "POST",
      body: formData,
    }
  );

  const data = await response.json();

  console.log(`Persons: ${data.persons}`);
  console.log(`Statues: ${data.statues}`);

  // عرض الصورة الناتجة مباشرة
  return (
    <div>
      <img src={data.output_image_base64} alt="Detection Result" />
      {data.detections.map((d, i) => (
        <p key={i}>
          {d.type === "statue" ? "🏛️" : "👤"} {d.name} — {(d.confidence * 100).toFixed(1)}%
        </p>
      ))}
    </div>
  );
};
```

---

### Flutter / Dart
```dart
import 'dart:convert';
import 'dart:io';
import 'package:http/http.dart' as http;

Future<Map<String, dynamic>> detectObjects(File imageFile) async {
  final uri = Uri.parse(
    'https://morefaat69-smart-statue-detector.hf.space/predict-image'
  );

  final request = http.MultipartRequest('POST', uri);
  request.files.add(
    await http.MultipartFile.fromPath('file', imageFile.path)
  );

  final response = await request.send();
  final body = await response.stream.bytesToString();
  final data = jsonDecode(body);

  print('Persons: ${data['persons']}');
  print('Statues: ${data['statues']}');

  // فك الـ Base64 وعرض الصورة
  final imageBytes = base64Decode(
    data['output_image_base64'].split(',')[1]
  );

  return data;
}

// عرض الصورة في Flutter
Image.memory(imageBytes)
```

---

## Models

| Model | Purpose | Classes |
|-------|---------|---------|
| `yolov8n.pt` | Person detection | 1 class: Person |
| `best.pt` | Egyptian statue detection | 84 classes |

### Supported Statues (84 classes)
The model can identify statues including:
`Akhenaten`, `Amenhotep III`, `Nefertiti`, `Sphinx`, `Mask of Tutankhamun`,
`Great Pyramids of Giza`, `Colossal Statue of Ramesses II`, `Hathor Capital`,
`Seated Statue of Djoser`, `Statue of Khafre` ... and 74 more.

---

## Configuration

| Parameter | Value | Description |
|-----------|-------|-------------|
| `CONF_THRESHOLD` | `0.25` | Minimum confidence to show detection |
| Person box color | 🟢 Green `(0,255,0)` | BGR format |
| Statue box color | 🔴 Red `(0,0,255)` | BGR format |
| Max image size | No limit | Processed as-is |

---

## Interactive Docs
Swagger UI available at:
```
https://morefaat69-smart-statue-detector.hf.space/docs
```