@libs-scripts-mep/mpai/README.md

Inference MPAI client

# MPAI — Métodos e Processos com IA

Ferramenta para captura de imagens, treinamento e inferência com modelos YOLOv8 (Ultralytics).

## ✨ Funcionalidades
- Captura de imagens com controle de parâmetros da câmera.

- Treinamento de modelos YOLOv8 (modo detect).

- Inferência em imagens e streaming de vídeo.


## 📦 Instalação
```bash
npm install @libs-scripts-mep/mpai
```

## 🔁 Atualização

```bash
npm update @libs-scripts-mep/mpai
```

## 🧹 Desinstalação

```bash
npm uninstall @libs-scripts-mep/mpai
```

## ⚙️ Dependências (Python)

> 💡 Recomendado: execute inference/dep_checker.py para instalar dependências compatíveis automaticamente (detecta e usa ambiente virtual se existir).

Ou instale manualmente:

```bash
pip install opencv-python pillow numpy ultralytics pyyaml websockets
```

## 🧪 Ambiente Virtual (opcional)

O comando abaixo cria um ambiente virtual para o projeto. O ambiente virtual pode ser ativado manualmente, ou seja, execute o comando abaixo na raiz do projeto.

```bash
python -m venv .venv
```

### Ativação:

> ⚠️ A ativação deve ser feita sempre que abrir o VS Code. Do contrário, será considerado o ambiente global.

PowerShell:

```powershell
.venv\Scripts\Activate.ps1
```

CMD: 

```bash
.venv\Scripts\activate
```

Bash/Linux: 
```bash
source .venv/bin/activate
```

## 📂 Dataset
O dataset é um conjunto de imagens anotadas no formato YOLO. Para criar o seu:

1. Use o script `data_collection/image_collector.py` para capturar imagens com variações de iluminação e ângulos.

2. As imagens vão para: `dataset/missing_annotation_images/`

3. Anote as imagens com ferramentas como [Make Sense](https://www.makesense.ai/)

4. Exporte no formato YOLO e organize:

```
dataset/
├── images/
│   ├── train/
│   └── val/
├── labels/
│   ├── train/
│   └── val/
└── clases.txt     # deve conter as classes anotadas na ordem correta, conforme utilizado na ferramenta de anotação
└── data.yaml      # arquivo que será modificado pelo script `generate_data_yaml.py`

```

5. Execute o script `generate_data_yaml.py` para gerar o data.yaml.

> 💡 Dica: Separe as imagens anotadas para treino/validação antes de mover, para evitar confusão.

### 🛑 Ignorando dataset no Git

Adicione o seguinte ao `.gitignore` do repositório do script

```
node_modules/@libs-scripts-mep/mpai/dataset/*
!node_modules/@libs-scripts-mep/mpai/dataset/**/.gitkeep
!node_modules/@libs-scripts-mep/mpai/dataset/**/*.yaml
```

## 🏋️‍♂️ Treinamento

### Modelos disponíveis

| Modelo    | Tamanho | Velocidade     | Precisão    | Indicação                       |
| --------- | ------- | -------------- | ----------- | ------------------------------- |
| `yolov8n` | \~6 MB  | 🔥 Muito rápido | Baixa       | Testes, dispositivos embarcados |
| `yolov8s` | \~11 MB | ⚡ Rápido       | Média-baixa | Tempo real, baixa latência      |
| `yolov8m` | \~25 MB | ⚖️ Balanceado   | Média       | GPU ou CPU robusta              |
| `yolov8l` | \~45 MB | 🐢 Mais lento   | Alta        | Workstations com GPU            |
| `yolov8x` | \~65 MB | 🐌 Lento        | Muito alta  | GPUs potentes                   |

um dos modelos acima deve ser indicado no `train.py`

```python
model = YOLO('yolov8m.pt')
```

> Atualmente este projeto suporta apenas o modo detect.

### Exemplo de treinamento:

``` python
# model_training/train.py

model.train(
    data='data.yaml',
    epochs=100,
    imgsz=640,
    batch=8,
    project='runs',
    name='meu_projeto',
    exist_ok=True,
    augment=True,
    degrees=5,
    scale=0.3,
    fliplr=0.5,
    flipud=0.1,
    device='cpu'  # ou '0' para GPU
)
```

### ⚠️ Treinamento com GPU

Versões do pytorch e torchvision especificas devem ser instaladas, dependendo do modelo da GPU (supoerte aos CUDA cores) da sua máquina. 

Verifique os requisitos em [pytorch.org](https://pytorch.org/get-started/locally/).

### Parâmetros importantes

data: caminho do arquivo .yaml gerado pelo script `model_training\generate_data_yaml.py`

- `batch`: depende da RAM ou VRAM (tente 8 ou 16)
- `imgsz`: resolução da imagem
- `device`: "cpu" ou "0" (GPU)
- `augment`: habilita técnicas como rotação, flip e escala
- `pretrained`: usar pesos base (default: True)
  
## 🔍 Inferência

Você pode usar o script `mpai-server.py` para disponibilizar o modelo treinado via serviço HTTP, e o `mpai-client.js` para enviar imagens (base64) e receber as detecções.

Ou se preferir fazer um teste rápido do modelo treinado, usando o script `inference/infer_webcam_yolo.py`, apenas apontando o caminho para o modelo treinado:

``` python
# inference/infer_webcam_yolo.py
RELATIVE_PATH = "../../your/model/path/weights/best.pt"
```