コンテンツにスキップ
quickthumb
すべてのドキュメント

よくある質問

インストール

対応するPythonのバージョンは？

Python 3.11以降です。パッケージの分類は3.11と3.12で、CIは3.11で実行します。背景除去のrembg追加機能も同じです。

quickthumbコマンドが見つかりません

コマンドラインツールは追加機能です。pip install "quickthumb[cli]"でインストールしてください。利用できる追加機能はインストールにまとめています。

SVGレイヤーでRenderingErrorが出るのはなぜですか？

SVGファイルの描画にはsvg追加機能が必要です。pip install "quickthumb[svg]"でインストールします。キャンバスをSVGへ出力する場合は不要です。

キャンバスとレイヤー

レイヤーのないキャンバスをレンダリングするとどうなりますか？

キャンバスと同じサイズの、完全に透明な画像になります。エラーではありません。

グループの子で「group children must not set position」が出るのはなぜですか？

グループ自身が子の位置を決めるためです。子のpositionを外し、代わりにグループを配置してください。

canvas.group(
    children=[{"type": "text", "content": "TITLE", "size": 96, "color": "#FFFFFF"}],
    position=("8%", "50%"),
    align=("left", "middle"),
)

子のalignも無視されます。グループの交差軸方向に子を揃えるには、グループのitem_alignを使います。

レンダリング前にデザインの問題を確認できますか？

canvas.diagnose()を呼ぶか、JSON仕様にquickthumb lint spec.jsonを実行してください。小さすぎる文字、キャンバスからのはみ出し、低いコントラスト、隠れたレイヤーなどを報告します。診断とCLIを参照してください。

テキストとフォント

テキストがキャンバスからはみ出します

max_widthを設定すると折り返せます。

canvas.text(content="A longer title that needs two lines", size=72, color="#FFFFFF", max_width="60%")

文字を小さくして収める場合は、max_width、max_height、または両方とともにauto_scale=Trueを追加します。

bold=Trueとweight=900を設定したらエラーになりました

同じ属性を指定するため、どちらか一方を使います。weightならより細かく指定できます。例：TextPart(text="STRONG", weight=900)。

Google Fontを使うには？

フォント名とfont_source="google"を指定します。一度ダウンロードしてキャッシュし、weightに合うファイルを選びます。

canvas.text(content="Hello", font="Inter", font_source="google", weight=800, size=72, color="#FFFFFF")

フォントファイルのURLを渡したり、QUICKTHUMB_FONT_DIRにフォントのフォルダーを指定したりする方法もあります。Webフォントと背景除去を参照してください。

画像

URLの画像は使えますか？

はい。background(image=...)とimage(path=...)はhttp(s) URLを受け付け、レンダリング中にダウンロードしてキャッシュします。設定はリモートアセットとキャッシュを参照してください。

人物の背景を除去するには？

画像レイヤーにremove_background=Trueを設定します。rembg追加機能が必要です。

canvas.image(path="portrait.jpg", position=("75%", "55%"), width=420, height=520, remove_background=True)

cover、contain、fillはどう違いますか？

coverは枠を埋め、収まらない部分を切り取ります。containは画像全体を枠内に収め、余白を残します。fillは縦横比を無視し、枠いっぱいに引き伸ばします。

出力

どの形式に出力できますか？

render()へ渡すファイルの拡張子で決まります。

種類 形式 必要なもの
画像 PNG、JPEG、WebP
ベクター・ドキュメント SVG、PDF、PPTX PDFとPPTXにはそれぞれpdf、pptx追加機能
Web HTML
アニメーション GIF、MP4、WebM MP4とWebMにはffmpeg

最初の出力は出力形式を選ぶから始めてください。各形式で維持されるものと失われるものはエクスポートリファレンスで説明しています。

PNGにqualityは指定できますか？

いいえ。qualityはJPEGとWebP専用です。PNGに渡すとRenderingErrorになります。

ファイルに書かずに画像を受け取るには？

png_base64 = canvas.to_base64(format="PNG")
jpeg_data_url = canvas.to_data_url(format="JPEG", quality=90)

JSON

Canvas.from_json()にdictを渡せますか？

いいえ。JSON文字列を受け付けます。先にjson.dumps(data)で変換してください。

to_json()でValidationErrorが出るのはなぜですか？

キャンバスに.custom(fn)レイヤーがあるためです。Python関数はJSONに保存できないので、先にそのレイヤーを取り除いてください。

to_json()の後にthemeブロックがなくなりました

仕様を読み込むときにテーマトークンを実際の値へ置き換えるため、to_json()は値だけを書き、themeブロックは残しません。トークンを編集し続けたい場合は、元の仕様ファイルを保管してください。

エラー

エラーの種類は何を意味しますか？

  • ValidationError：引数や仕様のフィールドが無効です。レイヤーの追加時、または仕様の読み込み時に発生します。
  • RenderingError：ダウンロードなど、描画中の処理に失敗しました。
  • MissingAssetError：仕様が参照するローカルファイルが存在しません。

どのエラーもdetailsに安定したコード、該当フィールドのJSON Pointer、レイヤーIDを持ちます。構造化エラーを参照してください。