Dokumentace

Všechno běží na vašem počítači: nainstalujte ho, namiřte na něj kameru a nastavte, kdy smí volat ven. Seřazeno podle toho, čeho chcete dosáhnout.

Instalace a spuštění

Od nuly ke kartě na obrazovce

Jeden příkaz nainstaluje klienta, váhy modelů i spouštěcí skripty. Jediný přístupový údaj v celém systému je váš klíč k Ximilaru.

Instalační skript

Vytvoří virtuální prostředí v ~/.cardstream, ověří wheel z vydání podle kontrolních součtů, stáhne váhy modelů a oba příkazy přidá do PATH. Další způsoby (wheel, Docker, ze zdrojového kódu) najdete na stránce Stažení.

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

Všechny způsoby instalace →

Ruční instalace

Funguje i klon repozitáře a pip. Volitelné doplňky jsou nezávislé: [client] je rozhraní a zdroje videa, [onnx] nebo [torch] poskytují backendy pro detektor a embedding.

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

Váš klíč k Ximilaru

Identifikaci zajišťuje Ximilar collectibles/v2. XIMILAR_API_KEY je jediná proměnná prostředí, kterou cokoli čte; všechno ostatní je přepínač.

$ export XIMILAR_API_KEY=your-key

První spuštění

Otevře rozhraní v prohlížeči s vaší webkamerou. Ukažte kartu: overlay ukazuje, jak stavový automat přemýšlí, a pak i shodu, jakmile dorazí.

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

Co máte nainstalované

Oba příkazy vypíšou svou verzi a skončí. Soubory modelů k tomu nejsou potřeba, takže to funguje hned po dokončení instalace.

$ cardstream-web --version
cardstream 0.5.2

Bez prohlížeče, pro sestavy

Stejné zpracování bez prohlížeče: výsledky se vypisují do terminálu. Stejné přepínače jako cardstream-web, jeden proces vedle kamery.

$ cardstream-client --source 0

Používání

Pošlete mu své vysílání

Zdroje jsou výměnné a analýza je stejná, ať zvolíte kterýkoli. Všechno je přepínač; ty důležité přenastavíte za běhu v okně nastavení.

Webkamery a soubory

Webkamera v prohlížeči je výchozí zdroj pro cardstream-web; index kamery, videosoubor nebo statický obrázek fungují všude. Hodí se k vyzkoušení před vysíláním.

$ cardstream-web # webkamera v prohlížeči
$ cardstream-client --source clip.mp4

Stažení streamu

Nasměrujte ho na IP kameru, enkodér nebo restreamovací službu: rtsp://, rtmp://, srt:// a JPEG přes ws://, s opakovaným připojováním s omezeným odstupem.

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

Ať posílá OBS

Spusťte ho jako příjemce a v OBS přidejte jeden výstup RTMP nebo SRT navíc. Potřebuje systémový ffmpeg (brew install ffmpeg).

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

Předvyplnění zúží hledání

Hra, kód edice a písmo se před odesláním ověří lokálně. S --game vždy předejte i --alphabet, protože předvyplněná hra zastaví endpointu jeho vlastní rozpoznávání písma.

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

Okno nastavení

Kategorii, hru, kód edice, písmo i prahy přenastavíte z prohlížeče během streamu. Restart není potřeba a ovládací prvky ověřují hodnoty stejně jako samotný proces.

Tři nastavení rozlišení

Co kamera zachytí, co se odešle a co se analyzuje, jsou tři různá čísla. Analýza běží v malém rozlišení; výřez pro identifikaci se znovu vyřízne z plného snímku.

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

Projděte si vysílání

Uložte vysílání a projděte si ho později

Ve výchozím stavu vypnuto. Jeden přepínač uloží historii, kterou stránka sestavuje (každou kartu, kterou jste ukázali, i s výřezem), do relace ve vašem vlastním účtu Ximilar, takže vysílání tam najdete i druhý den ráno.

Historie s náhledy

Rozhraní v prohlížeči vypisuje každou kartu, kterou jste ukázali, od nejnovější: náhled výřezu, podle kterého byla rozpoznána, její cenu s --price-stats a jak dlouho zůstala na streamu. Tento seznam zůstává na vašem počítači.

Uložení vysílání

--ximilar-stream NEW zahájí relaci a vypíše její ID. Od té chvíle se každý řádek historie ukládá průběžně během vysílání: nahrávání probíhá na pozadí po dávkách, při chybách sítě se opakuje a vysílání nikdy nezdrží. Při řádném ukončení se nahraje zbytek a relace se uzavře.

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

Ukládání vysílání podrobně →

Co se nahrává

Řádky jako text (karta, edice, cena, čas na streamu, placená volání, která za ní stojí) a výřez, podle kterého byl každý řádek rozpoznán, nejvýš 1024 px: tentýž obrázek, který už dostalo identifikační volání. --no-ximilar-stream-images omezí nahrávání jen na text. Váš účet Ximilar potřebuje službu Cards Cloud.

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

Procházení v aplikaci Ximilar

Každá relace se objeví v sekci Cards Cloud aplikace Ximilar: co jste ukázali a kdy, hodnota vysílání, jeho nejcennější produkty a nejčastější edice a každá karta i s výřezem. Označte, co se prodalo, opravte chybnou shodu, přidejte poznámky.

Otevřít aplikaci Ximilar →

Pokračování po restartu

Místo NEW předejte ID relace a vysílání pokračuje ve stejné relaci. I když ji řádné ukončení uzavřelo, jednoduše se znovu otevře. Účtuje se jen zahájení relace, takže pokračování nic nestojí.

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

Týmové pracovní prostory

Relace se uloží do výchozího pracovního prostoru vašeho API klíče. Jiný zadáte přes --ximilar-workspace; stejné ID pak předejte i při pokračování relace, která je uložená tam.

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

Spolehlivý provoz

Jedno identifikační volání na každou novou kartu

O tom, kdy je identifikační volání opravdu namístě, rozhodují lokální signály: pohyb, detekce a filtr identity. Tohle jsou nastavení, která ho drží na uzdě.

Prahy

Práh výsledku nepustí slabé shody do overlaye; práh podobnosti rozhoduje mezi stejnou a novou kartou; forget-after vymaže paměť, když je karta pryč dost dlouho.

$ cardstream-web --result-threshold 0.35

Doporučené spuštění

Segmentace RF-DETR a filtr identity s embeddingem v ONNX, tedy dodávané výchozí nastavení. Samotný příkaz cardstream-web spustí přesně tohle, jakmile jsou váhy na místě; vypsat to celé znamená stejné zpracování.

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

Zůstaňte na localhostu

Lokální aplikace nemá ověřování a drží váš API klíč. --host má výchozí hodnotu 127.0.0.1. Nechte ji tak a port nikdy nezpřístupňujte do místní sítě.

„Model not found“ při spuštění

Váhy modelů se stahují zvlášť, nejsou součástí repozitáře. Instalační skript i obraz Dockeru je stáhnou; do holého klonu repozitáře je musíte nahrát do model/segmentation/ a model/similarity/. scripts/build-from-source.sh --models to udělá za vás.

Zadejte hru, kterou ukazujete

Vysílání s jedinou hrou nepotřebuje, aby endpoint při každém volání hádal hru. Zadejte ji a hledání se zúží na tuto hru: rychlejší odpovědi, méně záměn tisků. Předejte k ní i --alphabet, protože předvyplněná hra zastaví endpointu jeho vlastní rozpoznávání písma.

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

ffmpeg, když ho potřebujete

--listen a --ffmpeg volají systémový ffmpeg. Obyčejné stahování streamu funguje i s instalací jen přes pip, posílání z OBS ne.

Podrobněji

Za hranicí výchozího nastavení

Vyměňte modely nebo si přečtěte kód: celé zpracování je jeden instalovatelný balíček.

Vlastní váhy

Detekce i filtr identity se směrují na backendy: rodina modelu určuje třídu, přípona souboru určuje runtime. RF-DETR nebo RT-DETRv2, .onnx nebo adresář transformers.

Backendy modelů →

Přehled modelů

Všechny váhy, které cardstream umí načíst, natrénované Ximilarem a zveřejněné pod licencí Apache-2.0 spolu s vydáními: co který model dělá, jak rychle běží a pod jakou licencí je.

Přehled modelů →

Stručné odpovědi

Kolik to stojí, co opouští počítač, jaké karty pozná a dva příkazy, které ho zase odstraní.

Přečíst časté dotazy →

README a hlášení problémů

README popisuje každý přepínač; chyby a dotazy patří do hlášení problémů na GitHubu.

Přečíst README →

Vydání a artefakty

Wheely, kontrolní součty a instalační skript, jedna sada na každé vydání. K tomu Docker a sestavení ze zdrojového kódu.

Stránka Stažení →