README.md

---
title: SAM2 Segmentation API
emoji: 🎯
colorFrom: purple
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
license: apache-2.0
---

# 🎯 SAM2 Segmentation API

Мощный REST API для сегментации объектов на изображениях с использованием Meta SAM2 (Segment Anything Model 2).

## ✨ Возможности

- **🎯 Box Prompts** - выделение прямоугольником
- **🖌️ Brush Prompts** - рисование кистью (зеленый = объект, красный = фон, белый = объект)
- **📍 Point Prompts** - клики по объектам
- **🔥 Batch API** - обработка множественных объектов за один запрос
- **🖼️ Extract Objects** - автоматическое извлечение объектов с прозрачностью
- **⚡ REST API** - полная документация в Swagger UI

## 🚀 Быстрый старт

### Web интерфейс

После запуска Space откройте:

- **Простой интерфейс**: `/web` - Box промпты
- **Продвинутый**: `/web/advanced` - Box + Brush промпты
- **API документация**: `/docs` - Swagger UI

### API Endpoints

#### POST `/segment/batch` - Батчинг API (рекомендуется)

Обрабатывает множественные объекты за один запрос.

**Пример запроса:**
```json
{
  "image": "data:image/jpeg;base64,...",
  "prompts": [
    {
      "id": 0,
      "type": "mask",
      "data": "data:image/png;base64,...",
      "label": "person",
      "selected": true
    }
  ],
  "options": {
    "extract_objects": true,
    "include_masks": false,
    "clean_masks": true
  }
}
```

#### POST `/segment` - Простая сегментация

С box промптом:
```bash
curl -X POST "/segment?box_x1=50&box_y1=50&box_x2=300&box_y2=400&extract_objects=true" \
  -F "file=@image.jpg"
```

## 📊 Производительность

⚠️ **CPU Version**: Работает на бесплатном CPU tier Hugging Face Spaces. Скорость обработки: ~5-10 секунд на изображение.

Для более быстрой обработки рекомендуется upgrade на GPU (Settings → Hardware).

## 🎨 Форматы масок

API поддерживает несколько форматов масок:

- **🟢 Зеленый** (R<100, G>150, B<100) - foreground (объект)
- **⚪ Белый** (R>200, G>200, B>200) - foreground (объект)
- **🔴 Красный** (R>150, G<100, B<100) - background (исключить)

## 🔧 Технологии

- Meta SAM2 2.1 (Segment Anything Model)
- FastAPI
- PyTorch
- OpenCV
- Pydantic

## 📝 Примеры использования

### Python

```python
import requests
import base64

# Загрузить изображение
with open("image.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

# Отправить запрос
response = requests.post(
    "https://YOUR-SPACE.hf.space/segment/batch",
    json={
        "image": f"data:image/jpeg;base64,{image_b64}",
        "prompts": [{
            "id": 0,
            "type": "box",
            "data": "",
            "bbox": {"x_min": 0.1, "y_min": 0.2, "x_max": 0.5, "y_max": 0.8},
            "label": "person",
            "selected": True
        }],
        "options": {"extract_objects": True}
    }
)

result = response.json()
print(f"Обработано объектов: {len(result['results'])}")
```

### JavaScript

```javascript
const response = await fetch('https://YOUR-SPACE.hf.space/segment/batch', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    image: imageBase64,
    prompts: [{
      id: 0,
      type: "box",
      data: "",
      bbox: {x_min: 0.1, y_min: 0.2, x_max: 0.5, y_max: 0.8},
      label: "person",
      selected: true
    }],
    options: {extract_objects: true}
  })
});

const result = await response.json();
console.log(`Обработано: ${result.results.length} объектов`);
```

## 📚 Документация

Полная интерактивная документация доступна по адресу `/docs` после запуска Space.

## 🤝 Поддержка

- Модель: SAM 2.1 Hiera Tiny (для CPU)
- Форматы изображений: JPG, PNG, WEBP, BMP
- Максимальный размер: рекомендуется до 2048x2048px для разумной скорости

## ⚡ Оптимизация для мобильных приложений

1. Уменьшайте размер изображения перед отправкой (1024x1024)
2. Используйте `include_masks: false` если контуры не нужны
3. Кэшируйте результаты на клиенте
4. Используйте батчинг API для множественных объектов

## 📄 Лицензия

Apache 2.0

## 🔗 Ссылки

- [SAM2 GitHub](https://github.com/facebookresearch/sam2)
- [SAM2 Paper](https://arxiv.org/abs/2408.00714)