Card Perception

Production-oriented computer vision for low-latency playing-card perception: reproducible single-card classification today, detector-plus-classifier multi-card video perception next.

This repository contains a modular PyTorch pipeline for single-card classification and the foundation for detector-plus-classifier multi-card video perception. The project started from a notebook baseline and was refactored into an experiment platform with reproducible configs, observability, model export, inference schemas, and latency benchmarking.

Why It Exists

This is a portfolio-grade ML engineering project: the interesting work is not just the final accuracy number, but the path from an unreliable notebook baseline to an exportable, measured, documented perception stack.

The project is intentionally scoped to perception. It does not include game strategy, betting logic, browser automation, or execution automation.

Current Champion

The current clean single-card champion is convnext_tiny_staged:

Model	Task	Accuracy	Macro F1	GPU P50 Latency	Params	Export
ConvNeXt-Tiny staged fine-tune	53-class card classification	99.25%	99.24%	2.66 ms	27.86M	TorchScript, ONNX

This is a clean public-dataset result. It should not be interpreted as live-video production readiness until target-domain crop, reject-case, and detector evaluations are complete.

Architecture

Current Case A pipeline:

flowchart LR
    A[Clean card image] --> B[Data transforms]
    B --> C[PyTorch model registry]
    C --> D[Training loop]
    D --> E[Evaluation reports]
    D --> F[TensorBoard / W&B logs]
    D --> G[Best checkpoint]
    G --> H[Batch-1 latency benchmark]
    G --> I[TorchScript / ONNX export]
    G --> J[Confidence-aware inference]

Loading

Target Case B direction:

flowchart LR
    A[Live table frame] --> B[Frame / ROI extraction]
    B --> C[Card-region detector]
    C --> D[Card crops]
    D --> E[ConvNeXt card classifier]
    E --> F[Confidence + abstention]
    F --> G[Temporal voting hooks]
    G --> H[Perception events]

Loading

Engineering Surface

• PyTorch model training with custom CNN and pretrained backbone experiments
• staged fine-tuning for transfer learning
• batch-1 latency and memory benchmarking
• ONNX and TorchScript export
• TensorBoard and W&B-compatible observability
• confidence, calibration, and abstention hooks
• dataset manifests and provenance-oriented experiment artifacts
• roadmap from single-card classification to multi-card localization

Evidence Trail

• Clean leaderboard
• Sanitized leaderboard JSON
• ConvNeXt-Tiny model card
• Clean dataset card
• Target-domain data plan
• Multi-card detection roadmap
• Detector dataset workflow
• Detector annotation guide
• Publication plan

Repository Layout

card_perception/
  configs/        experiment and data configs
  docs/           reports, model cards, dataset cards, data policies
  scripts/        training, evaluation, benchmark, export CLIs
  src/            package source
  tests/          unit and smoke tests
plans/            implementation and publication plans

Quick Start

Create or activate a Python environment with PyTorch installed, then install the package:

cd card_perception
pip install -e ".[extras]"

Run a smoke experiment:

python scripts/run_experiment.py --config configs/experiments/notebook_cnn_v1_baseline_smoke.yaml

Run the current clean champion config when the public card dataset is available locally:

python scripts/run_experiment.py --config configs/experiments/convnext_tiny_staged.yaml

Useful command entry points:

python scripts/train.py --config configs/experiments/convnext_tiny_staged.yaml
python scripts/evaluate.py --config configs/experiments/convnext_tiny_staged.yaml --checkpoint path/to/checkpoint-file
python scripts/benchmark_inference.py --config configs/experiments/convnext_tiny_staged.yaml --checkpoint path/to/checkpoint-file
python scripts/export_model.py --config configs/experiments/convnext_tiny_staged.yaml --checkpoint path/to/checkpoint-file

Single-Image Demo

Run confidence-aware inference without requiring the original training dataset:

python examples/inference_single_image.py \
  --checkpoint path/to/trusted-checkpoint.pt \
  --image examples/assets/synthetic_ace_of_spades.png \
  --threshold 0.80 \
  --warmup-runs 3

The JSON output includes predicted labels, confidence, abstention state, reason, and warmed batch-1 latency. Checkpoints are user-provided and are not committed to this repository.

See the inference demo guide and output schema example.

Data Policy

This repository does not include private live-feed recordings, extracted private frames, third-party dataset mirrors, checkpoints, or exported model binaries. See Public Data Policy.

Scope

In scope:

• perception
• inference
• latency
• exportability
• calibration and abstention
• dataset and experiment governance
• future detector-plus-classifier video perception

Out of scope:

• betting logic
• game strategy
• browser automation
• anti-bot or evasion work
• execution/clicking automation

Reports

• Case A clean leaderboard
• Multi-card data audit and prep plan
• Multi-card detection next steps
• Publication plan

Roadmap

• M1: public classifier release with model/data cards and reproducible configs
• M2: confidence-aware inference demo and export showcase
• M3: private target-domain crop and detector dataset pilots
• M4: single-class card detector and YOLO-style baseline
• M5: detector-plus-classifier multi-card perception prototype
• M6: temporal smoothing, active learning, and deployment optimization

License

Code is released under the Apache License 2.0. Dataset and model artifact availability may have separate licensing and provenance constraints.