Extraer imágenes en miniatura de documentos

🤖/document/thumbs genera una imagen para cada página de un archivo PDF o un archivo GIF animado que recorre todas las páginas en bucle.

Ejemplo de uso

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

Parámetros

• interpolate

  boolean | Record<string, boolean>

  Controla si las Assembly Variables se interpolan en campos de instrucciones individuales.

  De forma predeterminada, la mayoría de los campos de instrucciones de los Robots interpolan Assembly Variables. Establece esta opción en false para tratar todos los campos de instrucciones como texto literal, o establece la ruta de un campo individual en false para tratar únicamente ese campo como texto literal. En el caso de los campos específicos de un Robot que son literales de forma predeterminada, establece esta opción en true o la ruta de ese campo en true para volver a habilitar la interpolación.

  Usa nombres de campos como path o rutas con puntos como ffmpeg.vf para los objetos anidados.

• output_meta

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

  Te permite especificar un conjunto de metadatos cuyo cálculo requiere más recursos de CPU y que, por lo tanto, está desactivado de forma predeterminada para que tus Assemblies se procesen rápidamente.

  Para imágenes, puedes añadir "has_transparency": true a este objeto para determinar si la imagen contiene partes transparentes y "dominant_colors": true para extraer un array de códigos de color hexadecimales de la imagen.

  Para imágenes, también puedes añadir "blurhash": true para extraer una cadena BlurHash⁠, una representación compacta de un marcador de posición para la imagen que resulta útil para mostrar una vista previa desenfocada mientras se carga la imagen completa.

  Para videos, puedes añadir el parámetro "colorspace": true para extraer el espacio de color del video de salida.

  Para videos, también puedes añadir "interlaced": true para detectar si el video está entrelazado. Esto combina el indicador field_order de ffprobe, cuyo costo en recursos de procesamiento es bajo, con una pasada de muestreo limitada mediante idet sobre los primeros fotogramas de la fuente, y expone interlaced, field_order y un objeto de diagnóstico interlace_detection en file.meta. Esto requiere muchos recursos computacionales y se factura en consecuencia.

  Para audio, puedes añadir "mean_volume": true para obtener un único valor que represente el volumen promedio del archivo de audio.

  También puedes establecerlo en false para omitir la extracción de metadatos y acelerar la transcodificación.

• user_meta

  Record<string, any>(valor predeterminado: {})

  Añade metadatos personalizados a cada archivo emitido por este Robot sin modificar el contenido del archivo.

  Los valores se combinan con los user_meta existentes en el archivo de entrada. Si ambos objetos contienen la misma clave, el valor de este Robot tiene prioridad. Se admiten Assembly Variables, por ejemplo { "internal_file_id": "${file.id}" }.

• result

  boolean(valor predeterminado: false)

  Indica si los resultados de este Step deben aparecer en el Assembly Status JSON

• queue

  batch

  Establecer la cola en «batch» reduce manualmente la prioridad de los Jobs de este Step para evitar consumir cupos prioritarios con Jobs que no necesitan un tiempo de espera cero en la cola

• force_accept

  boolean(valor predeterminado: false)

  Forzar a un Robot a aceptar un tipo de archivo que habría ignorado.

  De forma predeterminada, los Robots ignoran los archivos que no reconocen. 🤖/video/encode, por ejemplo, ignorará sin problemas las imágenes de entrada.

  Si configuras el parámetro force_accept como true, puedes forzar a los Robots a aceptar todos los archivos que reciban. Esto normalmente provocará errores y solo debe usarse para depuración o para abordar casos extremos.

• ignore_errors

  boolean | Array<meta | execute>(valor predeterminado: [])

  Ignorar errores durante fases específicas del procesamiento.

  Establecer este parámetro en ["meta"] hará que el Robot ignore los errores durante la extracción de metadatos.

  Establecer este parámetro en ["execute"] hará que el Robot ignore los errores durante la fase principal de ejecución.

  Configurar este parámetro como true equivale a ["meta", "execute"] y hará que se ignoren los errores en ambas fases.

• use

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

  Especifica qué Step o Steps se usarán como entrada.

  • Puedes elegir cualquier nombre para los Steps, excepto ":original" (reservado para las subidas de usuarios gestionadas por Transloadit)
  • Puedes proporcionar varios Steps como entrada mediante arrays:

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

  • También puedes etiquetar los Steps de entrada con as para comunicar la intención semántica a los Robots:

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

  Consejo

  Probablemente eso sea todo lo que necesitas saber sobre use, pero puedes consultar los casos de uso avanzados.

• page

  string | number | null(valor predeterminado: null)

  La página del PDF que quieres convertir en una imagen. De forma predeterminada, el valor es null, lo que significa que todas las páginas se convertirán en imágenes.

• page_range

  string | null(valor predeterminado: null)

  Un intervalo de páginas que se extraerá, con el formato "start-end" (p. ej., "1-20"). La extracción comienza en la primera página del intervalo y continúa secuencialmente; se detiene sin generar errores cuando una página no existe. Esto resulta útil para archivos PDF cuyo número total de páginas no puede determinarse.

  Este parámetro no puede usarse junto con page y no es compatible con el formato GIF. Cuando se establece page_range, el Robot no necesita conocer de antemano el número total de páginas, lo que lo hace robusto para archivos PDF en los que falla la detección del número de páginas.

• format

  gif | jpeg | jpg | png(valor predeterminado: "png")

  El formato de las imágenes extraídas.

  Si especificas el valor "gif", se crea un GIF animado que recorre todas las páginas. Consulta esta demo EN (English) para obtener más información.

• delay

  string | number

  Si el formato de salida es "gif", este parámetro establece el número de centésimas de segundo que deben transcurrir antes de mostrar el siguiente fotograma de la animación. Por ejemplo, establece este parámetro en 100 para dejar que transcurra 1 segundo entre los fotogramas del GIF animado.

  Si el formato de salida no es "gif", este parámetro no tiene ningún efecto.

• stack

  ghostscript | vips | pdfium

  Selecciona la pila de renderizado de PDF. El valor predeterminado es Ghostscript.

  Usa "pdfium" para rasterizar páginas específicas o archivos PDF de una sola página con alta densidad de puntos por pulgada cuando Ghostscript sea demasiado lento o agote el espacio temporal, por ejemplo, con archivos PDF de CAD o planos de alta resolución, o archivos PDF inmobiliarios con capas. Esta pila utiliza PDFium mediante los bindings de Python pypdfium2 y Pillow para el encoding final de la imagen.

  Usa "vips" únicamente cuando quieras explícitamente que los archivos PDF se carguen con libvips. Tiene una menor sobrecarga, pero PDFium fue más rápido en las pruebas de planos de planta con alta densidad de puntos por pulgada y produjo una calidad de salida comparable.

  Actualmente, la pila "pdfium" admite salida JPG/PNG, resize_strategy: "fit", un valor específico de page o archivos PDF de una sola página, fondos hexadecimales opacos, antialiasing y pdf_use_cropbox.

  Actualmente, la pila "vips" admite salida JPG/PNG, resize_strategy: "fit", un valor específico de page o archivos PDF de una sola página, y fondos hexadecimales o transparentes.

• width

  string | number

  Ancho de la nueva imagen, en píxeles. Si no se especifica, se usará de forma predeterminada el ancho de la imagen de entrada

• height

  string | number

  Altura de la nueva imagen, en píxeles. Si no se especifica, se usará de forma predeterminada la altura de la imagen de entrada

• resize_strategy

  crop | fillcrop | fit | min_fit | pad | stretch(valor predeterminado: "pad")

  Una de las estrategias de redimensionamiento disponibles.

• background

  string(valor predeterminado: "#FFFFFF")

  El código hexadecimal o el nombre⁠ del color que se utiliza para rellenar el fondo (solo se usa con la estrategia de redimensionamiento pad).

  De forma predeterminada, el fondo de las imágenes transparentes se cambia a blanco. Consulta esta demo EN (English) para obtener información detallada sobre cómo conservar la transparencia en todos los tipos de imagen.

• alpha

  Remove | Set

  Cambia el funcionamiento del canal alfa de la imagen resultante. Los valores válidos son "Set" para habilitar la transparencia y "Remove" para eliminarla.

  Consulta aquí⁠ la documentación de ImageMagick para ver una lista de todos los valores válidos.

• density

  string

  Mientras que la calidad en memoria y la profundidad del formato de archivo especifican la resolución de color, la densidad de una imagen es su resolución espacial. Es decir, es la densidad de una imagen (en píxeles por pulgada) y define la separación entre los píxeles individuales (o su tamaño). Define el tamaño de la imagen en términos reales cuando se muestra en dispositivos o se imprime.

  Puedes establecer este valor como width o con el formato widthxheight.

  Si la imagen convertida tiene baja resolución, prueba a usar el parámetro de densidad para corregirla.

• antialiasing

  boolean(valor predeterminado: false)

  Controla si se utiliza el suavizado para eliminar los bordes dentados del texto o las imágenes de un documento.

• colorspace

  CMY | CMYK | Gray | HCL | HCLp | HSB | HSI | 28 más ↓

  Establece el espacio de color de la imagen. Consulta la documentación de ImageMagick⁠ para obtener información detallada sobre los valores disponibles.

  Ten en cuenta que, si usabas "RGB", recomendamos usar "sRGB". ImageMagick podría intentar encontrar el valor de colorspace más eficiente según el color de una imagen y utilizar de forma predeterminada, por ejemplo, "Gray". En ese caso, quizá debas usar este parámetro para forzar los colores.

• trim_whitespace

  boolean(valor predeterminado: true)

  Determina si el espacio en blanco adicional alrededor del PDF debe recortarse antes de convertirlo en una imagen. Si estableces este parámetro en true, solo se mostrará en la imagen el contenido real de la página del PDF.

  Si necesitas reflejar las dimensiones del PDF en la imagen, por lo general conviene establecer este parámetro en false.

• pdf_use_cropbox

  boolean(valor predeterminado: true)

  Algunos documentos PDF indican dimensiones incorrectas. Por ejemplo, pueden indicar que tienen orientación horizontal, aunque al abrirlos en lectores de escritorio adecuados en realidad tengan orientación vertical. Esto puede ocurrir si el documento tiene definido un cuadro de recorte. Cuando esta opción está habilitada (de forma predeterminada), el cuadro de recorte es el factor principal para determinar las dimensiones de las miniaturas resultantes.

• turbo

  boolean(valor predeterminado: true)

  Habilita el modo de alto rendimiento para procesar documentos más rápido.

  Cuando está habilitado, Turbo Mode proporciona dos optimizaciones clave:

  1. Extracción de páginas en paralelo: En documentos con más de 5 páginas, se ejecutan varios procesos en paralelo para extraer páginas simultáneamente. La cantidad de procesos paralelos se adapta al tamaño del documento (hasta 4 procesos para documentos con 13 páginas o más).

  2. Redimensionamiento distribuido: Las páginas extraídas se redimensionan simultáneamente en varias máquinas, lo que permite procesar documentos grandes hasta 20 veces más rápido.

  Los archivos se emiten a medida que están disponibles durante el procesamiento. Si estableces este parámetro en false, las páginas se extraen secuencialmente mediante un único proceso y los archivos se emiten solo después de que finaliza todo el procesamiento.

  Turbo Mode aumenta el precio porque el tamaño de archivo del documento de entrada se suma por cada página extraída. En documentos de una sola página, no mejora el rendimiento ni aumenta los cargos.

Demos

Publicaciones relacionadas del blog