imgboost-ai 0.1.0
Melhore a qualidade de imagens com IA - Processamento avançado para documentos, screenshots e fotos
License: MIT
Requires Python: >=3.8
Keywords: image, processing, ai, enhancement, super-resolution, ocr, document

# 🚀 ImgBoost

Biblioteca CLI profissional para melhorar qualidade de imagens usando IA e técnicas avançadas de processamento.

![Python](https://img.shields.io/badge/python-3.8+-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)

## ✨ Características

- 🎯 **4 Modos especializados** de processamento
- 🔧 **Denoise inteligente** com OpenCV
- 📈 **CLAHE** para melhoria de contraste adaptativo
- ✂️ **Sharpening** profissional
- 🌙 **Modo Dark UI** otimizado para interfaces escuras
- 📄 **Modo Texto/OCR** para documentos
- 🚀 **Super-resolução** com upscaling de alta qualidade
- ⚡ **Processamento em lote** com suporte a paralelização
- 💾 **Múltiplos formatos** (PNG, JPG, BMP, TIFF, WebP)

## 📦 Instalação

```bash
# Clone o repositório
git clone https://github.com/jpedrops092/imgboost.git
cd imgboost

# Instale em modo desenvolvimento
pip install -e .

# Ou instale as dependências manualmente
pip install -r requirements.txt
```

### Dependências

- Python >= 3.8
- OpenCV >= 4.8.0
- NumPy >= 1.24.0
- Click >= 8.1.0
- scikit-image >= 0.21.0
- tqdm >= 4.66.0
- PyTorch >= 2.0.0 (opcional, para super-resolução com IA)

## 🎯 Uso Rápido

### Modo Geral (melhoria padrão)

```bash
imgboost process foto.jpg
```

### Modo Texto/Documento (OCR)

```bash
imgboost process documento.png --mode text
```

### Modo Dark UI (WhatsApp, interfaces escuras)

```bash
imgboost process screenshot_whatsapp.png --mode dark
```

### Super-resolução (upscale 2x)

```bash
imgboost process imagem_baixa_res.jpg --mode superres
# Ou adicionar upscale a qualquer modo:
imgboost process foto.jpg --mode general --upscale
```

### Processar diretório inteiro

```bash
imgboost process ./minhas_fotos --mode general --output ./melhoradas
```

### Processamento em lote (paralelo)

```bash
imgboost batch ./minhas_fotos --workers 8
```

## 📋 Modos de Processamento

### 1. **General** (Padrão)
Melhoria geral balanceada:
- Denoise (redução de ruído)
- CLAHE (contraste adaptativo)
- Sharpening (nitidez)

**Ideal para:** Fotos gerais, prints, screenshots

### 2. **Text** (Texto/Documento)
Otimizado para leitura e OCR:
- Denoise focado
- Binarização adaptativa
- Deskew (correção de inclinação)
- Remoção de sombras

**Ideal para:** Documentos escaneados, fotos de papel, notas

### 3. **Dark** (Interfaces Escuras)
Otimizado para UIs com fundo escuro:
- Ajuste de gamma
- CLAHE agressivo
- Denoise seletivo
- Realce de texto em fundos escuros

**Ideal para:** WhatsApp Dark, apps com tema escuro, capturas noturnas

### 4. **Superres** (Super-resolução)
Upscaling com preservação de qualidade:
- Denoise pré-processamento
- Upscale 2x com LANCZOS4
- Unsharp mask pós-processamento
- Realce de textura

**Ideal para:** Imagens de baixa resolução, ampliação para impressão

## ⚙️ Opções Avançadas

```bash
imgboost process imagem.jpg \
  --mode general \
  --output ./output \
  --upscale \
  --quality 95 \
  --format png \
  --denoise-strength 15 \
  --contrast 4.0 \
  --sharpen \
  --verbose
```

### Parâmetros

- `--output, -o`: Pasta de saída (padrão: `output`)
- `--mode, -m`: Modo de processamento (`general`, `text`, `dark`, `superres`)
- `--upscale, -u`: Aplicar super-resolução 2x
- `--quality, -q`: Qualidade JPEG 1-100 (padrão: 95)
- `--format, -f`: Formato de saída (`auto`, `png`, `jpg`)
- `--denoise-strength, -d`: Força do denoise 0-30 (padrão: 10)
- `--contrast, -c`: Intensidade CLAHE 1.0-5.0 (padrão: 3.0)
- `--sharpen, -s`: Aplicar sharpening extra
- `--verbose, -v`: Modo verboso

## 📊 Exemplos Práticos

### Melhorar print de WhatsApp escuro

```bash
imgboost process whatsapp_dark.png --mode dark --sharpen --quality 100
```

### Preparar documento para OCR

```bash
imgboost process documento_foto.jpg --mode text --format png --output ./ocr
```

### Upscale de imagem para impressão

```bash
imgboost process logo_pequeno.png --mode superres --quality 100 --format png
```

### Processar pasta de fotos antigas

```bash
imgboost process ./fotos_antigas --mode general --upscale --denoise-strength 20
```

### Lote em paralelo (rápido)

```bash
imgboost batch ./muitas_fotos --workers 8
```

## 🔧 Uso Programático

Você também pode usar o ImgBoost como biblioteca Python:

```python
from imgboost import Engine

# Criar engine
engine = Engine(
    output_dir='output',
    quality=95,
    denoise_strength=10,
    contrast_clip=3.0
)

# Processar imagem
output_path = engine.run(
    'input.jpg',
    mode='general',
    upscale=True
)

print(f"Imagem salva em: {output_path}")
```

### Processamento customizado

```python
from imgboost.processors import ImageFilters, SuperResolution
from imgboost.utils import ImageIO

# Carregar
io = ImageIO()
img = io.load('input.jpg')

# Processar
filters = ImageFilters(denoise_strength=15)
img = filters.denoise(img)
img = filters.enhance_contrast(img)
img = filters.sharpen(img)

# Upscale
sr = SuperResolution()
img = sr.upscale(img, scale=2)

# Salvar
io.save(img, 'output.jpg', quality=95)
```

## 📚 Informações do Sistema

```bash
imgboost info
```

Mostra:
- Versão do ImgBoost
- Versões das dependências
- Disponibilidade de CUDA
- Modos disponíveis

## 🛠️ Desenvolvimento

### Estrutura do Projeto

```
imgboost/
├── imgboost/
│   ├── __init__.py
│   ├── cli.py              # Interface CLI
│   ├── core.py             # Engine principal
│   ├── processors/
│   │   ├── filters.py      # Filtros OpenCV
│   │   ├── document.py     # Processamento de documentos
│   │   └── superres.py     # Super-resolução
│   └── utils/
│       └── image_io.py     # I/O de imagens
├── setup.py
├── requirements.txt
└── README.md
```

### Adicionar novos processadores

1. Crie um arquivo em `imgboost/processors/`
2. Implemente sua classe de processamento
3. Importe em `imgboost/processors/__init__.py`
4. Use no `core.py`

### Executar testes

```bash
# Teste básico
imgboost process test_image.jpg --verbose

# Teste de lote
imgboost batch test_images/ --workers 4
```

## 🎓 Técnicas Implementadas

### Denoise
- **Fast Non-Local Means**: Preserva bordas enquanto remove ruído
- Força ajustável (0-30)

### Contraste
- **CLAHE**: Histogram equalization adaptativo
- Evita sobre-saturação
- Tile grid 8x8

### Sharpening
- **Unsharp Mask**: Sharpening profissional
- **Kernel customizado**: Controle de intensidade
- Preserva naturalidade

### Super-resolução
- **LANCZOS4**: Interpolação de alta qualidade
- **Multi-scale**: Preservação de detalhes
- **Texture enhancement**: Realce de texturas

### Processamento de Documentos
- **Adaptive Thresholding**: Binarização inteligente
- **Deskew**: Correção de inclinação
- **Shadow removal**: Remoção de sombras
- **Morphological operations**: Limpeza de ruído

## 🚀 Próximos Passos

- [ ] Integração com Real-ESRGAN para super-resolução com IA
- [ ] Suporte a vídeos
- [ ] Processamento de PDFs
- [ ] Interface web
- [ ] Presets customizáveis
- [ ] Batch processing com GPU
- [ ] Plugin para Photoshop/GIMP

## 📄 Licença

MIT License - veja LICENSE para detalhes

## 🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

1. Fork o projeto
2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
4. Push para a branch (`git push origin feature/AmazingFeature`)
5. Abra um Pull Request

## 📧 Suporte

- 🐛 **Issues**: [GitHub Issues](https://github.com/jpedrops092/imgboost/issues)
- 💬 **Discussões**: [GitHub Discussions](https://github.com/jpedrops092/imgboost/discussions)

## 🌟 Agradecimentos

- OpenCV pela biblioteca de processamento de imagens
- Real-ESRGAN pela inspiração em super-resolução
- Click pela excelente biblioteca CLI

---

Feito com ❤️ por ImgBoost Team