Upload TROUBLESHOOTING_QUICK_REFERENCE.md with huggingface_hub

TROUBLESHOOTING_QUICK_REFERENCE.md

@@ -0,0 +1,146 @@
+# TRIQA Hugging Face Demo - Quick Troubleshooting Reference
+
+## 🚨 Common Errors & Quick Fixes
+
+### 1. Short Description Too Long
+**Error**: `"short_description" length must be less than or equal to 60 characters long`
+
+**Quick Fix**:
+```yaml
+# In README.md
+short_description: TRIQA-IQA  # 9 characters
+```
+
+### 2. Missing timm Module
+**Error**: `ModuleNotFoundError: No module named 'timm'`
+
+**Quick Fix**:
+```txt
+# Add to requirements.txt
+timm>=0.6.0
+```
+
+### 3. Model Files Not Found
+**Error**: `FileNotFoundError: [Errno 2] No such file or directory: 'feature_models/...'`
+
+**Quick Fix**:
+1. Download from Box: https://utexas.box.com/s/8aw6axc2lofouja65uc726lca8b1cduf
+2. Create directories: `feature_models/` and `Regression_Models/`
+3. Upload model files to correct locations
+
+### 4. Build Failures
+**Error**: Various build errors
+
+**Quick Fix**:
+1. Check space logs
+2. Verify all dependencies in requirements.txt
+3. Test locally: `python app.py`
+
+## 📋 Essential Files Checklist
+
+### Required Files:
+- [ ] `app.py` - Main application
+- [ ] `README.md` - Space description
+- [ ] `requirements.txt` - Dependencies
+- [ ] `package.json` - Node.js config
+- [ ] `convnext_original.py` - Model architecture
+- [ ] `convnext_finetune.py` - Model architecture
+- [ ] `sample_image/` - Sample images
+
+### Model Files (Download from Box):
+- [ ] `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)
+
+## 🔧 Quick Commands
+
+### Upload Files:
+```bash
+# Python CLI
+python upload_to_space.py
+
+# Git method
+git clone https://huggingface.co/spaces/your-username/triqa-iqa
+cd triqa-iqa
+cp ../huggingface_demo/* .
+git add . && git commit -m "Add TRIQA demo" && git push
+```
+
+### Test Locally:
+```bash
+# Test file structure
+python test_demo.py
+
+# Test app
+python app.py
+```
+
+### Update Single File:
+```bash
+python -c "from huggingface_hub import HfApi; api = HfApi(); api.upload_file(path_or_fileobj='filename', path_in_repo='filename', repo_id='S-Rajesh/triqa-iqa', repo_type='space')"
+```
+
+## 📊 Requirements.txt Template
+
+```txt
+gradio>=4.0.0
+torch>=1.8.0
+torchvision>=0.9.0
+timm>=0.6.0
+pillow>=8.0.0
+numpy>=1.19.0
+scikit-learn>=0.24.0
+```
+
+## 🎯 README.md Metadata Template
+
+```yaml
+---
+title: TRIQA Image Quality Assessment
+emoji: 🖼️
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 4.0.0
+app_file: app.py
+pinned: false
+license: mit
+short_description: TRIQA-IQA
+---
+```
+
+## 🚀 Space URL Format
+
+```
+https://huggingface.co/spaces/USERNAME/SPACE-NAME
+```
+
+Example: `https://huggingface.co/spaces/S-Rajesh/triqa-iqa`
+
+## ⚡ Quick Debug Steps
+
+1. **Check build logs** in your space
+2. **Verify file paths** are correct
+3. **Test locally** before uploading
+4. **Check dependencies** in requirements.txt
+5. **Verify model files** are uploaded
+
+## 📞 Quick Links
+
+- **Space**: https://huggingface.co/spaces/S-Rajesh/triqa-iqa
+- **Box Download**: https://utexas.box.com/s/8aw6axc2lofouja65uc726lca8b1cduf
+- **GitHub**: https://github.com/rajeshsureddi/triqa
+- **Paper**: https://arxiv.org/pdf/2507.12687
+
+## ✅ Success Indicators
+
+- [ ] Space builds without errors
+- [ ] Demo interface loads
+- [ ] Sample images display
+- [ ] Quality prediction works
+- [ ] Paper links are accessible
+
+---
+
+**Remember**: Most issues are solved by checking the build logs and ensuring all dependencies are properly listed in requirements.txt! 🎯