README.md

---
title: ClusterFlux
emoji: 🧬
colorFrom: blue
colorTo: indigo
sdk: gradio
app_file: app.py
pinned: false
---

# ClusterFlux: YOLO Segmentation Model Server

**ClusterFlux** is an interactive and API-ready Gradio Space for orbital streak image segmentation. It serves a YOLO-based segmentation model, with version tracking and reproducibility features for scientific workflows.

- **Model version** is shown in the UI and included in API responses.
- **Weights** are managed with Git LFS for large file support.
- **Designed for integration** with annotation tools (e.g., CVAT) and downstream astronomical data pipelines.

## Quickstart

1. Install dependencies:

```bash
pip install -r requirements.txt
```

2. Run the server locally:

```bash
python app.py
```

3. Deploy to [Hugging Face Spaces](https://huggingface.co/spaces):
   - Push this directory to a new Space as a Gradio app.
   - If you update dependencies, restart the Space from the web UI to ensure a clean rebuild.

## Usage

- Upload an image to receive a segmentation mask generated by the latest YOLO model.
- The current model version is always visible for traceability.
- For programmatic access, use the Gradio API endpoint; the response includes both the mask and version.

## Deployment Workflow

- Model weights are copied into `weights/best.pt` and versioned via the `VERSION` file.
- `deploy.sh` automates model update and Hugging Face Space deployment, with Git LFS support.

## Integration
- The API will accept an image and return a segmentation mask (as an image) and the model version as a string.
- For annotation tool integration (e.g., CVAT), see the [NOTES.md](../NOTES.md) for design decisions and API tips.

## Notes
- Add any additional dependencies to `requirements.txt` as needed.
- For Spaces, ensure your model weights are included or downloadable (Git LFS required for files >10MB).
- If you change requirements.txt, restart the Space from the Hugging Face UI ("Restart from Scratch") to ensure dependency updates are applied.

## Citation & Context

This tool is part of the Swinburne DECam synthetic data and orbital streak segmentation research project. For scientific use, please cite appropriately and refer to the project thesis and [NOTES.md](../NOTES.md) for detailed methodology and rationale.

---

For more details, see the [Hugging Face Spaces config reference](https://huggingface.co/docs/hub/spaces-config-reference).