bone_2026/QWEN.md

# Bone Quality Assessment Project

## Project Overview

Medical AI service for automated assessment of DXA (bone densitometry) study quality. The system analyzes DICOM files and evaluates quality based on standard criteria.

### Core Purpose (Hackathon)
- Analyze DICOM densitometry studies
- Determine anatomical region (spine/hip)
- Binary classification: quality (OK/violation)
- Detailed violation type detection (motion, artifacts, position, ROI)
- Output results in XLSX/CSV format per requirements

### Tech Stack
| Component | Technology |
|-----------|------------|
| Backend | Python 3.10, FastAPI, Uvicorn |
| ML/Deep Learning | PyTorch, torchvision (ResNet18) |
| Image Processing | PIL, OpenCV, pydicom, scipy |
| Data Handling | pandas, openpyxl |
| Containerization | Docker |

---

## Project Structure

```
bone_2026/
├── src/
│   ├── main.py                    # FastAPI app (DXA mode)
│   ├── run.py                     # Server runner
│   ├── dxa/                       # DXA Quality module
│   │   ├── dataset.py            # DXADataset class
│   │   ├── model.py              # ResNet18 classifier
│   │   ├── train.py              # Training script
│   │   ├── inference.py          # Batch inference
│   │   └── __init__.py
│   ├── api/                       # REST endpoints & schemas
│   │   ├── endpoints.py          # Original endpoints
│   │   └── static/               # Web UI
│   │       ├── index.html
│   │       └── js/dxa-app.js
│   ├── core/                     # Orchestrator
│   ├── quality/                  # Quality scoring
│   │   ├── quality_scorer.py     # Base scorer
│   │   ├── detailed_assessment.py # NEW: Detailed assessment
│   │   ├── position_validator.py
│   │   └── artifact_detector.py
│   └── segmentators/             # Segmentation models
├── models/
│   └── dxa_model.pth             # Trained DXA classifier
├── dataset_hack/                  # DICOM datasets
│   ├── Для теста/                # Test data
│   └── НД_для_обучения/         # Training data
├── requirements.txt
├── Dockerfile
├── run.sh
└── README.md
```

---

## Implemented Features (Current)

### ✅ API Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/` | Web interface |
| GET | `/api/v1/health` | Health check |
| POST | `/api/v1/analyze` | Basic analysis |
| POST | `/api/v1/analyze/detailed` | **NEW: Detailed analysis with metrics** |
| POST | `/api/v1/analyze/sr` | **NEW: DICOM SR report** |
| POST | `/api/v1/batch` | Batch processing |
| POST | `/api/v1/export` | Export to XLSX |

### ✅ Detailed Assessment (`src/quality/detailed_assessment.py`)
- **Motion detection**: Laplacian variance, FFT blur analysis
- **Artifact detection**: Metal, implants, cement, calcifications
- **Spine completeness**: Vertebrae count, alignment, spacing
- **Hip completeness**: Full visibility, aspect ratio
- **Hip rotation**: Major axis angle calculation
- **ROI validation**: Boundary check, margin, size
- **Violation types**: correct, position_error, artifact_motion, artifact_other, labeling_error, incomplete_view, roi_error, rotation

### ✅ Web Interface
- Drag-and-drop DICOM upload
- Table with results (filter, sort, search)
- **NEW: Detail panel** - click on row to see:
  - Violation type
  - Reason (human-readable)
  - Motion metrics
  - Artifact detection
  - ROI validation

---

## DXA Module (`src/dxa/`)

### Dataset (`dataset.py`)
- Loads DICOM files from studies
- Parses annotation Excel file
- **Automatically detects anatomical region from image content**
- Maps regions: spine, hip_right, hip_left
- Quality labels: 0 (OK), 1 (violation)

### Model (`model.py`)
- Architecture: ResNet18 (pretrained on ImageNet)
- Task: Binary classification (quality OK vs violation)
- Input: 224x224 RGB images
- Output: class probabilities

### Training (`train.py`)
```bash
python src/dxa/train.py --epochs 10 --batch-size 16
```

### Inference (`inference.py`)
```bash
python src/dxa/inference.py \
    --input-path dataset_hack/Для\ теста \
    --output-path results.xlsx \
    --model-path models/dxa_model.pth
```

---

## Running the Project

### Training
```bash
python src/dxa/train.py --epochs 10
```

### Inference
```bash
python src/dxa/inference.py --input-path file.dcm --output-path result.xlsx
```

### API Server
```bash
python -m uvicorn src.main:app --host 0.0.0.0 --port 8000
```

Web UI: http://localhost:8000

---

## Output Format (per Hackathon Requirements)

### Basic Output
| Column | Description |
|--------|-------------|
| path_to_study | Path to study directory |
| study_uid | StudyInstanceUID from DICOM |
| image_uid | SOPInstanceUID from DICOM |
| anatomical_region | spine / hip_left / hip_right / hip |
| quality_class | 0 (OK), 1 (violation) |
| violation_type | Type of violation (if any) |
| processing_status | Success / Failure |
| time_of_processing | Processing time (seconds) |

### Detailed Output (/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, "severity": "HIGH" },
    "artifacts": { "any_detected": true, "metal_detected": false },
    "roi_check": { "valid": true }
  },
  "overall_quality": "POOR",
  "severity": "HIGH"
}
```

---

## Anatomical Region Detection

The system automatically determines the anatomical region from the DICOM image content:

### Algorithm (`src/dxa/inference.py`)
1. **Spine vs Hip** - by bright region shape:
   - Extract 95th percentile threshold
   - Calculate bounding box aspect ratio
   - Spine: bbox_aspect < 1.5 (more square)
   - Hip: bbox_aspect > 1.5 (vertically elongated)

2. **Hip Left vs Right** - by brightness asymmetry:
   - Calculate left/right bright pixel ratio
   - hip_left: L/R ratio < 0.7 (left side brighter)
   - hip_right: L/R ratio > 1.3 (right side brighter)
   - hip: unclear (fallback)

---

## Known Issues & Limitations

1. **Model training** - Needs retraining with new violation types
2. **Dataset size** - Currently ~100 studies, needs 500+
3. **Segmentation** - Uses simple threshold, needs proper model
4. **F1 score** - Currently ~0.27, needs improvement with weighted loss
5. **Heatmap visualization** - Not implemented (requires model retraining)

---

## Multi-Model Architecture (Planned)

See `docs/multi_model_architecture.md` for the planned pipeline:

```
Pipeline:
1. Region Detector → 2. Segmentator → 3. Quality Classifier → 4. Violation Type → 5. Aggregator
```

### Planned Models:

| Model | Purpose | File |
|-------|---------|------|
| Region Detector | Spine/Hip detection | `src/models/region_detector.py` |
| Segmentator | Bone segmentation | `src/models/segmentation/` |
| Quality Classifier | OK/Violation binary | `src/models/classification/quality.py` |
| Violation Classifier | 7+ violation types | `src/models/classification/violation.py` |
| Artifact Detector | Motion, metal detection | `src/models/artifacts/detector.py` |
| Grad-CAM | Attention heatmap | `src/models/visualization/gradcam.py` |

---

## Docker

```bash
docker build -t dxa-quality .
docker run -v /data:/data -p 8000:8000 dxa-quality
```

---

## Development Notes

### Code Style
- Follow existing patterns in src/
- Type hints where appropriate
- Minimal comments (only for context)

### Key Components
- **DXADataset**: Handles DICOM loading + annotation parsing
- **DXAQualityClassifier**: ResNet18-based classifier
- **process_dicom_files**: Batch inference with XLSX output
- **generate_quality_report**: Detailed assessment with metrics

### Dependencies
All in `requirements.txt`:
- `torch`, `torchvision` - Deep learning
- `pydicom` - DICOM handling
- `pandas`, `openpyxl` - Data/Excel
- `fastapi`, `uvicorn` - Web framework
- `Pillow`, `opencv-python-headless` - Image processing
- `scipy` - Image analysis (blur, artifacts)