Metadata-Version: 2.4
Name: djhudpicam
Version: 0.1.4
Summary: DJ HUD headless/Pi camera source node for the DJ HUD collective
License: MIT
Requires-Python: >=3.9
Requires-Dist: aiohttp
Requires-Dist: numpy
Requires-Dist: opencv-python
Requires-Dist: pillow
Provides-Extra: all
Requires-Dist: aiortc; extra == 'all'
Requires-Dist: picamera2; extra == 'all'
Requires-Dist: pyvirtualcam; extra == 'all'
Provides-Extra: pi
Requires-Dist: picamera2; extra == 'pi'
Provides-Extra: vdo
Requires-Dist: aiortc; extra == 'vdo'
Provides-Extra: virtualcam
Requires-Dist: pyvirtualcam; extra == 'virtualcam'
Description-Content-Type: text/markdown

# djhud-pi

**Pi Zero 2 W camera source node for the DJ HUD collective.**

Points a Pi Camera at a screen (laptop, CDJ display, mixer) and streams
cropped / perspective-corrected regions to the main DJ HUD app over the
WireGuard VPN — or directly to VDO.Ninja / a virtual camera device.

---

## Architecture

```
Pi Camera (picamera2)
    │
    ▼
CameraCapture  ──►  RegionSet (per-region perspective de-warp via OpenCV)
                         │
                         ▼
                   HUD Strip (numpy composite, 1280×100)
                         │
              ┌──────────┼──────────┐
              ▼          ▼          ▼
         VPN WebSocket  VDO.Ninja  Virtual Cam
         (aiohttp)      (aiortc)   (pyvirtualcam)
              │
              ▼
        Main DJ HUD app
        (StreamClient receiver — ws://10.66.66.x:8765/stream)
```

---

## Install

```bash
# On a Pi Zero 2 W with Raspberry Pi OS (Bookworm)
pip install djhud-pi

# With Pi Camera support
pip install "djhud-pi[pi]"

# Everything
pip install "djhud-pi[all]"
```

### System dependencies (Pi)

```bash
sudo apt install python3-tk python3-opencv libatlas-base-dev
sudo apt install python3-picamera2   # or: pip install picamera2
# For virtual camera output:
sudo modprobe v4l2loopback
```

---

## Run

```bash
djhudpi
# or
python -m djhudpi
```

---

## Workflow

1. **Start Camera** — select resolution & FPS, click ▶ Start Camera
2. **Add Regions** — click `+ Add`, name your region
3. **Place crop** — click in the preview to set crop origin, edit W/H in Edit dialog
4. **Perspective correction** — select a region, click `📐 Pick Warp Corners`,
   then click the 4 corners of the screen/display in the preview (TL→TR→BR→BL).
   Drag dots to fine-tune. Click Apply.
5. **Enable output** — tick VPN WebSocket Stream, enter your VPN port.
   The stream URL (e.g. `ws://10.66.66.3:8765/stream`) appears — paste it
   into the main DJ HUD app's StreamClient source field.
6. Config auto-saves on close to `~/.djhudpi_config.json`.

---

## Perspective de-warp

When pointing the Pi Camera at a screen at an angle, use **Pick Warp Corners**
to click the 4 corners of the screen content area. djhud-pi computes a
homography (`cv2.findHomography`) and `cv2.warpPerspective` to produce a
flat, front-on crop regardless of camera angle.

---

## Outputs

| Output | Protocol | Notes |
|--------|----------|-------|
| VPN WebSocket | JPEG over WS (aiohttp) | Matches main DJ HUD `StreamClient` |
| VDO.Ninja | WebRTC (aiortc) | Stub — port `vdoninja_client.py` from main app |
| Virtual Camera | v4l2loopback + pyvirtualcam | Use as webcam source in OBS/browser |

---

## File structure

```
src/djhudpi/
├── __init__.py       version
├── __main__.py       entry point
├── app.py            tkinter GUI
├── camera.py         picamera2 / OpenCV capture
├── region.py         Region model + perspective warp + composite
├── warp_picker.py    4-corner picker dialog
└── output.py         VPN stream / VDO.Ninja / virtual cam backends
```

---

## Development / testing on non-Pi hardware

Falls back to OpenCV `VideoCapture` automatically when `picamera2` is not
available, so you can develop and test on your Mac or Windows machine with
a regular webcam.

```bash
pip install "djhud-pi"   # no [pi] extra needed on non-Pi
djhudpi
```
