Plasmoid77/photo-to-pdf

Foto para PDF

O objetivo são páginas individuais na ordem correta, bordas justas e traços preservados nas margens. Trabalhe localmente com as fotos. Nenhum plugin especial ou MCP é necessário para este processo.

Método comprovado

1. Inspecione as fontes. Considere os EXIF. Verifique a ordem pelos nomes/horas e conteúdo; o horário de captura por si só não prova a sequência. Encontre capa, páginas duplas, duplicatas refotografadas, folhas em branco. O brilho não permite distinguir de forma confiável um desenho claro de uma página vazia. Se o papel estiver sobre um fundo claro (mesa branca, folha, tela próxima) e os contornos não forem detectados, peça para refotografar sobre uma superfície escura e fosca.
2. Marque as folhas. Para folhas avulsas (documentos, A4, inclusive paisagem), execute prepare --layout pages. O modo auto divide um contorno largo apenas se houver sinais de dobra (sombra do lombo ou linha de dobra), mas pode errar em folhas incomuns. scan.py prepare cria um manifest bruto e contatos com contornos. O detector encontra o papel como uma área clara e pouco saturada, puxa as bordas para a transição abrupta "papel → fundo escuro" e, para páginas duplas, procura a dobra. A dobra é o local onde as linhas de pauta se quebram. A sombra do lombo fica em uma página, portanto, para uma sombra profunda, a dobra é colocada na base da variação de brilho do lado escuro. Em cadernos de referência, o erro mediano da dobra é de 2–3 px. Isso ainda é uma hipótese. Páginas com flags não vazias (gutter-*, partner-mismatch, touches-frame, aspect-outlier, one-side-unruled, margin-ink, contour, full-frame-fallback, duplicate) devem ser marcadas manualmente primeiro. As demais, verifique pelas fotos: o detector pode pegar um monitor, um comprovante ou metade de uma página dupla. scan.py inspect fornece recortes ampliados de cada canto com divisões em frações do quadro — com eles, ajuste os cantos no manifest. Cada folha recebe seus quatro cantos TL, TR, BR, BL em coordenadas após rotação EXIF.
3. Corrija a perspectiva. Por padrão, uma matriz projetiva por folha. Não mova linhas/colunas individuais seguindo a borda detectada automaticamente: grade, texto, dedos e sombras podem ser confundidos com a borda e criar ondulações em toda a folha. Para um endireitamento completo e explícito de uma página de livro curvada, é necessário um algoritmo separado e comprovado, além de verificação geométrica adicional.
4. Ajuste as bordas. Prefira um corte justo, e não uma margem grande e uniforme em todos os lados. O bleed_px padrão é 0. Adicione uma margem pequena individualmente apenas se realmente houver conteúdo (anotações ou borda curvada com informação) além da reta entre os cantos. Verifique topos de letras, pontos em "i" e "j", datas à esquerda, texto próximo à dobra e linhas inferiores de desenhos. A linha inferior geralmente chega até a borda — ali o limite é pela mediana da borda, não justo. Se entre a borda ajustada e a margem do papel houver traços de caneta, o prepare desloca a borda para eles (campo margin_ink, no máximo 4% da largura). Lápis não é protegido assim; portanto, verifique visualmente datas e assinaturas a lápis próximas à borda. Uma borda curvada é aproximada por uma reta; os cantos de uma folha encurvada podem ficar ligeiramente fora do limite. Para cortes adicionais no PDF, use o comando crop, sem reesticar ou recompressar em JPEG.
5. Preserve traços claros. Correção suave de iluminação é aceitável; binarização agressiva pode apagar lápis. Para capas, fotos e cores importantes, desative enhance. Não redesenhe letras, esquemas ou partes faltantes do quadro com modelo generativo. Adicione OCR apenas quando necessário ou solicitado.
6. Verifique o PDF final. Use a skill de PDF disponível para criar/verificar, incluindo o marcador de operação previsto por ela. review renderiza todas as páginas, cria contatos e lista páginas com fundo ou conteúdo nas bordas (edges.json). compare mostra cada página da foto com margem de 4% e uma moldura vermelha de corte — visível o que fica fora. Revise o documento inteiro, não apenas as primeiras páginas. Esquema econômico para grande volume: execute compare para todas as páginas, distribua em lotes de no máximo 16 para agentes paralelos em um modelo barato com imagens (no Claude Code — Sonnet, no Codex — gpt-5.6-luna) com a tarefa de references/screening.md sem alterações. Abra você mesmo apenas as páginas onde o revisor indicou defect, e as páginas com flags do prepare; corrija apenas o confirmado. Em 32 páginas de rascunho com 8 erros de ângulo conhecidos >3%, esse esquema encontrou todos os 8 (Sonnet — 7, flags — o restante) com 4 falsos alarmes; Haiku encontrou 4 e adicionou apenas falsos alarmes, portanto apenas Haiku não é suficiente. No segundo caderno (32 páginas, tarefa não ajustada) Sonnet e gpt-5.6-luna encontraram faixas visíveis de fundo sem falsos alarmes, mas perderam páginas com erro de ângulo de 1,5–2%; gpt-6.1-terra marcou quase tudo, incluindo 12 de 19 páginas limpas — não há economia com ele. O esquema foi testado em um caderno, e a tarefa foi elaborada com base nas mesmas páginas: para documentos importantes ou dúvidas, revise todas as páginas você mesmo. Os números de página nas respostas dos revisores também verificam a ordem. Após o corte, verifique novamente as páginas afetadas; após alteração do algoritmo geométrico, verifique o documento inteiro. O número de páginas e um config correto não substituem a revisão.

Para essa digitalização, o usuário prefere remover folhas confirmadamente vazias; solicitação explícita para mantê-las tem prioridade. Elimine duplicatas após verificação visual, não por semelhança de grade/caligrafia. Mantenha a capa, a menos que haja outra instrução. Leia páginas duplas da esquerda para a direita quando a fonte estiver assim organizada.

Comandos

O caminho para os scripts é relativo a esta skill. Esquema e parâmetros: references/commands.md. Não transfira cantos, caminhos, números de página ou proporções de um caderno anterior.

python3 <skill>/scripts/scan.py prepare <photos> --work <work> --layout auto
python3 <skill>/scripts/scan.py inspect <work>/manifest.json --work <work>/inspect --ids 0006-L,0006-R
python3 <skill>/scripts/scan.py build <work>/manifest.json --output <work>/draft.pdf
python3 <skill>/scripts/scan.py measure <work>/draft-pages --work <work>/measure
python3 <skill>/scripts/scan.py review <work>/draft.pdf --work <work>/review
python3 <skill>/scripts/scan.py compare <work>/draft.scan.json --work <work>/compare

Dependências: Pillow, NumPy, OpenCV, ReportLab para fotos; pypdfium2 para crop; Poppler pdftoppm para review e measure em PDF. Importações separadas por comando. Verifique interpretadores/ambientes prontos disponíveis; se necessário, use um venv separado, sem alterar o Python global. Se OpenCV/NumPy estiverem como pacotes do sistema, crie o venv no mesmo interpretador com --system-site-packages (python3 -m venv; uv venv usa seu próprio Python por padrão e não enxergará o cv2 do sistema). Rede não é considerada obrigatória. Não incorpore caminhos do cache de uma máquina específica na skill.

Proporções e tamanho da folha. aspect: null é estimado a partir dos lados do contorno e, sob ângulo, pode ser deslocado em 1–2%. Para papel quadriculado, monte um rascunho e execute measure. Ele encontra o passo da quadrícula, calcula o tamanho físico das páginas e sugere um único aspect para todo o caderno e --width-mm. Use os valores da saída, não do caderno anterior. Com o mesmo --width-mm, todas as páginas do PDF terão o mesmo tamanho físico. Caso contrário, o tamanho é calculado a partir dos pixels e --dpi, e varia com a distância de captura.

build exige reviewed: true nas páginas incluídas: é uma marcação de verificação da marcação pelo agente, não uma aprovação adicional com o usuário. Não peça permissão para processamento rotineiro de fotos já fornecidas.

Regressões do detector. Um manifest verificado de caderno é a referência. Após alterar scan.py, execute prepare nas mesmas fotos e eval <novo manifest> --reference <referência>. O comando mostrará o erro dos ângulos em % da largura da página, a proporção de páginas marcadas e erros "silenciosos" — páginas não marcadas com erro maior que --tolerance (padrão 3%). Código de retorno 1 se houver mais erros silenciosos que --max-silent. Não coloque referências com fotos pessoais no repositório da skill.

Finalização

• Não modifique as fotos originais. Substitua o PDF existente após verificar a nova versão. Salve a marcação e os parâmetros para correções pontuais.
• Ao corrigir novamente, verifique primeiro a atualidade do arquivo. Evite recompressão JPEG acumulativa.
• Informe o resultado, o número de páginas e as limitações significativas das fontes. Se parte do conteúdo já estiver fora do quadro, indique isso em vez de afirmar que foi restaurado.
• A skill economiza preparação e reescrita de código; reconhecimento de bordas totalmente automático e eliminação da verificação visual não são prometidos.