Shuffle practice

This project has tools to inspect shuffles of a deck of playing cards.

Setup

Install torch using official instructions. The remaining dependencies are in requirements.txt.

python3 -m pip install -r requirements.txt

This project makes use of

• segment-anything for segmenting cards in an image,
• open_clip for labeling cards.

For segmentation, the vit_b model checkpoint is needed. Download and place it in data/sam_model/.

This project was developed on a cpu-only machine, and might be missing options to make use of a gpu.

All code has to be run from src/.

Data

Example images of a sequence of shuffles are in data/capture. The images have a capture_id of 20251008. Scripts for further processing use this capture_id.

Each image is of a full deck of cards laid out against a dark background. The order of cards is left-to-right, top-to-bottom. If the cards were stacked face down, the bottom-most card is considered the first card, and would be the top left card in an image. Similarly, the top-most card in a face-down stack is considered the last card, and would be the bottom right card in an image.

There are 8 images of decks in the example. One riffle shuffle was performed between each, for a total of 7 riffle shuffles between the first and last deck.

Segmentation

To segment each image into individual cards, run

python3 segmentation.py -c ../config/segmentation/example.yaml

The example.yaml config file has documentation on options. Segments are saved as images in data/segmentation. Representatives outputs are included in the repo. Results from running the script again may vary.

Segmentation uses SAM to generate masks, followed by some simple filtering of segments.

Classification

To label each card segment, run

python3 classification.py -c ../config/classification/example.yaml

The example.yaml config file has documentation on options. Predictions are saved as text files in data/classification. Representatives outputs are included in the repo. Results from running the script again may vary.

Labeling uses open_clip for zero-shot classification.

Manually labeled annotations are in data/annotation. Accuracy for the example images can be calculated with

python3 compute_classification_accuracy.py --capture-id 20251008

Model evaluation

A script to evaluate different models on the card classification task is clip_eval.py. To use it, first run

python3 clip_eval.py --load-models-only

to download models. Then run

python3 clip_eval.py --capture-id 20251008 --save-results

Representative output is in data/clip_eval_results.csv.

The accuracy of predictions by classification.py is better than that calculated by clip_eval.py for the same model. This is because classification.py uses a better strategy for assigning classes to instances from predicted scores.

Permutation stats

To calculate some permutation stats between the shuffles, run

python3 permutation_stats.py --capture-id 20251008

If a pair of indices is provided, the permutation matrix is also visualized.

# first shuffle
python3 permutation_stats.py --capture-id 20251008 --pairs 0 1
# all shuffles
python3 permutation_stats.py --capture-id 20251008 --pairs 0 -1