Reconhecimento de cartas com visão computacional

Projeto de detecção de objetos que identifica cartas de um baralho padrão pela webcam. Ele usa Ultralytics YOLO para localizar as cartas no quadro e classificá-las em uma das 52 combinações possíveis de valor e naipe.

Exemplos de classes: A_Espada, 10_Ouro, Q_Copas e K_Paus.

Como o projeto funciona

O fluxo é dividido em três partes:

1. Criar_diretórios.py organiza e copia as imagens e anotações de um dataset de cartas para a estrutura esperada pela YOLO.
2. YOLO_train.py treina o modelo yolo11s.pt com esse dataset. O resultado esperado é um arquivo de pesos, normalmente best.pt.
3. webcam.py abre a câmera principal, carrega best.pt e desenha na tela as detecções cuja confiança seja de pelo menos 50%.

Estrutura

.
├── Criar_diretórios.py  # prepara o dataset local
├── YOLO_train.py        # treinamento (configurado para Google Colab)
├── webcam.py            # inferência em tempo real
├── data.yaml            # caminhos e 52 classes do dataset
└── dataset/
    ├── images/{train,val,test}/
    └── labels/{train,val,test}/

As anotações devem estar no formato YOLO: um arquivo .txt por imagem, contendo classe e coordenadas normalizadas das caixas delimitadoras.

Requisitos

• Python 3.9 ou superior
• Uma webcam (para a etapa de inferência)
• Dataset de imagens de cartas já anotadas no formato YOLO

Instale as dependências:

pip install ultralytics opencv-python

Preparar o dataset

O script de preparação espera que o dataset de origem tenha a seguinte organização:

<dataset-origem>/
├── train/images/  e train/labels/
├── valid/images/  e valid/labels/
└── test/images/   e test/labels/

Antes de executá-lo, altere a variável dataset_origem em Criar_diretórios.py para o caminho onde o seu dataset foi salvo. Depois execute:

python Criar_diretórios.py

Isso cria e preenche dataset/images e dataset/labels, separando os dados entre treino, validação e teste.

Configurar e treinar

YOLO_train.py foi feito para ser executado no Google Colab e usa caminhos do Google Drive. Envie a pasta dataset ao Drive, ajuste os caminhos train, val e test em data.yaml para a localização real dos arquivos e execute:

python YOLO_train.py

O treinamento usa o modelo base yolo11s.pt, 150 épocas e imagens de 640 px. Ao fim, localize o arquivo best.pt gerado nos resultados do Ultralytics e copie-o para a raiz deste repositório, ou ajuste o caminho em webcam.py.

Para treinar localmente, também é necessário trocar, em YOLO_train.py, o valor de data pelo caminho local absoluto ou relativo para data.yaml.

Usar a webcam

Com best.pt na raiz do projeto, execute:

python webcam.py

Uma janela exibirá a imagem da câmera com caixas, nomes das cartas e níveis de confiança. Pressione q para encerrar.

Se houver mais de uma câmera, altere cv2.VideoCapture(0) em webcam.py para o índice correspondente.

Observações

• O arquivo de pesos treinado (best.pt) não é versionado neste repositório; ele precisa ser gerado ou obtido separadamente.
• A qualidade das detecções depende da variedade e da qualidade das imagens anotadas usadas no treinamento.
• data.yaml contém a ordem das 52 classes. Essa ordem deve ser a mesma usada nos arquivos de rótulo do dataset.

Próximos passos: assistente de Blackjack

Em uma evolução posterior deste projeto, o reconhecimento de cartas foi aplicado a um assistente de Blackjack para acompanhar uma partida entre uma pessoa e o computador. Essa etapa foi desenvolvida como um protótipo separado e seus arquivos não fazem parte desta versão do repositório.

O programa dividia o vídeo em duas regiões de interesse:

• Área do jogador: detectava as duas cartas visíveis, calculava o valor da mão e o apresentava na tela.
• Área do computador: considerava apenas a carta aberta do computador, respeitando a informação que estaria disponível ao jogador durante a rodada.

Com essas informações, o assistente também exibia uma recomendação ao jogador humano: comprar, segurar ou a indicação de que a mão estourou. Para estimar a melhor próxima decisão diante da carta oculta do computador e das cartas ainda possíveis no baralho, ele utilizava simulações de Monte Carlo: executava diversas partidas hipotéticas a partir do estado reconhecido e comparava os resultados esperados de comprar ou segurar.

Essa evolução demonstra uma aplicação prática do detector além da identificação individual de cartas, combinando visão computacional, regras do jogo e tomada de decisão sob incerteza.