README.md

---
title: Trace Visualizer
emoji: 🐢
colorFrom: green
colorTo: red
sdk: gradio
sdk_version: 6.5.1
app_file: app.py
pinned: false
---

# Trace Model Visualizer

Gradio app for visualizing trace/trajectory predictions from [mihirgrao/trace-model](https://huggingface.co/mihirgrao/trace-model).

## Features

- **Image input**: Upload an image
- **Trace prediction**: Model predicts trajectory points from the image
- **Visual overlay**: Trace is overlaid on the image with gradient coloring (green start → red end)
- **Coordinate output**: Predicted trace points are printed below

## Installation

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

## Usage

### Gradio app

```bash
python app.py
```

Then open the URL (default: http://localhost:7860).

1. Click **Load Model** to load the trace model (first run downloads from Hugging Face)
2. Upload an image and optionally enter a task instruction (e.g. "Pick up the red block")
3. Click **Run Inference**
4. View the overlay image and predicted trace points

### Eval server

Run a FastAPI server for batch evaluation (e.g. from scripts or the Gradio app):

```bash
python eval_server.py --model-id mihirgrao/trace-model --port 8001
```

Endpoints:
- `POST /predict` – single image + instruction
- `POST /predict_batch` – batch of `{image_path?|image_base64?, instruction}` samples
- `GET /health`, `GET /model_info`

### CLI script

```bash
python predict_trace.py image.png
python predict_trace.py image.png -i "Pick up the red block"
python predict_trace.py image.png -o output_trace.png -i "Stack the cube on the block"
python predict_trace.py image.png -o output.png -m mihirgrao/trace-model
```

- `image` – Path to input image
- `-i, --instruction` – Task / language instruction (e.g. "Pick up the red block")
- `-o, --output` – Where to save the overlay (default: `<image>_trace.png`)
- `-m, --model-id` – Model ID (default: mihirgrao/trace-model)
- `-p, --prompt` – Full prompt override (if set, ignores `-i`)