Docs

Documentazione

Tutto gira sul tuo computer: installalo, puntagli contro una videocamera e regola quando gli è permesso chiamare. Organizzato in base a quello che vuoi fare.

Installa e avvia

Da zero a una carta sullo schermo

Un solo comando installa il client, i pesi dei modelli e gli shim. L’unica credenziale di tutto il sistema è la tua chiave Ximilar.

Lo script di installazione

Crea un venv in ~/.cardstream, verifica il wheel della release con i suoi checksum, scarica i pesi dei modelli e mette entrambi i comandi nel tuo PATH. Gli altri metodi (wheel, Docker, sorgenti) sono nella pagina di download.

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

Tutti i metodi di installazione →

Installazione manuale

Vanno bene anche un checkout e pip. Gli extra sono indipendenti: [client] porta l’interfaccia e le sorgenti, [onnx] o [torch] forniscono i backend del rilevatore e dell’embedding.

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

La tua chiave Ximilar

L’identificazione si appoggia a Ximilar collectibles/v2. XIMILAR_API_KEY è l’unica variabile d’ambiente che viene letta: tutto il resto è un flag.

$ export XIMILAR_API_KEY=your-key

Primo avvio

Apre l’interfaccia nel browser con la tua webcam. Mostra una carta: l’overlay fa vedere la macchina a stati che ragiona e poi la corrispondenza, appena arriva.

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

Verifica quello che hai

Entrambi i comandi stampano la versione ed escono. Non servono i file dei modelli, quindi funziona appena l’installazione finisce.

$ cardstream-web --version
cardstream 0.5.0

Senza interfaccia, per le postazioni fisse

La stessa pipeline senza browser: i risultati vengono stampati nel terminale. Gli stessi flag di cardstream-web, un solo processo accanto alla videocamera.

$ cardstream-client --source 0

Usalo

Dagli il tuo show

Le sorgenti sono intercambiabili e l’analisi è identica qualunque tu scelga. Tutto è un flag; la finestra delle impostazioni regola in diretta quelli più importanti.

Webcam e file

La webcam del browser è la sorgente predefinita di cardstream-web; un indice, un file video o un’immagine fissa funzionano ovunque. Comodo per fare una prova prima dello show.

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

Prelevare un flusso

Puntalo su una videocamera IP, un encoder o un restreamer: flussi rtsp://, rtmp://, srt:// e feed JPEG ws://, con riconnessioni a intervalli crescenti ma limitati.

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

Lascia che sia OBS a inviare

Avvialo in ascolto e aggiungi in OBS un’uscita RTMP o SRT in più. Serve il binario ffmpeg di sistema (brew install ffmpeg).

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

Preimpostazioni che restringono la ricerca

Gioco, codice di set e sistema di scrittura vengono validati in locale prima di essere inviati. Passa sempre --alphabet quando passi --game: preimpostare il gioco impedisce all’endpoint di rilevare da solo l’alfabeto.

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

La finestra delle impostazioni

Categoria, gioco, codice di set, alfabeto e soglie si regolano dal browser a diretta in corso: nessun riavvio, e i controlli applicano la stessa validazione del processo.

Tre regolazioni di risoluzione

Ciò che la videocamera cattura, ciò che viene inviato e ciò che viene analizzato sono tre numeri distinti. L’analisi gira in piccolo; il ritaglio da identificare viene ricavato di nuovo dal fotogramma intero.

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

Rivedi lo show

Salva lo show, rivedilo dopo

Disattivato di default. Un flag salva lo storico che la pagina costruisce (ogni carta che hai mostrato, con il suo ritaglio) in una sessione del tuo account Ximilar, così lo show è ancora lì la mattina dopo.

Lo storico, con le miniature

L’interfaccia nel browser elenca ogni carta che hai mostrato, dalla più recente: una miniatura del ritaglio identificato, il suo prezzo con --price-stats e quanto è rimasta in diretta. Quell’elenco vive sul tuo computer.

Salva uno show

--ximilar-stream NEW avvia una sessione e ne stampa l’id. Da quel momento ogni riga dello storico viene salvata mentre lo show va avanti: i caricamenti sono raggruppati in background, ritentati in caso di errori di rete e non rallentano mai lo show. Un’uscita pulita carica quello che resta e chiude la sessione.

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

Il salvataggio di uno show, per intero →

Che cosa viene caricato

Le righe come testo (carta, set, prezzo, tempo in diretta, le chiamate a pagamento che ci stanno dietro) e il ritaglio da cui ogni riga è stata identificata, al massimo di 1024 px: l’immagine che la chiamata di identificazione ha già ricevuto. Con --no-ximilar-stream-images si salva solo il testo. Al tuo account Ximilar serve il servizio Cardstream.

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

Rivedilo nell’app Ximilar

Ogni sessione finisce nella sezione Cardstream dell’app Ximilar: che cosa hai mostrato e quando, il valore dello show, i prodotti di maggior valore e i set più frequenti, e ogni carta con il suo ritaglio. Segna cosa hai venduto, correggi una corrispondenza sbagliata, aggiungi note.

Apri l’app Ximilar →

Riprendi dopo un riavvio

Passa l’id della sessione al posto di NEW e lo show prosegue nella stessa sessione: anche se un’uscita pulita l’aveva chiusa, si riapre e basta. Viene addebitato solo l’avvio di una sessione, quindi riprendere non costa nulla.

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

Workspace di team

Una sessione viene salvata nel workspace predefinito della tua chiave API. Indicane un altro con --ximilar-workspace, e passa lo stesso id quando riprendi una sessione salvata lì.

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

Usalo con fiducia

Una chiamata di identificazione per carta distinta

Sono i segnali locali (movimento, rilevamento, filtro di identità) a decidere quando una chiamata di identificazione è davvero giustificata. Queste sono le regolazioni che lo tengono onesto.

Le soglie

Una soglia di risultato tiene fuori dall’overlay le corrispondenze deboli; la soglia di similarità decide tra stessa carta e carta nuova; forget-after azzera la memoria quando una carta è sparita da abbastanza tempo.

$ cardstream-web --result-threshold 0.35

La configurazione consigliata

Segmentazione RF-DETR con un filtro a embedding ONNX: sono le impostazioni predefinite. Un semplice cardstream-web esegue esattamente questo una volta che i pesi sono al loro posto; scriverlo per esteso dà la stessa pipeline.

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

Tienilo su localhost

L’app locale non ha autenticazione e custodisce la tua chiave API. --host vale 127.0.0.1 di default: lascialo così e non esporre mai la porta a una rete locale.

“Model not found” all’avvio

I pesi dei modelli si scaricano a parte, non fanno parte del repository. Lo script di installazione e l’immagine Docker li scaricano; con un semplice checkout vanno messi in model/segmentation/ e model/similarity/. Ci pensa scripts/build-from-source.sh --models.

Indica il gioco che stai mostrando

In uno show su un solo gioco non serve che l’endpoint indovini il gioco a ogni chiamata. Indicalo e la ricerca si restringe a quel gioco: risposte più rapide, meno stampe sbagliate. Passa anche --alphabet, perché preimpostare il gioco impedisce all’endpoint di rilevare da solo il sistema di scrittura.

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

ffmpeg, quando serve

--listen e --ffmpeg richiamano il binario ffmpeg di sistema. I semplici pull funzionano con la sola installazione via pip; la configurazione in cui è OBS a inviare, no.

Vai più a fondo

Oltre le impostazioni predefinite

Cambia i modelli o leggi il codice: l’intera pipeline è un unico pacchetto installabile.

Porta i tuoi pesi

Rilevamento e filtro di identità passano da backend: la famiglia sceglie la classe, l’estensione del file sceglie il runtime. RF-DETR o RT-DETRv2, un .onnx o una directory transformers.

I backend dei modelli →

Il catalogo dei modelli

Tutti i pesi che cardstream può caricare, addestrati da Ximilar e pubblicati con licenza Apache-2.0 insieme alle release: che cosa fa ciascuno, su che cosa gira e con quale licenza.

Catalogo dei modelli →

Risposte in breve

Quanto costa, che cosa esce dal computer, quali carte riconosce e i due comandi che lo rimuovono.

Leggi le FAQ →

README e issue

Il README copre ogni flag; le issue sono il posto giusto per bug e domande.

Leggi il README →

Release e artefatti

Wheel, checksum e script di installazione, un set per ogni release, più Docker e la build dai sorgenti.

Pagina di download →