🫘 Classificação de Sementes de Soja com Deep Features + Ensemble

Sistema de classificação de imagens de sementes de soja utilizando extração de deep features (ResNet50 / DINOv2) combinada com um ensemble de 20 classificadores (Soft Voting). O pipeline é avaliado por 10-Fold Stratified Cross-Validation e reporta métricas detalhadas (Acurácia, F1-Score, Matriz de Confusão).

📊 Dataset

Soybean Seeds — disponível publicamente no Kaggle:

🔗 Soybean Seeds Dataset (Kaggle)

Classe	Quantidade	Descrição
Broken soybeans	1.002	Sementes quebradas
Immature soybeans	1.125	Sementes imaturas
Intact soybeans	1.201	Sementes intactas (saudáveis)
Skin-damaged soybeans	1.127	Sementes com danos na casca
Spotted soybeans	1.058	Sementes com manchas

• Total: 5.513 imagens (227×227 pixels)
• Padrão de classificação: GB1352-2009 (Standard of Soybean Classification)
• Licença: CC BY 4.0

🏗️ Arquitetura do Pipeline

O projeto é dividido em 3 etapas sequenciais, cada uma com seu próprio script:

┌─────────────────────┐     ┌──────────────────────────┐     ┌─────────────────────┐
│  1. extractor.py    │ ──► │ 2. classificacao_        │ ──► │ 3. avaliar_          │
│                     │     │    ensemble.py            │     │    metricas.py       │
│  Extrai deep        │     │  Treina ensemble de 20   │     │  Calcula acurácia,   │
│  features com       │     │  classificadores (KNN,   │     │  F1-Score, matriz    │
│  ResNet50 ou DINOv2 │     │  SVM, RF, MLP) com       │     │  de confusão e       │
│                     │     │  10-Fold CV              │     │  classification      │
│  Saída: .npy        │     │  Saída: .npy             │     │  report              │
└─────────────────────┘     └──────────────────────────┘     └─────────────────────┘

Backbones disponíveis

Backbone	Dimensão do vetor	Descrição
ResNet50	2.048-D	CNN pré-treinada na ImageNet (torchvision)
DINOv2 (ViT-B/14)	768-D	Vision Transformer com self-supervision (Meta AI)

Classificadores do Ensemble (20 modelos)

Família	Variações	Detalhes
k-NN	5	k=3,5,7 (distance) + k=3,5 (uniform)
SVM	5	Linear, Poly(2), RBF com C=0.1, 1.0, 10.0
Random Forest	5	50/100/200 árvores, Gini e Entropy
MLP	5	Arquiteturas (50), (100), (50,50), (128) relu, (100) tanh

Combinação via Soft Voting — cada classificador contribui com suas probabilidades e a classe final é a de maior probabilidade média.

📋 Pré-requisitos

• Python 3.8 ou superior
• pip (gerenciador de pacotes Python)
• Git (para clonar o repositório)
• (Opcional) GPU NVIDIA com CUDA para acelerar a extração de features

🛠️ Instalação

1. Clone o repositório

git clone https://github.com/EricSL07/IA.git
cd IA

2. Crie e ative um ambiente virtual

python3 -m venv venv
source venv/bin/activate        # Linux / macOS
# venv\Scripts\activate         # Windows

3. Instale as dependências

pip install -r requirements.txt

4. Baixe o dataset

Faça o download do dataset no Kaggle e extraia dentro da pasta dataset/:

🔗 https://www.kaggle.com/datasets/ararsa-derese/soybean-seeds

# A estrutura final deve ficar assim:
dataset/
└── Soybean Seeds/
    ├── Broken soybeans/
    ├── Immature soybeans/
    ├── Intact soybeans/
    ├── Skin-damaged soybeans/
    └── Spotted soybeans/

🚀 Execução

O pipeline é composto por 3 scripts que devem ser executados nesta ordem. Cada um depende dos arquivos gerados pelo anterior.

---

Etapa 1 — Extração de Deep Features (extractor.py)

Carrega o backbone escolhido, percorre todas as imagens do dataset e gera vetores de features para cada imagem.

# Usando ResNet50 (padrão)
python extractor.py --model resnet50

# Usando DINOv2 (primeira execução faz download de ~330 MB)
python extractor.py --model dinov2

Arquivos gerados:

Arquivo	Conteúdo
features_X_{modelo}.npy	Matriz de features — shape(5513, dim)
labels_y_{modelo}.npy	Vetor de rótulos (0–4) — shape(5513,)
class_names_{modelo}.npy	Nomes das 5 classes

⏱️ Tempo estimado: ~2–5 min (GPU) ou ~15–30 min (CPU), dependendo do hardware.

---

Etapa 2 — Classificação com Ensemble (classificacao_ensemble.py)

Carrega as features extraídas, monta o ensemble de 20 classificadores (Soft Voting) e executa 10-Fold Stratified Cross-Validation.

# Deve usar o mesmo --model da Etapa 1
python classificacao_ensemble.py --model resnet50

# Ou, se usou DINOv2:
python classificacao_ensemble.py --model dinov2

Arquivo gerado:

Arquivo	Conteúdo
y_pred_ensemble_{modelo}.npy	Previsões out-of-fold para todas as 5.513 amostras

⏱️ Tempo estimado: ~5–20 min (varia com o hardware e backbone).

💡 Dica: o script imprime o tempo de cada fold. Observe o primeiro e multiplique por 10 para estimar o tempo total.

---

Etapa 3 — Avaliação de Métricas (avaliar_metricas.py)

Carrega os rótulos reais e as previsões salvas em disco, e calcula todas as métricas de desempenho — sem precisar re-treinar nada.

# Deve usar o mesmo --model das etapas anteriores
python avaliar_metricas.py --model resnet50

# Ou:
python avaliar_metricas.py --model dinov2

Métricas exibidas:

• ✅ Acurácia Global
• ✅ F1-Score Macro (trata todas as classes com peso igual)
• ✅ F1-Score Weighted (ponderado pela frequência de cada classe)
• ✅ Classification Report completo (Precision, Recall, F1 por classe)
• ✅ Matriz de Confusão formatada

⏱️ Tempo estimado: < 1 segundo (apenas carrega arrays .npy e calcula métricas).

---

Resumo rápido — execução completa

# Ativar o ambiente virtual
source venv/bin/activate

# Pipeline completo com ResNet50
python extractor.py --model resnet50
python classificacao_ensemble.py --model resnet50
python avaliar_metricas.py --model resnet50

# Pipeline completo com DINOv2
python extractor.py --model dinov2
python classificacao_ensemble.py --model dinov2
python avaliar_metricas.py --model dinov2

📂 Estrutura do Projeto

IA/
├── extractor.py                  # Etapa 1: Extração de deep features
├── classificacao_ensemble.py     # Etapa 2: Ensemble + Cross-Validation
├── avaliar_metricas.py           # Etapa 3: Avaliação de métricas
├── requirements.txt              # Dependências Python
├── dataset/                      # Dataset de imagens (não versionado)
│   └── Soybean Seeds/
│       ├── Broken soybeans/
│       ├── Immature soybeans/
│       ├── Intact soybeans/
│       ├── Skin-damaged soybeans/
│       └── Spotted soybeans/
├── features_X_resnet50.npy       # Features extraídas (gerado)
├── features_X_dinov2.npy         # Features extraídas (gerado)
├── labels_y_resnet50.npy         # Rótulos (gerado)
├── labels_y_dinov2.npy           # Rótulos (gerado)
├── class_names_resnet50.npy      # Nomes das classes (gerado)
├── class_names_dinov2.npy        # Nomes das classes (gerado)
├── y_pred_ensemble_resnet50.npy  # Previsões do ensemble (gerado)
├── y_pred_ensemble_dinov2.npy    # Previsões do ensemble (gerado)
└── venv/                         # Ambiente virtual (não versionado)

🧠 Tecnologias Utilizadas

• PyTorch — backbone de extração de features (ResNet50, DINOv2)
• scikit-learn — classificadores (KNN, SVM, RF, MLP), ensemble e métricas
• NumPy — manipulação de arrays e persistência (.npy)
• Pillow — carregamento e pré-processamento de imagens

📄 Licença

Este projeto é de código aberto e está disponível sob a licença MIT.

---

Nota: O dataset não é incluído no repositório (listado no .gitignore). Faça o download diretamente pelo Kaggle e extraia na pasta dataset/.