플랫 PDF에서 구조화된 UI로: PDF-to-Visual-Struct 파이프라인의 내부

Engineering2026-04-23

PDF의 문제점

PDF는 어디에나 있습니다 — 제품 사양서, 재무 보고서, 규정 준수 양식, 레거시 디자인 산출물 — 그리고 자동화에 거의 일관되게 적대적입니다. PDF는 평면적인 드로잉 명령의 스트림입니다: "(120, 440)으로 이동, Helvetica 12로 글리프 'H' 표시, 오른쪽으로 이동, 'e' 표시…". 버튼, 카드, 헤더의 개념이 없습니다. 계층 구조가 없습니다. 심지어 단어라는 신뢰할 수 있는 개념조차 없습니다.

이것이 바로 PDF to Visual Struct를 만든 이유입니다. POST /v1/open/pdf_to_design에 PDF를 보내면 Codia Studio를 구동하는 것과 동일한 Visual Element Schema를 돌려받습니다: 바운딩 박스, 레이아웃 설정, 스타일 사양을 갖춘 타입이 지정된 UI 요소의 계층적 JSON 트리입니다. 이 트리는 기계가 읽을 수 있고, 디자이너가 읽을 수 있으며, 한 번의 변환으로 실행 가능한 코드가 됩니다.

이 글에서는 파이프라인을 살펴봅니다 — API가 하는 일, 출력하는 Schema, 그리고 그 위에 무엇을 구축할 수 있는지 알아봅니다.

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"'

두 가지 입력: PDF 파일과 0부터 시작하는 페이지 번호입니다. 40페이지 문서의 모든 페이지를 원한다면 루프를 돌리고 병렬화하세요 — API는 페이지 단위로 상태가 없으며 동시 요청을 잘 처리합니다. 공식 목표는 문서당 100+ 페이지, 50+ 요소 유형, 페이지당 2초 미만의 응답입니다. 실제로 대부분의 단일 페이지 PDF는 파일이 수신되면 600–1200ms 내에 결과가 반환됩니다.

응답의 구조

최상위 레벨은 다음과 같습니다:

json

{
  "configuration": {
    "scalingFactor": 1,
    "baseWidth": 1940,
    "measurementUnit": "px"
  },
  "pages": [
    {
      "visualElement": { /* root element */ }
    }
  ],
  "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 컴포넌트를 생성할 수 있습니다.
boundingBox — 기본 좌표계에서 [x, y, width, height]입니다. 절대 레이아웃에서 자식을 배치하거나 후처리 시 겹침과 그룹을 감지하는 데 사용합니다.
layoutConfig — 부모가 자식을 플로우, 플렉스 행/열, 또는 자유 배치(Absolute)로 배치했는지 알려줍니다. Figma의 오토 레이아웃 모델에서 영감을 받아 Figma로의 왕복 변환이 간단합니다.
styleConfig — 너비/높이 크기 조정 전략(FIXED, FILL_CONTAINER, HUG_CONTENT), 배경 페인트, 테두리, 모서리 반경, 타이포그래피. CSS 개념에 충분히 가까워서 생성기가 깔끔한 스타일시트를 출력할 수 있습니다.
processingMeta.detectionScore — 이 요소에 대한 감지기의 신뢰도(0–1). 다운스트림 아티팩트를 생성하기 전에 낮은 신뢰도 노드를 제거하고 싶을 때 유용합니다.

파이프라인이 실제로 하는 일

PDF를 이 Schema로 변환하는 것은 단일 모델 호출이 아닙니다 — 짧은 파이프라인입니다:

래스터화 + 추출. PDF 스트림을 파싱하여 텍스트 런, 벡터 경로, 내장 래스터 이미지를 추출합니다. 스캔된 페이지는 병렬로 실행되는 OCR 패스로 전달됩니다.
레이아웃 분석. 비전 모델이 페이지를 영역 — 헤더, 본문 블록, 사이드바, 그림, 표, 캡션 — 으로 분할하고 각각에 대략적인 유형을 할당합니다. 여기서 Panel 경계가 생성됩니다.
요소 감지. 각 영역 내부의 더 밀집된 모델이 개별 UI 요소 — 버튼, 아이콘, 폼 필드, 차트 시리즈 — 를 식별합니다. 이 단계에서 elementType 분류가 생성됩니다.
텍스트 그룹핑. 원시 글리프 위치가 단어, 줄, 단락으로 클러스터링된 다음 가장 가까운 컨테이너 요소에 첨부됩니다.
Schema 조립. 계층 구조가 구체화되고, 부모-자식 링크가 해결되며, 요소별 스타일이 계산됩니다. 좌표는 baseWidth로 정규화됩니다.

2단계와 3단계가 지연 시간 예산의 대부분을 차지합니다. 그 전후의 모든 것은 비교적 저렴합니다.

이를 기반으로 구축할 수 있는 것

Schema는 의도적으로 범용적입니다. 팀들이 이를 기반으로 출시한 구체적인 사례들:

디자인 임포트. 레거시 PDF 사양을 한 번에 편집 가능한 Figma 프레임으로 변환합니다. 레이아웃 설정이 Figma 오토 레이아웃 시맨틱을 반영하므로 임포트 시 오토 레이아웃이 올바르게 재구축됩니다.

레거시 현대화. 500페이지 PDF 매뉴얼을 반응형 웹 버전으로 생성합니다. 각 페이지가 하나의 라우트가 되고, 요소 유형이 컴포넌트 선택을 주도합니다.

시각적 회귀 테스트. 두 빌드에서 기준 페이지를 렌더링하고, 둘 다 API를 통해 처리한 후 요소 트리를 비교합니다. 요소 수준의 차이 비교는 폰트 변경이나 서브픽셀 안티앨리어싱에서 픽셀 비교보다 훨씬 안정적입니다.

레이아웃 인식 RAG. 검색을 위해 PDF를 인덱싱할 때 원시 텍스트 덤프를 버리세요. 요소 단위로 청크를 나누고 부모-자식 관계를 보존하면 퍼지 휴리스틱 없이 "4페이지의 CTA가 무엇인가" 또는 "11페이지 두 번째 표의 세 번째 열이 무엇인가"에 답할 수 있습니다.

차트 추출. Chart 노드는 충분한 메타데이터(축 라벨, 시리즈 색상, 그룹화된 텍스트)를 포함하므로 스크린샷을 렌더링하는 대신 라이브 차트 컴포넌트로 변환할 수 있습니다.

정확도에 대한 참고 사항

실제 감지 품질은 PDF 원본, 텍스트 선명도, 레이아웃 복잡도에 따라 달라집니다. 제품 디자인 PDF는 비교적 파싱하기 쉽지만, 스캔된 법률 문서와 수기 주석이 달린 양식은 OCR 노이즈가 더 많고 detectionScore 값이 낮을 수 있으므로 필터링을 계획하세요.

시작하기

codia.ai/dashboard/developer에서 API 키를 받으세요.
위의 curl을 보유한 아무 PDF에 대해 시도해 보세요.
선호하는 언어로 응답 트리를 탐색하세요 — Schema는 순수 JSON이므로 SDK가 필요하지 않습니다.
파싱을 건너뛰고 바로 Figma 파일로 가고 싶다면, 동일한 파이프라인으로 구축된 PDF to Design Figma 플러그인을 확인하세요.

전체 레퍼런스, 요청/응답 형태, 에러 코드는 개발자 문서에 있습니다. 더 높은 레이트 리밋이나 프라이빗 배포가 필요하면 [email protected]로 연락하세요 — 데이터 레지던시 요구사항이 있는 기업을 위해 파이프라인은 격리된 컨테이너로 제공됩니다.

PDF는 사라지지 않을 것입니다. 지난 10년간 모든 디자인 자동화 노력의 완고한 마지막 단계였습니다. PDF에 깔끔하고 타입이 지정된 구조를 부여하는 것이 다시 일급 시민으로 만드는 첫 번째 단계입니다.

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

← 글 목록으로 돌아가기