1. Visão geral do pipeline
Ordem operacional típica:
extrair GPX/GPS (ou EXIF) → geocode/organizar → segmentar (Mask2Former/ADE20K) → dividir em 3 faixas (meio/direita/esquerda) → gerar patches (224×224) → filtrar por cobertura/dominância → treinar ViT v1 → 2º ciclo (refino/remoção de inconsistências) → treinar ViT v2 com dataset mais puro → inferência + exportação CSV/GeoJSON
Recomendação prática: manter logs de versão (Python, torch, torchvision, transformers, CUDA) e um arquivo
requirements.txt ou export do ambiente (conda env export) junto do projeto.
2. Sistema e ambiente de execução
| Item | Uso no projeto | Como verificar (exemplos) |
|---|---|---|
| Sistema Operacional | Execução local do pipeline e acesso a GPU. | winverpython -c "import platform; print(platform.platform())" |
| Python (ambiente) | Scripts de treino/inferência, geração de patches e exportações. | python --versionwhere python |
| Gerenciador de ambiente | Isolamento do ambiente (ex.: pt312). |
conda env list ou pip -V |
| CUDA + Driver NVIDIA | Aceleração em GPU (treino ViT e inferência). | nvidia-smipython -c "import torch; print(torch.cuda.is_available())" |
Observação: se usar AMP/autocast, confirme que o device é CUDA e que a versão do PyTorch está alinhada à sua versão de CUDA/driver.
3. Bibliotecas Python principais
| Biblioteca | Uso no pipeline | Como verificar |
|---|---|---|
| torch (PyTorch) | Treino e inferência do ViT; DataLoader; AMP/autocast. | python -c "import torch; print(torch.__version__)" |
| torchvision | Modelo vit_b_16, transforms, utilitários de visão. |
python -c "import torchvision; print(torchvision.__version__)" |
| transformers (Hugging Face) | Mask2Former + AutoImageProcessor. |
python -c "import transformers; print(transformers.__version__)" |
| Pillow (PIL) | Leitura/gravação de imagens; recortes de patches. | python -c "from PIL import Image; import PIL; print(PIL.__version__)" |
| numpy | Operações com arrays e máscaras (segmentation map). | python -c "import numpy as np; print(np.__version__)" |
| pandas | CSV de resultados; consolidações. | python -c "import pandas as pd; print(pd.__version__)" |
| tqdm | Barra de progresso e monitoramento. | python -c "import tqdm; print(tqdm.__version__)" |
| scikit-learn | Split (train/val/test) e métricas (prec/recall/f1). | python -c "import sklearn; print(sklearn.__version__)" |
| matplotlib | Curvas de treino/figuras. | python -c "import matplotlib; print(matplotlib.__version__)" |
4. Modelos de IA utilizados
| Modelo | Tipo | Função no projeto | Origem / checkpoint |
|---|---|---|---|
| Mask2Former | Swin-Tiny (ADE20K) Segmentação semântica |
Identificar pixels de classes urbanas (ex.: 6=road, 9=grass, 11=sidewalk) para orientar a geração de patches “puros”. | facebook/mask2former-swin-tiny-ade-semantic |
| Vision Transformer (ViT-B/16) | Classificação | Classificar patches em asphalt, brick, grass (modelo treinado/fine-tuned no seu dataset). | Checkpoint local (.pth) |
5. Programas externos e utilitários
| Ferramenta | Uso | Como verificar |
|---|---|---|
| ExifTool | Extrair coordenadas GPS e metadados dos frames (EXIF). | exiftool -verConfig do script: Config.EXIFTOOL_PATH |
| FFmpeg (opcional) | Extração de frames a partir de vídeo (quando aplicável). | ffmpeg -version |
| QGIS (recomendado) | Validar CSV/GeoJSON em mapa; inspeção espacial; estilos e exportações. | Ajuda → Sobre (versão) ou qgis --version (se disponível) |
6. Formatos de dados e saídas do projeto
Entradas comuns: vídeo .mp4 (opcional), frames .jpg/.png com EXIF/GPS, GPX, pastas por classe ADE (ex.: class_6, class_9, class_11), imagens recortadas/resize.
Saídas: patches organizados por material (asphalt/brick/grass), CSV com atributos por patch, GeoJSON com pontos (lat/lon) para visualização em mapa.
7. Conhecimentos necessários
- Visão computacional: classificação vs. segmentação; o que é um patch; efeitos de resize/normalização; qualidade de dados (frames pretos).
- Deep Learning: fine-tuning; overfitting; split estratificado; métricas (precisão/recall/F1); threshold de score; batch inference.
- Geodados: latitude/longitude; CRS (WGS84); GeoJSON; validação em QGIS; noções de ruído de GPS.
- Python: organização de pastas; leitura/escrita de imagens; manipulação com numpy/pandas; ambientes (conda/pip).
- GPU: VRAM; ajuste de batch size; autocast/AMP; monitorar
nvidia-smi.
8. Checklist de qualidade para patches
Antes de retreinar o ViT com patches, aplique filtros automáticos:
- Excluir patches muito escuros/pretos (ex.: média de brilho abaixo de um limiar).
- Excluir patches com pouca textura (desvio padrão muito baixo) quando isso indicar “vazio”.
- Garantir cobertura mínima da classe ADE válida no patch e dominância ≥ 70%.
- Armazenar no CSV:
ade_dominant_label,ade_dominant_fraction,score, caminho do patch, frame e coordenadas.
Se quiser, dá para criar um script de “limpeza de patches” (remove pretos/escuros) antes do treino do ViT v2.
9. Interface Web do projeto (Gradio)
O pipeline termina numa aplicação web construída com Gradio, permitindo que o usuário execute inferências e explore os resultados em um navegador (localmente e/ou online).
- Upload de imagem/frames (ou seleção de amostras já existentes).
- Execução de inferência (ViT) e visualização de classe prevista vs classe verdadeira (quando disponível).
- Geração de saídas (CSV/HTML/PDF/ZIP) e download pela interface.
- Galeria/grade de resultados e filtros (ex.: apenas erros, apenas acertos).
| Componente | Uso na interface | Exemplos |
|---|---|---|
| gr.Blocks / Tabs | Estrutura da página e separação por módulos do pipeline. | gr.Blocks(), gr.Tab() |
| Inputs | Entrada de dados e parâmetros de execução. | gr.Image(), gr.File(), gr.Dropdown(), gr.Slider() |
| Outputs | Exibição de resultados e exportações. | gr.Label(), gr.Dataframe(), gr.Gallery(), gr.File() |
| Fila/concorrência | Evita travamentos e controla quantas execuções rodam ao mesmo tempo. | demo.queue(concurrency_count=...) |
Boas práticas: mantenha o Gradio como a “camada final”. A UI chama funções do pipeline (segmentação, geração de patches, inferência e exportação), mas a lógica pesada deve ficar em módulos (ex.:
src/).
10. Publicação no Hugging Face Spaces
O produto final do projeto é um Hugging Face Space com a aplicação Gradio rodando online. Isso exige organizar o repositório do Space e garantir que o app não dependa de caminhos locais do Windows (ex.: D:\...).
| Arquivo/pasta | Obrigatório | Função |
|---|---|---|
app.py |
Sim | Entrada do Space (constrói e expõe a UI do Gradio). |
requirements.txt |
Sim | Dependências (ex.: gradio, torch, transformers, etc.). |
src/ |
Recomendado | Módulos do pipeline (IO, pré-processamento, inferência, exportação, utilitários). |
assets/ / outputs/ |
Recomendado | Imagens de exemplo, ícones e diretório de saídas geradas no runtime. |
| Modelos (checkpoint) | Depende | Podem ficar no repo, ser baixados do Hub, ou serem carregados sob demanda (melhor para manter o Space leve). |
- Paths relativos: use
./dados,./models,./outputsem vez de caminhos absolutos. - Hardware: selecione CPU/GPU no Space conforme o custo/necessidade. Otimize batch/resize/AMP para economizar VRAM.
- Persistência: se precisar manter arquivos entre execuções, use o storage do Space; caso contrário, trate saídas como temporárias.
- Segredos: tokens/keys devem ir em “Secrets” do Space (nunca commitados).
Ponto crítico: no Space o ambiente é Linux. Ajuste separadores de caminho, permissões e dependências (ex.: wheels do PyTorch/torchvision compatíveis).
11. Conhecimentos Web necessários (mínimo útil)
Mesmo usando Gradio (que abstrai frontend), é útil dominar o mínimo para operar e depurar uma aplicação web em produção:
| Conhecimento | Por que importa | Nível |
|---|---|---|
| HTTP básico | Uploads/downloads, erros 404/500, timeouts e limites de request. | Essencial |
| HTML/CSS (noções) | Entender layout, documentação (README) e pequenas customizações. | Útil |
| Logs e debugging | Interpretar logs do Space e erros de import/dependências/VRAM. | Essencial |
| Linux básico | Paths, permissões, execução em container e diferenças para Windows. | Essencial |
| Versionamento (git) | Atualizar o Space, rastrear mudanças, rollback e releases. | Essencial |
12. Checklist final (do local ao Space)
- Reprodutibilidade: rodar localmente apenas com
python app.py+requirements.txt. - Sem hardcode: remover
D:\e usar paths relativos + criação automática de./outputs. - Performance: limitar resolução, usar batch pequeno, considerar AMP/autocast e cache de modelo.
- UX: abas claras (Upload / Inferência / Relatórios), mensagens de erro amigáveis e barras de progresso.
- Deploy: commit no repo do Space, validar build e revisar logs; documentar uso no
README.md.