Twibot YOLOv5 — Twinit Card Detector

A fine-tuned YOLOv5s object detector that locates Twinit game cards on a black background. Exported to TorchScript for fast inference from both Python and C++ (LibTorch).

It is the detection stage of the Twibot project, a bot that plays the Twinit card-matching game. The full pipeline crops each detected card and pairs identical ones using SIFT descriptors and a FLANN matcher.


Architecture	YOLOv5s (fine-tuned)
Format	TorchScript (`best.torchscript`)
Input	RGB image, 640×640 letterboxed, normalized to [0, 1]
Classes	`card`, `hand` (see `card.names`)
Size	~7.5 MB
Inference	~5 ms on NVIDIA GTX 1060

Files

best.torchscript — TorchScript-exported YOLOv5s weights.
card.names — class label file, one class per line.

Intended use

Use this model as the detection front-end for a Twinit-playing pipeline: locate cards in a frame, then feed the cropped boxes to a downstream matcher (e.g. SIFT + FLANN, as in the original repo).

It is not a general playing-card detector — it has only been trained on Twinit cards laid out on a dark surface.

Out-of-scope use

Detecting cards from other games (poker, Magic, Uno, …).
Cards on busy or light backgrounds.
Cards at extreme angles or heavily occluded.
Any safety-critical application.

Usage

Python (PyTorch)

import cv2
import torch

model = torch.jit.load("best.torchscript", map_location="cpu").eval()

img = cv2.imread("scene.jpg")                # HxWx3, BGR
img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
resized = cv2.resize(img_rgb, (640, 640))    # use a letterbox helper in practice
tensor = (
    torch.from_numpy(resized)
    .permute(2, 0, 1)
    .float()
    .unsqueeze(0)
    / 255.0
)

with torch.no_grad():
    raw = model(tensor)[0]                   # [1, 25200, 7] -> 4 bbox + obj + 2 cls

# Apply confidence + NMS filtering — see the repo for a full example.

C++ (LibTorch + OpenCV)

The original repository ships a complete C++ runner under twibotcpp/, including letterbox preprocessing and NMS post-processing.

Recommended thresholds

Parameter	Value
Confidence threshold	`0.4`
NMS IoU threshold	`0.6`

Training

Base model: YOLOv5s.
Dataset: a small custom set of Twinit cards on a black background, manually annotated by the author. The dataset is not publicly released.
Hardware: NVIDIA GeForce GTX 1060.
Framework: ultralytics/yolov5.

See the project repository for the full training context.

Limitations and biases

Trained on a single, small dataset captured in a fixed setup (black background, indoor lighting). Domain shift will hurt accuracy.
The hand class has very limited training signal compared to card.
Generalization to other camera angles, lighting conditions, or card layouts has not been validated.

Source code

Full project (Python + C++ inference, training notes, SIFT-based matcher): https://github.com/adlane98/twibot

Downloads last month: -; Downloads are not tracked for this model. How to track