COMPLETE_SETUP_GUIDE.md

# TRIQA Hugging Face Demo - Complete Setup Guide

## 📋 Overview

This guide documents the complete process of creating and deploying a TRIQA Image Quality Assessment demo on Hugging Face Spaces, including all troubleshooting steps and solutions.

## 🎯 What We Built

- **Web Demo**: Interactive Gradio interface for image quality assessment
- **Space URL**: https://huggingface.co/spaces/S-Rajesh/triqa-iqa
- **Features**: Upload images, get quality scores (1-5 scale), sample images, paper links
- **Architecture**: ConvNeXt-based content-aware and quality-aware feature extraction

## 📁 File Structure

```
huggingface_demo/
├── app.py                          # Main Gradio application
├── README.md                       # Space description (Hugging Face format)
├── requirements.txt                # Python dependencies
├── package.json                    # Node.js configuration
├── convnext_original.py            # Original ConvNeXt model
├── convnext_finetune.py            # Fine-tuned ConvNeXt model
├── sample_image/                   # Sample images for testing
│   ├── 233045618.jpg
│   ├── 25239707.jpg
│   ├── 44009500.jpg
│   ├── 5129172.jpg
│   └── 85119046.jpg
├── test_demo.py                    # Local testing script
├── upload_to_space.py              # Python upload script
├── upload_with_git.sh              # Git upload script
├── QUICK_START.md                  # Quick start guide
├── UPLOAD_METHODS.md               # Upload methods documentation
├── HUGGINGFACE_SETUP.md            # Detailed setup guide
└── COMPLETE_SETUP_GUIDE.md         # This file
```

## 🚀 Step-by-Step Setup Process

### Step 1: Create Hugging Face Space

1. **Go to Hugging Face Spaces**: https://huggingface.co/spaces
2. **Click "Create new Space"**
3. **Fill in the details**:
   - **Space name**: `triqa-iqa` (or your preferred name)
   - **License**: MIT
   - **SDK**: Gradio
   - **Hardware**: CPU (or GPU if available)
   - **Visibility**: Public

### Step 2: Prepare Files

#### Core Application Files:
- `app.py` - Main Gradio application
- `README.md` - Space description (with proper metadata)
- `requirements.txt` - Python dependencies
- `package.json` - Node.js configuration

#### Model Architecture Files:
- `convnext_original.py` - Original ConvNeXt model
- `convnext_finetune.py` - Fine-tuned ConvNeXt model

#### Sample Images:
- `sample_image/` directory with 5 sample images

### Step 3: Upload Files

#### Method 1: Python CLI (Used in this project)
```bash
# Login to Hugging Face
huggingface-cli login

# Run upload script
python upload_to_space.py
```

#### Method 2: Git (Alternative)
```bash
# Clone your space
git clone https://huggingface.co/spaces/your-username/triqa-iqa
cd triqa-iqa

# Copy files
cp ../huggingface_demo/* .
cp -r ../huggingface_demo/sample_image .

# Commit and push
git add . && git commit -m "Add TRIQA demo" && git push
```

#### Method 3: Web Interface
- Go to your space on Hugging Face
- Click "Files" tab
- Drag and drop files

### Step 4: Upload Model Files

**IMPORTANT**: Model files must be uploaded separately due to size:

1. **Download from Box**: https://utexas.box.com/s/8aw6axc2lofouja65uc726lca8b1cduf
2. **Create directories** in your space:
   - `feature_models/`
   - `Regression_Models/`
3. **Upload model files**:
   - `feature_models/convnext_tiny_22k_224.pth` (170MB)
   - `feature_models/triqa_quality_aware.pth` (107MB)
   - `Regression_Models/KonIQ_scaler.save`
   - `Regression_Models/KonIQ_TRIQA.save` (111MB)

## 🔧 Troubleshooting & Solutions

### Issue 1: Short Description Too Long
**Error**: `"short_description" length must be less than or equal to 60 characters long`

**Solution**:
```yaml
# In README.md metadata
short_description: TRIQA-IQA  # 9 characters - under limit
```

**Original**: `Image Quality Assessment using ConvNeXt features` (78 characters)
**Fixed**: `TRIQA-IQA` (9 characters)

### Issue 2: Missing timm Module
**Error**: `ModuleNotFoundError: No module named 'timm'`

**Solution**: Add `timm` to requirements.txt
```txt
gradio>=4.0.0
torch>=1.8.0
torchvision>=0.9.0
timm>=0.6.0          # Added this
pillow>=8.0.0
numpy>=1.19.0
scikit-learn>=0.24.0
```

### Issue 3: Model Files Not Found
**Error**: `FileNotFoundError: [Errno 2] No such file or directory: 'feature_models/...'`

**Solution**: 
1. Download model files from Box
2. Create required directories in space
3. Upload model files to correct locations

### Issue 4: Build Failures
**Common Causes**:
- Missing dependencies in requirements.txt
- Incorrect file paths
- Syntax errors in code

**Solution**:
1. Check space logs for specific errors
2. Verify all dependencies are listed
3. Test locally first: `python app.py`

## 📝 Key Files Explained

### app.py
- **Purpose**: Main Gradio web interface
- **Key Features**:
  - Image upload interface
  - Quality prediction function
  - Sample images display
  - Paper links and citation
  - Error handling for missing models

### README.md
- **Purpose**: Space description and metadata
- **Key Sections**:
  - YAML frontmatter (title, emoji, colors, SDK)
  - Project description
  - Usage instructions
  - Model file requirements
  - Citation and paper links

### requirements.txt
- **Purpose**: Python dependencies
- **Key Dependencies**:
  - `gradio>=4.0.0` - Web interface
  - `torch>=1.8.0` - Deep learning framework
  - `timm>=0.6.0` - Model architectures
  - `scikit-learn>=0.24.0` - Regression models

### convnext_original.py & convnext_finetune.py
- **Purpose**: Model architectures
- **convnext_original.py**: Content-aware features
- **convnext_finetune.py**: Quality-aware features

## 🎯 Demo Features

### User Interface:
- **Image Upload**: Drag & drop or click to upload
- **Quality Assessment**: Click button to get score
- **Sample Images**: Pre-loaded examples for testing
- **Results Display**: Quality score (1-5 scale)
- **Paper Links**: Direct links to research papers
- **Citation**: Proper BibTeX citation

### Technical Features:
- **Multi-scale Processing**: Original + half-size images
- **Hook-based Feature Extraction**: Same as original code
- **Error Handling**: Graceful handling of missing files
- **Responsive Design**: Works on desktop and mobile

## 📊 Upload Methods Comparison

| Method | Pros | Cons | Best For |
|--------|------|------|----------|
| Python CLI | Automated, handles multiple files | Requires Python setup | Multiple files, automation |
| Git | Version control, familiar | Manual steps | Developers, version control |
| Web Interface | Simple, no setup | Manual, one file at a time | Single files, quick uploads |

## 🔍 Testing & Validation

### Local Testing:
```bash
# Test file structure
python test_demo.py

# Test app locally
python app.py
```

### Space Testing:
1. Check build logs for errors
2. Upload sample image
3. Verify quality score output
4. Test all sample images

## 📚 Dependencies & Versions

### Python Dependencies:
- `gradio>=4.0.0` - Web interface framework
- `torch>=1.8.0` - PyTorch deep learning
- `torchvision>=0.9.0` - Computer vision utilities
- `timm>=0.6.0` - Model architectures
- `pillow>=8.0.0` - Image processing
- `numpy>=1.19.0` - Numerical computing
- `scikit-learn>=0.24.0` - Machine learning

### System Requirements:
- Python 3.8+
- CUDA GPU (recommended) or CPU
- 4GB+ RAM (for model loading)

## 🚨 Common Pitfalls & Solutions

### 1. File Size Limits
- **Issue**: Model files too large for regular upload
- **Solution**: Use Git LFS or upload via web interface

### 2. Build Timeouts
- **Issue**: Space build fails due to timeout
- **Solution**: Optimize requirements, use CPU hardware

### 3. Memory Issues
- **Issue**: Out of memory during model loading
- **Solution**: Use CPU hardware, optimize model loading

### 4. Path Issues
- **Issue**: File not found errors
- **Solution**: Check file paths, verify directory structure

## 📈 Performance Optimization

### Model Loading:
- Load models once at startup
- Use `torch.no_grad()` for inference
- Clear GPU cache if needed

### Memory Management:
- Process images in batches
- Use appropriate image sizes
- Monitor memory usage

## 🔄 Maintenance & Updates

### Regular Updates:
1. Check for dependency updates
2. Test with new sample images
3. Update documentation
4. Monitor space performance

### Version Control:
- Keep track of model file versions
- Document changes in commit messages
- Test thoroughly before updates

## 📞 Support & Resources

### Documentation:
- This guide: `COMPLETE_SETUP_GUIDE.md`
- Quick start: `QUICK_START.md`
- Upload methods: `UPLOAD_METHODS.md`

### External Resources:
- Hugging Face Spaces: https://huggingface.co/spaces
- Gradio Documentation: https://gradio.app/docs/
- PyTorch Documentation: https://pytorch.org/docs/

### Contact:
- GitHub: https://github.com/rajeshsureddi/triqa
- Paper: https://arxiv.org/pdf/2507.12687

## ✅ Success Checklist

- [ ] Space created on Hugging Face
- [ ] All files uploaded successfully
- [ ] Model files uploaded to correct directories
- [ ] Build completed without errors
- [ ] Demo loads and displays interface
- [ ] Sample images work correctly
- [ ] Quality prediction works
- [ ] Paper links are accessible
- [ ] Citation is properly formatted

## 🎉 Final Result

Your TRIQA demo is now live at: **https://huggingface.co/spaces/S-Rajesh/triqa-iqa**

The demo provides:
- Interactive image quality assessment
- Professional web interface
- Academic paper integration
- Easy-to-use sample images
- Proper citation and documentation

This complete setup guide ensures that anyone can recreate and maintain the TRIQA Hugging Face demo successfully! 🚀