src/sharp/web/README.md

SHARP Web: Frontend (Gradio) + Backend (FastAPI)

This directory provides a separated deployment:

• Backend API (api_server.py) runs on a GPU cloud with FastAPI
• Frontend UI (app.py) runs on Hugging Face Spaces with Gradio

The UI calls the API via HTTP; the API performs model inference and returns PLY results.

Repository Layout

• src/sharp/web/api_server.py — FastAPI backend hosting inference endpoints
• src/sharp/web/app.py — Gradio frontend calling the backend
• requirements_api.txt — Backend dependencies (GPU cloud)
• requirements.txt — Frontend dependencies (HF Spaces)

Backend (GPU Cloud)

Install

On your GPU cloud instance:

# From repository root
pip install -r requirements_api.txt

Notes:

• Ensure CUDA is available if using NVIDIA GPUs. The Torch version in requirements_api.txt is compiled for CUDA 12 on Linux.
• On macOS, MPS (Apple Silicon) may be detected; otherwise CPU fallback is used.

Run

From repository root:

python src/sharp/web/api_server.py

or with Uvicorn:

uvicorn src.sharp.web.api_server:app --host 0.0.0.0 --port 8000

Endpoints

• GET /health — Basic health check, device info, and model-loaded flag
• POST /predict — Multipart upload of one or more images (files field); returns JSON with per-image metadata and PLY contents base64-encoded
• POST /predict/download — Multipart upload of one or more images; returns a ZIP stream containing PLY files

CORS is enabled by default to allow calls from the Hugging Face Space. For production, set allow_origins to your specific Space domain.

Frontend (Hugging Face Spaces)

Install

On HF Spaces:

pip install -r requirements.txt

This installs only Gradio and Requests.

Configure

Set environment variable API_BASE_URL in your Space to point to the public backend URL, for example:

API_BASE_URL=https://your-api.example.com

If running locally for testing, API_BASE_URL defaults to http://localhost:8000.

Run

Locally:

python src/sharp/web/app.py

Gradio will start on port 7860 by default (configured to 0.0.0.0 in the script).

On HF Spaces, simply setting the Space’s “Run” command to python src/sharp/web/app.py is sufficient.

Usage (Frontend)

• Single Image tab: upload one image and click Predict to download its PLY.
• Batch tab: upload multiple images and click Predict Batch to download a ZIP containing PLY files.
• The frontend calls the backend POST /predict and assembles results for user download.

Quick Local Test

1. Start backend:

   uvicorn src.sharp.web.api_server:app --host 0.0.0.0 --port 8000
   

2. Start frontend (in another terminal):

   API_BASE_URL=http://localhost:8000 python src/sharp/web/app.py
   

3. Open the Gradio UI (http://localhost:7860), upload images, and verify outputs.

Notes & Troubleshooting

• If imports like fastapi or gradio show unresolved in your IDE, ensure the correct environment is selected and dependencies installed via the respective requirements file.
• Network access from HF Spaces to the GPU API must be allowed; ensure your API endpoint is accessible over HTTPS where possible.
• For security, consider locking down CORS to your Space origin and adding authentication (e.g., an API key header) if needed.