Zum Inhalt

nestris-core Erkennungs-Engine & Capture-Station

Latest release CI License Rust Beta

nestris-core liest Classic NES Tetris aus einem Videosignal. Es findet das Spielfeld im Bild, korrigiert Perspektive und Linsenverzerrung und erkennt auf jedem Frame Score, Lines, Level, das nĂ€chste und das aktuelle Teil, das ganze 10×20-Spielfeld und die Teilestatistik. Daraus entstehen Spielereignisse und Statistiken.

Es ist eine hochperformante Rust-Portierung der frĂŒheren Python-Engine, drahtkompatibel und gegen sie verifiziert. Außerdem enthĂ€lt es nestris-station, den Dienst, der auf jeder Turnierstation lĂ€uft.

Repository Neueste Version laden

Einsatzmöglichkeiten

  • nestris-station

    Ein Debian-Dienst ohne Bildschirm fĂŒr Turnierstationen. Er ĂŒbernimmt v4l2-Capture, RFID-Anmeldung, Cheat-Erkennung, PrĂŒfung, MQTT und den Upload der Aufzeichnungen und lĂ€uft unter systemd mit Watchdog. Wird als .deb fĂŒr amd64 und arm64 ausgeliefert.

  • nestris-CLI

    run, replay, bench, verify, list-devices, screens. Schreibt JSONL, NDJSON oder einen WebSocket-Stream und zeichnet jedes Spiel als NGF auf.

  • Desktop-GUIs

    Die egui-GUI und die Qt-6/QML-GUI (angelehnt an das NestrisChamps-Layout classic_1080) haben je drei Vorschauen, ein Dashboard, ein Statistikfenster und einen Einstellungsdialog fĂŒr jede Engine-Option.

  • Browser-GUI

    Die Engine als WebAssembly (rund 270 KB gzip) lÀuft in einem Web Worker. Sie nimmt Videodateien, Replays, eine Kamera oder eine Bildschirmfreigabe und lÀdt fertige Spiele als .ngf.gz herunter.

Erkennungs-Pipeline

flowchart LR
    IN["<span style='color:#f8fafc'>Capture-Karte · Webcam ·<br/>Videodatei · RTSP/SRT ·<br/>.ngf-Replay</span>"]:::hw --> FF["<span style='color:#111111'>ffmpeg</span>"]:::core
    FF --> CAL["<span style='color:#111111'>Selbstkalibrierung<br/>RANSAC-Homographie<br/>+ Entzerrung</span>"]:::core
    CAL --> CAN["<span style='color:#111111'>Kanonisches 256×240-<br/>NES-Bild</span>"]:::core
    CAN --> CLS["<span style='color:#111111'>Bildschirm-Klassifikator<br/>(Kachel-Signaturen)</span>"]:::core
    CLS --> OCR["<span style='color:#111111'>Ziffern · Teile ·<br/>Spielfeld · Statistikleiste</span>"]:::core
    OCR --> FUSE["<span style='color:#111111'>Zustandsfusion<br/>PlausibilitÀt, Ereignisse</span>"]:::core
    FUSE --> INT["<span style='color:#111111'>IntegritĂ€t<br/>Cheat + PrĂŒfung</span>"]:::core
    FUSE --> ST["<span style='color:#111111'>Statistiken</span>"]:::core
    INT & ST --> OUT["<span style='color:#ffffff'>JSON v4 · NGF · MQTT</span>"]:::ext

    classDef core fill:#22d3ee,stroke:#0e7490,color:#111,stroke-width:2px
    classDef ext fill:#64748b,stroke:#334155,color:#fff,stroke-width:2px
    classDef hw fill:#1f2937,stroke:#94a3b8,color:#f8fafc,stroke-dasharray:4 3
  • Keine manuelle Kalibrierung. Ein Lock-Zustandsautomat (UNLOCKED → ACQUIRING → LOCKED ⇄ DRIFT → LOST) findet Spielfeld und Beschriftungsanker und rechnet im Hintergrund nach. Optionales kontinuierliches Tracking kommt mit Handkameras oder bewegten Kameras zurecht.
  • Bildschirm-Klassifikator. Er vergleicht das NES-Kachellayout jedes Bildschirms. Auf ĂŒber 60 000 von Hand beschrifteten Stations-Frames lag er zu 100 % richtig.
  • Modifizierte ROMs. Hexadezimale Score-Anzeigen werden unterstĂŒtzt.

Gegen die Referenz-Engine verifiziert

Die Python-Engine ist die Referenz. Die Gleichwertigkeit wird in vier Stufen geprĂŒft:

Stufe Was verglichen wird Ergebnis
1 · CV-Golden-Tests Bildverarbeitungs-Grundfunktionen gegen OpenCV/numpy innerhalb dokumentierter Toleranzen, viele byte-genau
2 · Erkennungs-Replay Jedes Feld auf von Python entzerrten Frames 100 % Übereinstimmung, jede Spielfeldzelle eingeschlossen
3 · Zustandsautomat-Replay 15 TestfĂ€lle × 1200 Frames byte-genaues JSON inklusive SchlĂŒsselreihenfolge
4 · Gesamte Pipeline (nestris verify) Ende-zu-Ende auf allen TestfÀllen mindestens 99,5 % pro Feld gefordert, die meisten bei 100,000 %

Jede neue Funktion steckt hinter einem Konfigurationsschalter, dessen Standardwert die Referenzausgabe byte-genau reproduziert.

Leistung

Engine p50 pro Frame Durchsatz
nestris-core (Rust, parallel) ≈ 2,9 ms (p99 4,6 ms) ≈ 350 fps
Python-Referenz-Engine ≈ 12,8 ms ≈ 78 fps

Die LĂ€ufe sind deterministisch. RANSAC wird pro Frame fest initialisiert, daher liefern zwei LĂ€ufe ĂŒber dieselbe Eingabe bitgleiche Ergebnisse.

Statistiken

Neben den Rohwerten berechnet die Engine Turnierstatistiken. Alle Definitionen stehen in der Statistik-Referenz.

  • Basis: Teile pro Sekunde, Score pro Minute, Tetris-Rate, Burn, Drought / lĂ€ngste Drought, Anzahl der AbrĂ€umarten, Teile
  • Erweitert: Punkteverteilung nach AbrĂ€umart, Effizienz (EFF), Pace bis Line 230, I-Teil-Drought-Verlauf, Spielfeldform (Löcher, Tetris-bereit, Doppelbrunnen, saubere SchrĂ€ge), Teileverteilung

nestris-station im Detail

flowchart LR
    NES["<span style='color:#f8fafc'>🎼 NES</span>"]:::hw --> USB["<span style='color:#f8fafc'>USB-Capture<br/>v4l2</span>"]:::hw --> FF["<span style='color:#111111'>ffmpeg</span>"]:::core --> ENG["<span style='color:#111111'>Engine</span>"]:::core --> SES["<span style='color:#111111'>Session<br/>Spielstart / -ende</span>"]:::core
    RD["<span style='color:#111111'>RFID-Leser<br/>(serielles JSON v2)</span>"]:::rfid --> PLY["<span style='color:#111111'>Spieler</span>"]:::core --> SES
    SES --> SPOOL["<span style='color:#111111'>Spool auf Platte</span>"]:::core --> MQTT["<span style='color:#ffffff'>MQTT → Host</span>"]:::ext
    SES --> REC["<span style='color:#111111'>.ngf.gz-Aufzeichnung</span>"]:::core --> UP["<span style='color:#111111'>Upload-Warteschlange</span>"]:::core --> HTTP["<span style='color:#111111'>HTTP PUT → NestrisLTM</span>"]:::ltm
    MQTT -. "cmd" .-> RD

    classDef ltm fill:#f5b800,stroke:#7a5c00,color:#111,stroke-width:2px
    classDef core fill:#22d3ee,stroke:#0e7490,color:#111,stroke-width:2px
    classDef rfid fill:#f472b6,stroke:#be185d,color:#111,stroke-width:2px
    classDef ext fill:#64748b,stroke:#334155,color:#fff,stroke-width:2px
    classDef hw fill:#1f2937,stroke:#94a3b8,color:#f8fafc,stroke-dasharray:4 3

Installation unter Debian 12/13

sudo apt install ./nestris-station_<version>-1_amd64.deb   # installiert ffmpeg mit
sudoedit /etc/nestris-station/station.toml                 # capture.device, rfid.port, mqtt.host, station.id
sudo systemctl enable --now nestris-station
journalctl -u nestris-station -f                           # Live-Log

Das Paket installiert das Programm, eine systemd-Unit und /etc/nestris-station/station.toml und legt den Dienstbenutzer nestris an. Reihenfolge der Einstellungen: eingebaute Standardwerte → Konfigurationsdatei → Umgebungsvariablen NESTRIS_STATION__<SECTION>__<KEY> → --set key=value. Unbekannte SchlĂŒssel sind Fehler.

Abschnitt Wichtige Einstellungen
station id (MQTT-Topic und PrÀfix der Spiel-ID), name
capture device (GerÀtepfad oder Stream-URL), Auflösung, stall_timeout_s
rfid enabled, port, baud (115200)
mqtt host, port, Zugangsdaten, TLS, topic_prefix, live_max_hz (60)
recording enabled, dir, keep_days (30), max_gb (20)
host url (NestrisLTM), token_file (Scope stations)
integrity Schwellwerte fĂŒr Cheat-Erkennung und PrĂŒfung

Selbstheilung

Ausfall Reaktion
Prozess stĂŒrzt ab systemd startet ihn nach 3 s neu
Hauptschleife hÀngt systemd-Watchdog (30 s) startet neu
Engine-Panic bei einem Frame Engine wird im Prozess neu aufgebaut; Spiel als engine_restart markiert
ffmpeg-Fehler / keine Frames Neustart mit exponentiellem Backoff
Capture-Stick abgesteckt waiting_for_device, weiter beim Wiederanstecken
Leser abgesteckt Wiederverbindungsschleife, solange rfid: offline
Broker / Netzwerk weg Ergebnisse warten im Spool und werden nachgesendet

Release-Dateien

Datei Plattform Inhalt
nestris-station_<v>-1_amd64.deb / _arm64.deb Debian 12 / 13 Stations-Dienst
nestris-v<v>-<os>-bundle.zip windows-x64, linux-x64, macos-arm64 CLI + GUIs als Bundle (Windows inklusive ffmpeg)
nestris-cli-
, nestris-gui-
, nestris-qt-gui-v<v>-<os>.zip wie oben Einzelwerkzeuge; Qt als Ordner, AppImage oder .app
nestris-web-v<v>.zip jeder statische Webserver Browser-GUI
SHA256SUMS.txt / .sig – PrĂŒfsummen und Ed25519-Signatur

nestris-core steht unter der MIT-Lizenz.