In Arbeit2026

axis_ptz_rotate

Native ACAP zur automatischen Rotationskompensation an AXIS-PTZ-Kameras

Native ACAP-Erweiterung für die AXIS Q6078-E (ARTPEC-8, aarch64), die Montagefehler der Kamerahalterung automatisch korrigiert: Das Live-Bild wird anhand des aktuellen Schwenkwinkels rotiert, gesteuert durch eine benutzerkonfigurierbare Mapping-Tabelle mit bis zu 360 Stützpunkten und linearer Interpolation.

C (C99)ACAP Native SDK 1.15OpenGL ES 2.0/3.0EGLVAPIXVDO APIH.264RTSPMJPEGDockerAXIS OS 11.x

Native ACAP-Erweiterung für die AXIS Q6078-E (ARTPEC-8, aarch64), die Montagefehler der Kamerahalterung automatisch korrigiert: Das Live-Bild wird anhand des aktuellen Schwenkwinkels rotiert, gesteuert durch eine benutzerkonfigurierbare Mapping-Tabelle mit bis zu 360 Stützpunkten und linearer Interpolation.

Hintergrund

Die AXIS Q6078-E ist eine motorisierte PTZ-Kamera für anspruchsvolle Überwachungsinstallationen. In der Praxis lässt sich die Kamera selten perfekt lotrecht montieren — selbst kleine Winkelabweichungen der Halterung führen je nach Schwenkposition zu einer messbaren Horizontverkippung im Bild. Softwareseitige Bildstabilisierung löst dieses Problem nicht, da der Fehler winkelabhängig ist und kein einheitlicher Offset ausreicht.

axis_ptz_rotate schließt diese Lücke: Eine frei editierbare Lookup-Tabelle ordnet jedem Schwenkwinkel einen individuellen Rotationskorrekturwert zu. Der ACAP interpoliert linear zwischen den Stützpunkten, berechnet automatisch den minimalen Zoom-Faktor zur Vermeidung von Bildbeschnitt und wendet die Korrektur GPU-beschleunigt auf jeden Frame an — ohne die primäre Kamera-Pipeline zu berühren.

Kernfunktionen

  • Echtzeit-Bildrotation per GPU-Shader (OpenGL ES) auf Basis des Pan-Winkels
  • Benutzerdefinierte Mapping-Tabelle (max. 360 Einträge, 1°-Auflösung, lineare Interpolation, 360°-Wrap-Around)
  • Auto-Zoom verhindert schwarze Ecken nach der Rotation — berechnet aus dem maximalen Korrekturwert der Tabelle
  • Event-gesteuertes Update ausschließlich bei stehendem PTZ-Motor (kein Blur durch Interpolation während der Bewegung)
  • Separater H.264-RTSP-Ausgabestream — die primäre Kamerastream bleibt unverändert
  • MJPEG-Vorschau (720p, 5 fps) für die Web-Oberfläche
  • Kein externer Abhängigkeitsgraph — Cross-Compile vollständig im Docker-Container

Technischer Stack

ACAP-Core (C99)

  • ACAP Native SDK 1.15 (axisecp/acap-native-sdk:1.15-aarch64-ubuntu22.04), Zielarchitektur aarch64 / ARTPEC-8
  • VDO API für NV12-Framecapture in konfigurierbarer Auflösung (1080p / 2K / 4K)
  • VAPIX Event Stream zur PTZ-Positionserkennung; automatischer Fallback auf 200-ms-Polling bei ausbleibenden Events
  • HTTP CGI-Handler über den internen lighttpd der Kamera (/local/ptzrotate/api/...)
  • Persistenz unter /usr/local/packages/ptzrotate/localdata/ (mapping.json, settings.json)

GPU-Pipeline (OpenGL ES)

  • EGL-Surfaceless-Kontext direkt auf dem ARTPEC-8
  • NV12-Frames als Dual-Texture (Y-Plane + UV-Plane), Rotation per Fragment-Shader
  • 2D-Rotationsmatrix um Bildmitte, skaliert mit Auto-Zoom-Faktor s = max(|cos α| + (h/w)·|sin α|, |cos α| + (w/h)·|sin α|)
  • Render in FBO, Readback als NV12 für den Encoder

Ausgabe

  • H.264 / RTSP — separater Stream rtsp://<cam>/local/ptzrotate/stream.h264
  • MJPEG-Vorschau — multipart/x-mixed-replace auf /local/ptzrotate/api/preview.mjpg, Shared-File-Tee mit stb_image_write.h (MIT/PD, vendored)

Web-Oberfläche (Vanilla JS)

  • Kein Build-Step, kein Framework — statische Dateien unter html/
  • Live-Vorschau: Kamera-MJPEG (links) vs. rotierter Plugin-Stream (rechts)
  • Mapping-Tabellen-Editor: Zeilen hinzufügen / löschen, sortieren, JSON-Import/Export
  • Kalibrierungsassistent: Schritt-für-Schritt durch alle Stützpunkte mit Echtzeit-Vorschau
  • Einstellungsseite: Auflösung, Framerate, Aktivierung

Architektur

AXIS Q6078-E (ARTPEC-8)
│
├─ VAPIX Event Stream ──────────────────┐
│   (PTZ stopped event)                │
│   Fallback: 200ms Polling            ▼
│                               PTZ Service
│                               (pan_angle, is_moving)
│                                      │
│                                 lookup + Interpolation
│                                      │
├─ VDO Capture (NV12) ─────────▶ GPU Rotator (OpenGL ES)
│                                      │
│                               H.264 Encoder
│                               ├── RTSP Stream
│                               └── MJPEG 720p Preview
│
└─ Web UI (lighttpd / CGI)
    ├── Live-Vorschau (Input ◀│▶ Output)
    ├── Mapping-Tabellen-Editor
    ├── Kalibrierungsassistent
    └── Einstellungen / Import / Export

Entwicklungsphasen

Phase Inhalt Status
0a SDK ↔ Firmware-Kompatibilität ✅ Abgeschlossen
0b Toolchain & Simulator-Strategie ✅ Abgeschlossen
1 ACAP-Skeleton (Manifest, Main-Loop, Web-UI-Shell) ✅ Abgeschlossen
2 PTZ-Service (Event-Subscription + Polling-Fallback) ✅ Abgeschlossen
3 Mapping-Tabellen-Modul (Interpolation, Persistenz, HTTP-API) ✅ Abgeschlossen
4a VDO-Capture (Real + synthetisches Testmuster) ✅ Abgeschlossen
4b GPU-Rotations-Shader (OpenGL ES, Zoom, FBO-Readback) ✅ Abgeschlossen
4c H.264-Encoder + RTSP-Server (permissiv lizenziert) ✅ Abgeschlossen
5 MJPEG-Vorschau-Endpoint ✅ Abgeschlossen
6 Kalibrierungsassistent (Backend) ✅ Abgeschlossen
7 Web-Oberfläche (Vorschau, Tabellen-Editor, Kalibrierung) ✅ Abgeschlossen
8 Manuelle On-Device-Verifikation (via VPN durch den Nutzer) Offen
9 Packaging & Dokumentation Offen

Aktueller Stand

Alle simulator-verifizierbaren Phasen (0a–7) sind abgeschlossen. Die Web-Oberfläche ist vollständig funktionsfähig; der GPU-Rendering-Pfad, das Kalibrierungssystem und die vollständige HTTP-API sind implementiert. Ausstehend: manuelle Verifikation auf der physischen Kamera (Phase 8, erfordert VPN-Zugang) und finales Packaging (Phase 9).

Das ACAP wird als unsigned EAP per Sideload installiert. Eine mögliche zukünftige Veröffentlichung über den Axis App Store bleibt durch die gewählte Lizenzpolitik (ausschließlich MIT/BSD/Apache-2.0-Abhängigkeiten) offen.

Proprietär — alle Rechte vorbehalten.