This repository contains a complete Computer Vision pipeline to detect, segment, and classify poker cards from raw images. By combining traditional image processing with an ensemble of Machine Learning classifiers (KNN, SVM, Random Trees), the system achieves a highly robust 97.3% final card classification accuracy.
The system processes raw images through a carefully designed pipeline:
-
Card Extraction & Cropping We start by identifying the largest white contour in the image, computing its bounding box, and applying a perspective transform (homography) to flatten and extract the card upright.
-
Motif Finding Using connected component analysis on the cropped card, we isolate the internal characters (numbers/letters) and suits, collectively referred to as "motifs".
-
Feature Extraction For each isolated motif, a set of 102 descriptive features is computed:
- Geometric Features: Basic shape metrics including aspect ratio, solidity, extent, equivalent diameter, and relative centroid position.
- Hu Moments: A set of 7 rotation-invariant structural descriptors.
- Spatial Histogram: A 9x9 normalized spatial grid mapping the pixel density of the contour. This feature is the most impactful, effectively capturing the internal structural layout of the motifs.
Figure 2: Example of 3x2 Spatial Histogram. It splits the motif contour into a grid to calculate point density, uniquely mapping the structural geometry. -
Classifier Training The extracted features are normalized and fed into three distinct machine learning classifiers: K-Nearest Neighbors (KNN), Support Vector Machines (SVM), and Random Forests (RF).
-
Direct Card Classification (Ensemble Voting) The final card identity is classified using a majority voting mechanism over the predicted motifs from all three models. This ensemble approach successfully mitigates the individual weaknesses of each classifier.
We conducted an ablation study to measure the impact of each feature subset. The inclusion of the Spatial Histogram dramatically improved the baseline performance, pushing KNN motif accuracy to over 99%.
| Configuration | KNN Acc | SVM Acc | RF Acc |
|---|---|---|---|
| Baseline (Geometry Only) | 91.52% | 90.68% | 93.02% |
| Geometry + Hu Moments | 90.26% | 92.54% | 93.99% |
| Geometry + Spatial Histogram | 99.04% | 97.35% | 98.44% |
| All Features (Base+Hu+Hist) | 98.98% | 97.05% | 98.62% |
When combining the motif predictions to classify the entire card, the individual models perform as follows:
- KNN Model: 93.0%
- SVM Model: 89.9%
- Random Forest (RF): 94.7%
🏆 Ensemble Result (KNN + SVM + RF): 97.3%
First, ensure you have the necessary dependencies installed:
pip install -r requirements.txtTo test the complete pipeline on a single image and view the classification process visually, run the demo script:
python demo.py --image demo/demo_card.jpg- Feature Selection: Identify and retain only the most impactful geometric and spatial features to reduce dimensionality, remove noise, and improve classification speed.
- Model Tuning: Perform systematic hyperparameter tuning (e.g., Grid Search) to optimize the underlying SVM configurations (Kernel type, C parameter) and Random Forest parameters (max depth, number of trees).
- Different Models: Explore end-to-end Deep Learning architectures like Convolutional Neural Networks (CNNs), which could naturally resolve orientation ambiguities (like 6 vs 9) without requiring manual feature extraction.
Despite the high accuracy, the system has a few known edge cases:
- 6 / 9 Confusion: Because the numbers 6 and 9 are geometrically symmetrical upon rotation, they can be easily confused depending on orientation.
- Q / 0 (10) Confusion: The rounded internal structures of a Queen ('Q') and a '10' ('0' internally) appear very similar under harsh lighting or glare.
- Blurred Images: Excessive blur merges the contours during the thresholding step, causing the connected component analysis to fail entirely.