التوثيق — cardstream

التوثيق

كل شيء يعمل على جهازك: ثبّته، ووجّه إليه كاميرا، واضبط متى يُسمح له بإرسال طلب. مرتَّب بحسب ما تحاول فعله.

التثبيت والتشغيل

من لا شيء إلى بطاقة على الشاشة

أمر واحد يثبّت العميل وأوزان النماذج وملفات shim. وبيانات الاعتماد الوحيدة في النظام كله هي مفتاح Ximilar الخاص بك.

سكربت التثبيت

ينشئ venv في ~/.cardstream، ويتحقق من ملف wheel الخاص بالإصدار بمطابقة مجاميعه الاختبارية، ويجلب أوزان النماذج، ويضع الأمرين كليهما على 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.0

بلا واجهة، للتجهيزات

مسار المعالجة نفسه بلا متصفح: تُطبع النتائج في الطرفية. الخيارات نفسها التي يقبلها 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 px، وهي الصورة التي استلمها طلب التعرّف أصلًا. والخيار --no-ximilar-stream-images يقصر الحفظ على النص. ويحتاج حسابك على Ximilar إلى خدمة Cardstream.

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

راجعه في تطبيق Ximilar

كل جلسة تصل إلى قسم Cardstream في تطبيق 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 والبلاغات

ملف README يغطي كل الخيارات، وصفحة Issues هي مكان الأخطاء والأسئلة.

اقرأ README ←

الإصدارات وملفاتها

ملفات wheel والمجاميع الاختبارية وسكربت التثبيت، طقم واحد لكل إصدار، ومعها Docker والبناء من المصدر.

صفحة التنزيل ←