nestris-core Erkennungs-Engine & Capture-Station¶
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
.debfĂŒr amd64 und arm64 ausgeliefert. -
nestris-CLIrun,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.gzherunter.
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.