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](https://huggingface.co/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)
```bash
# 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](https://console.cloud.google.com/storage/browser/gresearch/maxim/ckpt/)

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