Canvas

Canvasは寸法と順序付きレイヤー一覧を持つ最上位オブジェクトです。作成用フィールドは、Deckスライドや正規JSONにも共通するレイヤー用語に従います。

作成

`Canvas(width=None, height=None)`

from quickthumb import Canvas

canvas = Canvas(1280, 720)

パラメーター	型	説明
`width`	`int \\| None`	幅（ピクセル）。正の整数です。
`height`	`int \\| None`	高さ（ピクセル）。正の整数です。

幅と高さは両方指定するか、両方省きます。サイズなしのCanvas()は未設定サイズの状態です。レイヤーは追加できますが、直接サイズを与えるか、サイズ付きのDeckへ追加して既定サイズを継承するまでは、描画、診断、シリアライズができません。canvas.has_sizeで区別できます。

`Canvas.from_aspect_ratio(ratio, base_width)`

縦横比の文字列と基準幅から作ります。高さは自動計算します。

wide     = Canvas.from_aspect_ratio("16:9", base_width=1280)   # 1280×720
square   = Canvas.from_aspect_ratio("1:1",  base_width=1080)   # 1080×1080
vertical = Canvas.from_aspect_ratio("9:16", base_width=1080)   # 1080×1920

パラメーター	型	説明
`ratio`	`str`	`"16:9"`など`"W:H"`形式の縦横比です。
`base_width`	`int`	幅（ピクセル）です。

レイヤービルダー

すべてのビルダーはキャンバスを変更してselfを返すため、メソッドを連続して呼べます。

メソッド	説明
`.background(...)`	キャンバス全体の背景を追加
`.text(...)`	テキストを追加
`.image(...)`	重ねる画像を追加
`.shape(...)`	図形を追加
`.path(...)`	塗りや線のあるパスを描画
`.svg(...)`	描画時にラスタライズするSVGを追加
`.video(...)`	動く構成へ動画クリップを追加
`.counter(...)`	動く数字を追加
`.group(...)`	子を自動配置するグループを追加
`.outline(...)`	キャンバスの枠線を追加
`.chart(...)`	型付き仕様から決定的な棒・折れ線グラフを追加
`.qr_code(...)`	正方形のQRコードを追加
`.custom(fn)`	Pillowのコールバックレイヤーを追加

全パラメーターはデータの可視化や各レイヤーのページを参照してください。

数字のアニメーション

.counter(from_, to, duration, ...)で数字をテキストレイヤーとして動かせます。position、size、colorなど通常の文字オプションを渡します。

from quickthumb import Canvas

canvas = Canvas(320, 180).background(color="#102030").counter(
    0, 100, 2, suffix="%", size=64, color="#FFFFFF", position=(40, 50)
)
canvas.render("counter.gif")

delay、decimals、minimum_integer_digits、prefix、suffix、groupingで時間と表示形式を制御します。styleは"plain"、"odometer"、"flip"、easingは"linear"、"ease_in"、"ease_out"、"ease_in_out"です。静止出力は最終値を表示します。

`.diagnose()`

ファイルを保存せず、配置や読みやすさを検査します。Diagnosticを格納するfindings付きのDiagnosticReportを返し、問題がなければリストは空です。

for finding in canvas.diagnose().findings:
    print(finding.severity, finding.code, finding.message)

コードはoff-canvas、tiny-text、text-overflow、text-clipped、missing-glyph、low-contrast、layer-overlap、layer-hidden、edge-crowdingです。詳細と同等のCLIコマンドquickthumb lint（またはquickthumb diagnose）は診断とCLIを参照してください。

`.prefetch_assets()`（任意）

必ず呼ぶ必要はありません。render()とexport()はリモート画像、SVG、文字の塗り、フォントを自分でダウンロードし、export()はasset_manifestも返します。長い出力の前に通信失敗や期限切れキャッシュを確認したい場合、または後のオフライン描画用にキャッシュを用意する場合だけ使ってください。描画せずマニフェストを返します。

manifest = canvas.prefetch_assets().asset_manifest
if any(entry.status == "stale" for entry in manifest):
    ...  # decide whether to proceed with cached bytes

状態、QUICKTHUMB_ASSET_MAX_AGE、オフラインモードはリモートアセットとキャッシュを参照してください。

出力メソッド

`.export(path, policy=None, *, format=None, quality=None, animation=None)`

render()と同様に保存し、保存した1ファイルのwritten_pathsを持つExportResultを返します。パスは文字列かpathlib.Pathです。format、quality、animation、policyはrender()と同じ意味です。

result = canvas.export("card.png")
print(result.written_paths)

結果のフィールド、機能ポリシーの事前検査、export()と以下のメソッドとの関係は推奨出力APIを参照してください。

`.render(path, format=None, quality=None, debug=False, animation=None, policy=None)`

描画結果をファイルへ保存します。拡張子で形式を選び、.svg、.pptx、.pdfはベクター・文書、.gif、.mp4、.webm、.movはレイヤーのanimationを再生するアニメーションになります。エクスポートを参照してください。

Canvasの.lotはLottieベクターに記載した限定範囲のネイティブベクターを保存します。fpsと最後の保持はLottieOptionsで指定します。未対応の内容はPNGへ置き換えず、書き込み前に拒否します。

from quickthumb import GifOptions, VideoOptions

canvas.render("output.png")
canvas.render("output.jpg", format="JPEG", quality=85)
canvas.render("output.webp", format="WEBP", quality=90)
canvas.render("debug.png", debug=True)  # raster output with public layer-id bboxes
canvas.render("output.svg")
canvas.render("output.pptx")  # requires quickthumb[pptx]
canvas.render("output.pdf")   # requires quickthumb[pdf]
canvas.render("output.gif")   # animated; .mp4/.webm/.mov require the ffmpeg binary
canvas.render(
    "preview.gif",
    animation=GifOptions(fps=8, max_size=(540, 960), colors=128),
)
canvas.render("preview.mp4", animation=VideoOptions(fps=30))

パラメーター	型	既定値	説明
`path`	`str`	—	出力パスです。
`format`	`str \\| None`	`None`	大文字小文字を区別しない`"PNG"`、`"JPEG"`、`"WEBP"`の再指定です。文書・アニメーション拡張子では拒否します。
`quality`	`int \\| None`	`None`	圧縮品質。JPEGは1–95、WebPは1–100で、それ以外は拒否します。
`debug`	`bool`	`False`	視覚確認用に公開レイヤーIDの境界をラスター出力へ描きます。
`animation`	`GifOptions \\| VideoOptions \\| LottieOptions \\| None`	`None`	GIFは`GifOptions`、MP4/WebM/MOVは`VideoOptions`、`.lot`は`LottieOptions`です。
`policy`	`ExportPolicy \\| None`	`None`	動画・HTML・PPTXの`reduced_motion`などのポリシーです。`render()`と`export()`は書き込み前に`unsupported_motion`を適用します。`export()`は明示的に要求した静的SVG検証も報告します。

注意

format="PNG"にqualityを渡すとRenderingErrorになります。文書・アニメーション（.svg、.pptx、.pdf、.html、.gif、.mp4、.webm、.mov、.lot）にdebug=Trueを渡してもRenderingErrorになります。

GifOptions、VideoOptions、LottieOptionsはquickthumbから取得できます。GifOptionsはfps、hold、matte、loop、max_size=(width, height)、colorsを、VideoOptionsはfps、hold、matte、soundtrack=AudioTrack(...)、loop_audioを受け付けます。

VideoOptions(transparent=True)はVP9 WebMとProRes 4444 MOVのアルファを維持します。厳密なブール型で既定はFalseです。他の出力はすべて拒否します。両方のholdは厳密な有限の非負数（既定3秒）で、既定値なら保存時に省略します。描画にはworkers（厳密な整数1–8、既定1）とrender_quality="standard"または"high"を指定できます。spawnや対応入力は並列描画を参照してください。MP4/WebM/MOVはGIFのサイズ・パレット制御を拒否します。

`.to_svg(embed_fonts=False)`

SVG文書の文字列を返します。embed_fonts=Trueで使用したフォントを@font-faceのデータURLとして埋め込みます。

svg = canvas.to_svg(embed_fonts=True)

`.to_pptx()`

編集可能なテキストボックスとオートシェイプを持つ1枚のPowerPointをバイト列で返します。pptx追加機能が必要です。

with open("deck.pptx", "wb") as f:
    f.write(canvas.to_pptx())

`.to_pdf()`

1ページのPDFをバイト列で返します。背景と図形はネイティブベクターです。安全に埋め込めるフォントで複雑なシェーピングが不要なら、選択可能な文字も使います。未対応の文字はピクセル単位で一致する画像断片にします。pdf追加機能が必要です。

with open("card.pdf", "wb") as f:
    f.write(canvas.to_pdf())

`.to_gif(...)` / `.to_mp4(...)` / `.to_webm(...)` / `.to_mov(...)`

レイヤーのanimationを順に再生し、最後の静止状態をhold秒保つアニメーションを返します。GIFと動画を参照してください。アニメーションがなければ1フレームのGIFです。.to_mp4()、.to_webm()、.to_mov()にはPATH上かQUICKTHUMB_FFMPEGで指定したffmpegが必要です。

gif_bytes = canvas.to_gif(fps=20, hold=3.0, loop=0, matte="#000000")
mp4_bytes = canvas.to_mp4(fps=30, hold=2.0, soundtrack="music.mp3")
webm_bytes = canvas.to_webm(fps=30, hold=2.0)
overlay_bytes = canvas.to_webm(fps=30, hold=2.0, transparent=True)

.to_mp4()/.to_webm()/.to_mov()は、動画の長さに切って多重化する音声ファイルsoundtrackと、明示的な再指定loop_audioも受け付けます。AudioTrack(..., loop=True)は短いトラックを繰り返します。従来の文字列パスは以前のループ既定値を維持します。GIFに音声は含められません。全パラメーターはDeck APIを参照してください。

全アニメーションバイトメソッドはキーワード専用のworkers=1、render_quality="standard"を受け付けます。"high"はスーパーサンプリングを有効にします。.to_gif()は比率を保つmax_size=Noneと、パレットのcolors=None（指定時2–256）も受け付けます。既存の位置引数は変わりません。

.to_webm()と.to_mov()のキーワード専用transparentは出力マットだけを省き、作成した背景は残ります。コーデック、アルファのデコード、切り替えは透過WebMを参照してください。

.to_mov()は.to_webm()と同じパラメーターと時間で、ProRes 4444映像とAAC音声に固定されます。奇数や1ピクセルの寸法も保ちます。RGBAソースは8ビットです。16ビットのアルファ符号化はデコード後の8ビット値に1段階の差を生むことがあり、色は損失のある4:4:4 YUVです。測定した変換の限界とエンコーダー要件はProRes MOVを参照してください。render()とexport()は不透明・透明の両方でVideoOptionsと.movを受け付けます。

`.export_image_sequence(output_directory, *, format="png", quality=None, matte=None, lossless=None, options=None, policy=None)`

既存の親の下に新しいディレクトリを作り、アニメーションを独立したPNG（既定）、JPEG、WebPとmanifest.jsonで保存します。ImageSequenceOptions(fps=30, hold=3, workers=1, render_quality="standard")が時間と合成を、メソッドのキーワードが画像符号化を選びます。JPEGは不透明マット（既定白）のRGBで、quality=1..95です。WebPはアルファを保ちlossless=Trueに対応し、損失WebPは品質指定に対応します。PNGと無損失WebPはレンダラーのRGBA8を正確に保ちます。不透明なWebPがRGBで開かれる場合もあり、マニフェストのモードは論理的なRGBAデコードを説明します。結果には実際のフレーム数、時間、符号化、保存先を報告します。検証、形式別メタデータ、上書きしないアトミックな公開は画像シーケンスを参照してください。

`.to_base64(format="PNG", quality=None)`

描画画像をbase64文字列で返します。

b64 = canvas.to_base64(format="PNG")
b64 = canvas.to_base64(format="WEBP", quality=90)

パラメーター	型	既定値	説明
`format`	`str`	`"PNG"`	`"PNG"`、`"JPEG"`、`"WEBP"`です。
`quality`	`int \\| None`	`None`	JPEGは1–95、WebPは1–100の圧縮品質です。

`.to_data_url(format="PNG", quality=None)`

描画画像をデータURL（data:<mime>;base64,...）で返します。

url = canvas.to_data_url(format="JPEG", quality=90)
# → "data:image/jpeg;base64,..."

パラメーター	型	既定値	説明
`format`	`str`	`"PNG"`	`"PNG"`、`"JPEG"`、`"WEBP"`です。
`quality`	`int \\| None`	`None`	JPEGは1–95、WebPは1–100の圧縮品質です。

`.inspect()`

レイヤーID、順序、可視性、境界、作成時の文字配置情報を持つ決定的なCanvasInspectionを返します。ファイルは出力しません。寸法のために既存のフォントや画像を読む場合がありますが、親レイヤーの描画は呼び出しません。

report = canvas.inspect()
for layer in report.layers:
    print(layer.id, layer.bbox)

親子関係のあるシーンの境界は、アニメーションフレームではなく作成時の静的レイアウトです。描画ピクセルより広い保守的な境界になる場合があります。canvas.render("debug.png", debug=True)で表示できます。クリップ、マスク、カウンター、親変換は複雑なレイアウトの検査を参照してください。

`.to_json()`

キャンバスをJSON文字列にします。

json_str = canvas.to_json()

.custom(fn)があれば、コールバックを保存できないためValidationErrorになります。

`Canvas.from_json(json_str)`

JSON文字列からキャンバスを復元します。

canvas = Canvas.from_json(json_str)

補足

from_json()はdictではなくJSON文字列を受け付けます。dictなら先にjson.dumps(data)を使ってください。

`.custom(fn)`

PillowのImageを受け取り返すコールバックを追加します。

from PIL import ImageDraw
from quickthumb import Canvas

def draw_badge(image):
    d = ImageDraw.Draw(image)
    d.polygon([(70, 70), (240, 70), (155, 180)], fill="#FF3B30")
    return image

canvas = Canvas(512, 512).custom(draw_badge)

規則	詳細
`fn`は呼び出し可能	`PIL.Image.Image`を受け取ります。
戻り値	変更した同じ画像、同じサイズの新しい画像、`None`を返せます。
エラー	コールバックの例外は`RenderingError`で包みます。
保存	カスタムレイヤーはJSONに保存できません。

Canvas

作成

Canvas(width=None, height=None)

Canvas.from_aspect_ratio(ratio, base_width)

レイヤービルダー

数字のアニメーション

.diagnose()

.prefetch_assets()（任意）

出力メソッド

.export(path, policy=None, *, format=None, quality=None, animation=None)

.render(path, format=None, quality=None, debug=False, animation=None, policy=None)

.to_svg(embed_fonts=False)

.to_pptx()

.to_pdf()

.to_gif(...) / .to_mp4(...) / .to_webm(...) / .to_mov(...)

.export_image_sequence(output_directory, *, format="png", quality=None, matte=None, lossless=None, options=None, policy=None)

.to_base64(format="PNG", quality=None)

.to_data_url(format="PNG", quality=None)

.inspect()

.to_json()

Canvas.from_json(json_str)

.custom(fn)