# Stan projektu po sesji: UVC controls + przebudowa menu formatu

## Kontekst

Aplikacja uruchomiona na docelowym Mac Mini. Kamera ELP dostarcza klatki w formacie NV12 (przez backend AVFoundation). Stare menu z osobnymi podmenu `Resolution` i `FPS` nie nadawało się do użycia — kamera eksponuje formaty jako kombinacje (rozdzielczość + fps + pixel format), a ich niezależne ustawianie dawało nieskoordynowane wyniki.

Dodano też interfejs do kontroli parametrów obrazu kamery.

---

## Zmiany w tej sesji

### 1. Menu formatu — przebudowane (`app/ui/menu_bar.py`)

**Przed:** dwa osobne podmenu — `Video → Resolution` i `Video → FPS`.

**Po:** jedno podmenu `Video → Resolution` z pozycjami reprezentującymi pełny format:

```
1920×1080 @ 30fps (NV12)
1920×1080 @ 30fps (MJPG)
1280×720 @ 30fps (NV12)
1280×720 @ 5fps (YUY2)
640×480 @ 30fps (MJPG)
...
```

Każda pozycja odpowiada dokładnie jednemu `CameraFormat` z `CameraInfo.formats`. Kolejność odzwierciedla sortowanie z `CameraEnumerator` (największa powierzchnia → najwyższe fps).

**Sygnały:**

- Usunięto: `resolution_selected(int, int)`, `fps_selected(float)`
- Dodano: `format_selected(CameraFormat)` — emituje pełny obiekt formatu
- Dodano: `camera_settings_requested()` — otwiera dialog ustawień

**Metody publiczne:**

- `populate_formats(camera_info)` — zamiast `populate_resolutions` + `populate_fps`
- `set_active_format(fmt)` — zaznacza aktywny format po zmianie (matching po w/h/fps/pixel_format)
- Usunięto: `set_console_level()` (przeniesione do wewnętrznego `_on_log_toggled`)

**Nowe menu `Image`:**

```
Image
  └── Camera Settings…   → otwiera CameraSettingsDialog
```

---

### 2. CameraService — `set_format()` (`app/camera/camera_service.py`)

**Przed:** dwie metody `set_resolution(w, h)` i `set_fps(fps)` przechowujące `_desired_width`, `_desired_height`, `_desired_fps` osobno.

**Po:** jedna metoda `set_format(fmt: CameraFormat)` przechowująca `_desired_fmt: CameraFormat | None`.

```python
def set_format(self, fmt: CameraFormat) -> None:
    self._desired_fmt = fmt
    if self._current_info is not None:
        self.start(self._current_info)   # stop+start jak poprzednio
```

**Scoring przy wyborze formatu Qt (`_apply_format`):**

Poprzednio scoringował tylko rozdzielczość i fps. Teraz uwzględnia też pixel format:

```python
exact_res  = int(w == desired.width and h == desired.height) * 1000
exact_pf   = int(pf == desired.pixel_format) * 500
exact_fps  = int(abs(f - desired.max_fps) < 0.5) * 100
area_diff  = abs(w * h - desired.width * desired.height)
score      = exact_res + exact_pf + exact_fps - area_diff
```

Pixel format jest drugim co do ważności kryterium (po rozdzielczości, przed fps).

**Nowa właściwość:**

```python
@property
def qt_camera(self) -> QCamera | None:
    ...
```

Udostępnia wewnętrzny `QCamera` dla `CameraSettingsDialog` (potrzebny do ustawiania WB i exposure przez Qt API).

**Poprawione logowanie:**

`_log_actual_format()` loguje teraz ostrzeżenia zarówno dla FPS jak i rozdzielczości jeśli kamera nie dostarczyła tego co było żądane.

---

### 3. Warstwa UVC (`app/camera/uvc/`)

Nowy pakiet z abstrakcją dla sterowania parametrami obrazu przez UVC (USB Video Class).

#### Dlaczego osobna warstwa, nie Qt?

`QCamera.Feature` w Qt6 obejmuje: `ColorTemperature`, `ExposureCompensation`, `IsoSensitivity`, `ManualExposureTime`, `CustomFocusPoint`, `FocusDistance`. **Nie obejmuje** brightness, contrast, saturation, hue, sharpness, gamma, backlight compensation — są to niskopoziomowe UVC/V4L2 controls poza zakresem Qt Multimedia.

Sterowanie nimi wymaga osobnych bibliotek natywnych, innych na każdej platformie.

#### Dostępne biblioteki

| Biblioteka | Platforma | Instalacja | Uwagi |
|---|---|---|---|
| `duvc-ctl` | Windows only | `pip install duvc-ctl` | DirectShow, stabilna, PyPI, MIT |
| `pyuvc` | macOS + Linux | `brew install libusb jpeg-turbo && pip install pyuvc` | libuvc bindings, wymaga kompilacji |
| `uvc-py` | macOS + Linux (Win w planie) | `pip install uvc-py` | dev/alpha, brak UVC controls |

#### Struktura

```
app/camera/uvc/
├── __init__.py      # make_uvc_controller(name) — factory z detekcją platformy
├── base.py          # UvcControllerBase ABC, UvcParam enum, UvcParamInfo dataclass
├── stub.py          # NullUvcController — no-op fallback
├── windows.py       # WindowsUvcController — duvc-ctl (DirectShow)
└── macos.py         # MacUvcController — pyuvc (libuvc)
```

#### `UvcParam` enum

```python
class UvcParam(Enum):
    BRIGHTNESS
    CONTRAST
    SATURATION
    HUE
    SHARPNESS
    GAMMA
    WHITE_BALANCE
    BACKLIGHT_COMPENSATION
    EXPOSURE
```

#### `UvcParamInfo` dataclass

```python
@dataclass
class UvcParamInfo:
    param: UvcParam
    supported: bool
    minimum: int = 0
    maximum: int = 100
    default: int = 50
    current: int = 50
    step: int = 1
    auto_supported: bool = False
    auto_enabled: bool = False
```

#### `UvcControllerBase` ABC — interfejs

```python
def open(self, device_name: str) -> bool     # otwiera uchwyt do urządzenia
def close(self) -> None
def is_open(self) -> bool
def get_param_info(self, param: UvcParam) -> UvcParamInfo
def get_all_params(self) -> list[UvcParamInfo]
def set_value(self, param: UvcParam, value: int) -> bool
def set_auto(self, param: UvcParam, enabled: bool) -> bool
```

#### `make_uvc_controller(device_name)` — factory

Detekcja platformy w runtime:

```python
if system == "Windows":
    → WindowsUvcController (duvc-ctl)
elif system == "Darwin":
    → MacUvcController (pyuvc)
else:
    → NullUvcController
```

Jeśli biblioteka nie jest zainstalowana — `ImportError` przechwycony, fallback na `NullUvcController`. Loguje `WARNING` z instrukcją instalacji.

#### `WindowsUvcController` — szczegóły

- Łączy się z pierwszym urządzeniem którego nazwa zawiera `device_name` (case-insensitive)
- Mapowanie `UvcParam → duvc-ctl VidProp/CamProp` string:
  - `BRIGHTNESS → "brightness"`, `CONTRAST → "contrast"`, ..., `EXPOSURE → "exposure"`
- `set_auto()` używa `duvc.CamMode.AUTO/MANUAL`
- `_refresh_supported()` odpytuje `cam.get_supported_properties()` po otwarciu

#### `MacUvcController` — szczegóły

- Używa `uvc.device_list()` do wyszukania urządzenia po nazwie
- Otwiera przez `uvc.Capture(uid)`
- Mapowanie `UvcParam → pyuvc display_name` string:
  - `WHITE_BALANCE → "White Balance temperature"`, `EXPOSURE → "Absolute Exposure Time"`, itd.
- `auto_mode` via `ctrl.auto_mode` (atrybut pyuvc control)

---

### 4. CameraSettingsDialog (`app/ui/camera_settings_dialog.py`)

`QDialog` ze scrollowaną zawartością, dwoma sekcjami. Zmiany aplikowane **na żywo** (brak OK/Apply — tylko Close).

#### Sekcja Qt Camera Controls

| Kontrolka | Widget | Akcja |
|---|---|---|
| White Balance | `QComboBox` (8 trybów + Manual) | `camera.setWhiteBalanceMode()` |
| Colour Temp (K) | `QSpinBox` 2000–10000, krok 100 | `camera.setColorTemperature()` — widoczny tylko w trybie Manual |
| Exposure Mode | `QComboBox` (Auto / Manual) | `camera.setExposureMode()` |
| Exposure Time (s) | `QDoubleSpinBox`, 6 miejsc po przecinku | `camera.setManualExposureTime()` — widoczny tylko w trybie Manual |

Dynamiczna widoczność: pola `Colour Temp` i `Exposure Time` pojawiają się tylko gdy wybrano tryb Manual.

Tryby WB sprawdzane przez `camera.isWhiteBalanceModeSupported()` przed aplikacją — jeśli kamera nie obsługuje trybu, zmiana jest ignorowana (logowane DEBUG).

#### Sekcja UVC Camera Controls

Dla każdego `UvcParam`:

- Jeśli `supported=False`: wyświetla "Not supported" (disabled)
- Jeśli `supported=True`: `QSlider` + `QSpinBox` zsynchronizowane dwukierunkowo
- Jeśli `auto_supported=True`: dodatkowy `QCheckBox "Auto"` — po zaznaczeniu blokuje slider i spinbox

Jeśli `NullUvcController` (żadne kontrolki nieobsługiwane): sekcja wyświetla notatkę:

```
UVC controls not available.
Install duvc-ctl (Windows) or pyuvc (macOS) to enable.
```

---

### 5. MainWindow — aktualizacje (`app/ui/main_window.py`)

**Nowe pola:**

```python
self._uvc: UvcControllerBase = NullUvcController()
```

**Nowe metody:**

- `_open_uvc(cam)` — zamyka poprzedni UVC controller i otwiera nowy dla wybranej kamery
- `_on_format_selected(fmt)` → `camera_service.set_format(fmt)`
- `_on_settings_requested()` → tworzy `CameraSettingsDialog(qt_camera, uvc)` i wywołuje `.exec()`

**Zmiany w `_wire_signals()`:**

- Usunięto: `menu.resolution_selected`, `menu.fps_selected`
- Dodano: `menu.format_selected → _on_format_selected`
- Dodano: `menu.camera_settings_requested → _on_settings_requested`

**`closeEvent`:**

- Dodano: `self._uvc.close()` jeśli `is_open()`

---

### 6. Testy (`tests/test_uvc.py`) — nowy plik, 15 testów

| Klasa testowa | Co testuje |
|---|---|
| `TestNullUvcController` | `open` → False, `is_open` → False, `close` bez wyjątku, `get_param_info` → unsupported, `get_all_params` zwraca wszystkie `UvcParam`, `set_value`/`set_auto` → False bez wyjątku |
| `TestUvcParamInfo` | wartości domyślne dataclass, flaga `supported=False`, custom range |
| `TestMakeUvcControllerFallback` | zwraca instancję `UvcControllerBase`, fallback na stub gdy `ImportError` |

Łącznie testów: **35** (20 poprzednich + 15 nowych), wszystkie zielone.

---

## Decyzje architektoniczne

### Dlaczego `set_format()` zamiast osobnych `set_resolution`/`set_fps`?

Kamera ELP przez AVFoundation eksponuje formaty jako niepodzielne kombinacje `(W × H, fps, pixel_format)`. Próba niezależnej zmiany rozdzielczości bez zmiany fps (i odwrotnie) prowadziła do niespójnych stanów — kamera ignorowała jedną z wartości albo wybierała domyślny format. Jeden `CameraFormat` jako atomowa jednostka wyboru eliminuje problem.

### Dlaczego warstwowa architektura UVC a nie jedna biblioteka?

Brak cross-platform biblioteki Python dla UVC controls. `duvc-ctl` — Windows only (DirectShow), `pyuvc` — macOS/Linux (libuvc). Warstwa abstrakcji z platformową detekcją w runtime pozwala:
- Działać bez żadnej biblioteki (NullUvcController — grayed-out w UI)
- Dodać obsługę nowej platformy bez zmiany warstwy wyżej
- Testować logikę UI niezależnie od dostępności sprzętu

### Dlaczego Qt controls i UVC controls w jednym dialogu?

WB i exposure są dostępne przez oba API (Qt i UVC). Qt API jest wyżej poziomowe (tryby, EV), UVC daje surowe wartości rejestrów. Użytkownik widzi jedno spójne miejsce — nie musi wiedzieć przez które API co działa.

---

## Pliki zmienione / dodane

### Zmienione

| Plik | Co zmieniono |
|---|---|
| `app/ui/menu_bar.py` | Przebudowa menu: `format_selected` zamiast `resolution_selected`+`fps_selected`, nowe menu Image |
| `app/camera/camera_service.py` | `set_format()` zamiast `set_resolution`/`set_fps`, `qt_camera` property, lepsza walidacja w `_log_actual_format` |
| `app/ui/main_window.py` | UVC lifecycle, nowe sygnały menu, `_on_settings_requested` |

### Dodane

| Plik | Co zawiera |
|---|---|
| `app/camera/uvc/__init__.py` | `make_uvc_controller()` factory |
| `app/camera/uvc/base.py` | `UvcControllerBase`, `UvcParam`, `UvcParamInfo` |
| `app/camera/uvc/stub.py` | `NullUvcController` |
| `app/camera/uvc/windows.py` | `WindowsUvcController` (duvc-ctl) |
| `app/camera/uvc/macos.py` | `MacUvcController` (pyuvc) |
| `app/ui/camera_settings_dialog.py` | `CameraSettingsDialog` |
| `tests/test_uvc.py` | 15 testów UVC layer |

---

## Instalacja bibliotek UVC

### Mac Mini (cel docelowy)

```bash
brew install libusb jpeg-turbo
pip install pyuvc
```

### Windows (dev)

```bash
pip install duvc-ctl
```

### Bez bibliotek

Aplikacja działa normalnie — sekcja UVC w `CameraSettingsDialog` wyświetla komunikat o braku biblioteki. Qt controls (WB, Exposure) działają niezależnie od UVC.

---

## Next Steps

1. Przetestować na Mac Mini z kamerą ELP:
   - czy `MacUvcController` otwiera urządzenie po `pip install pyuvc`
   - czy slidery zmieniają rzeczywiste parametry kamery
   - czy `Camera Settings…` poprawnie pokazuje zakresy dla ELP (np. brightness 0–255)

2. Sprawdzić czy AVFoundation na macOS honoruje `setCameraFormat` bez stop+start (Qt docs mówią że na macOS inny proces może nadpisać format — `_log_actual_format` oznaczy to jako warning)

3. Dodać `set_active_format()` call po `_log_actual_format()` żeby menu zaznaczało faktycznie działający format (nie żądany)

4. Rozważyć `QSlider` z etykietą wartości min/max/default w dialogu — aktualnie są tylko slider + spinbox

5. (Opcjonalnie) Preset systemu: zapisz/wczytaj ustawienia do JSON per kamera

---

## Critical Context

- `CameraService.qt_camera` → `QCamera | None` — potrzebny do `CameraSettingsDialog`, jest `None` gdy kamera zatrzymana
- `make_uvc_controller(name)` zwraca **już otwarty lub próbujący otworzyć** kontroler; `MainWindow._open_uvc()` nie wywołuje `.open()` ponownie jeśli `is_open()` zwróci True
- `MacUvcController` używa `uvc.device_list()` (pyuvc API) — wymaga że kamera **nie jest** aktywnie używana przez inny proces (ograniczenie libusb na macOS)
- `WindowsUvcController` działa **równolegle** z Qt — DirectShow pozwala na jednoczesny dostęp do controls i streamu
- Testy UVC nie wymagają sprzętu ani bibliotek natywnych — `NullUvcController` jest czystym Pythonem

## Uruchamianie

```bash
# Windows dev
.venv-win\Scripts\python.exe -m app.main

# Mac Mini (po instalacji pyuvc)
.venv/bin/python -m app.main
```