Docs

Documentatie

Alles draait op je eigen machine: installeer het, richt er een camera op en stel bij wanneer het een aanroep mag doen. Gegroepeerd naar wat je wilt bereiken.

Installeren en starten

Van niets naar een kaart in beeld

Eén commando installeert de client, de modelgewichten en de shims. Het enige inloggegeven in het hele systeem is je Ximilar-sleutel.

Het installatiescript

Maakt een venv aan in ~/.cardstream, controleert de release-wheel aan de hand van de checksums, haalt de modelgewichten op en zet beide commando’s in je PATH. De andere manieren (wheel, Docker, broncode) staan op de downloadpagina.

$ curl -fsSL https://raw.githubusercontent.com/Ximilar-com/cardstream/main/scripts/install.sh | sh

Alle installatiemanieren →

Handmatig installeren

Een checkout en pip werken ook. De extras staan los van elkaar: [client] is de UI en de bronnen, [onnx] of [torch] leveren de backends voor de detector en de embedder.

$ git clone https://github.com/Ximilar-com/cardstream && cd cardstream
$ pip install -e '.[client,onnx]'

Je Ximilar-sleutel

De identificatie loopt via Ximilar collectibles/v2. XIMILAR_API_KEY is de enige omgevingsvariabele die ergens wordt uitgelezen; al het andere is een flag.

$ export XIMILAR_API_KEY=your-key

De eerste start

Opent de browser-UI met je webcam. Houd een kaart omhoog; de overlay laat de toestandsmachine zien terwijl ze nadenkt, en de match zodra die er is.

$ cardstream-web
# → http://127.0.0.1:8001

Controleer wat je hebt

Beide commando’s tonen hun versie en stoppen. Daar zijn geen modelbestanden voor nodig, dus het werkt zodra de installatie klaar is.

$ cardstream-web --version
cardstream 0.5.0

Headless, voor vaste opstellingen

Dezelfde pipeline zonder browser: de resultaten verschijnen in de terminal. Dezelfde flags als cardstream-web, één proces naast de camera.

$ cardstream-client --source 0

Gebruiken

Geef het je show

Bronnen zijn verwisselbaar en de analyse is dezelfde, welke je ook kiest. Alles is een flag; de belangrijkste stel je live bij in het instellingenvenster.

Webcams en bestanden

De webcam van de browser is de standaard voor cardstream-web; een index, een videobestand of een stilstaand beeld werken overal. Handig om te testen vóór de show.

$ cardstream-web # webcam van de browser
$ cardstream-client --source clip.mp4

Een stream ophalen

Richt het op een IP-camera, een encoder of een restreamer: rtsp://, rtmp://, srt:// en ws://-JPEG-feeds, met een begrensde backoff bij het opnieuw verbinden.

$ cardstream-web --source rtsp://cam/stream1

Laat OBS pushen

Draai het als listener en voeg in OBS één extra RTMP- of SRT-uitvoer toe. Heeft de ffmpeg-binary van je systeem nodig (brew install ffmpeg).

$ cardstream-web --source rtmp://0.0.0.0:1935/live --listen

Vooraf invullen verkleint de zoekruimte

Spel, setcode en schrift worden lokaal gecontroleerd voordat ze worden verstuurd. Geef altijd --alphabet mee als je --game meegeeft: is het spel vooraf ingevuld, dan detecteert het endpoint het alfabet niet meer zelf.

$ cardstream-web --game "Pokémon" --alphabet japanese --set-code M4

Het instellingenvenster

Categorie, spel, setcode, alfabet en drempels zijn tijdens de stream vanuit de browser bij te stellen. Zonder herstart, en de knoppen hebben dezelfde validatie als het proces.

Drie resolutieknoppen

Wat de camera opneemt, wat er wordt verstuurd en wat er wordt geanalyseerd, zijn aparte getallen. De analyse draait klein; de uitsnede voor de identificatie wordt opnieuw uit het volledige frame gesneden.

$ cardstream-web --camera-width 3840 --width 1280

De show terugkijken

Sla de show op, kijk hem later terug

Standaard uit. Eén flag slaat de geschiedenis die de pagina opbouwt (elke kaart die je hebt laten zien, met zijn uitsnede) op in een sessie in je eigen Ximilar-account. Zo is de show er de ochtend erna nog.

De geschiedenis, met thumbnails

De browser-UI toont elke kaart die je hebt laten zien, de nieuwste bovenaan: een thumbnail van de uitsnede die is geïdentificeerd, de prijs als je --price-stats gebruikt, en hoe lang hij op stream bleef. Die lijst staat op je eigen machine.

Een show opslaan

--ximilar-stream NEW start een sessie en toont de id ervan. Vanaf dat moment wordt elke rij van de geschiedenis opgeslagen terwijl de show loopt: uploads gaan in batches op de achtergrond, worden bij netwerkfouten opnieuw geprobeerd en houden de show nooit op. Sluit je netjes af, dan wordt de rest geüpload en de sessie gesloten.

$ cardstream-web --game "Pokémon" --alphabet latin \
    --price-stats --ximilar-stream NEW

Een show opslaan, alle details →

Wat er wordt geüpload

De rijen als tekst (kaart, set, prijs, tijd op stream, de betaalde aanroepen erachter) en de uitsnede waarop elke rij is geïdentificeerd, hooguit 1024 px: het beeld dat de identificatie-aanroep al had gekregen. Met --no-ximilar-stream-images blijft het bij tekst. Je Ximilar-account heeft de dienst Cardstream nodig.

$ cardstream-web --ximilar-stream NEW --no-ximilar-stream-images

Terugkijken in de Ximilar-app

Elke sessie komt in het onderdeel Cardstream van de Ximilar-app terecht: wat je hebt laten zien en wanneer, de waarde van de show, de waardevolste producten en de topsets, en elke kaart met zijn uitsnede. Markeer wat verkocht is, corrigeer een verkeerde match, voeg notities toe.

Open de Ximilar-app →

Verdergaan na een herstart

Geef de sessie-id mee in plaats van NEW en de show gaat verder in dezelfde sessie. Ook als die bij een nette afsluiting al was gesloten: hij gaat gewoon weer open. Alleen het starten van een sessie wordt gefactureerd, dus verdergaan kost niets.

$ cardstream-web --ximilar-stream <session-id>

Teamworkspaces

Een sessie wordt opgeslagen in de standaardworkspace van je API-sleutel. Kies een andere met --ximilar-workspace, en geef dezelfde id mee als je verdergaat met een sessie die daar is opgeslagen.

$ cardstream-web --ximilar-stream NEW \
    --ximilar-workspace <workspace-id>

Met vertrouwen draaien

Eén identificatie-aanroep per nieuwe kaart

Lokale signalen (beweging, detectie, het identiteitsfilter) beslissen wanneer een identificatie-aanroep echt nodig is. Dit zijn de knoppen die het eerlijk houden.

Drempels

Een resultaatdrempel houdt zwakke matches van de overlay; de gelijkenisdrempel beslist tussen dezelfde kaart en een nieuwe; forget-after wist het geheugen zodra een kaart lang genoeg weg is.

$ cardstream-web --result-threshold 0.35

De aanbevolen configuratie

RF-DETR-segmentatie met een ONNX-embedding als identiteitsfilter: de meegeleverde standaardinstellingen. Een kaal cardstream-web draait precies dit zodra de gewichten op hun plek staan; het voluit schrijven geeft dezelfde pipeline.

$ cardstream-web \
    --segmentor-model model/segmentation/onnx/model.onnx \
    --embed-model model/similarity/onnx/model.onnx

Houd het op localhost

De lokale app heeft geen authenticatie en bevat je API-sleutel. --host staat standaard op 127.0.0.1: laat dat zo en stel de poort nooit open voor een LAN.

“Model not found” bij het opstarten

De modelgewichten zijn een aparte download en zitten niet in de repo. Het installatiescript en de Docker-image halen ze op; bij een kale checkout moeten ze in model/segmentation/ en model/similarity/ worden gezet. scripts/build-from-source.sh --models doet dat voor je.

Geef op welk spel je laat zien

Bij een show met één spel hoeft het endpoint niet bij elke aanroep het spel te raden. Noem het en de zoekruimte beperkt zich tot dat spel: snellere antwoorden, minder verkeerde drukken. Geef er --alphabet bij op, want is het spel vooraf ingevuld, dan detecteert het endpoint het schrift niet meer zelf.

$ cardstream-web --game "Pokémon" --alphabet japanese

ffmpeg, als je het nodig hebt

--listen en --ffmpeg roepen de ffmpeg-binary van je systeem aan. Gewoon ophalen werkt met een installatie via alleen pip; de opzet waarbij OBS pusht niet.

Dieper duiken

Verder dan de standaardinstellingen

Wissel de modellen of lees de code: de hele pipeline is één installeerbaar pakket.

Gebruik je eigen gewichten

De detectie en het identiteitsfilter kiezen hun backend zelf: de familie bepaalt de klasse, de bestandsextensie de runtime. RF-DETR of RT-DETRv2, .onnx of een transformers-map.

Modelbackends →

Het modeloverzicht

Alle gewichten die cardstream kan laden, getraind door Ximilar en samen met de releases gepubliceerd onder Apache-2.0: wat elk model doet, hoe snel het draait en welke licentie erop zit.

Modeloverzicht →

Korte antwoorden

Wat het kost, wat de machine verlaat, welke kaarten het benoemt, en de twee commando’s waarmee je het weer verwijdert.

Lees de FAQ →

README en issues

De README behandelt elke flag; issues zijn de plek voor bugs en vragen.

Lees de README →

Releases en artefacten

Wheels, checksums en het installatiescript, één set per release, plus Docker en builds vanaf de broncode.

Downloadpagina →