Extraire des miniatures de documents

🤖/document/thumbs génère une image pour chaque page d’un fichier PDF ou un fichier GIF animé qui fait défiler toutes les pages en boucle.

Exemple d’utilisation

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

Paramètres

• interpolate

  boolean | Record<string, boolean>

  Détermine si les Assembly Variables sont interpolées pour chaque champ d’instruction.

  Par défaut, la plupart des champs d’instruction des Robots interpolent les Assembly Variables. Définissez ce paramètre sur false pour traiter tous les champs d’instruction comme du texte littéral, ou définissez le chemin d’un champ individuel sur false pour traiter uniquement ce champ comme du texte littéral. Pour les champs propres à un Robot qui sont littéraux par défaut, définissez ce paramètre sur true ou définissez le chemin de ce champ sur true pour réactiver l’interpolation.

  Utilisez des noms de champs tels que path, ou des chemins avec points tels que ffmpeg.vf pour les objets imbriqués.

• output_meta

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

  Permet de spécifier un ensemble de métadonnées dont le calcul est plus coûteux en puissance CPU et qui sont donc désactivées par défaut afin que le traitement de vos Assemblies reste rapide.

  Pour les images, vous pouvez ajouter "has_transparency": true dans cet objet pour déterminer si l’image contient des parties transparentes, et "dominant_colors": true pour extraire de l’image un tableau de codes couleur hexadécimaux.

  Pour les images, vous pouvez également ajouter "blurhash": true pour extraire une chaîne BlurHash⁠ — une représentation compacte d’un espace réservé pour l’image, utile pour afficher un aperçu flou pendant le chargement de l’image complète.

  Pour les images, "thumbhash": true extrait plutôt un ThumbHash⁠ encodé en base64 dans meta.thumbhash, accompagné de meta.has_alpha (qui indique si un canal alpha existe, même lorsque l’image est entièrement opaque). Il décrit les pixels orientés selon les données EXIF et utilise la première image des images animées. L’extraction est effectuée au mieux : les images de plus de 40 mégapixels, les formats non pris en charge ou un décodage échoué ou limité ne produisent aucun espace réservé. Une extraction réussie ajoute des frais de métadonnées équivalents à 20 % des octets de ce fichier. Aucun supplément ThumbHash ne s’applique lorsque l’option est désactivée ou lorsqu’aucun hash n’est produit.

  Définissez cette option sur le Step qui produit l’image, par exemple /upload/handle pour les originaux téléversés ou /image/resize pour les sorties traitées. La définir uniquement sur /transloadit/store ne déclenche pas l’extraction : le stockage conserve les métadonnées du Step producteur. Transloadit Storage conserve un hash généré avec sa version immuable et le renvoie dans les résultats stockés et lors des lectures natives de ressources. Les téléversements directs vers S3 ne génèrent pas d’espaces réservés. Un espace réservé contient des informations sur l’image : protégez-le donc avec les mêmes contrôles d’accès que l’image complète.

  Pour les vidéos, vous pouvez ajouter le paramètre "colorspace": true pour extraire l’espace colorimétrique de la vidéo de sortie.

  Pour les vidéos, vous pouvez également ajouter "interlaced": true pour détecter si la vidéo est entrelacée. Cette option combine l’indicateur ffprobe peu coûteux field_order avec une passe d’échantillonnage idet limitée sur les premières images de la source, et expose interlaced, field_order ainsi qu’un objet de diagnostic interlace_detection sous file.meta. Cette opération est coûteuse en calcul et facturée en conséquence.

  Pour l’audio, vous pouvez ajouter "mean_volume": true pour obtenir une valeur unique représentant le volume moyen du fichier audio.

  Vous pouvez également définir cette option sur false pour ignorer l’extraction des métadonnées et accélérer le transcodage.

• user_meta

  Record<string, any>(par défaut : {})

  Ajoute des métadonnées JSON personnalisées à chaque fichier émis sans modifier son contenu. Les objets et tableaux imbriqués sont pris en charge.

  L’héritage dépend du Robot. Les valeurs sont fusionnées avec la valeur user_meta existante du fichier de sortie ; le Step actuel remplace les clés de premier niveau correspondantes. Attribuez explicitement les clés requises lorsqu’un Robot crée de nouvelles sorties.

  Dans les Steps de traitement, ${file.*} désigne la première entrée et ${result.*} le fichier émis. Les valeurs sont évaluées pour chaque sortie après l’exécution du Robot, avant l’extraction ultérieure des métadonnées et le stockage temporaire. Sur :original, les valeurs sont évaluées pour chaque téléversement avant l’extraction des métadonnées.

  Les Steps en aval lisent ${file.user_meta.key}. Consultez Métadonnées personnalisées pour un exemple complet et les règles d’héritage.

• result

  boolean(par défaut : false)

  Indique si les résultats de ce Step doivent figurer dans l’Assembly Status JSON

• queue

  batch

  Définir la file d’attente sur « batch » abaisse manuellement la priorité des Jobs de ce Step afin d’éviter de consommer des emplacements prioritaires de Jobs pour des Jobs qui n’ont pas besoin d’un temps d’attente nul dans la file

• force_accept

  boolean(par défaut : false)

  Forcer un Robot à accepter un type de fichier qu’il aurait ignoré.

  Par défaut, les Robots ignorent les fichiers qu’ils ne connaissent pas. Le Robot 🤖/video/encode, par exemple, ignorera volontiers les images en entrée.

  Avec le paramètre force_accept défini sur true, vous pouvez forcer les Robots à accepter tous les fichiers qui leur sont envoyés. Cela entraîne généralement des erreurs et ne doit être utilisé que pour le débogage ou pour traiter des cas limites.

• ignore_errors

  boolean | Array<meta | execute>(par défaut : [])

  Ignore les erreurs pendant certaines phases du traitement.

  Si vous définissez cette valeur sur ["meta"], le Robot ignorera les erreurs lors de l’extraction des métadonnées.

  Si vous définissez cette valeur sur ["execute"], le Robot ignorera les erreurs lors de la phase d’exécution principale.

  Définir cette valeur sur true équivaut à ["meta", "execute"] : les erreurs seront alors ignorées dans les deux phases.

• use

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

  Indique quel(s) Step(s) utiliser comme entrée.

  • Vous pouvez choisir n’importe quel nom pour les Steps, sauf ":original" (réservé aux téléversements des utilisateurs gérés par Transloadit)
  • Vous pouvez fournir plusieurs Steps en entrée à l’aide de tableaux :

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

  • Vous pouvez également étiqueter les Steps d’entrée avec as pour transmettre une intention sémantique aux Robots :

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

  Astuce

  C’est probablement tout ce que vous devez savoir sur use, mais vous pouvez consulter les cas d’utilisation avancés.

• page

  string | number | null(par défaut : null)

  La page du PDF que vous souhaitez convertir en image. La valeur par défaut est null, ce qui signifie que toutes les pages seront converties en images.

• page_range

  string | null(par défaut : null)

  Une plage de pages à extraire, au format "start-end" (par exemple, "1-20"). L’extraction commence à la première page de la plage et se poursuit séquentiellement, puis s’arrête proprement lorsqu’une page n’existe pas. Cette option est utile pour les PDF dont le nombre total de pages ne peut pas être déterminé.

  Le début doit être au moins égal à 1, et la fin doit être supérieure ou égale au début.

  Ce paramètre ne peut pas être utilisé avec page et n’est pas pris en charge avec le format GIF. Lorsque page_range est défini, le Robot n’a pas besoin de connaître le nombre total de pages à l’avance, ce qui le rend robuste face aux PDF pour lesquels la détection du nombre de pages échoue.

• format

  gif | jpeg | jpg | png(par défaut : "png")

  Le format des images extraites.

  Si vous spécifiez la valeur "gif", un gif animé faisant défiler toutes les pages est créé. Consultez cette démo EN (English) pour en savoir plus.

• delay

  string | number

  Si votre format de sortie est "gif", ce paramètre définit le nombre de centièmes de seconde à attendre avant l’affichage de l’image suivante dans l’animation. Définissez-le par exemple sur 100 pour laisser passer 1 seconde entre les images du gif animé.

  Si votre format de sortie n’est pas "gif", ce paramètre n’a aucun effet.

• stack

  ghostscript | vips | pdfium

  Sélectionne la pile de rendu PDF. Ghostscript est utilisé par défaut.

  Utilisez "pdfium" pour rastériser à haute résolution en DPI des pages spécifiques d’un PDF ou des PDF d’une seule page lorsque Ghostscript est trop lent ou épuise l’espace de stockage temporaire, par exemple avec des PDF haute résolution de CAD, de plans techniques ou de plans immobiliers à calques. Cette pile utilise PDFium via les liaisons Python fournies par pypdfium2 et Pillow pour l’encodage final des images.

  Utilisez "vips" uniquement si vous souhaitez explicitement charger les PDF avec libvips. Cette pile entraîne moins de surcharge, mais PDFium s’est montré plus rapide lors des tests sur des plans d’étage à haute résolution en DPI, tout en produisant une qualité de sortie comparable.

  La pile "pdfium" prend actuellement en charge les sorties JPG/PNG, resize_strategy: "fit", une valeur précise pour page ou les PDF d’une seule page, les arrière-plans opaques définis en hexadécimal, antialiasing et pdf_use_cropbox.

  La pile "vips" prend actuellement en charge les sorties JPG/PNG, resize_strategy: "fit", une valeur précise pour page ou les PDF d’une seule page, ainsi que les arrière-plans définis en hexadécimal ou transparents.

• width

  string | number

  Largeur de la nouvelle image, en pixels. Si elle n’est pas spécifiée, la largeur de l’image d’entrée est utilisée par défaut

• height

  string | number

  Hauteur de la nouvelle image, en pixels. Si elle n’est pas spécifiée, la hauteur de l’image d’entrée est utilisée par défaut

• resize_strategy

  crop | fillcrop | fit | min_fit | pad | stretch(par défaut : "pad")

  L’une des stratégies de redimensionnement disponibles.

• background

  string(par défaut : "#FFFFFF")

  Le code hexadécimal ou le nom⁠ de la couleur utilisée pour remplir l’arrière-plan (uniquement pour la stratégie de redimensionnement pad).

  Par défaut, l’arrière-plan des images transparentes devient blanc. Pour savoir comment préserver la transparence pour tous les types d’images, consultez cette démo EN (English).

• alpha

  Remove | Set

  Modifie le fonctionnement du canal alpha de l’image obtenue. Les valeurs valides sont "Set" pour activer la transparence et "Remove" pour la supprimer.

  Pour connaître toutes les valeurs valides, consultez la documentation ImageMagick ici⁠.

• density

  string

  Alors que la qualité en mémoire et la profondeur du format de fichier définissent la résolution des couleurs, la densité d’une image correspond à sa résolution spatiale. Cette densité, exprimée en pixels par pouce, définit l’espacement ou la taille des pixels individuels. Elle détermine la taille physique de l’image lorsqu’elle est affichée sur un appareil ou imprimée.

  La valeur de densité accepte soit un seul nombre, noté width, soit une valeur au format largeur par hauteur, noté widthxheight.

  Si votre image convertie a une faible résolution, essayez d’utiliser le paramètre density pour y remédier.

• antialiasing

  boolean(par défaut : false)

  Détermine si l’anticrénelage est utilisé pour supprimer les bords en escalier du texte ou des images d’un document.

• colorspace

  CMY | CMYK | Gray | HCL | HCLp | HSB | HSI | 28 de plus ↓

  Définit l’espace colorimétrique de l’image. Pour en savoir plus sur les valeurs disponibles, consultez la documentation ImageMagick⁠.

  Notez que si vous utilisiez "RGB", nous vous recommandons d’utiliser "sRGB". ImageMagick peut chercher le colorspace le plus efficace en fonction de la couleur d’une image et choisir par défaut, par exemple, "Gray". Pour forcer les couleurs, vous devrez alors peut-être utiliser ce paramètre.

• trim_whitespace

  boolean(par défaut : true)

  Détermine si les espaces blancs supplémentaires autour du PDF doivent être supprimés avant sa conversion en image. Si vous définissez ce paramètre sur true, seul le contenu réel de la page PDF sera visible dans l’image.

  Si vous devez conserver les dimensions du PDF dans votre image, il est généralement conseillé de définir ce paramètre sur false.

• pdf_use_cropbox

  boolean(par défaut : true)

  Certains documents PDF indiquent des dimensions erronées. Par exemple, ils déclarent une orientation paysage, mais s’affichent en réalité en mode portrait dans des lecteurs de bureau fiables. Cela peut se produire lorsqu’une zone de recadrage (cropbox) est définie dans le document. Lorsque cette option est activée (par défaut), la zone de recadrage prévaut pour déterminer les dimensions des miniatures obtenues.

• turbo

  boolean(par défaut : true)

  Active le mode haute performance (le Turbo Mode) pour accélérer le traitement des documents.

  Lorsqu’il est activé, le Turbo Mode apporte deux optimisations clés :

  1. Extraction parallèle des pages : pour les documents de plus de 5 pages, plusieurs processus s’exécutent en parallèle pour extraire les pages simultanément. Le nombre de processus parallèles augmente avec la taille du document (jusqu’à 4 processus pour les documents de 13 pages ou plus).

  2. Redimensionnement distribué : les pages extraites sont redimensionnées simultanément sur plusieurs machines, permettant un traitement jusqu’à 20 fois plus rapide pour les documents volumineux.

  Les fichiers sont émis au fur et à mesure qu’ils deviennent disponibles pendant le traitement. Si vous définissez ce paramètre sur false, les pages sont extraites séquentiellement à l’aide d’un seul processus, et les fichiers ne sont émis qu’une fois tout le traitement terminé.

  Le Turbo Mode augmente le coût, car la taille du fichier du document d’entrée est ajoutée pour chaque page extraite. Les documents d’une seule page ne bénéficient d’aucun gain de performance et n’entraînent aucun supplément de facturation.

Démonstrations

Articles de blog associés