Spaces:
Running
Running
File size: 16,512 Bytes
5354077 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 | <!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>
|