Tài liệu — cardstream

Tài liệu

Mọi thứ chạy trên máy của bạn: cài đặt, hướng camera vào, rồi chỉnh xem khi nào nó được phép gọi ra ngoài. Sắp xếp theo việc bạn đang muốn làm.

Cài đặt và chạy

Từ con số không đến một tấm thẻ trên màn hình

Một lệnh cài client, trọng số mô hình và các shim. Thông tin xác thực duy nhất trong cả hệ thống là key Ximilar của bạn.

Script cài đặt

Tạo một venv trong ~/.cardstream, đối chiếu wheel của bản phát hành với checksum, tải trọng số mô hình và đặt cả hai lệnh lên PATH của bạn. Các cách cài khác (wheel, Docker, mã nguồn) nằm ở trang tải về.

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

Mọi cách cài đặt →

Cài thủ công

Một bản checkout cùng pip cũng được. Các extra độc lập với nhau: [client] là giao diện và các nguồn hình, [onnx] hoặc [torch] cung cấp backend cho bộ phát hiện và embedding.

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

Key Ximilar của bạn

Việc nhận diện chạy bằng Ximilar collectibles/v2. XIMILAR_API_KEY là biến môi trường duy nhất được đọc; mọi thứ khác đều là cờ.

$ export XIMILAR_API_KEY=your-key

Lần chạy đầu tiên

Mở giao diện trình duyệt với webcam của bạn. Đưa một tấm thẻ lên; overlay cho thấy máy trạng thái đang suy nghĩ, rồi đến kết quả khớp khi nó về.

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

Kiểm tra thứ bạn đang có

Cả hai lệnh in ra phiên bản rồi thoát. Không cần tệp mô hình nào, nên dùng được ngay khi cài đặt xong.

$ cardstream-web --version
cardstream 0.5.0

Headless, cho các dàn máy

Vẫn pipeline đó nhưng không có trình duyệt: kết quả in ra terminal. Cùng các cờ như cardstream-web, một tiến trình ngay cạnh camera.

$ cardstream-client --source 0

Sử dụng

Đưa buổi live của bạn vào

Nguồn hình thay được tùy ý, và dù bạn chọn nguồn nào thì việc phân tích vẫn y hệt. Mọi thứ đều là cờ; những cờ quan trọng chỉnh lại được trực tiếp trong hộp thoại cài đặt.

Webcam và tệp

Webcam của trình duyệt là mặc định của cardstream-web; chỉ số webcam, tệp video hay ảnh tĩnh thì dùng được ở mọi nơi. Rất hợp để thử trước buổi live.

$ cardstream-web # webcam của trình duyệt
$ cardstream-client --source clip.mp4

Kéo một luồng về

Trỏ nó vào một camera IP, một encoder hoặc một dịch vụ restream: rtsp://, rtmp://, srt:// và luồng JPEG qua ws://, tự kết nối lại với thời gian chờ tăng dần có giới hạn.

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

Để OBS đẩy sang

Chạy nó ở chế độ lắng nghe và thêm một đầu ra RTMP hoặc SRT trong OBS. Cần có ffmpeg cài trên hệ thống (brew install ffmpeg).

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

Điền sẵn để thu hẹp tìm kiếm

Game, mã set và hệ chữ viết được kiểm tra cục bộ trước khi gửi đi. Hễ truyền --game thì truyền luôn --alphabet, vì khi đã điền sẵn game, endpoint sẽ không tự nhận biết hệ chữ viết nữa.

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

Hộp thoại cài đặt

Danh mục, game, mã set, hệ chữ viết và các ngưỡng đều chỉnh lại được từ trình duyệt ngay giữa stream: không phải khởi động lại, và các nút điều khiển áp dụng cùng phép kiểm tra giá trị như tiến trình.

Ba mức chỉnh độ phân giải

Thứ camera thu, thứ được gửi đi và thứ được phân tích là ba con số riêng. Việc phân tích chạy ở kích thước nhỏ; ảnh cắt để nhận diện được cắt lại từ khung hình đầy đủ.

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

Xem lại buổi live

Lưu buổi live, xem lại sau

Mặc định là tắt. Một cờ sẽ lưu lịch sử mà trang dựng lên, tức mọi tấm thẻ bạn đã đưa lên kèm ảnh cắt của nó, vào một phiên trong tài khoản Ximilar của chính bạn, để sáng hôm sau buổi live vẫn còn đó.

Lịch sử, kèm ảnh thu nhỏ

Giao diện trình duyệt liệt kê mọi tấm thẻ bạn đã đưa lên, mới nhất ở trên cùng: ảnh thu nhỏ của ảnh cắt đã được nhận diện, giá của nó nếu có --price-stats, và thời gian nó ở trên stream. Danh sách này nằm trên máy của bạn.

Lưu một buổi live

--ximilar-stream NEW bắt đầu một phiên và in ra id của nó. Từ đó, mỗi dòng lịch sử được lưu dần trong lúc buổi live diễn ra: việc tải lên được gom thành lô ở chế độ nền, tự thử lại khi lỗi mạng và không bao giờ làm chậm buổi live. Khi thoát bình thường, phần còn lại được tải lên và phiên được đóng.

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

Lưu buổi live, đầy đủ chi tiết →

Những gì được tải lên

Các dòng ở dạng văn bản (thẻ, set, giá, thời gian trên stream, các lượt gọi tính phí đứng sau) và ảnh cắt mà mỗi dòng được nhận diện từ đó, tối đa 1024 px: chính là bức ảnh mà lượt gọi nhận diện đã nhận. --no-ximilar-stream-images thì chỉ lưu văn bản. Tài khoản Ximilar của bạn cần có dịch vụ Cardstream.

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

Xem lại trong ứng dụng Ximilar

Mọi phiên đều về mục Cardstream của ứng dụng Ximilar: bạn đã đưa lên gì và khi nào, giá trị của buổi live, các sản phẩm giá trị nhất và các set đứng đầu, cùng từng tấm thẻ kèm ảnh cắt. Đánh dấu thẻ đã bán, sửa một kết quả sai, thêm ghi chú.

Mở ứng dụng Ximilar →

Tiếp tục sau khi khởi động lại

Truyền id của phiên thay cho NEW, và buổi live tiếp tục trong cùng phiên đó. Kể cả khi một lần thoát bình thường đã đóng phiên, nó chỉ việc mở lại. Chỉ việc bắt đầu một phiên mới bị tính phí, nên tiếp tục thì không tốn gì.

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

Workspace của nhóm

Phiên được lưu trong workspace mặc định của API key. Chỉ định một workspace khác bằng --ximilar-workspace, và truyền đúng id đó khi bạn tiếp tục một phiên đã lưu ở đấy.

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

Vận hành thật vững

Một lượt gọi nhận diện cho mỗi thẻ khác nhau

Các tín hiệu cục bộ (chuyển động, phát hiện, bộ lọc trùng thẻ) quyết định khi nào một lượt gọi nhận diện thật sự đáng thực hiện. Đây là những tùy chỉnh giữ cho điều đó luôn đúng.

Các ngưỡng

Ngưỡng kết quả giữ các kết quả khớp yếu không lên overlay; ngưỡng tương đồng quyết định thẻ cũ hay thẻ mới; forget-after xóa bộ nhớ khi một tấm thẻ đã vắng mặt đủ lâu.

$ cardstream-web --result-threshold 0.35

Cấu hình chạy khuyến nghị

Phân đoạn bằng RF-DETR cùng một bộ lọc embedding ONNX: đây là mặc định đi kèm. Lệnh cardstream-web trần chạy đúng cấu hình này khi trọng số đã ở đúng chỗ; viết đầy đủ ra thì vẫn là pipeline đó.

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

Giữ nó ở localhost

Ứng dụng cục bộ không có xác thực và đang giữ API key của bạn. --host mặc định là 127.0.0.1: cứ để nguyên và đừng bao giờ mở cổng ra mạng LAN.

“Model not found” khi khởi động

Trọng số mô hình phải tải riêng, không nằm trong repo. Script cài đặt và image Docker tự tải chúng; một bản checkout trần thì cần đặt chúng vào model/segmentation/ và model/similarity/. scripts/build-from-source.sh --models làm việc đó giúp bạn.

Chỉ rõ game bạn đang đưa lên

Một buổi live chỉ có một game thì không cần endpoint đoán game ở mỗi lượt gọi. Gọi tên nó ra và việc tìm kiếm thu hẹp về game đó: trả lời nhanh hơn, ít nhầm bản in hơn. Truyền kèm --alphabet, vì khi đã điền sẵn game, endpoint sẽ không tự nhận biết hệ chữ viết nữa.

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

ffmpeg, khi bạn cần đến

--listen và --ffmpeg gọi ffmpeg cài trên hệ thống. Kéo luồng thông thường chạy được với bản cài chỉ bằng pip; cấu hình để OBS đẩy sang thì không.

Đào sâu hơn

Vượt ra ngoài mặc định

Đổi mô hình hoặc đọc mã: cả pipeline là một gói cài đặt duy nhất.

Mang trọng số của riêng bạn

Việc phát hiện và bộ lọc trùng thẻ được định tuyến theo backend: họ mô hình chọn lớp, phần mở rộng của tệp chọn runtime. RF-DETR hoặc RT-DETRv2, .onnx hoặc một thư mục transformers.

Các backend mô hình →

Kho mô hình

Mọi bộ trọng số cardstream có thể nạp, do Ximilar huấn luyện và công bố theo Apache-2.0 cùng các bản phát hành: mỗi bộ làm gì, chạy nhanh đến đâu và theo giấy phép nào.

Kho mô hình →

Trả lời ngắn gọn

Tốn bao nhiêu, thứ gì rời khỏi máy, nó gọi tên được những thẻ nào, và hai lệnh để gỡ nó đi.

Đọc phần hỏi đáp →

README và issue

README nói về mọi cờ; issue là nơi dành cho lỗi và câu hỏi.

Đọc README →

Bản phát hành và artifact

Wheel, checksum và script cài đặt, mỗi bản phát hành một bộ, cùng với Docker và bản build từ mã nguồn.

Trang tải về →