ドキュメントからサムネイル画像を抽出
🤖/document/thumbs は、PDF ファイルの各ページの画像、またはすべてのページを繰り返し表示するアニメーション GIF ファイルを生成します。

注意事項
- 複数ページの PDF ファイルを複数の画像に変換すると、結果の画像は、最初の画像が文書の最初のページのサムネイルとなるように、ページ順に並びます。
- 各結果画像の
meta.thumb_indexキーでも、対応するページを確認できます。これらのサムネイルのインデックスは、1 ではなく、0 から始まります。
使用例
PDF ドキュメントのすべてのページを、幅 200px の個別の画像に変換します:
{
"steps": {
"thumbnailed": {
"resize_strategy": "fit",
"robot": "/document/thumbs",
"trim_whitespace": false,
"use": ":original",
"width": 200
}
}
}パラメーター
interpolateboolean | Record<string, boolean>処理設定の各フィールドで Assembly Variables を展開するかどうかを制御します。
デフォルトでは、Robot の処理設定のほとんどのフィールドで Assembly Variables が展開されます。すべての設定フィールドをリテラルテキストとして扱うには、このパラメーターを
falseに設定してください。特定のフィールドだけをリテラルテキストとして扱うには、そのフィールドのパスをfalseに設定してください。デフォルトでリテラルとして扱われる Robot 固有のフィールドで展開を有効にするには、このパラメーターをtrueに設定するか、そのフィールドのパスをtrueに設定してください。pathのようなフィールド名を使用してください。ネストされたオブジェクトには、ffmpeg.vfのようなドット区切りのパスを使用してください。output_metaRecord<string, boolean> | boolean | Array<string>算出に多くの CPU リソースを要するメタデータを指定できます。Assembly の処理速度を維持するため、これらはデフォルトで無効になっています。
画像の場合、このオブジェクトに
"has_transparency": trueを追加すると、画像に透明な部分が含まれるかどうかを抽出できます。"dominant_colors": trueを追加すると、画像から 16 進数のカラーコードの配列を抽出できます。画像の場合、
"blurhash": trueを追加すると、画像のプレースホルダーをコンパクトに表す BlurHash 文字列も抽出できます。画像全体の読み込み中に、ぼかしたプレビューを表示するのに役立ちます。画像の場合、代わりに
"thumbhash": trueを使用すると、base64 エンコードされた ThumbHash をmeta.thumbhashに抽出し、meta.has_alpha(完全に不透明な場合も含め、アルファチャンネルが存在するかどうか)も抽出します。ThumbHash は EXIF の向きを反映したピクセルを表し、アニメーション画像では最初のフレームを使用します。抽出はベストエフォートです。40 メガピクセルを超える画像、非対応の形式、デコードの失敗やデコード処理の上限への到達があった場合、プレースホルダーは生成されません。抽出に成功すると、そのファイルのバイト数の 20% に相当するメタデータ料金が加算されます。無効な場合やハッシュが生成されない場合、ThumbHash の追加料金は発生しません。このオプションは画像を生成する Step に設定してください。たとえば、アップロードされた元画像では
/upload/handle、処理済みの出力では/image/resizeに設定します。/transloadit/storeにのみ設定しても、抽出は要求されません。ストレージは生成元のメタデータを保持します。Transloadit Storage は生成されたハッシュをその不変のバージョンとともに永続化し、保存済みの結果やネイティブのアセット読み取り時に返します。S3 への直接アップロードではプレースホルダーは生成されません。プレースホルダーには画像情報が含まれるため、画像全体と同じアクセス制御で保護してください。動画の場合、
"colorspace": trueパラメーターを追加すると、出力動画の色空間を抽出できます。動画の場合、
"interlaced": trueを追加すると、インターレース動画かどうかも検出できます。これは、低コストの ffprobe のfield_orderフラグと、ソースの先頭フレームに対する処理範囲を制限したidetサンプリング処理を組み合わせ、file.metaの下にinterlaced、field_order、診断用のinterlace_detectionオブジェクトを出力します。この処理は計算コストが高く、それに応じて課金されます。音声の場合、
"mean_volume": trueを追加すると、音声ファイルの平均音量を表す単一の値を取得できます。また、
falseに設定すると、メタデータの抽出をスキップしてトランスコードを高速化できます。user_metaRecord<string, any>(デフォルト:{})出力される各ファイルに、ファイルの内容を変更せずにカスタム JSON メタデータを追加します。ネストしたオブジェクトと配列に対応しています。
継承の動作は Robot によって異なります。値は出力ファイルの既存の
user_metaとマージされ、一致するトップレベルのキーは現在の Step によって置き換えられます。Robot が新しい出力を作成する場合は、必要なキーを明示的に割り当ててください。処理 Step では、
${file.*}は最初の入力を、${result.*}は出力されるファイルを参照します。値は Robot の実行後、後続のメタデータ抽出と一時保存の前に、出力ごとに評価されます。:originalでは、メタデータ抽出の前にアップロードごとに値が評価されます。後続の Step は
${file.user_meta.key}を読み取ります。完全な例と継承ルールについては、カスタムメタデータ を参照してください。resultboolean(デフォルト:false)この Step の結果を Assembly Status JSON に含めるかどうか
queuebatchqueue を 'batch' に設定すると、このステップのジョブの優先度を手動で下げ、キューの待ち時間がゼロである必要のないジョブが優先ジョブスロットを消費しないようにします。
force_acceptboolean(デフォルト:false)通常は無視するファイルタイプを Robot に強制的に受け入れさせます。
デフォルトでは、Robot は認識できないファイルを無視します。たとえば、🤖/video/encodeは入力画像を無視します。
force_acceptパラメーターをtrueに設定すると、Robot に渡されたすべてのファイルを強制的に受け入れさせることができます。通常、この設定はエラーにつながるため、デバッグやエッジケースへの対処にのみ使用してください。ignore_errorsboolean | Array<meta | execute>(デフォルト:[])処理の特定のフェーズでエラーを無視します。
このパラメーターを
["meta"]に設定すると、Robot はメタデータ抽出中のエラーを無視します。このパラメーターを
["execute"]に設定すると、Robot はメイン実行フェーズ中のエラーを無視します。このパラメーターを
trueに設定すると、["meta", "execute"]と同じ動作になり、両方のフェーズでエラーを無視します。usestring | Array<string> | Array<object> | object入力として使用する Step を指定します。
- Step には任意の名前を付けられます。ただし、
":original"は Transloadit が処理するユーザーアップロード用に予約されています。 - 配列を使用して、複数の Step を入力として指定できます。
{ "use": [ ":original", "encoded", "resized" ] } - 入力 Step に
asでタグを付けて、意味上の用途を Robot に伝えることもできます。{ "use": [ { "name": ":original", "as": "image" }, { "name": ":original", "as": "mask" } ] }
ヒントuseについては、通常ここまでの内容で十分ですが、高度な使用例 も参照できます。- Step には任意の名前を付けられます。ただし、
pagestring | number | null(デフォルト:null)画像に変換する PDF のページを指定します。デフォルト値は
nullで、すべてのページを画像に変換します。page_rangestring | null(デフォルト:null)抽出するページ範囲を
"start-end"形式(例:"1-20")で指定します。範囲内の最初のページから順に抽出し、存在しないページに達すると正常に停止します。総ページ数を判定できない PDF に便利です。開始値は
1以上、終了値は開始値以上である必要があります。このパラメーターは
pageと併用できず、GIF 形式にも対応していません。page_rangeを設定すると、Robot は総ページ数を事前に把握する必要がなくなるため、ページ数の検出に失敗する PDF も安定して処理できます。formatgif | jpeg | jpg | png(デフォルト:"png")抽出する画像の形式を指定します。
値に
"gif"を指定すると、すべてのページを順に表示するアニメーション GIF が作成されます。詳しくは、こちらのデモ (English)をご覧ください。delaystring | number出力形式が
"gif"の場合、このパラメーターはアニメーションの次のフレームを表示するまでの時間を 100 分の 1 秒単位で設定します。たとえば、アニメーション GIF のフレーム間隔を 1 秒にするには、100に設定します。出力形式が
"gif"でない場合、このパラメーターは効果がありません。stackghostscript | vips | pdfiumPDF のレンダリングスタックを選択します。デフォルトは Ghostscript です。
高解像度の CAD、設計図、レイヤーを含む不動産関連の PDF などで、Ghostscript の処理が遅すぎる場合や作業用領域を使い切ってしまう場合は、特定ページまたは単一ページの PDF を高 DPI でラスタライズするために
"pdfium"を使用してください。このスタックは、Python のpypdfium2バインディングを介して PDFium を使用し、最終的な画像エンコードには Pillow を使用します。libvips による PDF 読み込みを明示的に希望する場合にのみ、
"vips"を使用してください。オーバーヘッドは小さいものの、高 DPI の間取り図を使ったテストでは、PDFium のほうが高速で、同等の出力品質を実現しました。"pdfium"スタックは現在、JPG/PNG 出力、resize_strategy: "fit"、特定のpageまたは単一ページの PDF、不透明な背景色の 16 進数指定、antialiasing、およびpdf_use_cropboxに対応しています。"vips"スタックは現在、JPG/PNG 出力、resize_strategy: "fit"、特定のpageまたは単一ページの PDF、および背景色の 16 進数指定または透明な背景に対応しています。widthstring | number新しい画像の幅をピクセル単位で指定します。指定しない場合は、入力画像の幅がデフォルト値になります
heightstring | number新しい画像の高さをピクセル単位で指定します。指定しない場合は、入力画像の高さがデフォルト値になります
resize_strategycrop | fillcrop | fit | min_fit | pad | stretch(デフォルト:"pad")利用可能なリサイズ方式のいずれかを指定します。
backgroundstring(デフォルト:"#FFFFFF")背景の塗りつぶしに使用する色の16進コードまたは色名です(pad リサイズ方式でのみ使用)。
デフォルトでは、透明な画像の背景は白に変更されます。すべての画像タイプで透明度を維持する方法については、このデモ (English)を参照してください。
alphaRemove | Set結果画像のアルファチャンネルの動作を変更します。有効な値は、透明度を有効にする
"Set"と、透明度を削除する"Remove"です。有効な値の一覧は、ImageMagick のドキュメントを参照してください。
densitystringメモリ上の品質とファイル形式のビット深度が色の解像度を指定するのに対し、画像の密度は空間解像度を表します。つまり、画像の密度(1 インチあたりのピクセル数)は、個々のピクセルの間隔(または大きさ)を定義します。これにより、デバイスでの表示時や印刷時の画像の物理的なサイズが決まります。
この値には、特定の
width、またはwidthxheightという形式を指定できます。変換後の画像の解像度が低い場合は、density パラメーターでの調整をお試しください。
antialiasingboolean(デフォルト:false)文書内のテキストや画像のギザギザを取り除くために、アンチエイリアシングを使用するかどうかを制御します。
colorspaceCMY | CMYK | Gray | HCL | HCLp | HSB | HSI |画像の色空間を設定します。指定できる値の詳細は、ImageMagick のドキュメントを参照してください。
"RGB"を使用していた場合は、"sRGB"の使用をお勧めします。ImageMagick は画像の色に基づいて最も効率的なcolorspaceを選ぼうとし、たとえば"Gray"をデフォルトにすることがあります。その場合、色を強制的に指定するには、このパラメーターが必要になることがあります。trim_whitespaceboolean(デフォルト:true)PDF を画像に変換する前に、周囲の余分な余白を切り取るかどうかを指定します。
trueに設定すると、画像には PDF ページの実際の内容だけが表示されます。画像に PDF の寸法を反映する必要がある場合は、通常、
falseに設定することをお勧めします。pdf_use_cropboxboolean(デフォルト:true)PDF 文書によっては、記録されている寸法が実際と異なることがあります。たとえば、横向きと記録されていても、適切に表示できるデスクトップ用ビューアーで開くと、実際には縦向きで表示される場合があります。これは、文書に cropbox が定義されている場合に起こり得ます。このオプションが有効な場合(デフォルト)、生成するサムネイルの寸法は cropbox を優先して決定します。
turboboolean(デフォルト:true)高性能モードを有効にして、文書処理を高速化します。
Turbo Mode を有効にすると、主に二つの最適化が適用されます。
-
ページの並列抽出:ページ数が 5 を超える文書では、複数のプロセスを並列実行し、ページを同時に抽出します。並列プロセス数は文書のサイズに応じて増加します(ページ数が 13 以上の文書では、最大 4 プロセス)。
-
分散リサイズ:抽出したページを複数のマシンで同時にリサイズし、大きな文書では最大 20 倍の処理速度を実現します。
処理中は、ファイルが利用可能になり次第出力されます。
falseに設定すると、単一のプロセスでページを順に抽出し、すべての処理が完了してからファイルを出力します。Turbo Mode では、抽出したページごとに入力文書のファイルサイズが課金対象に加算されるため、料金が増加します。単一ページの文書では、性能の向上も追加料金もありません。
-
デモ
- Service to convert documents into animated GIFs (English)
- Service to convert a document into separate images (English)
- Service to convert the first page of a doc into an image (English)
- Service to make a screenshot of site using an HTML file (English)
- Overlay videos with dynamic artwork generated with HTML & JS (English)
- Service to take screenshots of a website using a URL (English)
関連ブログ記事
- ドキュメントを画像に変換する新しい Robot の紹介
- フレーム間隔を指定して PDF をアニメーション GIF に変換
- Transloadit が SVG 画像に対応
- /document/thumbs Robotに density パラメーターを追加
- 今後の Transloadit のお客様向け新料金モデル
- チュートリアル:/video/merge で動画スライドショーを作成
- Markdown ファイルを数秒で HTML や PDF に変換
- ドキュメントのページの向きを自動補正
- /document/thumbs の Turbo Mode の紹介
- /document/extract で PDF からテキストと画像を抽出