SETUP_HF_SPACE.md

Setting up MAXIM as a Hugging Face Space

This guide will help you convert this MAXIM repository into a Hugging Face Space.

Files Created for Hugging Face Space

The following files have been created for the Hugging Face Space:

1. app.py - Main Gradio application file
2. requirements_hf.txt - Dependencies for the Space (rename to requirements.txt when uploading)
3. README_hf.md - Space documentation (rename to README.md when uploading)

Setup Instructions

Step 1: Create a New Hugging Face Space

1. Go to Hugging Face Spaces
2. Click "Create new Space"
3. Choose a name for your Space (e.g., "maxim-image-processing")
4. Select "Gradio" as the SDK
5. Choose "Public" or "Private" visibility
6. Click "Create Space"

Step 2: Upload Files

You have two options:

Option A: Git Upload (Recommended)

# Clone your new space
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# Copy files from this repository
cp /path/to/maxim/app.py .
cp /path/to/maxim/requirements_hf.txt requirements.txt
cp /path/to/maxim/README_hf.md README.md

# Copy the maxim module
cp -r /path/to/maxim/maxim .

# Copy example images (optional)
cp -r /path/to/maxim/maxim/images .

# Add, commit and push
git add .
git commit -m "Initial commit: MAXIM image processing space"
git push

Option B: Web Interface Upload

1. Upload app.py to the root of your Space
2. Rename and upload requirements_hf.txt as requirements.txt
3. Rename and upload README_hf.md as README.md
4. Upload the entire maxim/ folder
5. Optionally upload the maxim/images/ folder for examples

Step 3: Configure Space Settings

In your Space settings:

1. Hardware: Start with CPU. You may need to upgrade to GPU for faster inference
2. Timeout: Set to 30-60 seconds depending on expected processing time
3. Environment Variables: None required for basic setup

Step 4: Model Checkpoints

The app is configured to automatically download model checkpoints. However, for better performance:

1. Pre-download checkpoints and upload them to your Space
2. Update the MODELS dictionary in app.py to point to local files instead of URLs
3. This will reduce startup time and provide more reliable access

Model Checkpoint URLs

The main checkpoints you'll need:

• Enhancement (Retouching): https://drive.google.com/uc?id=1-BRKozXh81PtwoMZ9QN3kCAieLzozHIq
• Other models: Available at Google Cloud Storage

Step 5: Test Your Space

1. Once uploaded, your Space will automatically build and deploy
2. Test with the provided example images
3. Try uploading your own images
4. Verify all model types work correctly

Customization Options

Adding More Models

To add more MAXIM model variants:

1. Add entries to the MODELS dictionary in app.py
2. Download the corresponding checkpoints
3. Update the dropdown choices in the Gradio interface

Improving Performance

• Pre-download and include model checkpoints in the Space
• Use GPU hardware for faster inference
• Implement model caching to avoid reloading
• Add progress bars for long-running operations

UI Improvements

• Add model descriptions and use cases
• Include before/after comparisons
• Add image quality metrics display
• Implement batch processing for multiple images

Troubleshooting

Common Issues:

1. Memory errors: Upgrade to higher memory hardware
2. Timeout errors: Increase timeout settings or optimize model loading
3. Dependency conflicts: Check that all versions in requirements.txt are compatible
4. Model download failures: Pre-upload checkpoints to avoid download issues

Debug Tips:

• Check the Space logs for detailed error messages
• Test locally with gradio app.py before uploading
• Start with one model type and gradually add more
• Use smaller test images initially

Example Usage

After setup, users can:

1. Upload images in common formats (PNG, JPG, etc.)
2. Select from available image processing tasks
3. View processed results side-by-side with originals
4. Download enhanced images

The Space will handle all the preprocessing, model inference, and postprocessing automatically.