README.md

---
title: Tunnel Crack Detection
emoji: 🔍
colorFrom: blue
colorTo: red
sdk: streamlit
sdk_version: 1.28.0
app_file: app.py
pinned: false
license: agpl-3.0
---

# 🔍 Tunnel Crack Detection

A state-of-the-art web application for detecting cracks and defects in tunnel infrastructure using YOLOv12-DINO deep learning model. Deployed on Hugging Face Spaces for easy access and sharing.

## Features

- 🔍 **Real-time crack detection** using YOLOv12-DINO
- 🖼️ **Interactive web interface** built with Streamlit
- 📊 **Detailed analysis** with charts and detection tables
- 📁 **Large file support** (up to 5GB model weights)
- 📈 **Detection history** and results export
- 🎯 **Configurable parameters** (confidence, IoU thresholds)

## 🚀 Quick Start

This application is deployed on Hugging Face Spaces. Simply:

1. **Upload your YOLOv12-DINO model weights** (.pt file) using the sidebar
2. **Upload a tunnel image** for analysis  
3. **Click "Analyze for Cracks"** to get instant results!

## 🛠️ Local Setup

### Prerequisites

- Python 3.8 or higher
- YOLOv12-DINO trained model weights (.pt file)

### Installation

1. **Clone or navigate to the project directory:**
   ```bash
   cd /Users/sompoteyouwai/env/deploy_tunnel_crack
   ```

2. **Create a virtual environment (recommended):**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

### Running the Application

1. **Start the Streamlit app:**
   ```bash
   streamlit run streamlit_app.py
   ```

2. **Open your browser** and navigate to `http://localhost:8501`

3. **Load the model:**
   - If the default model exists at `/Users/sompoteyouwai/env/model_weight/segment_defect.pt`, click "Load Default Model"
   - Alternatively, upload your own model weights (.pt file)

4. **Upload an image** and click "Detect Cracks" to analyze

## Usage

### Model Loading
- **Default Model**: The app automatically detects if the default model is available
- **Custom Model**: Upload your own YOLOv12-DINO trained weights
- **Device Selection**: Choose between CPU, CUDA (GPU), or MPS (Apple Silicon)

### Detection Parameters
- **Confidence Threshold**: Minimum confidence score for detections (0.01-1.0)
- **IoU Threshold**: Intersection over Union threshold for Non-Maximum Suppression (0.01-1.0)
- **Image Size**: Input resolution for the model (320-1280 pixels)

### Results
- **Annotated Images**: View detected cracks with bounding boxes
- **Detection Summary**: Count and classification of detected defects
- **Interactive Charts**: Pie charts and confidence distributions
- **Detailed Table**: Exportable CSV with detection coordinates and metadata
- **History**: Track multiple detection sessions

## File Structure

```
deploy_tunnel_crack/
├── streamlit_app.py      # Main Streamlit application
├── inference.py          # YOLOv12-DINO inference engine
├── requirements.txt      # Python dependencies
├── README.md            # This file
└── run.sh               # Quick start script
```

## Model Information

The application expects a YOLOv12-DINO model trained for crack/defect detection. The default model path is:
```
/Users/sompoteyouwai/env/model_weight/segment_defect.pt
```

### Supported Model Features:
- Object detection and segmentation
- Multiple defect classes
- Configurable inference parameters
- GPU acceleration support

## Troubleshooting

### Common Issues:

1. **Model not found**: Ensure the model file exists at the specified path or upload a custom model
2. **CUDA errors**: Install appropriate PyTorch version for your GPU
3. **Memory issues**: Reduce image size or use CPU device for large images
4. **Import errors**: Ensure all dependencies are installed: `pip install -r requirements.txt`

### Performance Tips:
- Use GPU (CUDA/MPS) for faster inference
- Optimize image size based on your hardware capabilities
- Adjust confidence threshold to filter false positives

## Development

To modify or extend the application:

1. **Streamlit App**: Edit `streamlit_app.py` for UI changes
2. **Inference Engine**: Modify `inference.py` for model-related changes
3. **Dependencies**: Update `requirements.txt` for new packages

## License

This project is for tunnel infrastructure monitoring and maintenance applications.