From b625703e8628e15f8e2b3e73f756caf5c46abd44 Mon Sep 17 00:00:00 2001 From: Martin Laasmaa Date: Fri, 5 Dec 2025 09:38:16 +0200 Subject: [PATCH] Adding readme --- README.md | 493 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 493 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..61f376f --- /dev/null +++ b/README.md @@ -0,0 +1,493 @@ +# Microscopy Object Detection Application + +A desktop application for detecting organelles and membrane branching structures in microscopy images using YOLOv8, featuring comprehensive training, validation, and visualization capabilities. + +![Python](https://img.shields.io/badge/python-3.8+-blue.svg) +![PySide6](https://img.shields.io/badge/PySide6-6.5+-green.svg) +![YOLOv8](https://img.shields.io/badge/YOLOv8-Ultralytics-orange.svg) + +## Features + +- **🎯 Object Detection**: Real-time and batch detection of microscopy objects +- **🎓 Model Training**: Fine-tune YOLOv8s on custom microscopy datasets +- **📊 Validation & Metrics**: Comprehensive model validation with visualization +- **💾 Database Storage**: SQLite database for detection results and metadata +- **📈 Visualization**: Interactive plots and charts using pyqtgraph +- **🖼️ Annotation Tool**: Manual annotation interface (future feature) +- **📤 Export**: Export detection results to CSV, JSON, or Excel +- **⚙️ Configuration**: Flexible configuration management + +## Technology Stack + +- **ML Framework**: [Ultralytics YOLOv8](https://github.com/ultralytics/ultralytics) +- **GUI Framework**: [PySide6](https://doc.qt.io/qtforpython/) +- **Visualization**: [pyqtgraph](https://www.pyqtgraph.org/) +- **Database**: SQLite3 +- **Image Processing**: OpenCV, Pillow + +## Prerequisites + +- Python 3.8 or higher +- CUDA-capable GPU (recommended for training, optional for inference) +- 8GB RAM minimum +- 2GB disk space for models and data + +## Installation + +### 1. Clone the Repository + +```bash +git clone +cd object_detection +``` + +### 2. Create Virtual Environment + +```bash +# Linux/Mac +python3 -m venv venv +source venv/bin/activate + +# Windows +python -m venv venv +venv\Scripts\activate +``` + +### 3. Install Dependencies + +```bash +pip install -r requirements.txt +``` + +### 4. Download Base Model + +The application will automatically download the YOLOv8s.pt model on first use, or you can download it manually: + +```bash +# The model will be downloaded automatically by ultralytics +# Or download manually from: https://github.com/ultralytics/assets/releases +``` + +## Quick Start + +### 1. Launch the Application + +```bash +python main.py +``` + +### 2. Configure Image Repository + +1. Go to **File → Settings** +2. Set the path to your image repository +3. Click **Save** + +### 3. Perform Detection + +1. Navigate to the **Detection** tab +2. Select a model (default: yolov8s.pt) +3. Choose an image or folder +4. Set confidence threshold +5. Click **Detect** +6. View results and save to database + +### 4. Train Custom Model + +1. Navigate to the **Training** tab +2. Prepare your dataset in YOLO format: + ``` + dataset/ + ├── train/ + │ ├── images/ + │ └── labels/ + ├── val/ + │ ├── images/ + │ └── labels/ + └── data.yaml + ``` +3. Select dataset YAML file +4. Configure training parameters +5. Click **Start Training** +6. Monitor progress in real-time + +### 5. View Results + +1. Navigate to the **Results** tab +2. Browse detection history +3. Filter by date, model, class, or confidence +4. Export results to CSV/JSON/Excel + +## Project Structure + +``` +object_detection/ +├── main.py # Application entry point +├── requirements.txt # Python dependencies +├── ARCHITECTURE.md # Detailed architecture documentation +├── IMPLEMENTATION_GUIDE.md # Implementation specifications +├── README.md # This file +├── config/ +│ └── app_config.yaml # Application configuration +├── src/ +│ ├── database/ # Database operations +│ │ ├── db_manager.py # Database manager +│ │ ├── models.py # Data models +│ │ └── schema.sql # Database schema +│ ├── model/ # ML model operations +│ │ ├── yolo_wrapper.py # YOLO wrapper +│ │ └── inference.py # Inference engine +│ ├── gui/ # User interface +│ │ ├── main_window.py # Main window +│ │ ├── tabs/ # Application tabs +│ │ ├── dialogs/ # Dialog windows +│ │ └── widgets/ # Custom widgets +│ └── utils/ # Utility modules +│ ├── config_manager.py # Configuration management +│ ├── logger.py # Logging setup +│ └── file_utils.py # File operations +├── data/ # Data directory +│ ├── models/ # Saved models +│ ├── datasets/ # Training datasets +│ └── results/ # Detection results +├── tests/ # Unit tests +└── docs/ # Documentation +``` + +## Dataset Format + +### YOLO Format Structure + +``` +dataset/ +├── train/ +│ ├── images/ +│ │ ├── img001.png +│ │ ├── img002.png +│ │ └── ... +│ └── labels/ +│ ├── img001.txt +│ ├── img002.txt +│ └── ... +├── val/ +│ ├── images/ +│ └── labels/ +├── test/ +│ └── images/ +└── data.yaml +``` + +### Label Format + +Each label file (`.txt`) contains one line per object: +``` + +``` + +All coordinates are normalized to 0-1 range. + +Example `img001.txt`: +``` +0 0.5 0.5 0.3 0.4 +1 0.2 0.3 0.15 0.2 +``` + +### data.yaml Configuration + +```yaml +path: /path/to/dataset +train: train/images +val: val/images +test: test/images # optional + +names: + 0: organelle + 1: membrane_branch + +nc: 2 +``` + +## Database Schema + +The application uses SQLite with the following main tables: + +- **models**: Stores trained model information and metrics +- **images**: Stores image metadata and paths +- **detections**: Stores detection results with bounding boxes +- **annotations**: Stores manual annotations (future feature) + +See [`ARCHITECTURE.md`](ARCHITECTURE.md) for detailed schema information. + +## Configuration + +### Application Configuration ([`config/app_config.yaml`](config/app_config.yaml)) + +```yaml +database: + path: "data/detections.db" + +image_repository: + base_path: "" # Set via GUI + allowed_extensions: [".jpg", ".jpeg", ".png", ".tif", ".tiff"] + +models: + default_base_model: "yolov8s.pt" + models_directory: "data/models" + +training: + default_epochs: 100 + default_batch_size: 16 + default_imgsz: 640 + default_patience: 50 + +detection: + default_confidence: 0.25 + max_batch_size: 100 + +visualization: + bbox_colors: + organelle: "#FF6B6B" + membrane_branch: "#4ECDC4" + bbox_thickness: 2 +``` + +## Usage Examples + +### Training a Model + +```python +from src.model.yolo_wrapper import YOLOWrapper + +# Initialize wrapper +yolo = YOLOWrapper("yolov8s.pt") + +# Train model +results = yolo.train( + data_yaml="dataset/data.yaml", + epochs=100, + imgsz=640, + batch=16, + name="organelle_detector" +) + +print(f"Training complete! mAP50: {results['metrics']['mAP50']}") +``` + +### Batch Detection + +```python +from src.model.inference import InferenceEngine +from src.database.db_manager import DatabaseManager + +# Initialize components +db = DatabaseManager("data/detections.db") +engine = InferenceEngine( + model_path="data/models/best.pt", + db_manager=db, + model_id=1 +) + +# Detect objects in multiple images +results = engine.detect_batch( + image_paths=["img1.jpg", "img2.jpg"], + repository_root="/path/to/images", + conf=0.25 +) + +print(f"Processed {len(results)} images") +``` + +### Querying Detection Results + +```python +from src.database.db_manager import DatabaseManager + +db = DatabaseManager("data/detections.db") + +# Get all detections for a specific class +detections = db.get_detections( + filters={'class_name': 'organelle'} +) + +# Export to CSV +db.export_detections_to_csv( + output_path="results.csv", + filters={'confidence': 0.5} # Only high-confidence detections +) +``` + +## GUI Tabs + +### 1. Detection Tab +- Single image or batch detection +- Real-time visualization +- Adjustable confidence threshold +- Save results to database + +### 2. Training Tab +- Dataset selection +- Hyperparameter configuration +- Real-time training progress +- Loss and metric plots + +### 3. Validation Tab +- Model validation +- Confusion matrix +- Precision-Recall curves +- Per-class metrics + +### 4. Results Tab +- Detection history browser +- Advanced filtering +- Statistics dashboard +- Export functionality + +### 5. Annotation Tab (Future) +- Manual annotation tool +- YOLO format export +- Annotation verification + +## Development + +### Running Tests + +```bash +# Run all tests +pytest + +# Run with coverage +pytest --cov=src tests/ + +# Run specific test file +pytest tests/test_database.py +``` + +### Code Style + +```bash +# Format code +black src/ tests/ + +# Lint code +pylint src/ + +# Type checking +mypy src/ +``` + +### Building Documentation + +```bash +# Generate API documentation +cd docs +make html +``` + +## Troubleshooting + +### Common Issues + +**Issue**: CUDA out of memory during training + +**Solution**: Reduce batch size in training parameters or use CPU for training + + +**Issue**: Model not found error + +**Solution**: Ensure YOLOv8s.pt is downloaded. Run: +```python +from ultralytics import YOLO +model = YOLO('yolov8s.pt') # Will auto-download +``` + + +**Issue**: Database locked error + +**Solution**: Close any other connections to the database file + + +**Issue**: Import errors + +**Solution**: Ensure virtual environment is activated and dependencies are installed: +```bash +source venv/bin/activate # Linux/Mac +pip install -r requirements.txt +``` + +## Performance Tips + +1. **GPU Acceleration**: Use CUDA-capable GPU for training and inference +2. **Batch Processing**: Process multiple images at once for efficiency +3. **Image Size**: Use appropriate input size (640px default) for balance between speed and accuracy +4. **Confidence Threshold**: Adjust confidence threshold to filter false positives +5. **Database Indexing**: Keep database size manageable for fast queries + +## Roadmap + +### Phase 1 (Core Features) ✅ +- ✅ Model training and validation +- ✅ Real-time and batch detection +- ✅ Results storage in SQLite +- ✅ Basic visualization + +### Phase 2 (Enhanced Features) 🚧 +- [ ] Annotation tool implementation +- [ ] Advanced filtering and search +- [ ] Model comparison tools +- [ ] Enhanced export options + +### Phase 3 (Advanced Features) 📋 +- [ ] Real-time camera detection +- [ ] Multi-model ensemble +- [ ] Cloud storage integration +- [ ] Collaborative annotation + +## Contributing + +Contributions are welcome! Please follow these steps: + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request + +## License + +This project is licensed under the MIT License - see the LICENSE file for details. + +## Acknowledgments + +- [Ultralytics YOLOv8](https://github.com/ultralytics/ultralytics) for the object detection model +- [PySide6](https://doc.qt.io/qtforpython/) for the GUI framework +- [pyqtgraph](https://www.pyqtgraph.org/) for visualization + +## Citation + +If you use this application in your research, please cite: + +```bibtex +@software{microscopy_object_detection, + title = {Microscopy Object Detection Application}, + author = {Your Name}, + year = {2024}, + url = {https://github.com/yourusername/object_detection} +} +``` + +## Contact + +For questions, issues, or suggestions: +- Open an issue on GitHub +- Email: your.email@example.com + +## Support + +If you find this project helpful, please consider: +- ⭐ Starring the repository +- 🐛 Reporting bugs +- 💡 Suggesting new features +- 📖 Improving documentation + +--- + +**Happy detecting! 🔬🔍** \ No newline at end of file