Spaces:
Running
Running
| <html lang="pt-BR"> | |
| <head> | |
| <meta charset="utf-8" /> | |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> | |
| <title>Software, Modelos e Conhecimentos Necessários — Superfícies Urbanas</title> | |
| <style> | |
| :root { --max: 980px; } | |
| body { font-family: system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif; line-height: 1.45; margin: 0; color: #111; } | |
| header { padding: 40px 18px 22px; background: #f6f7f9; border-bottom: 1px solid #e5e7eb; } | |
| main { max-width: var(--max); margin: 0 auto; padding: 26px 18px 60px; } | |
| h1 { font-size: 1.9rem; margin: 0 0 10px; } | |
| .subtitle { margin: 0; color: #374151; } | |
| h2 { margin-top: 34px; border-top: 1px solid #e5e7eb; padding-top: 24px; } | |
| .pill { display: inline-block; font-size: 0.82rem; padding: 3px 10px; border: 1px solid #e5e7eb; border-radius: 999px; background: #fff; color: #374151; } | |
| code, pre { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; } | |
| pre { padding: 12px 14px; background: #0b1020; color: #e5e7eb; border-radius: 10px; overflow-x: auto; } | |
| table { width: 100%; border-collapse: collapse; margin: 14px 0 4px; } | |
| th, td { text-align: left; vertical-align: top; padding: 10px 10px; border-bottom: 1px solid #e5e7eb; } | |
| th { background: #f9fafb; font-weight: 650; } | |
| ul { margin: 10px 0 0 18px; } | |
| .note { padding: 12px 14px; border: 1px solid #e5e7eb; background: #fff; border-radius: 12px; } | |
| footer { max-width: var(--max); margin: 0 auto; padding: 0 18px 28px; color: #6b7280; } | |
| </style> | |
| </head> | |
| <body> | |
| <header> | |
| <div style="max-width: var(--max); margin: 0 auto;"> | |
| <span class="pill">Documento (v2)</span> | |
| <h1>Software, Modelos e Conhecimentos Necessários</h1> | |
| <p class="subtitle"><strong>Projeto de Classificação de Superfícies Urbanas</strong> (Mask2Former + ViT + Patches + GPS)</p> | |
| <p class="subtitle">Versão do documento: <strong>2025-12-15</strong> — foco em execução local (Windows + GPU).</p> | |
| </div> | |
| </header> | |
| <main> | |
| <h2>1. Visão geral do pipeline</h2> | |
| <p><strong>Ordem operacional típica:</strong></p> | |
| <pre>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</pre> | |
| <div class="note"> | |
| <strong>Recomendação prática:</strong> manter logs de versão (Python, torch, torchvision, transformers, CUDA) e um arquivo | |
| <code>requirements.txt</code> ou export do ambiente (<code>conda env export</code>) junto do projeto. | |
| </div> | |
| <h2>2. Sistema e ambiente de execução</h2> | |
| <table> | |
| <thead> | |
| <tr> | |
| <th>Item</th> | |
| <th>Uso no projeto</th> | |
| <th>Como verificar (exemplos)</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><strong>Sistema Operacional</strong></td> | |
| <td>Execução local do pipeline e acesso a GPU.</td> | |
| <td><code>winver</code><br><code>python -c "import platform; print(platform.platform())"</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>Python (ambiente)</strong></td> | |
| <td>Scripts de treino/inferência, geração de patches e exportações.</td> | |
| <td><code>python --version</code><br><code>where python</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>Gerenciador de ambiente</strong></td> | |
| <td>Isolamento do ambiente (ex.: <code>pt312</code>).</td> | |
| <td><code>conda env list</code> ou <code>pip -V</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>CUDA + Driver NVIDIA</strong></td> | |
| <td>Aceleração em GPU (treino ViT e inferência).</td> | |
| <td><code>nvidia-smi</code><br><code>python -c "import torch; print(torch.cuda.is_available())"</code></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <div class="note"> | |
| <strong>Observação:</strong> se usar AMP/autocast, confirme que o device é CUDA e que a versão do PyTorch está alinhada à sua versão de CUDA/driver. | |
| </div> | |
| <h2>3. Bibliotecas Python principais</h2> | |
| <table> | |
| <thead> | |
| <tr> | |
| <th>Biblioteca</th> | |
| <th>Uso no pipeline</th> | |
| <th>Como verificar</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><strong>torch (PyTorch)</strong></td> | |
| <td>Treino e inferência do ViT; DataLoader; AMP/autocast.</td> | |
| <td><code>python -c "import torch; print(torch.__version__)"</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>torchvision</strong></td> | |
| <td>Modelo <code>vit_b_16</code>, transforms, utilitários de visão.</td> | |
| <td><code>python -c "import torchvision; print(torchvision.__version__)"</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>transformers (Hugging Face)</strong></td> | |
| <td>Mask2Former + <code>AutoImageProcessor</code>.</td> | |
| <td><code>python -c "import transformers; print(transformers.__version__)"</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>Pillow (PIL)</strong></td> | |
| <td>Leitura/gravação de imagens; recortes de patches.</td> | |
| <td><code>python -c "from PIL import Image; import PIL; print(PIL.__version__)"</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>numpy</strong></td> | |
| <td>Operações com arrays e máscaras (segmentation map).</td> | |
| <td><code>python -c "import numpy as np; print(np.__version__)"</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>pandas</strong></td> | |
| <td>CSV de resultados; consolidações.</td> | |
| <td><code>python -c "import pandas as pd; print(pd.__version__)"</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>tqdm</strong></td> | |
| <td>Barra de progresso e monitoramento.</td> | |
| <td><code>python -c "import tqdm; print(tqdm.__version__)"</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>scikit-learn</strong></td> | |
| <td>Split (train/val/test) e métricas (prec/recall/f1).</td> | |
| <td><code>python -c "import sklearn; print(sklearn.__version__)"</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>matplotlib</strong></td> | |
| <td>Curvas de treino/figuras.</td> | |
| <td><code>python -c "import matplotlib; print(matplotlib.__version__)"</code></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2>4. Modelos de IA utilizados</h2> | |
| <table> | |
| <thead> | |
| <tr> | |
| <th>Modelo</th> | |
| <th>Tipo</th> | |
| <th>Função no projeto</th> | |
| <th>Origem / checkpoint</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><strong>Mask2Former</strong></td> | |
| <td>Swin-Tiny (ADE20K)<br>Segmentação semântica</td> | |
| <td>Identificar pixels de classes urbanas (ex.: 6=road, 9=grass, 11=sidewalk) para orientar a geração de patches “puros”.</td> | |
| <td><code>facebook/mask2former-swin-tiny-ade-semantic</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>Vision Transformer (ViT-B/16)</strong></td> | |
| <td>Classificação</td> | |
| <td>Classificar patches em <em>asphalt</em>, <em>brick</em>, <em>grass</em> (modelo treinado/fine-tuned no seu dataset).</td> | |
| <td>Checkpoint local (<code>.pth</code>)</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2>5. Programas externos e utilitários</h2> | |
| <table> | |
| <thead> | |
| <tr> | |
| <th>Ferramenta</th> | |
| <th>Uso</th> | |
| <th>Como verificar</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><strong>ExifTool</strong></td> | |
| <td>Extrair coordenadas GPS e metadados dos frames (EXIF).</td> | |
| <td><code>exiftool -ver</code><br>Config do script: <code>Config.EXIFTOOL_PATH</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>FFmpeg (opcional)</strong></td> | |
| <td>Extração de frames a partir de vídeo (quando aplicável).</td> | |
| <td><code>ffmpeg -version</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>QGIS (recomendado)</strong></td> | |
| <td>Validar CSV/GeoJSON em mapa; inspeção espacial; estilos e exportações.</td> | |
| <td>Ajuda → Sobre (versão) ou <code>qgis --version</code> (se disponível)</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2>6. Formatos de dados e saídas do projeto</h2> | |
| <p><strong>Entradas comuns:</strong> vídeo <code>.mp4</code> (opcional), frames <code>.jpg/.png</code> com EXIF/GPS, GPX, pastas por classe ADE (ex.: <code>class_6</code>, <code>class_9</code>, <code>class_11</code>), imagens recortadas/resize.</p> | |
| <p><strong>Saídas:</strong> patches organizados por material (<code>asphalt/brick/grass</code>), CSV com atributos por patch, GeoJSON com pontos (lat/lon) para visualização em mapa.</p> | |
| <h2>7. Conhecimentos necessários</h2> | |
| <ul> | |
| <li><strong>Visão computacional:</strong> classificação vs. segmentação; o que é um patch; efeitos de resize/normalização; qualidade de dados (frames pretos).</li> | |
| <li><strong>Deep Learning:</strong> fine-tuning; overfitting; split estratificado; métricas (precisão/recall/F1); threshold de score; batch inference.</li> | |
| <li><strong>Geodados:</strong> latitude/longitude; CRS (WGS84); GeoJSON; validação em QGIS; noções de ruído de GPS.</li> | |
| <li><strong>Python:</strong> organização de pastas; leitura/escrita de imagens; manipulação com numpy/pandas; ambientes (conda/pip).</li> | |
| <li><strong>GPU:</strong> VRAM; ajuste de batch size; autocast/AMP; monitorar <code>nvidia-smi</code>.</li> | |
| </ul> | |
| <h2>8. Checklist de qualidade para patches</h2> | |
| <p>Antes de retreinar o ViT com patches, aplique filtros automáticos:</p> | |
| <ul> | |
| <li>Excluir patches muito escuros/pretos (ex.: média de brilho abaixo de um limiar).</li> | |
| <li>Excluir patches com pouca textura (desvio padrão muito baixo) quando isso indicar “vazio”.</li> | |
| <li>Garantir cobertura mínima da classe ADE válida no patch e dominância ≥ 70%.</li> | |
| <li>Armazenar no CSV: <code>ade_dominant_label</code>, <code>ade_dominant_fraction</code>, <code>score</code>, caminho do patch, frame e coordenadas.</li> | |
| </ul> | |
| <div class="note"> | |
| Se quiser, dá para criar um script de “limpeza de patches” (remove pretos/escuros) antes do treino do ViT v2. | |
| </div> | |
| <h2>9. Interface Web do projeto (Gradio)</h2> | |
| <p>O pipeline termina numa <strong>aplicação web</strong> construída com <strong>Gradio</strong>, permitindo que o usuário execute inferências e explore os resultados em um navegador (localmente e/ou online).</p> | |
| <ul> | |
| <li>Upload de imagem/frames (ou seleção de amostras já existentes).</li> | |
| <li>Execução de inferência (ViT) e visualização de classe prevista vs classe verdadeira (quando disponível).</li> | |
| <li>Geração de saídas (CSV/HTML/PDF/ZIP) e download pela interface.</li> | |
| <li>Galeria/grade de resultados e filtros (ex.: apenas erros, apenas acertos).</li> | |
| </ul> | |
| <table> | |
| <thead> | |
| <tr> | |
| <th>Componente</th> | |
| <th>Uso na interface</th> | |
| <th>Exemplos</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><strong>gr.Blocks</strong> / <strong>Tabs</strong></td> | |
| <td>Estrutura da página e separação por módulos do pipeline.</td> | |
| <td><code>gr.Blocks()</code>, <code>gr.Tab()</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>Inputs</strong></td> | |
| <td>Entrada de dados e parâmetros de execução.</td> | |
| <td><code>gr.Image()</code>, <code>gr.File()</code>, <code>gr.Dropdown()</code>, <code>gr.Slider()</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>Outputs</strong></td> | |
| <td>Exibição de resultados e exportações.</td> | |
| <td><code>gr.Label()</code>, <code>gr.Dataframe()</code>, <code>gr.Gallery()</code>, <code>gr.File()</code></td> | |
| </tr> | |
| <tr> | |
| <td><strong>Fila/concorrência</strong></td> | |
| <td>Evita travamentos e controla quantas execuções rodam ao mesmo tempo.</td> | |
| <td><code>demo.queue(concurrency_count=...)</code></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <div class="note"> | |
| <strong>Boas práticas:</strong> 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.: <code>src/</code>). | |
| </div> | |
| <h2>10. Publicação no Hugging Face Spaces</h2> | |
| <p>O produto final do projeto é um <strong>Hugging Face Space</strong> 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.: <code>D:\...</code>).</p> | |
| <table> | |
| <thead> | |
| <tr> | |
| <th>Arquivo/pasta</th> | |
| <th>Obrigatório</th> | |
| <th>Função</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><code>app.py</code></td> | |
| <td><strong>Sim</strong></td> | |
| <td>Entrada do Space (constrói e expõe a UI do Gradio).</td> | |
| </tr> | |
| <tr> | |
| <td><code>requirements.txt</code></td> | |
| <td><strong>Sim</strong></td> | |
| <td>Dependências (ex.: <code>gradio</code>, <code>torch</code>, <code>transformers</code>, etc.).</td> | |
| </tr> | |
| <tr> | |
| <td><code>src/</code></td> | |
| <td>Recomendado</td> | |
| <td>Módulos do pipeline (IO, pré-processamento, inferência, exportação, utilitários).</td> | |
| </tr> | |
| <tr> | |
| <td><code>assets/</code> / <code>outputs/</code></td> | |
| <td>Recomendado</td> | |
| <td>Imagens de exemplo, ícones e diretório de saídas geradas no runtime.</td> | |
| </tr> | |
| <tr> | |
| <td>Modelos (checkpoint)</td> | |
| <td>Depende</td> | |
| <td>Podem ficar no repo, ser baixados do Hub, ou serem carregados sob demanda (melhor para manter o Space leve).</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <ul> | |
| <li><strong>Paths relativos:</strong> use <code>./dados</code>, <code>./models</code>, <code>./outputs</code> em vez de caminhos absolutos.</li> | |
| <li><strong>Hardware:</strong> selecione CPU/GPU no Space conforme o custo/necessidade. Otimize batch/resize/AMP para economizar VRAM.</li> | |
| <li><strong>Persistência:</strong> se precisar manter arquivos entre execuções, use o storage do Space; caso contrário, trate saídas como temporárias.</li> | |
| <li><strong>Segredos:</strong> tokens/keys devem ir em “Secrets” do Space (nunca commitados).</li> | |
| </ul> | |
| <div class="note"> | |
| <strong>Ponto crítico:</strong> no Space o ambiente é Linux. Ajuste separadores de caminho, permissões e dependências (ex.: wheels do PyTorch/torchvision compatíveis). | |
| </div> | |
| <h2>11. Conhecimentos Web necessários (mínimo útil)</h2> | |
| <p>Mesmo usando Gradio (que abstrai frontend), é útil dominar o mínimo para operar e depurar uma aplicação web em produção:</p> | |
| <table> | |
| <thead> | |
| <tr> | |
| <th>Conhecimento</th> | |
| <th>Por que importa</th> | |
| <th>Nível</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><strong>HTTP básico</strong></td> | |
| <td>Uploads/downloads, erros 404/500, timeouts e limites de request.</td> | |
| <td>Essencial</td> | |
| </tr> | |
| <tr> | |
| <td><strong>HTML/CSS (noções)</strong></td> | |
| <td>Entender layout, documentação (README) e pequenas customizações.</td> | |
| <td>Útil</td> | |
| </tr> | |
| <tr> | |
| <td><strong>Logs e debugging</strong></td> | |
| <td>Interpretar logs do Space e erros de import/dependências/VRAM.</td> | |
| <td>Essencial</td> | |
| </tr> | |
| <tr> | |
| <td><strong>Linux básico</strong></td> | |
| <td>Paths, permissões, execução em container e diferenças para Windows.</td> | |
| <td>Essencial</td> | |
| </tr> | |
| <tr> | |
| <td><strong>Versionamento (git)</strong></td> | |
| <td>Atualizar o Space, rastrear mudanças, rollback e releases.</td> | |
| <td>Essencial</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2>12. Checklist final (do local ao Space)</h2> | |
| <ul> | |
| <li><strong>Reprodutibilidade:</strong> rodar localmente apenas com <code>python app.py</code> + <code>requirements.txt</code>.</li> | |
| <li><strong>Sem hardcode:</strong> remover <code>D:\</code> e usar paths relativos + criação automática de <code>./outputs</code>.</li> | |
| <li><strong>Performance:</strong> limitar resolução, usar batch pequeno, considerar AMP/autocast e cache de modelo.</li> | |
| <li><strong>UX:</strong> abas claras (Upload / Inferência / Relatórios), mensagens de erro amigáveis e barras de progresso.</li> | |
| <li><strong>Deploy:</strong> commit no repo do Space, validar build e revisar logs; documentar uso no <code>README.md</code>.</li> | |
| </ul> | |
| </main> | |
| <footer> | |
| <p>Gerado automaticamente a partir do PDF original.</p> | |
| </footer> | |
| </body> | |
| </html> | |