# 🦴 Bone Quality Assessment

[![Python](https://img.shields.io/badge/Python-3.10-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.104-green.svg)](https://fastapi.tiangolo.com/)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.1-red.svg)](https://pytorch.org/)
[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/)

## 📋 Описание

Сервис искусственного интеллекта для автоматизированной оценки качества денситометрических изображений и их разметки. Система получает на вход рентгеновское денситометрическое исследование в формате DICOM, и оценивает качество выполнения исследования по стандартным критериям, а также корректность разметки анатомических структур на изображениях.

### Основные возможности

- 🖼️ **Анализ изображений** — загрузка и обработка медицинских изображений
- 🧠 **Сегментация объектов** — выделение анатомических структур (позвонки, кости)
- 📊 **Оценка качества** — проверка по 3 критериям:
  - Артефакты (движение, шум, размытость)
  - Позиционирование (правильное расположение объекта)
  - Контрастность (качество изображения)
- 🔍 **Детекция нарушений** — определение типа нарушения для некачественных исследований
- 🌐 **Web-интерфейс** — удобная загрузка и визуализация результатов
- 📡 **REST API** — интеграция с внешними системами
- 📈 **Визуализация маски** — отображение сегментации на изображении

## 🏗️ Архитектура

![!img](public/static/arch.png)


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

### Требования

- Python 3.10+
- PyTorch 2.1+
- Docker (опционально)

### Локальная установка

```bash
# 1. Клонирование репозитория
git clone https://github.com/yourusername/bone-quality-assessment.git
cd bone-quality-assessment

# 2. Создание виртуального окружения
python -m venv venv
source venv/bin/activate  # Linux/Mac
# или
venv\Scripts\activate  # Windows

# 3. Установка зависимостей
pip install -r requirements.txt

# 4. Загрузка обученной модели (опционально)
# Поместите модель в папку models/unet_cats_dogs.pth

# 5. Запуск сервера
python run.py
```

Docker

```bash
# 1. Сборка образа
docker build -t bone-quality-api .

# 2. Запуск контейнера
docker run -p 8000:8000 bone-quality-api

# 3. Или используя docker-compose
docker-compose up -d
```


📡 API Endpoints

| Метод  | 	Эндпоинт         | 	Описание                |
|--------|-------------------|--------------------------|
| GET    | 	/	               | Главная страница         
| GET    | /docs	            | Swagger UI документация  
| GET    | 	/redoc	          | ReDoc документация       
| GET    | 	/api/v1/health	  | Проверка статуса сервиса 
| POST   | 	/api/v1/analyze	 | Анализ изображения       


Пример запроса
```bash
curl -X POST "http://localhost:8000/api/v1/analyze" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/image.jpg"
```

Пример ответа

```json
{
  "overall_quality": "GOOD",
  "severity": "LOW",
  "issues": [],
  "confidence": 0.9,
  "metrics": {
    "artifact": {
      "artifact": false,
      "num_objects": 1,
      "edge_energy": 0.234,
      "object_size": 0.123
    },
    "position": {
      "position": [0.45, 0.52],
      "valid": true,
      "deviation": 0.032
    },
    "contrast": {
      "valid": true,
      "contrast": 0.456
    }
  },
  "mask": "base64_encoded_mask_image"
}
```


📊 Интерфейс
Веб-интерфейс доступен по адресу http://localhost:8000/:

 - 📤 Drag-and-drop загрузка изображений
 - 🔍 Автоматический анализ
 - 🎯 Визуализация маски сегментации
 - 📈 Детальные метрики качества
 - 🏷️ Подробный отчет о нарушениях


🛠️ Технологии

|Компонент | Технология
|-|-|
|Бэкенд	| Python 3.10, FastAPI, Uvicorn
|ML	| PyTorch, NumPy, SciPy
|Обработка изображений |	PIL, OpenCV
|Визуализация |	HTML5, CSS3, Canvas API
|Контейнеризация | 	Docker, Docker Compose
|Документация | 	Swagger UI, ReDoc


📁 Структура проекта
```text
bone-quality-assessment/
├── src/
│   ├── api/
│   │   ├── endpoints.py      # FastAPI эндпоинты
│   │   └── static/
│   │       └── index.html    # Web-интерфейс
│   ├── models/
│   │   └── unet.py          # U-Net архитектура
│   └── quality/
│       └── quality_scorer.py # Оценка качества
├── models/
│   └── unet_cats_dogs.pth   # Обученная модель
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── run.py
└── README.md
```

🧪 Тестирование
```bash
# Запуск тестов (если есть)
pytest tests/
```

# Проверка API

```bash
curl http://localhost:8000/api/v1/health
```

## 📊 Метрики качества

Артефакты

*Описание:* Обнаружение шума, размытости, фрагментации

Проверка:

 - Энергия границ (edge_energy)
 - Количество объектов (num_objects)
 - Размер объекта (object_size)

### Позиционирование

*Описание:* Проверка правильности расположения объекта

Проверка:

 - Центр масс объекта
 - Отклонение от центра изображения
 - Минимальный размер объекта

### Контраст

*Описание:* Оценка качества изображения

Проверка:

 - Контраст внутри объекта
 - Отношение средних (объект/фон)
 - Интенсивность пикселей

## 🚀 Деплой
На сервер
```bash
# Копирование на сервер
scp -r ./bone-quality-assessment user@server:/var/www/
```

# Запуск в фоновом режиме
nohup python run.py > logs/out.log 2>&1 &

Использование с Nginx
```nginx
location /api/ {
    proxy_pass http://localhost:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}
```

## 🤝 Вклад в проект
 - Fork репозитория
 - Создайте ветку для вашей фичи (git checkout -b feature/amazing-feature)
 - Commit изменений (git commit -m 'Add amazing feature')
 - Push в ветку (git push origin feature/amazing-feature)
 - Откройте Pull Request


**📄 Лицензия**

MIT License

👥 Команда
Грачев Денис — Разработка - GitHub

### 🙏 Благодарности

***Oxford-IIIT Pet Dataset*** для обучения модели

***Сообществу PyTorch и FastAPI***

📞 Контакты
 - 📧 Email: your.email@example.com
 - 🐦 Telegram: @oxydencher
 - 🐙 GitHub: gdg6

<div align="center"> <sub>Built with ❤️ for the Bone Quality Assessment Hackathon</sub> </div>