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)

# Login to Hugging Face
huggingface-cli login

# Run upload script
python upload_to_space.py

Method 2: Git (Alternative)

# 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:

# 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

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:

# 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! 🚀