# 🦴 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)

## 🎯 Доступные режимы

### DXA Режим (хакатон)
Анализ денситометрических исследований:
```bash
# Обучение
python src/dxa/train.py --epochs 10

# Инференс
python src/dxa/inference.py --input-path dataset_hack/Для\ теста --output-path results.xlsx
```


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

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

- 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/dxa_model.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	 | Базовый анализ изображения
| POST   | 	/api/v1/analyze/detailed	 | Детальный анализ с метриками
| POST   | 	/api/v1/analyze/sr	 | Анализ с DICOM SR отчётом
| POST   | 	/api/v1/batch	 | Пакетный анализ файлов
| POST   | 	/api/v1/export	 | Анализ и экспорт в XLSX


Пример запроса
```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"
}
```

### Детальный анализ (/api/v1/analyze/detailed)

Возвращает расширенную информацию с детализацией нарушений:

```json
{
  "anatomical_region": "spine",
  "quality_class": 1,
  "quality_label": "Violation detected",
  "violation_type": "artifact_motion",
  "reason": "Обнаружен артефакт движения (размытие)",
  "confidence": 0.85,
  "confidence_per_class": {
    "correct": 0.15,
    "violation": 0.85
  },
  "view_quality": "full",
  "metrics": {
    "motion": {
      "motion_detected": true,
      "blur_laplacian": 0.001,
      "severity": "HIGH"
    },
    "artifacts": {
      "any_detected": false,
      "metal_detected": false
    },
    "roi_check": {
      "valid": true
    }
  },
  "spine_completeness": {
    "valid": true,
    "num_vertebrae": 4
  },
  "overall_quality": "POOR",
  "severity": "HIGH"
}
```


📊 Интерфейс
Веб-интерфейс доступен по адресу 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_2026/
├── src/
│   ├── dxa/                   # DXA Quality модуль
│   │   ├── model.py          # ResNet18 классификатор
│   │   ├── dataset.py        # Загрузчик данных
│   │   ├── train.py          # Обучение
│   │   └── inference.py      # Инференс
│   ├── api/                   # REST API
│   ├── quality/               # Оценка качества
│   └── main.py                # FastAPI приложение
├── models/
│   └── dxa_model.pth         # Обученная модель
├── dataset_hack/              # DICOM датасет
├── Dockerfile
├── requirements.txt
├── run.sh
└── 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>