261 lines
6.2 KiB
Markdown
261 lines
6.2 KiB
Markdown
# Quick Start Guide
|
|
|
|
This guide will help you get the Microscopy Object Detection Application up and running quickly.
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.8 or higher
|
|
- pip package manager
|
|
- (Optional) CUDA-capable GPU for faster training and inference
|
|
|
|
## Installation
|
|
|
|
### 1. Clone or Navigate to Project Directory
|
|
|
|
```bash
|
|
cd /home/martin/code/object_detection
|
|
```
|
|
|
|
### 2. Create Virtual Environment
|
|
|
|
```bash
|
|
python3 -m venv venv
|
|
source venv/bin/activate # On Linux/Mac
|
|
# or
|
|
venv\Scripts\activate # On Windows
|
|
```
|
|
|
|
### 3. Install Dependencies
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
This will install:
|
|
- ultralytics (YOLOv8)
|
|
- PySide6 (GUI framework)
|
|
- pyqtgraph (visualization)
|
|
- OpenCV and Pillow (image processing)
|
|
- And other dependencies
|
|
|
|
**Note:** The first run will automatically download the YOLOv8s.pt model (~22MB).
|
|
|
|
### 4. Verify Installation
|
|
|
|
```bash
|
|
python -c "import PySide6; import ultralytics; print('Installation successful!')"
|
|
```
|
|
|
|
## First Run
|
|
|
|
### Launch the Application
|
|
|
|
```bash
|
|
python main.py
|
|
```
|
|
|
|
The application window should open with 5 tabs:
|
|
- **Detection**: For running object detection
|
|
- **Training**: For training custom models (placeholder)
|
|
- **Validation**: For validating models (placeholder)
|
|
- **Results**: For viewing detection history (placeholder)
|
|
- **Annotation**: Future feature (placeholder)
|
|
|
|
## Configuration
|
|
|
|
### Set Up Image Repository
|
|
|
|
1. Go to **File → Settings**
|
|
2. Under "General" tab, click "Browse..." next to "Base Path"
|
|
3. Select your microscopy images directory
|
|
4. Click "Save"
|
|
|
|
This tells the application where your images are stored.
|
|
|
|
### Adjust Detection Settings
|
|
|
|
In the Settings dialog:
|
|
- **Detection tab**: Adjust default confidence threshold (0.25 default)
|
|
- **Training tab**: Configure default training parameters
|
|
- All settings are saved to [`config/app_config.yaml`](config/app_config.yaml)
|
|
|
|
## Running Detection
|
|
|
|
### Single Image Detection
|
|
|
|
1. Go to the **Detection** tab
|
|
2. Select a model from the dropdown (default: Base Model yolov8s.pt)
|
|
3. Adjust confidence threshold with the slider
|
|
4. Click "Detect Single Image"
|
|
5. Select an image file
|
|
6. View results in the results panel
|
|
|
|
### Batch Detection
|
|
|
|
1. Go to the **Detection** tab
|
|
2. Select a model
|
|
3. Click "Detect Batch (Folder)"
|
|
4. Select a folder containing images
|
|
5. Confirm the number of images to process
|
|
6. Wait for processing to complete
|
|
7. Results are automatically saved to the database
|
|
|
|
## Understanding the Results
|
|
|
|
Detection results include:
|
|
- **Image path**: Location of the processed image
|
|
- **Detections**: Number of objects found
|
|
- **Class names**: Types of objects detected (e.g., organelle, membrane_branch)
|
|
- **Confidence scores**: Detection confidence (0-1)
|
|
- **Bounding boxes**: Object locations (stored in database)
|
|
|
|
All results are stored in the SQLite database at [`data/detections.db`](data/detections.db).
|
|
|
|
## Database
|
|
|
|
The application uses SQLite to store:
|
|
- **Models**: Information about trained models
|
|
- **Images**: Metadata about processed images
|
|
- **Detections**: All detection results with bounding boxes
|
|
- **Annotations**: Manual annotations (future feature)
|
|
|
|
### View Database Statistics
|
|
|
|
Go to **Tools → Database Statistics** to see:
|
|
- Total number of detections
|
|
- Detections per class
|
|
- Average confidence scores
|
|
|
|
## Next Steps
|
|
|
|
### Training Custom Models (Coming Soon)
|
|
|
|
The Training tab will allow you to:
|
|
1. Select a YOLO-format dataset
|
|
2. Configure training parameters
|
|
3. Monitor training progress
|
|
4. Save trained models
|
|
|
|
### Preparing Your Dataset
|
|
|
|
For training, you'll need data in YOLO format:
|
|
```
|
|
dataset/
|
|
├── train/
|
|
│ ├── images/
|
|
│ │ ├── img001.png
|
|
│ │ └── ...
|
|
│ └── labels/
|
|
│ ├── img001.txt
|
|
│ └── ...
|
|
├── val/
|
|
│ ├── images/
|
|
│ └── labels/
|
|
└── data.yaml
|
|
```
|
|
|
|
See [`README.md`](README.md) for detailed dataset format information.
|
|
|
|
## Troubleshooting
|
|
|
|
### Application Won't Start
|
|
|
|
**Error: Module not found**
|
|
```bash
|
|
# Make sure virtual environment is activated
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
**Error: Qt platform plugin**
|
|
```bash
|
|
# Install system Qt dependencies (Linux)
|
|
sudo apt-get install libxcb-xinerama0
|
|
```
|
|
|
|
### Detection Not Working
|
|
|
|
**No models available**
|
|
- The base YOLOv8s model will be downloaded automatically on first use
|
|
- Make sure you have internet connection for the first run
|
|
|
|
**Images not found**
|
|
- Verify the image repository path in Settings
|
|
- Check that image files have supported extensions (.jpg, .png, .tif, etc.)
|
|
|
|
### Performance Issues
|
|
|
|
**Slow detection**
|
|
- Use a GPU if available (CUDA will be auto-detected)
|
|
- Reduce batch size in settings
|
|
- Process fewer images at once
|
|
|
|
**Out of memory**
|
|
- Reduce batch size
|
|
- Use CPU instead of GPU for large images
|
|
- Process images sequentially rather than in batch
|
|
|
|
## File Locations
|
|
|
|
- **Database**: `data/detections.db`
|
|
- **Configuration**: `config/app_config.yaml`
|
|
- **Logs**: `logs/app.log`
|
|
- **Models**: `data/models/`
|
|
- **Results**: Stored in database
|
|
|
|
## Command Line Tips
|
|
|
|
### Check GPU Availability
|
|
|
|
```bash
|
|
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"
|
|
```
|
|
|
|
### View Logs
|
|
|
|
```bash
|
|
tail -f logs/app.log
|
|
```
|
|
|
|
### Backup Database
|
|
|
|
```bash
|
|
cp data/detections.db data/detections_backup_$(date +%Y%m%d).db
|
|
```
|
|
|
|
## Getting Help
|
|
|
|
- Read the full documentation in [`README.md`](README.md)
|
|
- Check architecture details in [`ARCHITECTURE.md`](ARCHITECTURE.md)
|
|
- Review implementation guide in [`IMPLEMENTATION_GUIDE.md`](IMPLEMENTATION_GUIDE.md)
|
|
- Check logs in `logs/app.log` for error messages
|
|
|
|
## What's Implemented
|
|
|
|
✅ **Core Infrastructure**
|
|
- Project structure and configuration
|
|
- Database schema and operations
|
|
- YOLO model wrapper
|
|
- Inference engine with batch processing
|
|
- Configuration management
|
|
- Logging system
|
|
|
|
✅ **GUI Components**
|
|
- Main window with menu bar
|
|
- Settings dialog
|
|
- Detection tab with single/batch detection
|
|
- Placeholder tabs for future features
|
|
|
|
🚧 **In Progress / Planned**
|
|
- Training tab implementation
|
|
- Validation tab with metrics
|
|
- Results browser and visualization
|
|
- Annotation tool
|
|
- Advanced filtering and export
|
|
- Real-time camera detection
|
|
|
|
---
|
|
|
|
**Happy detecting! 🔬🔍**
|
|
|
|
For questions or issues, please refer to the documentation or check the application logs. |