README.md

---
title: "AngleForge: Robotic-Arm Multi-Angle Image Dataset Creator"
emoji: 📐
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.19.0
app_file: app.py
suggested_hardware: zero-a10g
pinned: false
license: cc-by-4.0
---

# 📐 AngleForge
### Robotic-Arm Multi-Angle Image Dataset Creator

Turn real-world photos into **multi-viewpoint image datasets** for
**Hugging Face Datasets** and **Edge Impulse**, using **Qwen Image Edit** to
re-render each object from new camera angles (top-down/overhead, bird's-eye,
worm's-eye, 45°/90° rotations, close-up, wide-angle, dolly moves).

A **simulated robotic arm** can call the **`grab_viewpoints` API** to pull a
series of angle images per object into a dataset — bootstrapping perception and
inspection models from real captures.

## Backends (automatic selection)

- 🖥️ **Local Qwen Image Edit** — free, runs on a CUDA GPU / ZeroGPU
  (`Qwen/Qwen-Image-Edit-2509` + `linoyts/Qwen-Image-Edit-Rapid-AIO`
  transformer + `dx8152/Qwen-Edit-2509-Multiple-angles` LoRA).
- ☁️ **HF Inference Providers** — serverless fallback, needs a Hugging Face
  token (no local GPU required).

## Robotic-arm API

The Space exposes `grab_viewpoints` for programmatic use. A robot-arm client
requests a series of viewpoints from one image:

```python
from gradio_client import Client, handle_file

client = Client("eoinedge/angleforge")  # add hf_token=... for a private Space
views = client.predict(
    handle_file("part.jpg"),
    ["top_down", "birds_eye", "rotate_left_45", "close_up"],
    1234,   # seed
    512,    # image size
    "",     # HF token (serverless backend)
    api_name="/grab_viewpoints",
)
# `views` is a list of generated viewpoint images the arm can save into a dataset.
```

## Using the Space UI

1. **Grab viewpoints** tab — upload one image, pick angles, preview the series.
2. **Build dataset** tab — add labelled classes (label + source images), pick
   angles and augmentations, then build.
3. *(Optional)* Push the dataset to a Hugging Face repo and/or upload directly
   to your Edge Impulse project.
4. Download the resulting zip.

### Space secrets (optional)

| Secret | Purpose |
|---|---|
| `HF_TOKEN` | HF token (serverless backend + pushing datasets) |
| `EDGE_IMPULSE_API_KEY` | Edge Impulse project API key |

## Command line

```bash
pip install -r requirements.txt

# input/<label>/*.jpg  ->  multi-angle dataset
python generate.py --input input --out output --hf-out hf_dataset \
  --angles top_down birds_eye rotate_left_45 close_up

# push to HF (private) + upload to Edge Impulse
python generate.py --input input \
  --push-hf-repo "username/industrial-angles" --hf-token "$HF_TOKEN" --hf-private \
  --edge-impulse-api-key "$EDGE_IMPULSE_API_KEY"
```

## Output layout

```text
output/
  edge_impulse_upload/
    training/  good_part.<id>.jpg ...
    testing/   good_part.<id>.jpg ...
  hf_imagefolder/
    train/<label>/ ...
    test/<label>/ ...
  metadata.csv
  dataset_summary.json

hf_dataset/
  train/<label>/ ...
  test/<label>/ ...
  metadata.csv
  README.md            # dataset card
```

## Notes & limitations

Synthetic multi-view images are a great **bootstrap** for robotic-arm
perception, but validate with real captures from the arm's own camera before
deployment. Verify your use of the Qwen models complies with their licenses.

## License

CC BY 4.0.