# examples/python-consumer

Reference Python consumer для cuframes через `ctypes` wrapper.

## Use case

AI/ML pipeline (PyTorch / ONNX / TensorRT) которому нужны декодированные кадры
с камер. Без cuframes — каждый Python скрипт открывает RTSP + decode сам.
С cuframes — подписывается на готовые NV12 frames от publisher'а.

## Запуск

```bash
# Publisher должен быть запущен (см. tools/cuframes-rtsp-source или Docker image)
cuframes-rtsp-source --rtsp rtsp://admin:pw@cam-ip:554/... --key cam-parking &

# Consumer (same host, либо same docker namespace — см. требования ниже)
python3 cuframes_consumer.py --key cam-parking --max-frames 100
```

Ожидаемый output:
```
[consumer] connected to 'cam-parking'
[consumer] first frame: 640x480 NV12, pitch_y=640, pitch_uv=640, cuda_ptr=0x...
[consumer] received=25 seq=42 pts_ms=...
...
=== RESULT ===
received: 100 / 100
elapsed: 3.96s
avg_fps: 25.03
```

## Что этот пример НЕ делает

- **НЕ копирует** GPU NV12 frame на host — `cuda_ptr` это raw CUDA device pointer.
  Для реальной работы нужно:
  - `pycuda` / `cupy` / `cuda-python` библиотека для CUDA memcpy
  - либо передать `cuda_ptr` напрямую в GPU-aware ML framework (PyTorch's
    `torch.cuda.IntTensor.from_dlpack` etc.)

- **НЕ конвертирует** NV12 → RGB. Используй `cv2.cvtColor(nv12, cv2.COLOR_YUV2RGB_NV12)`
  на host или GPU-side conversion.

- **НЕ обрабатывает** inference — это skeleton, в твоём pipeline replace
  comment-block `### ВАШ ML PIPELINE ЗДЕСЬ ###` с актуальным кодом.

## Требования

| | Значение |
|---|---|
| Python | 3.8+ |
| `libcuframes.so.0` | в `LD_LIBRARY_PATH` (либо `/usr/local/lib`) |
| Publisher running | да, с matching `--key` |
| Same IPC namespace | да (host либо `ipc:container:<publisher>` в docker) |
| Same PID namespace | да (host либо `pid:container:<publisher>` в docker) |
| NVIDIA GPU + driver | для access `cuda_ptr` (read-only frame от publisher'а) |

## Docker-style

```yaml
# В compose рядом с publisher service
ai-pipeline:
  image: your-ai-image:cuda
  runtime: nvidia
  ipc: "container:cuframes-pub-parking"
  pid: "container:cuframes-pub-parking"
  volumes:
    - cuframes_sock:/run/cuframes:ro
  environment:
    LD_LIBRARY_PATH: /usr/local/lib
  command: python3 /app/cuframes_consumer.py --key cam-parking --max-frames 1000000
```

## v0.3 → first-class pybind11 bindings

Текущий ctypes pattern будет заменён на native pybind11 bindings в v0.3 cuframes
([ROADMAP.md](../../ROADMAP.md)). Тогда API будет более pythonic + zero-copy через
`__cuda_array_interface__` / `dlpack`.