Extrair imagens em miniatura de documentos

🤖/document/thumbs gera uma imagem para cada página de um arquivo PDF ou um arquivo GIF animado que percorre todas as páginas em loop.

Exemplo de uso

{
  "steps": {
    "thumbnailed": {
      "resize_strategy": "fit",
      "robot": "/document/thumbs",
      "trim_whitespace": false,
      "use": ":original",
      "width": 200
    }
  }
}

Parâmetros

• interpolate

  boolean | Record<string, boolean>

  Controla se as Assembly Variables são interpoladas em campos individuais de instruções.

  Por padrão, a maioria dos campos de instruções dos Robots interpola Assembly Variables. Defina isso como false para tratar todos os campos de instruções como texto literal, ou defina o caminho de um campo individual como false para tratar apenas esse campo como texto literal. Para campos específicos de um Robot que são literais por padrão, defina isso como true ou defina o caminho desse campo como true para voltar a usar a interpolação.

  Use nomes de campos como path ou caminhos com pontos como ffmpeg.vf para objetos aninhados.

• output_meta

  Record<string, boolean> | boolean | Array<string>

  Permite especificar um conjunto de metadados cujo cálculo exige mais CPU e que, por isso, vem desativado por padrão para manter o processamento das suas Assemblies rápido.

  Para imagens, você pode adicionar "has_transparency": true neste objeto para extrair se a imagem contém partes transparentes e "dominant_colors": true para extrair um array de códigos de cores hexadecimais da imagem.

  Para imagens, você também pode adicionar "blurhash": true para extrair uma string BlurHash⁠ — uma representação compacta de um placeholder da imagem, útil para exibir uma prévia desfocada enquanto a imagem completa carrega.

  Para vídeos, você pode adicionar o parâmetro "colorspace": true para extrair o espaço de cores do vídeo de saída.

  Para vídeos, você também pode adicionar "interlaced": true para detectar se o vídeo é entrelaçado. Isso combina a flag computacionalmente barata field_order do ffprobe com uma passagem de amostragem idet limitada sobre os primeiros quadros da origem, expondo interlaced, field_order e um objeto de diagnóstico interlace_detection em file.meta. Isso é computacionalmente caro e cobrado de acordo.

  Para áudio, você pode adicionar "mean_volume": true para obter um único valor que representa o volume médio do arquivo de áudio.

  Você também pode definir isso como false para pular a extração de metadados e acelerar a transcodificação.

• user_meta

  Record<string, any>(padrão: {})

  Adiciona metadados JSON personalizados a cada arquivo emitido sem modificar seu conteúdo. Objetos e arrays aninhados são suportados.

  A herança depende do Robot. Os valores são mesclados com o user_meta existente no arquivo de saída; o Step atual substitui as chaves de nível superior com o mesmo nome. Atribua explicitamente as chaves necessárias quando um Robot criar novas saídas.

  Nos Steps de processamento, ${file.*} se refere à primeira entrada e ${result.*} ao arquivo emitido. Os valores são avaliados para cada saída após a execução do Robot, antes da extração subsequente de metadados e do armazenamento temporário. Em :original, os valores são avaliados para cada upload antes da extração de metadados.

  Os Steps subsequentes leem ${file.user_meta.key}. Consulte Metadados personalizados para ver um exemplo completo e as regras de herança.

• result

  boolean(padrão: false)

  Se os resultados deste Step devem estar presentes no Assembly Status JSON

• queue

  batch

  Definir a fila como “batch” rebaixa manualmente a prioridade dos Jobs deste Step, para evitar o consumo de vagas prioritárias de Jobs em Jobs que não precisam de tempo zero de espera na fila

• force_accept

  boolean(padrão: false)

  Forçar um Robot a aceitar um tipo de arquivo que ele teria ignorado.

  Por padrão, os Robots ignoram arquivos que não conhecem. O 🤖/video/encode, por exemplo, ignora tranquilamente imagens de entrada.

  Com o parâmetro force_accept definido como true, você pode forçar os Robots a aceitar todos os arquivos enviados a eles. Isso normalmente leva a erros e só deve ser usado para depuração ou para lidar com casos extremos.

• ignore_errors

  boolean | Array<meta | execute>(padrão: [])

  Ignorar erros durante fases específicas do processamento.

  Definir isso como ["meta"] fará com que o Robot ignore erros durante a extração de metadados.

  Definir isso como ["execute"] fará com que o Robot ignore erros durante a fase principal de execução.

  Definir isso como true equivale a ["meta", "execute"] e fará com que erros sejam ignorados nas duas fases.

• use

  string | Array<string> | Array<object> | object

  Especifica quais Steps usar como entrada.

  • Você pode escolher qualquer nome para os Steps, exceto ":original" (reservado para uploads de usuários tratados pela Transloadit)
  • Você pode fornecer vários Steps como entrada usando arrays:

    {
      "use": [
        ":original",
        "encoded",
        "resized"
      ]
    }
    

  • Você também pode marcar os Steps de entrada com as para transmitir intenção semântica aos Robots:

    {
      "use": [
        {
          "name": ":original",
          "as": "image"
        },
        {
          "name": ":original",
          "as": "mask"
        }
      ]
    }
    

  Dica

  Provavelmente é tudo o que você precisa saber sobre use, mas você pode ver os casos de uso avançados.

• page

  string | number | null(padrão: null)

  A página do PDF que você quer converter em imagem. Por padrão, o valor é null, o que significa que todas as páginas serão convertidas em imagens.

• page_range

  string | null(padrão: null)

  Um intervalo de páginas a extrair, no formato "start-end" (por exemplo, "1-20"). A extração começa na primeira página do intervalo e prossegue sequencialmente, encerrando normalmente quando uma página não existe. Isso é útil para PDFs cujo número total de páginas não pode ser determinado.

  O início deve ser pelo menos 1, e o fim deve ser maior ou igual ao início.

  Este parâmetro não pode ser usado junto com page e não é compatível com o formato GIF. Quando page_range está definido, o Robot não precisa saber antecipadamente o número total de páginas, o que o torna robusto para PDFs em que a detecção do número de páginas falha.

• format

  gif | jpeg | jpg | png(padrão: "png")

  O formato das imagens extraídas.

  Se você especificar o valor "gif", será criado um GIF animado que percorre todas as páginas. Veja esta demonstração EN (English) para saber mais.

• delay

  string | number

  Se o formato de saída for "gif", este parâmetro define o intervalo em centésimos de segundo antes da exibição do próximo quadro da animação. Defina-o como 100, por exemplo, para que se passe 1 segundo entre os quadros do GIF animado.

  Se o formato de saída não for "gif", este parâmetro não terá efeito.

• stack

  ghostscript | vips | pdfium

  Seleciona o stack de renderização de PDF. O padrão é Ghostscript.

  Use "pdfium" para rasterização de PDFs em alto DPI de páginas específicas ou de página única quando o Ghostscript for muito lento ou esgotar o espaço temporário, por exemplo, com PDFs de CAD em alta resolução, plantas ou PDFs imobiliários com camadas. Esse stack usa PDFium por meio dos bindings Python pypdfium2 e Pillow para a codificação final da imagem.

  Use "vips" somente quando você quiser explicitamente carregar PDFs com libvips. Ele tem menor sobrecarga, mas o PDFium foi mais rápido em testes com plantas baixas em alto DPI, produzindo qualidade de saída comparável.

  O stack "pdfium" atualmente oferece suporte a saída JPG/PNG, resize_strategy: "fit", um page específico ou PDFs de página única, fundos opacos em hexadecimal, antialiasing e pdf_use_cropbox.

  O stack "vips" atualmente oferece suporte a saída JPG/PNG, resize_strategy: "fit", um page específico ou PDFs de página única e fundos em hexadecimal ou transparentes.

• width

  string | number

  Largura da nova imagem, em pixels. Se não for especificada, o padrão será a largura da imagem de entrada

• height

  string | number

  Altura da nova imagem, em pixels. Se não for especificada, será usada a altura da imagem de entrada

• resize_strategy

  crop | fillcrop | fit | min_fit | pad | stretch(padrão: "pad")

  Uma das estratégias de redimensionamento disponíveis.

• background

  string(padrão: "#FFFFFF")

  O código hexadecimal ou o nome⁠ da cor usada para preencher o fundo (usado apenas na estratégia de redimensionamento pad).

  Por padrão, o fundo de imagens transparentes é alterado para branco. Para detalhes sobre como preservar a transparência em todos os tipos de imagem, veja esta demonstração EN (English).

• alpha

  Remove | Set

  Altera como o canal alfa da imagem resultante deve funcionar. Os valores válidos são "Set" para habilitar a transparência e "Remove" para remover a transparência.

  Para ver a lista de todos os valores válidos, consulte a documentação do ImageMagick aqui⁠.

• density

  string

  Enquanto a qualidade em memória e a profundidade do formato de arquivo especificam a resolução de cores, a densidade de uma imagem é sua resolução espacial. Ou seja, é a densidade (em pixels por polegada) de uma imagem e define a distância entre os pixels individuais (ou o tamanho deles). Ela define o tamanho físico da imagem quando exibida em dispositivos ou impressa.

  Você pode definir este valor como um width específico ou no formato widthxheight.

  Se a imagem convertida tiver baixa resolução, tente usar o parâmetro density para resolver isso.

• antialiasing

  boolean(padrão: false)

  Controla se o antialiasing é usado ou não para remover bordas serrilhadas de textos ou imagens em um documento.

• colorspace

  CMY | CMYK | Gray | HCL | HCLp | HSB | HSI | mais 28 ↓

  Define o espaço de cores da imagem. Para detalhes sobre os valores disponíveis, consulte a documentação do ImageMagick⁠.

  Observe que, se você estava usando "RGB", recomendamos usar "sRGB". O ImageMagick pode tentar encontrar o colorspace mais eficiente com base na cor de uma imagem e adotar, por exemplo, "Gray" como padrão. Nesse caso, para forçar as cores, talvez seja necessário usar este parâmetro.

• trim_whitespace

  boolean(padrão: true)

  Determina se o espaço em branco adicional ao redor do PDF deve ser removido antes da conversão em imagem. Se você definir este parâmetro como true, apenas o conteúdo real da página do PDF será exibido na imagem.

  Se você precisar refletir as dimensões do PDF na imagem, geralmente é uma boa ideia definir este parâmetro como false.

• pdf_use_cropbox

  boolean(padrão: true)

  Alguns documentos PDF informam dimensões incorretas. Por exemplo, indicam que estão em modo paisagem, mas, quando abertos em bons leitores para desktop, estão na verdade em modo retrato. Isso pode acontecer se o documento tiver uma cropbox definida. Quando esta opção está habilitada (por padrão), a cropbox tem prioridade na determinação das dimensões das miniaturas resultantes.

• turbo

  boolean(padrão: true)

  Ativa o modo de alto desempenho para um processamento mais rápido de documentos.

  Quando ativado, o Turbo Mode oferece duas otimizações principais:

  1. Extração paralela de páginas: Para documentos com mais de 5 páginas, vários processos são executados em paralelo para extrair páginas simultaneamente. O número de processos paralelos aumenta conforme o tamanho do documento (até 4 processos para documentos com 13 ou mais páginas).

  2. Redimensionamento distribuído: As páginas extraídas são redimensionadas simultaneamente em várias máquinas, proporcionando um processamento até 20 vezes mais rápido para documentos grandes.

  Os arquivos são disponibilizados à medida que ficam prontos durante o processamento. Se você definir este parâmetro como false, as páginas serão extraídas sequencialmente usando um único processo, e os arquivos serão disponibilizados somente após a conclusão de todo o processamento.

  O Turbo Mode aumenta o preço, pois o tamanho do arquivo do documento de entrada é somado a cada página extraída. Não há benefícios de desempenho nem aumento nas cobranças para documentos de página única.

Demonstrações

Publicações relacionadas no blog