フラット PDF から構造化 UI へ：PDF-to-Visual-Struct パイプラインの内側

Engineering2026-04-23

PDF の問題点

PDF はあらゆるところに存在します — 製品仕様書、財務レポート、コンプライアンスフォーム、レガシーデザイン成果物 — そしてほぼ例外なく自動化に対して非友好的です。PDF はフラットな描画命令のストリームに過ぎません：「座標 (120, 440) に移動し、Helvetica 12 でグリフ 'H' を表示、右に移動して 'e' を表示…」。ボタン、カード、ヘッダーといった概念は一切ありません。階層構造もなければ、信頼できる「単語」の概念すら存在しません。

そのギャップを埋めるために PDF to Visual Struct を構築しました。PDF を POST /v1/open/pdf_to_design に送信すると、Codia Studio を支える Visual Element Schema と同じ形式が返されます：型付きの UI 要素を持つ階層的な JSON ツリーで、バウンディングボックス、レイアウト設定、スタイル仕様が含まれます。このツリーは機械可読であり、デザイナーにも読みやすく、実行可能なコードへの変換まであと一歩の距離です。

この記事では、パイプラインの全体像 — API が何をするか、出力するスキーマ、そしてその上に何を構築できるかを解説します。

API の呼び出し

リクエストは単一の multipart/form-data POST です。SDK は不要です。

bash

curl 'https://api.codia.ai/v1/open/pdf_to_design' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --form 'pdf_file=@"invoice.pdf"' \
  --form 'page_no="0"'

入力は2つ：PDF ファイルとゼロインデックスのページ番号です。40ページのドキュメント全体が必要な場合は、ループして並列化してください — API はページ単位でステートレスであり、並行処理にも対応しています。公称スペックは1ドキュメントあたり100ページ以上、50以上の要素タイプ、ページあたり2秒以内のレスポンスです。実際には、ほとんどの単一ページ PDF はファイルがイングレスに到達した後 600〜1200 ms で返ってきます。

レスポンスの構造

トップレベルは以下のようになります：

json

{
  "configuration": {
    "scalingFactor": 1,
    "baseWidth": 1940,
    "measurementUnit": "px"
  },
  "pages": [
    {
      "visualElement": { /* ルート要素 */ }
    }
  ],
  "size": {
    "height": 1080,
    "width": 1940
  }
}

configuration は座標の解釈方法を示します。baseWidth と measurementUnit が基準フレームです — ビューポートをリサイズする場合、すべてのバウンディングボックスをその比率でスケーリングしてください。size はレイアウトが解決された正規化キャンバスです。

各ページには単一の visualElement ルートがあります。その childElements 配列を走査することで、ドキュメントの再帰的な深さ優先探索が可能です。すべてのノードは同じコアフィールドを持ちます：

json

{
  "elementId": "pdf_page_1",
  "elementName": "PDF Document Page",
  "elementType": "Panel",
  "displayName": "First Page",
  "displayOrder": 0,
  "boundingBox": [0, 0, 595, 842],
  "layoutConfig": {
    "positionMode": "Normal",
    "flexibleMode": "Absolute"
  },
  "styleConfig": {
    "widthSpec":  { "sizing": "FIXED", "value": 595 },
    "heightSpec": { "sizing": "FIXED", "value": 842 },
    "backgroundSpec": {
      "type": "COLOR",
      "backgroundColor": { "rgbValues": [255, 255, 255] }
    }
  },
  "processingMeta": {
    "surfaceArea": 501490,
    "detectionScore": 0.92,
    "textContainerized": false
  },
  "childElements": []
}

知っておくべきフィールド：

elementType — 強い型です。Panel、Text、Image、Icon、Button、Table、Chart、その他数十種類。これが出力を実用的にするポイントで、ヒューリスティクスなしで HTML、Flutter ウィジェット、React コンポーネントを生成するために switch 文で分岐できます。
boundingBox — 基準座標系での [x, y, width, height]。これを使って絶対レイアウトで子要素を配置したり、後処理でオーバーラップやグループを検出できます。
layoutConfig — 親が子要素をフロー、flex の行/列、自由配置（Absolute）のどれでレイアウトしたかを示します。Figma のオートレイアウトモデルに着想を得ており、Figma へのラウンドトリップが容易です。
styleConfig — 幅/高さのサイジング戦略（FIXED、FILL_CONTAINER、HUG_CONTENT）、背景ペイント、ボーダー、角丸、タイポグラフィ。CSS の概念に十分近いため、ジェネレーターがクリーンなスタイルシートを出力できます。
processingMeta.detectionScore — 0〜1 の検出信頼度スコア。ダウンストリームのアーティファクト生成前に低信頼度ノードを除外したい場合に便利です。

パイプラインの実際の処理

PDF をこのスキーマに変換するのは単一のモデル呼び出しではなく、短いパイプラインです：

ラスタライズ＋抽出。 PDF ストリームを解析してテキストラン、ベクターパス、埋め込みラスター画像を抽出します。スキャンされたページは並列で OCR パスに送られます。
レイアウト分析。 ビジョンモデルがページをヘッダー、本文ブロック、サイドバー、図、テーブル、キャプションなどの領域にセグメント化し、それぞれに粗い型を割り当てます。ここが Panel の境界の出どころです。
要素検出。 各領域内でより密なモデルが個々の UI 要素 — ボタン、アイコン、フォームフィールド、チャート系列 — を識別します。このステージが elementType の分類を生成します。
テキストグルーピング。 生のグリフ位置が単語、行、段落にクラスタリングされ、最も近いコンテナ要素に関連付けられます。
スキーマ組み立て。 階層が実体化され、親子リンクが解決され、要素ごとのスタイルが計算されます。座標は baseWidth に正規化されます。

ステップ 2 と 3 がレイテンシバジェットの大部分を占めます。それ以外はすべて比較的軽量です。

この上に構築できるもの

スキーマは意図的に汎用的に設計されています。チームがこの上に構築した具体的な例をいくつか紹介します：

デザインインポート。 レガシー PDF 仕様を1パスで編集可能な Figma フレームに変換。レイアウト設定が Figma オートレイアウトのセマンティクスを反映しているため、インポート時にオートレイアウトが正しく再構築されます。

レガシーモダナイゼーション。 500ページの PDF マニュアルからレスポンシブ Web バージョンを生成。各ページがルートになり、要素タイプがコンポーネント選択を駆動します。

ビジュアルリグレッションテスト。 ベースラインページを2つのビルドでレンダリングし、両方を API に通して要素ツリーを diff。要素レベルの差分は、フォントの変更やサブピクセルアンチエイリアシングによるピクセル差分よりもはるかに安定しています。

レイアウト認識型 RAG。 PDF をリトリーバル用にインデックスする際、生のテキストダンプではなく要素単位でチャンクし、親子関係を保持することで、「4ページ目の CTA は何か」や「11ページ目の2番目のテーブルの3列目は何か」といった質問にファジーなヒューリスティクスなしで答えられます。

チャート抽出。 チャートノードは十分なメタデータ（軸ラベル、系列の色、グループ化されたテキスト）を持つため、スクリーンショットのレンダリングではなくライブチャートコンポーネントに変換できます。

精度について

実際の検出品質は、PDF の生成元、テキストの明瞭さ、レイアウトの複雑さによって変わります。プロダクトデザイン PDF は比較的解析しやすい一方、スキャンされた法的文書や手書き注釈のあるフォームでは OCR ノイズが多くなり、detectionScore が低くなる傾向があります。

はじめ方

codia.ai/dashboard/developer で API キーを取得してください。
手元の PDF に対して上記の curl を試してください。
お好みの言語でレスポンスツリーを走査してください — スキーマはプレーンな JSON であり、SDK は不要です。
パースをスキップして直接 Figma ファイルを取得したい場合は、同じパイプラインで構築された PDF to Design Figma プラグインをご覧ください。

完全なリファレンス、リクエスト/レスポンスの形状、エラーコードは開発者ドキュメントにあります。より高いレート制限やプライベートデプロイメントが必要な場合は [email protected] までご連絡ください — パイプラインはデータレジデンシー要件のある企業向けに独立したコンテナとして提供されます。

PDF がなくなることはありません。PDF は過去10年間、あらゆるデザイン自動化の取り組みにおいて頑固なラストマイルでした。クリーンで型付けされた構造を与えることが、PDF を再びファーストクラスの存在にするための第一歩です。

#pdf#visual-struct#api#design-automation#schema

← すべての記事に戻る