# Deploying Oculus Server to HuggingFace Spaces

This guide explains how to deploy the Oculus Server application to HuggingFace Spaces.

## Step 1: Prepare for Deployment

1. Create a HuggingFace account at [huggingface.co](https://huggingface.co) if you don't have one already
2. Install the Hugging Face CLI tool:
   ```bash
   pip install huggingface_hub
   ```
3. Login to HuggingFace:
   ```bash
   huggingface-cli login
   ```

## Step 2: Create Required Files

### Create `app.py`

Create a new file called `app.py` in the root directory with the following content:

```python
import gradio as gr
from modules.element_processing import process_screenshot
from modules.element_detector import initialize_models
import asyncio
import io
import os
import numpy as np
from PIL import Image

# Initialize models on startup
async def init():
    await initialize_models()

loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
loop.run_until_complete(init())

# Create a mock background tasks class
class MockBackgroundTasks:
    def add_task(self, *args, **kwargs):
        pass

# Define interface
def process_image(image):
    # Convert image to bytes
    img_byte_arr = io.BytesIO()
    image.save(img_byte_arr, format='PNG')
    image_data = img_byte_arr.getvalue()
    
    # Process the screenshot
    background_tasks = MockBackgroundTasks()
    elements, image_path = loop.run_until_complete(
        process_screenshot(image_data, background_tasks)
    )
    
    # Format output
    result_text = "\n".join([
        f"icon {element['code']}: {{"
        f"'type': '{element['type']}', "
        f"'centerX': {element['center_x']}, "
        f"'centerY': {element['center_y']}, "
        f"'content': '{element.get('text_content', element.get('object_label', ''))}'}}"
        for element in elements
    ])
    
    # Load annotated image
    annotated_img = None
    if image_path and os.path.exists(image_path):
        annotated_img = Image.open(image_path)
    
    return annotated_img, result_text

# Create interface
demo = gr.Interface(
    fn=process_image,
    inputs=gr.Image(type="pil"),
    outputs=[
        gr.Image(type="pil", label="Annotated Image"),
        gr.Textbox(label="Detected Elements")
    ],
    title="UI Element Detection",
    description="Upload a screenshot to detect UI elements"
)

# Launch the app
demo.launch()
```

### Update requirements.txt

Update the `requirements.txt` file to include Gradio and other necessary dependencies:

```
fastapi==0.110.0
uvicorn==0.27.1
pydantic==2.6.3
pillow==10.2.0
opencv-python==4.9.0.80
easyocr==1.7.2
ultralytics==8.3.97
numpy<2
gradio>=4.0.0
```

## Step 3: Configure Environment

1. Create a `.env` file in the root directory with essential configuration:
   ```
   OCR_BACKEND=easyocr
   ANNOTATION_DIR=annotated
   FONT_SIZE=24
   JPEG_QUALITY=85
   ```

2. Ensure the `annotated` directory exists:
   ```bash
   mkdir -p annotated
   ```

## Step 4: Set Up the Model Weights

1. Make sure your YOLOv8 model weights are included in the repository
2. If using Git LFS, add a `.gitattributes` file to track large model files:
   ```
   weights/*.pt filter=lfs diff=lfs merge=lfs -text
   ```

## Step 5: Create a HuggingFace Space

1. Create a new Space on HuggingFace:
   ```bash
   huggingface-cli repo create oculus-ui-detector --type space
   ```

2. Clone the newly created Space:
   ```bash
   git clone https://huggingface.co/spaces/YOUR_USERNAME/oculus-ui-detector
   ```

3. Add all your files to the Space:
   ```bash
   cp -R . /path/to/oculus-ui-detector
   cd /path/to/oculus-ui-detector
   ```

4. Commit and push your changes:
   ```bash
   git add .
   git commit -m "Initial commit"
   git push
   ```

## Step 6: Configure the Space

Visit your Space on HuggingFace and:

1. Set the SDK to "Gradio"
2. Set the Space hardware (recommended: GPU enabled)
3. Add any required Secrets in the Settings tab if you're using Google OCR or other services requiring API keys

## Step 7: API Access

The Gradio interface has API access enabled. There are two ways to access your app via API:

### Option 1: Using Gradio's Client API

You can interact with your app programmatically using the Gradio client:

```python
import gradio as gr

# Connect to your HuggingFace Space
client = gr.Client("https://huggingface.co/spaces/YOUR_USERNAME/oculus-ui-detector")

# Call the function with a data URI
result = client.predict(
    "data:image/png;base64,YOUR_BASE64_DATA_HERE",  # data_uri
    api_name="/process_image_data_uri"
)

# Or upload an image directly
with open("screenshot.png", "rb") as f:
    result = client.predict(
        f,  # image file
        api_name="/process_image_upload"
    )

print(result)
```

### Option 2: Using REST API

You can also use the REST API directly:

```python
import requests
import json
import base64

# For data URI endpoint
url = "https://YOUR_USERNAME-oculus-ui-detector.hf.space/api/process_image_data_uri"

# Read and encode image to base64
with open("screenshot.png", "rb") as image_file:
    encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
    data_uri = f"data:image/png;base64,{encoded_string}"

# Make the API request
response = requests.post(
    url,
    json={"data": [data_uri]}
)

print(json.loads(response.content)["data"])
```

### API Documentation

The API endpoints will be automatically documented at:
- https://YOUR_USERNAME-oculus-ui-detector.hf.space/docs

This documentation shows all available API endpoints and their parameters.

## Step 7: Deployment Options

HuggingFace Spaces provides several deployment options:

1. **Basic Deployment**: The app will be built automatically when you push to the repository
2. **Docker Deployment**: For advanced configuration, you can use a Dockerfile to customize the environment
3. **Custom Domain**: Connect your Space to a custom domain in the Settings tab

## Troubleshooting

If you encounter issues during deployment:

1. Check the Space logs for error messages
2. Ensure all dependencies are correctly specified
3. Verify model files are correctly uploaded
4. Make sure the `annotated` directory is properly configured

For model size issues:

1. Consider using `huggingface_hub` to download your models on startup
2. Use a smaller version of the model
3. Use model quantization to reduce size

## Additional Resources

- [HuggingFace Spaces Documentation](https://huggingface.co/docs/hub/spaces)
- [Gradio Documentation](https://www.gradio.app/docs/)
- [Git LFS Documentation](https://git-lfs.github.com/)