SustainableUrbanSystemsLab/Eddy3D-GAN

Eddy3D GAN Wind Prediction API

 

FastAPI service that serves the GAN surrogate model for urban pedestrian-level wind flow prediction.

Live API Endpoint: https://sustainableurbansystemslab-eddy3d-gan.hf.space

ONNX Model Hosting

The ONNX model file (GAN-21-05-2023-23-Generative.onnx, ~208 MB) is not included in this repository. The container downloads it at startup from a URL you provide.

The model is hosted on Hugging Face:

https://huggingface.co/SustainableUrbanSystemsLab/UrbanWind-GAN/resolve/main/GAN-21-05-2023-23-Generative.onnx

MODEL_URL defaults to this URL if not provided, but you can override it via environment variable.

Optional: SHA-256 Integrity Check

Generate a checksum and set MODEL_SHA256 to verify downloads:

shasum -a 256 GAN-21-05-2023-23-Generative.onnx

Local Development

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Place your model file
cp /path/to/GAN-21-05-2023-23-Generative.onnx model.onnx

# Run the server
uv run uvicorn api:app --reload --port 8000

API Endpoints

/predict.bin

Accepts a JSON body with data_b64, a base64-encoded GZip payload containing a flat float32 array of 786,432 values (3 x 512 x 512), channel-first order (R, G, B), normalised to [-1, 1].

{
  "data_b64": "H4sIA..."
}

Returns only the GZip-compressed float32 wind field as application/gzip. Response headers include X-Eddy3D-Width, X-Eddy3D-Height, and X-Eddy3D-Value-Type.

Performance Settings

ONNX Runtime thread settings are configurable:

ONNX_INTRA_OP_THREADS=8
ONNX_INTER_OP_THREADS=1
ONNX_EXECUTION_MODE=SEQUENTIAL

By default, ONNX_INTRA_OP_THREADS uses up to 8 available CPU cores.

Docker

docker build -t eddy3d-gan-api .
docker run -p 8000:8000 -e MODEL_URL="https://huggingface.co/SustainableUrbanSystemsLab/UrbanWind-GAN/resolve/main/GAN-21-05-2023-23-Generative.onnx" eddy3d-gan-api