🖼️ Roteiro de Validação e Otimização de Imagens

Este documento fornece um roteiro completo para validar, converter e otimizar imagens no projeto Artes do Sul.

📋 Índice

Pré-requisitos
Validação de Imagens
Conversão para WebP
Atualização de Referências
Arquivamento de Originais
Workflow Completo
Troubleshooting

🔧 Pré-requisitos

Ferramentas Necessárias

Instale pelo menos uma das seguintes ferramentas:

Opção 1: cwebp (Recomendado - Melhor qualidade)

# Via Chocolatey
choco install webp

# Ou baixe manualmente
# https://developers.google.com/speed/webp/download

Opção 2: ImageMagick

# Via Chocolatey
choco install imagemagick

# Ou baixe manualmente
# https://imagemagick.org/script/download.php#windows

Opção 3: Python com Pillow (Já instalado no projeto)

# Verificar se está instalado
python -c "from PIL import Image; print('OK')"

# Se não estiver, instalar
pip install Pillow

🔍 Validação de Imagens

Passo 1: Identificar Imagens que Precisam de Otimização

# Listar todas as imagens em assets/img
Get-ChildItem -Path "assets\img" -Recurse -Include *.jpg,*.jpeg,*.png | 
    Select-Object Name, Length, @{Name="SizeKB";Expression={[math]::Round($_.Length/1KB,2)}} | 
    Sort-Object Length -Descending | 
    Format-Table -AutoSize

# Encontrar imagens grandes (>500KB)
Get-ChildItem -Path "assets\img" -Recurse -Include *.jpg,*.jpeg,*.png | 
    Where-Object { $_.Length -gt 500KB } | 
    Select-Object FullName, @{Name="SizeMB";Expression={[math]::Round($_.Length/1MB,2)}}

Passo 2: Verificar Imagens sem Versão WebP

# Encontrar imagens que não têm versão WebP
Get-ChildItem -Path "assets\img" -Recurse -Include *.jpg,*.jpeg,*.png | 
    ForEach-Object {
        $webp = $_.FullName -replace '\.(jpg|jpeg|png)$', '.webp'
        if (-not (Test-Path $webp)) {
            [PSCustomObject]@{
                Image = $_.Name
                Path = $_.FullName
                SizeKB = [math]::Round($_.Length/1KB, 2)
            }
        }
    } | Format-Table -AutoSize

Passo 3: Verificar Referências em Posts

# Encontrar posts que referenciam imagens não otimizadas
Get-ChildItem -Path "_posts" -Recurse -Filter "*.md" | 
    Select-String -Pattern '\.(jpg|jpeg|png)' | 
    Select-Object Filename, LineNumber, Line

🔄 Conversão para WebP

Método 1: Script PowerShell (Recomendado)

O script convert_to_webp.ps1 detecta automaticamente qual ferramenta usar:

# Converter uma imagem específica
.\scripts\convert_to_webp.ps1 -ImagePath "assets\img\pacto-federativo.png"

# Com qualidade personalizada (1-100, padrão: 80)
.\scripts\convert_to_webp.ps1 -ImagePath "assets\img\pacto-federativo.png" -Quality 85

# Converter múltiplas imagens
Get-ChildItem -Path "assets\img" -Filter "*.png" | ForEach-Object {
    .\scripts\convert_to_webp.ps1 -ImagePath $_.FullName
}

Método 2: Script de Otimização em Lote

# Usar o script de otimização completo
.\scripts\optimize_images.ps1 -Path "assets\img" -ConvertToWebP

Método 3: Python (Alternativa)

# Converter uma imagem
python scripts/convert_to_webp_python.py assets/img/pacto-federativo.png 80

# Converter múltiplas imagens
Get-ChildItem -Path "assets\img" -Filter "*.png" | ForEach-Object {
    python scripts/convert_to_webp_python.py $_.FullName 80
}

Qualidade Recomendada

Tipo de Imagem	Qualidade	Uso
Fotografias	80-85	Melhor compressão mantendo qualidade
Screenshots	75-80	Boa compressão para imagens com texto
Logos/Ícones	90-95	Alta qualidade para gráficos
Thumbnails	70-75	Máxima compressão para miniaturas

📝 Atualização de Referências

Passo 1: Atualizar Posts para Usar WebP

# Atualizar automaticamente posts que têm WebP disponível
.\scripts\replace_images_with_webp.ps1 -PostsPath "_posts" -DryRun

# Aplicar mudanças
.\scripts\replace_images_with_webp.ps1 -PostsPath "_posts"

Passo 2: Atualizar Includes

# Atualizar projetos.md
.\scripts\update_projetos_webp.ps1 -DryRun

# Aplicar mudanças
.\scripts\update_projetos_webp.ps1

Passo 3: Verificar Referências Restantes

# Encontrar posts que ainda referenciam PNG/JPG
Get-ChildItem -Path "_posts" -Recurse -Filter "*.md" | 
    Select-String -Pattern '\.(jpg|jpeg|png)' | 
    Where-Object { $_.Line -notmatch 'webp' } | 
    Select-Object Filename, LineNumber, Line

📦 Arquivamento de Originais

Passo 1: Criar Estrutura de Arquivo

# Criar pasta de arquivo por mês
$archivePath = ".arquive\$(Get-Date -Format 'yyyy-MM')"
New-Item -ItemType Directory -Path $archivePath -Force

Passo 2: Mover Imagens Originais

# Mover imagens que já têm WebP para arquivo
Get-ChildItem -Path "assets\img" -Recurse -Include *.jpg,*.jpeg,*.png | 
    ForEach-Object {
        $webp = $_.FullName -replace '\.(jpg|jpeg|png)$', '.webp'
        if (Test-Path $webp) {
            $archivePath = ".arquive\$(Get-Date -Format 'yyyy-MM')"
            New-Item -ItemType Directory -Path $archivePath -Force | Out-Null
            $destPath = Join-Path $archivePath $_.Name
            Move-Item -Path $_.FullName -Destination $destPath -Force
            Write-Host "Arquivado: $($_.Name) -> $destPath"
        }
    }

Passo 3: Verificar Arquivo

# Listar arquivos arquivados
Get-ChildItem -Path ".arquive" -Recurse | 
    Select-Object FullName, Length, LastWriteTime | 
    Format-Table -AutoSize

🔄 Workflow Completo

Roteiro Passo a Passo

1. Preparação

# Verificar ferramentas instaladas
cwebp -version
# ou
magick -version
# ou
python -c "from PIL import Image; print('OK')"

2. Identificação

# Listar imagens grandes
Get-ChildItem -Path "assets\img" -Recurse -Include *.jpg,*.jpeg,*.png | 
    Where-Object { $_.Length -gt 500KB } | 
    Select-Object Name, @{Name="SizeMB";Expression={[math]::Round($_.Length/1MB,2)}}

3. Conversão

# Converter todas as imagens grandes para WebP
Get-ChildItem -Path "assets\img" -Recurse -Include *.jpg,*.jpeg,*.png | 
    Where-Object { $_.Length -gt 500KB } | 
    ForEach-Object {
        .\scripts\convert_to_webp.ps1 -ImagePath $_.FullName -Quality 80
    }

4. Validação

# Verificar se WebP foi criado e comparar tamanhos
Get-ChildItem -Path "assets\img" -Recurse -Include *.png | 
    ForEach-Object {
        $webp = $_.FullName -replace '\.png$', '.webp'
        if (Test-Path $webp) {
            $original = $_.Length
            $converted = (Get-Item $webp).Length
            $savings = $original - $converted
            $percent = ($savings / $original) * 100
            [PSCustomObject]@{
                Image = $_.Name
                Original = "$([math]::Round($original/1KB,2)) KB"
                WebP = "$([math]::Round($converted/1KB,2)) KB"
                Savings = "$([math]::Round($savings/1KB,2)) KB ($([math]::Round($percent,1))%)"
            }
        }
    } | Format-Table -AutoSize

5. Atualização de Referências

# Atualizar posts
.\scripts\replace_images_with_webp.ps1 -PostsPath "_posts"

# Atualizar includes
.\scripts\update_projetos_webp.ps1

6. Arquivamento (Opcional)

# Mover originais para arquivo
Get-ChildItem -Path "assets\img" -Recurse -Include *.jpg,*.jpeg,*.png | 
    ForEach-Object {
        $webp = $_.FullName -replace '\.(jpg|jpeg|png)$', '.webp'
        if (Test-Path $webp) {
            $archivePath = ".arquive\$(Get-Date -Format 'yyyy-MM')"
            New-Item -ItemType Directory -Path $archivePath -Force | Out-Null
            Move-Item -Path $_.FullName -Destination (Join-Path $archivePath $_.Name)
        }
    }

7. Verificação Final

# Verificar se não há mais referências a PNG/JPG em posts
Get-ChildItem -Path "_posts" -Recurse -Filter "*.md" | 
    Select-String -Pattern '\.(jpg|jpeg|png)' | 
    Measure-Object | 
    Select-Object -ExpandProperty Count

# Se retornar 0, todas as referências foram atualizadas!

🛠️ Scripts Disponíveis

1. `convert_to_webp.ps1`

Uso: Converter uma imagem específica para WebP

.\scripts\convert_to_webp.ps1 -ImagePath "assets\img\imagem.png" -Quality 80

2. `convert_to_webp_python.py`

Uso: Alternativa usando Python/Pillow

python scripts/convert_to_webp_python.py assets/img/imagem.png 80

3. `optimize_images.ps1`

Uso: Otimização completa (WebP + redimensionamento + compressão)

.\scripts\optimize_images.ps1 -Path "assets\img" -Quality 80

4. `replace_images_with_webp.ps1`

Uso: Substituir referências em posts e arquivar originais

.\scripts\replace_images_with_webp.ps1 -PostsPath "_posts" -ArchivePath ".arquive"

5. `update_projetos_webp.ps1`

Uso: Atualizar referências em _includes/projetos.md

.\scripts\update_projetos_webp.ps1

📊 Métricas de Sucesso

Antes da Otimização

Tamanho total das imagens: X MB
Número de imagens: Y
Imagens sem WebP: Z

Após Otimização

Tamanho total reduzido: X - Y MB (redução de Z%)
Todas as imagens têm versão WebP
Referências atualizadas nos posts

Verificar Economia Total

# Calcular economia total
$originalTotal = (Get-ChildItem -Path "assets\img" -Recurse -Include *.jpg,*.jpeg,*.png | 
    Measure-Object -Property Length -Sum).Sum

$webpTotal = (Get-ChildItem -Path "assets\img" -Recurse -Include *.webp | 
    Measure-Object -Property Length -Sum).Sum

$savings = $originalTotal - $webpTotal
$percent = ($savings / $originalTotal) * 100

Write-Host "Economia total: $([math]::Round($savings/1MB,2)) MB ($([math]::Round($percent,1))%)"

⚠️ Troubleshooting

Problema: cwebp não encontrado

Solução:

# Instalar via Chocolatey
choco install webp

# Ou adicionar ao PATH manualmente
# Baixar de: https://developers.google.com/speed/webp/download

Problema: ImageMagick não encontrado

Solução:

# Instalar via Chocolatey
choco install imagemagick

# Ou baixar de: https://imagemagick.org/script/download.php#windows

Problema: Pillow não instalado

Solução:

pip install Pillow

Problema: Script não executa

Solução:

# Permitir execução de scripts
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problema: WebP não é criado

Verificações:

Verificar se a imagem original existe
Verificar permissões de escrita
Verificar espaço em disco
Tentar converter manualmente para testar

Problema: Qualidade muito baixa

Solução:

# Aumentar qualidade (90-95 para alta qualidade)
.\scripts\convert_to_webp.ps1 -ImagePath "imagem.png" -Quality 90

📋 Checklist de Validação

Use este checklist para garantir que todas as imagens estão otimizadas:

Todas as imagens grandes (>500KB) foram convertidas para WebP
Todas as referências em posts foram atualizadas para WebP
_includes/projetos.md foi atualizado
Imagens originais foram arquivadas (se desejado)
Economia de espaço foi calculada
Site foi testado localmente após mudanças
Build do Jekyll foi executado sem erros

🔗 Recursos Adicionais

📝 Notas

Sempre faça backup antes de arquivar imagens originais
Teste localmente após atualizar referências
Mantenha originais até confirmar que WebP funciona corretamente
Use qualidade 80-85 para melhor equilíbrio tamanho/qualidade
Valide visualmente algumas imagens convertidas para garantir qualidade

Última atualização: 2025-01-27

...reflexão...

getMessage();

📋 Índice

🔧 Pré-requisitos

Ferramentas Necessárias

Opção 1: cwebp (Recomendado - Melhor qualidade)

Opção 2: ImageMagick

Opção 3: Python com Pillow (Já instalado no projeto)

🔍 Validação de Imagens

Passo 1: Identificar Imagens que Precisam de Otimização

Passo 2: Verificar Imagens sem Versão WebP

Passo 3: Verificar Referências em Posts

🔄 Conversão para WebP

Método 1: Script PowerShell (Recomendado)

Método 2: Script de Otimização em Lote

Método 3: Python (Alternativa)

Qualidade Recomendada

📝 Atualização de Referências

Passo 1: Atualizar Posts para Usar WebP

Passo 2: Atualizar Includes

Passo 3: Verificar Referências Restantes

📦 Arquivamento de Originais

Passo 1: Criar Estrutura de Arquivo

Passo 2: Mover Imagens Originais

Passo 3: Verificar Arquivo

🔄 Workflow Completo

Roteiro Passo a Passo

1. Preparação

2. Identificação

3. Conversão

4. Validação

5. Atualização de Referências

6. Arquivamento (Opcional)

7. Verificação Final

🛠️ Scripts Disponíveis

1. convert_to_webp.ps1

2. convert_to_webp_python.py

3. optimize_images.ps1

4. replace_images_with_webp.ps1

5. update_projetos_webp.ps1

📊 Métricas de Sucesso

Antes da Otimização

Após Otimização

Verificar Economia Total

⚠️ Troubleshooting

Problema: cwebp não encontrado

Problema: ImageMagick não encontrado

Problema: Pillow não instalado

Problema: Script não executa

Problema: WebP não é criado

Problema: Qualidade muito baixa

📋 Checklist de Validação

🔗 Recursos Adicionais

📝 Notas

Modelos (para web app):

Erro

1. `convert_to_webp.ps1`

2. `convert_to_webp_python.py`

3. `optimize_images.ps1`

4. `replace_images_with_webp.ps1`

5. `update_projetos_webp.ps1`