Dokumentacja

Wszystko działa na Twoim komputerze: zainstaluj, skieruj kamerę i ustaw, kiedy wolno mu wysyłać zapytania. Pogrupowane według tego, co chcesz zrobić.

Instalacja i uruchomienie

Od zera do karty na ekranie

Jedno polecenie instaluje klienta, wagi modeli i shimy. Jedyne dane dostępowe w całym systemie to Twój klucz Ximilar.

Skrypt instalacyjny

Tworzy venv w ~/.cardstream, sprawdza wheel z wydania względem sum kontrolnych, pobiera wagi modeli i umieszcza oba polecenia w Twoim PATH. Pozostałe sposoby (wheel, Docker, kod źródłowy) znajdziesz na stronie pobierania.

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

Wszystkie sposoby instalacji →

Instalacja ręczna

Sklonowane repozytorium i pip też wystarczą. Dodatki (extras) są niezależne: [client] to interfejs i źródła, a [onnx] lub [torch] dostarczają backendy detektora i modelu embeddingów.

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

Twój klucz Ximilar

Identyfikację zapewnia Ximilar collectibles/v2. XIMILAR_API_KEY to jedyna zmienna środowiskowa, którą cokolwiek tu czyta. Cała reszta to flagi.

$ export XIMILAR_API_KEY=your-key

Pierwsze uruchomienie

Otwiera interfejs w przeglądarce z obrazem z kamery internetowej. Pokaż kartę do kamery: nakładka pokazuje, jak maszyna stanów podejmuje decyzję, a potem dopasowanie, gdy tylko nadejdzie.

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

Sprawdź, co masz

Oba polecenia wypisują wersję i kończą pracę. Nie potrzebują plików modeli, więc działa to od razu po zakończeniu instalacji.

$ cardstream-web --version
cardstream 0.5.0

Bez interfejsu, dla setupów

Ten sam potok przetwarzania bez przeglądarki: wyniki trafiają na terminal. Te same flagi co w cardstream-web, jeden proces obok kamery.

$ cardstream-client --source 0

Używanie

Podaj mu swoją transmisję

Źródła są wymienne, a analiza wygląda tak samo bez względu na to, które wybierzesz. Wszystko jest flagą, a najważniejsze z nich okno ustawień zmienia na żywo.

Kamery internetowe i pliki

W cardstream-web domyślna jest kamera internetowa w przeglądarce. Indeks kamery, plik wideo albo pojedynczy obraz działają wszędzie. Dobre do testów przed transmisją.

$ cardstream-web # kamera internetowa w przeglądarce
$ cardstream-client --source clip.mp4

Pobieranie streamu

Skieruj go na kamerę IP, enkoder albo restreamer: rtsp://, rtmp://, srt:// oraz klatki JPEG przez ws://, z ponownym łączeniem w rosnących, ale ograniczonych odstępach.

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

Niech OBS wysyła

Uruchom go w trybie nasłuchu i dodaj w OBS jedno dodatkowe wyjście RTMP lub SRT. Wymaga systemowego programu ffmpeg (brew install ffmpeg).

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

Wartości podane z góry zawężają wyszukiwanie

Gra, kod setu i system pisma są sprawdzane lokalnie, zanim zostaną wysłane. Zawsze podawaj --alphabet razem z --game: po podaniu gry endpoint przestaje samodzielnie wykrywać alfabet.

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

Okno ustawień

Kategorię, grę, kod setu, alfabet i progi można zmieniać z przeglądarki w trakcie streamu: bez restartu, a kontrolki mają tę samą walidację co proces.

Trzy ustawienia rozdzielczości

To, co rejestruje kamera, to, co jest wysyłane, i to, co jest analizowane, to osobne liczby. Analiza działa na małym obrazie, a wycinek do identyfikacji jest wycinany na nowo z pełnej klatki.

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

Przegląd transmisji

Zapisz transmisję, przejrzyj ją później

Domyślnie wyłączone. Jedna flaga zapisuje historię, którą buduje strona (każdą pokazaną kartę razem z jej wycinkiem), do sesji na Twoim koncie Ximilar, więc następnego ranka transmisja wciąż tam jest.

Historia z miniaturami

Interfejs w przeglądarce wymienia każdą pokazaną kartę, od najnowszej: miniaturę zidentyfikowanego wycinka, cenę (z --price-stats) i czas, jaki karta spędziła na streamie. Ta lista żyje na Twoim komputerze.

Zapisz transmisję

Flaga --ximilar-stream NEW rozpoczyna sesję i wypisuje jej id. Od tej chwili każdy wiersz historii jest zapisywany w trakcie transmisji: wysyłki idą partiami w tle, są ponawiane po błędach sieci i nigdy nie wstrzymują transmisji. Poprawne zakończenie pracy wysyła to, co zostało, i zamyka sesję.

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

Zapisywanie transmisji w szczegółach →

Co jest wysyłane

Wiersze jako tekst (karta, set, cena, czas na streamie, stojące za nimi płatne zapytania) oraz wycinek, z którego zidentyfikowano każdy wiersz, najwyżej 1024 px: ten sam obraz, który dostało już zapytanie o identyfikację. Flaga --no-ximilar-stream-images ogranicza zapis do tekstu. Twoje konto Ximilar musi mieć usługę Cardstream.

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

Przejrzyj ją w aplikacji Ximilar

Każda sesja trafia do sekcji Cardstream w aplikacji Ximilar: co i kiedy było pokazane, wartość transmisji, jej najcenniejsze produkty i najczęstsze sety oraz każda karta z wycinkiem. Oznacz, co się sprzedało, popraw błędne dopasowanie, dodaj notatki.

Otwórz aplikację Ximilar →

Wznów po restarcie

Podaj id sesji zamiast NEW, a transmisja potoczy się dalej w tej samej sesji. Nawet jeśli zamknęło ją poprawne zakończenie pracy, po prostu otworzy się ponownie. Płatne jest tylko rozpoczęcie sesji, więc wznowienie nic nie kosztuje.

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

Przestrzenie robocze zespołu

Sesja jest zapisywana w domyślnej przestrzeni roboczej Twojego klucza API. Inną wskażesz flagą --ximilar-workspace. Podaj to samo id, gdy wznawiasz zapisaną tam sesję.

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

Działaj pewnie

Jedno zapytanie o identyfikację na każdą nową kartę

Lokalne sygnały (ruch, detekcja, bramka tożsamości) decydują, kiedy zapytanie o identyfikację jest naprawdę uzasadnione. Oto ustawienia, które trzymają to w ryzach.

Progi

Próg wyniku nie dopuszcza słabych dopasowań do nakładki. Próg podobieństwa rozstrzyga, czy to ta sama karta, czy nowa. Ustawienie forget-after czyści pamięć, gdy karty nie ma wystarczająco długo.

$ cardstream-web --result-threshold 0.35

Zalecane uruchomienie

Segmentacja RF-DETR z bramką embeddingów w ONNX, czyli dostarczane ustawienia domyślne. Samo polecenie cardstream-web uruchamia dokładnie to, gdy wagi są już na miejscu. Wypisanie tych flag wprost daje dokładnie to samo.

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

Zostań na localhost

Lokalna aplikacja nie wymaga uwierzytelniania i przechowuje Twój klucz API. Flaga --host ma domyślną wartość 127.0.0.1. Zostaw ją i nigdy nie wystawiaj portu do sieci LAN.

„Model not found” przy starcie

Wagi modeli pobiera się osobno, nie są częścią repozytorium. Skrypt instalacyjny i obraz Docker pobierają je automatycznie. Przy samym sklonowanym repozytorium trzeba je umieścić w model/segmentation/ i model/similarity/, co zrobi za Ciebie scripts/build-from-source.sh --models.

Podaj grę, którą pokazujesz

Przy transmisji z jedną grą endpoint nie musi zgadywać gry przy każdym zapytaniu. Podaj ją, a wyszukiwanie zawęzi się do tej gry: szybsze odpowiedzi, mniej pomyłek co do wersji karty. Dodaj do tego --alphabet, bo po podaniu gry endpoint przestaje samodzielnie wykrywać system pisma.

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

ffmpeg, gdy jest potrzebny

Flagi --listen i --ffmpeg uruchamiają systemowy program ffmpeg. Zwykłe pobieranie streamu działa, gdy instalujesz wyłącznie przez pip. Wariant z wysyłaniem z OBS już nie.

Głębiej

Poza ustawienia domyślne

Podmień modele albo przeczytaj kod: całość to jeden instalowalny pakiet.

Własne wagi

Detekcja i bramka tożsamości same dobierają backend: rodzina modelu wyznacza klasę, a rozszerzenie pliku środowisko uruchomieniowe. RF-DETR albo RT-DETRv2, plik .onnx albo katalog transformers.

Backendy modeli →

Katalog modeli

Wszystkie wagi, które cardstream potrafi wczytać, wytrenowane przez Ximilar i publikowane na licencji Apache-2.0 razem z wydaniami: co robi każdy model, jak szybko działa i na jakiej jest licencji.

Katalog modeli →

Krótkie pytania, krótkie odpowiedzi

Ile to kosztuje, co opuszcza komputer, jakie karty rozpoznaje i dwa polecenia, które to wszystko usuwają.

Przeczytaj FAQ →

README i zgłoszenia

README opisuje każdą flagę, a zgłoszenia (issues) to miejsce na błędy i pytania.

Przeczytaj README →

Wydania i pliki

Wheele, sumy kontrolne i skrypt instalacyjny, jeden komplet na wydanie, a do tego Docker i budowanie ze źródeł.

Strona pobierania →