README.md

---
title: BASILISC Texture Worker
emoji: 🐉
colorFrom: gray
colorTo: purple
sdk: gradio
sdk_version: 5.49.1
python_version: 3.10.13
app_file: app.py
pinned: false
license: apache-2.0
short_description: Reference-image 3D texturing for BASILISC
models:
  - huanngzh/mv-adapter
  - stabilityai/stable-diffusion-xl-base-1.0
  - madebyollin/sdxl-vae-fp16-fix
  - ZhengPeng7/BiRefNet
---

# BASILISC Texture Worker

ZeroGPU backend for **BASILISC Auto Materialer**.

**v1.0.5:** simplified Space builds by moving the pinned MV-Adapter source fetch to runtime; this avoids pip resolving the entire upstream Git repository during the image build.

It accepts an existing GLB mesh plus one reference image and returns a textured GLB using the open-source MV-Adapter image+geometry pipeline.

## Required Space setting

After creating/uploading this Space, open **Settings → Hardware** and select **ZeroGPU**.

The Blender add-on talks to the named Gradio API endpoint:

`/basilisc_texture`

## Attribution

This worker builds on MV-Adapter by Zehuan Huang et al. The upstream project is Apache-2.0 licensed. See `NOTICE.md`.

## One-command deployment from Linux

1. Create a Hugging Face **write** token.
2. Unzip this bundle.
3. In a terminal inside the folder, run:

```bash
bash deploy.sh YOUR_HF_USERNAME/BASILISC-Texture-Worker
```

The script securely prompts for your Hugging Face write token, creates a private deployment virtual environment inside this folder, installs the deployment client there, creates/updates the Gradio Space, uploads the worker files, and requests the `zero-a10g` (ZeroGPU) hardware flavor. It does not modify Linux Mint's system Python. If `python3-venv` is missing, the script will tell you exactly which `apt` command to run. If your account requires the hardware choice to be confirmed in the UI, open the Space's Settings page and select **ZeroGPU** there.

## Deployment troubleshooting

The deployment script validates the token before creating or uploading anything. It prints the authenticated Hugging Face username so you can verify that the repository namespace matches the account associated with the token. A Hugging Face User Access Token with **Write** permission is required to create or update the Space.


## Deployment security

The deployment token is read only from the process environment. v1.0.5 uploads an explicit allow-list of runtime files and performs a local token-pattern scan before any upload. Deployment scripts, virtual environments, logs, and other local files are never uploaded.


## ZeroGPU quota behavior

The worker uses dynamic GPU reservations instead of reserving five minutes for every call:

- Draft (15 steps / 1K): 115 seconds
- Standard (25 steps / 2K): 210 seconds
- Final (35 steps / 4K): 285 seconds

Draft can fit within the current anonymous ZeroGPU allowance. Standard and Final should be called with an authenticated Hugging Face token. The scheduler checks the declared reservation against the caller's remaining quota before the job starts.