Spaces:

roundb
/

Conhecimento

Running

App Files Files Community

roundb commited on Dec 16, 2025

Commit

5354077

verified ·

1 Parent(s): 05a17c7

Upload index.html

Browse files

Files changed (1) hide show

index.html +383 -0

index.html ADDED Viewed

	@@ -0,0 +1,383 @@

+<!doctype html>
+<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>