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:

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

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

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

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

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

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