ドキュメントの検査とサンプリング

CanvasとDeckの両方を扱うツールやエージェントではinspect_document()を使ってください。既存のレイアウト、モーション、診断レポートと観察したアセット情報を、DocumentInspectionにまとめます。

from quickthumb import Canvas, Deck, inspect_document

document = Deck(slides=[Canvas(320, 180).background(color="#FFFFFF")])
report = inspect_document(document, target="video", fps=24, max_samples=100)
print(report.model_dump_json(indent=2))

for page_index, page in enumerate(report.pages):
    print(page_index, page.width, page.height, len(page.layers))

共通フィールド

フィールド	両方の文書での意味
`version`	結果スキーマのバージョン。現在は`"1"`です。
`kind`	ソースの識別子。`"canvas"`か`"deck"`です。
`width`, `height`	アニメーションの出力ステージと同じ、最初のページのピクセル寸法です。
`pages`	Canvasでは`CanvasInspection`1件、Deckでは文書順の全スライドです。
`motion`	既存の`MotionInspection`。タイミング、サンプルしたプロパティ状態、スライド別の詳細、機能の行、出力診断を含みます。
`diagnostics`	既存の`DiagnosticReport`。Deckの指摘は`slide_index`を維持し、文書全体の指摘では`null`です。
`asset_manifest`	観察したアセット参照、解決状態、利用できる識別情報・ハッシュ・キャッシュ情報です。

各ページはレイヤーID、順序、入れ子の子、バウンディングボックス、文字の測定値を維持します。サイズが混在するDeckでも各ページの寸法を保ちます。外側の寸法は作成時のDeck既定値と違っても最初のページのものです。従来のdeck.inspect()は、引き続き作成時の既定値を報告します。

targetには出力系統を1つ（raster、html、pptx、video）、系統のイテラブル、または全4系統を表すNoneを指定します。policy、fps、max_samplesはそのままinspect_motion()へ渡します。モーション観察はmax_samplesで制限され、ラスターフレームではなくプロパティの状態です。空のDeckや無効なオプションには、既存の構造化Quickthumbエラーを返します。

ファイルは出力しません。ただし個別の検査・診断と同様、測定のためにフォントの読み込み、アセットの解決、メディアのデコードを行う場合があります。マニフェストは処理後の状態を表し、別の事前取得を始めたり未解決リソースが利用可能だと保証したりはしません。明示的な解決にはprefetch_assets()、環境の準備確認にはdoctorを使ってください。

canvas.inspect()とdeck.inspect()の結果型やJSONフィールドは変わりません。レイアウトだけが必要なら、これらの限定されたメソッドを使ってください。

DocumentInspection.model_json_schema()はこの結果の構造を説明します。文書作成用のスキーマは引き続き入力仕様を表し、この結果とは異なります。DiagnosticReportと同様、診断の指摘は通常のJSONオブジェクトとして復元されます。JSONを往復した後はPythonの診断クラスに依存せず、code、severity、message、位置のフィールドを読んでください。

基準サンプルとレイアウトを対応付ける

両方の文書のsample()は、同じFrameSequenceを返します。均等なサンプル格子は観察の時刻であり、エンコードされたフレームのインデックスではありません。GIF・動画の量子化とナレーションの差はアニメーションのタイミングを参照してください。ページ番号は0始まりで、frames[].slideとtimeline[].slideに一致します。

from quickthumb import DocumentInspection, FrameSequence

layout = DocumentInspection.model_validate_json(report.model_dump_json())
samples = FrameSequence.model_validate_json(document.sample().model_dump_json())
for frame in samples.frames:
    page = layout.pages[frame.slide]
    print(frame.index, frame.time, frame.width, frame.height, len(page.layers))

このループには文書の種類による分岐が不要です。kindはソースを識別し、ページ別・フレーム別の情報もそのまま使えます。

sample()は作成時の静的なRGBAを各ページ1フレーム取得し、そのページの寸法と透明度を維持します。timeはNone、durationは0、timelineは空です。
sample(time=[0, 0.5])やsample(fps=24)はアニメーションのタイムラインを取得します。フレームは時刻順で、最初のページの寸法と不透明なマットを使います。
frames[].indexは観察順、frames[].slideは表示中のページを表します。タイムライン区間がページの時間と切り替えを説明します。
environmentはレンダラーのバージョンを記録します。各フレームはその環境で決定的に比較できるよう、RGBAの生データとSHA-256ダイジェストを持ちます。

時間の意味は別々です。report.motion.durationは従来の作成済みモーション検査の意味を維持します。samples.durationはhold引数と解決されたナレーション時間を含む基準キャプチャの長さです。たとえば静的Canvasのモーション長は0ですが、hold=2で時間指定したサンプルは2秒です。再生比較にはサンプルのduration、fps、timeline、フレームのtimeを使い、レイアウトレポートやプロパティサンプルから推測しないでください。