תיעוד — cardstream

תיעוד

הכול רץ על המחשב שלכם: מתקינים, מכוונים אליו מצלמה, וקובעים מתי מותר לו לשלוח קריאה החוצה. מסודר לפי מה שאתם מנסים לעשות.

התקנה והרצה

מכלום ועד קלף על המסך

פקודה אחת מתקינה את הלקוח, את משקלי המודלים ואת קובצי ה-shim. פרט הגישה היחיד בכל המערכת הוא מפתח Ximilar שלכם.

סקריפט ההתקנה

יוצר venv בתיקייה ~/.cardstream, מאמת את קובץ ה-wheel של הגרסה מול ה-checksums שלו, מוריד את משקלי המודלים ומכניס את שתי הפקודות ל-PATH. שאר הדרכים (wheel, Docker, קוד מקור) נמצאות בעמוד ההורדה.

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

כל דרכי ההתקנה ←

התקנה ידנית

אפשר גם עם עותק של המאגר ו-pip. התוספות בלתי תלויות זו בזו: [client] הוא הממשק והמקורות, ואילו [onnx] או [torch] מספקים את המנועים לגלאי ולמודל ההטמעה.

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

מפתח Ximilar שלכם

הזיהוי מבוסס על Ximilar collectibles/v2. XIMILAR_API_KEY הוא משתנה הסביבה היחיד שמשהו קורא; כל השאר הוא דגל.

$ export XIMILAR_API_KEY=your-key

הרצה ראשונה

פותחת את ממשק הדפדפן על מצלמת הרשת. מחזיקים קלף מול המצלמה; שכבת-העל מראה את מכונת המצבים חושבת, ואת ההתאמה כשהיא מגיעה.

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

בדיקה של מה שמותקן

שתי הפקודות מדפיסות את הגרסה שלהן ויוצאות. לא צריך קובצי מודל, כך שזה עובד ברגע שההתקנה מסתיימת.

$ cardstream-web --version
cardstream 0.5.2

בלי ממשק, למערכות

אותו צינור בלי דפדפן: התוצאות מודפסות בטרמינל. אותם דגלים כמו cardstream-web, תהליך אחד ליד המצלמה.

$ cardstream-client --source 0

שימוש

מזינים אליו את השידור

המקורות ניתנים להחלפה, והניתוח זהה בכל מקור שבוחרים. הכול נקבע בדגלים; חלון ההגדרות מכוונן את החשובים שבהם תוך כדי שידור.

מצלמות רשת וקבצים

מצלמת הרשת של הדפדפן היא ברירת המחדל של cardstream-web; אינדקס, קובץ וידאו או תמונה סטטית עובדים בכל מקום. טוב לבדיקה לפני השידור.

$ cardstream-web # מצלמת הרשת של הדפדפן
$ cardstream-client --source clip.mp4

משיכת זרם

מכוונים אותו אל מצלמת IP, מקודד או שירות ריסטרים: rtsp://, rtmp://, srt:// וזרמי JPEG ב-ws://, עם התחברות מחדש בהשהיות מוגבלות.

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

דחיפה מ-OBS

מריצים אותו כמאזין ומוסיפים ב-OBS עוד פלט RTMP או SRT. דורש את קובץ ההפעלה ffmpeg של המערכת (brew install ffmpeg).

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

מילוי מראש מצמצם את החיפוש

משחק, קוד סט ומערכת כתב נבדקים מקומית לפני שהם נשלחים. תמיד מעבירים --alphabet יחד עם --game: מילוי מראש של המשחק מונע מנקודת הקצה לזהות את האלפבית בעצמה.

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

חלון ההגדרות

קטגוריה, משחק, קוד סט, אלפבית וספים ניתנים לכוונון מהדפדפן באמצע השידור: בלי הפעלה מחדש, והפקדים עוברים את אותו אימות כמו התהליך.

שלוש הגדרות רזולוציה

מה שהמצלמה מצלמת, מה שנשלח ומה שמנותח הם שלושה מספרים נפרדים. הניתוח רץ ברזולוציה קטנה; תמונת החיתוך לזיהוי נחתכת מחדש מהפריים המלא.

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

סקירת השידור

שומרים את השידור, עוברים עליו אחר כך

כבוי כברירת מחדל. דגל אחד שומר את ההיסטוריה שהעמוד בונה (כל קלף שהצגתם, עם תמונת החיתוך שלו) בסשן בחשבון Ximilar שלכם, כך שהשידור עדיין שם למחרת בבוקר.

ההיסטוריה, עם תמונות ממוזערות

ממשק הדפדפן מציג כל קלף שהצגתם, מהחדש לישן: תמונה ממוזערת של תמונת החיתוך שזוהתה, המחיר שלו עם --price-stats, וכמה זמן הוא נשאר בשידור. הרשימה הזאת נשמרת על המחשב שלכם.

שמירת שידור

--ximilar-stream NEW פותח סשן ומדפיס את המזהה שלו. מאותו רגע כל שורה בהיסטוריה נשמרת תוך כדי השידור: ההעלאות נאספות לקבוצות ברקע, נשלחות שוב בשגיאות רשת ואף פעם לא מעכבות את השידור. יציאה תקינה מעלה את מה שנשאר וסוגרת את הסשן.

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

שמירת שידור, בפירוט ←

מה מועלה

השורות כטקסט (קלף, סט, מחיר, זמן בשידור, הקריאות בתשלום שמאחוריהן) ותמונת החיתוך שממנה זוהתה כל שורה, עד 1024 פיקסלים: התמונה שקריאת הזיהוי כבר קיבלה. --no-ximilar-stream-images שומר טקסט בלבד. חשבון Ximilar שלכם צריך את שירות Cards Cloud.

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

סקירה באפליקציית Ximilar

כל סשן מגיע לאזור Cards Cloud באפליקציית Ximilar: מה הצגתם ומתי, שווי השידור, המוצרים היקרים ביותר והסטים המובילים, וכל קלף עם תמונת החיתוך שלו. מסמנים מה נמכר, מתקנים התאמה שגויה, מוסיפים הערות.

לאפליקציית Ximilar ←

המשך אחרי הפעלה מחדש

מעבירים את מזהה הסשן במקום NEW, והשידור ממשיך באותו סשן: גם אם יציאה תקינה סגרה אותו, הוא פשוט נפתח מחדש. רק פתיחת סשן מחויבת, כך שהמשך לא עולה כלום.

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

סביבות עבודה של צוות

סשן נשמר בסביבת העבודה שמוגדרת כברירת מחדל למפתח ה-API שלכם. אפשר לציין אחרת עם --ximilar-workspace, ולהעביר את אותו מזהה כשממשיכים סשן שנשמר שם.

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

הפעלה בביטחון

קריאת זיהוי אחת לכל קלף שונה

אותות מקומיים (תנועה, איתור, מסנן הזהות) מחליטים מתי קריאת זיהוי באמת מוצדקת. אלה ההגדרות שמחזיקות את זה בשליטה.

ספים

סף התוצאה מרחיק התאמות חלשות משכבת-העל; סף הדמיון מכריע בין אותו קלף לקלף חדש; forget-after מוחק את הזיכרון אחרי שקלף נעדר מספיק זמן.

$ cardstream-web --result-threshold 0.35

ההרצה המומלצת

סגמנטציה עם RF-DETR ומסנן הטמעה ב-ONNX: ברירות המחדל שמגיעות עם החבילה. cardstream-web בלי דגלים מריץ בדיוק את זה ברגע שהמשקלים במקום; לכתוב את הכול במפורש זה אותו צינור.

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

נשארים ב-localhost

האפליקציה המקומית פועלת בלי אימות ומחזיקה את מפתח ה-API שלכם. ברירת המחדל של --host היא 127.0.0.1: משאירים אותה כך ולעולם לא חושפים את הפורט לרשת המקומית.

"Model not found" בהפעלה

משקלי המודלים הם הורדה נפרדת, לא חלק מהמאגר. סקריפט ההתקנה ותמונת ה-Docker מורידים אותם; עותק נקי של המאגר צריך שיניחו אותם בתיקיות model/segmentation/ ו-model/similarity/. הפקודה scripts/build-from-source.sh --models עושה את זה בשבילכם.

מציינים את המשחק שמוצג

שידור של משחק אחד לא צריך שנקודת הקצה תנחש את המשחק בכל קריאה. מציינים אותו, והחיפוש מצטמצם למשחק הזה: תשובות מהירות יותר, פחות הדפסות שגויות. מעבירים איתו גם --alphabet, כי מילוי מראש של המשחק מונע מנקודת הקצה לזהות את מערכת הכתב בעצמה.

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

ffmpeg, כשצריך אותו

--listen וגם --ffmpeg מפעילים את קובץ ההפעלה ffmpeg של המערכת. משיכה רגילה עובדת גם בהתקנה עם pip בלבד; מערך הדחיפה מ-OBS לא.

לעומק

מעבר לברירות המחדל

מחליפים מודלים או קוראים את הקוד: כל הצינור הוא חבילה אחת שמתקינים.

משקלים משלכם

האיתור ומסנן הזהות מנותבים לפי מנוע: המשפחה בוחרת את המחלקה, וסיומת הקובץ בוחרת את סביבת הריצה. RF-DETR או RT-DETRv2, קובץ .onnx או תיקיית transformers.

מנועי המודלים ←

גן המודלים

כל משקל ש-cardstream יכול לטעון, שאומן על ידי Ximilar ופורסם ברישיון Apache-2.0 יחד עם הגרסאות: מה כל אחד עושה, באיזו מהירות הוא רץ, ומה הרישיון שלו.

גן המודלים ←

תשובות קצרות

כמה זה עולה, מה יוצא מהמחשב, אילו קלפים הוא מזהה, ושתי הפקודות שמסירות אותו.

לשאלות הנפוצות ←

README ו-Issues

ה-README מתעד כל דגל; ב-Issues מדווחים על באגים ושואלים שאלות.

לקריאת ה-README ←

גרסאות וקבצים

קובצי wheel, checksums וסקריפט ההתקנה, סט אחד לכל גרסה, וגם בנייה עם Docker ומקוד המקור.

לעמוד ההורדה ←