PDFSyntax - PDF 파일 내부 구조의 HTML 시각화

 (github.com/desgeeko)
2P by GN⁺ | ★ favorite | 댓글 1개
  • PDFSyntax는 PDF Specification의 7장 “Syntax”에 초점을 맞춘 Python 라이브러리로, PDF 파일의 내부 문서 구조를 바이트 단위까지 검사하고 변환하는 데 사용됨
  • 순수 Python으로 처음부터 작성됐고 의존성이 없는 경량 라이브러리이며, 단순성과 불변성을 중시함
  • 기본 편집 방식은 PDF 사양이 허용하는 비파괴적 증분 업데이트로, 원본 파일 끝에 변경 섹션을 추가하며 되감기나 단일 리비전으로 합치기가 가능함
  • CLI는 overview, disasm, text, fonts, browse 등을 제공하며, browse는 PDF 소스를 보기 좋게 출력하고 하이퍼링크가 포함된 정적 HTML로 내부 구조를 탐색하게 함
  • 현재는 베타 품질의 작업 중인 프로젝트로 API가 언제든 바뀔 수 있고, MIT 라이선스이지만 아직 외부 기여는 받지 않음

PDF 내부 구조 검사와 변환

  • PDFSyntax는 PDF 파일의 내부 구조를 검사하고 변환하기 위한 Python 라이브러리임
  • Portable Document Format(PDF) Specification의 7장인 “Syntax”에 초점을 맞춤
  • 문서 구조 관리를 바이트 수준까지 구현해 다음과 같은 용도에 사용됨
    • 메타데이터 접근
    • 페이지 회전
    • PDF 읽기/쓰기 작업
    • 내부 객체 접근과 조작

설계 방향

  • 내부 함수들은 PDF 읽기/쓰기 작업을 위한 API 툴킷으로 노출됨
  • 일부 기능은 터미널이나 브라우저에서 사용할 수 있도록 CLI로도 제공됨
  • 라이브러리는 순수 Python으로 작성됐고 외부 의존성이 없음
  • 단순성과 불변성을 중시함
  • 기본 편집 방식은 원본을 직접 덮어쓰지 않고 원본 파일 끝에 변경 내용을 추가하는 증분 업데이트임
    • 필요하면 리비전을 되감을 수 있음
    • 모든 리비전을 하나로 합칠 수도 있음

설치와 CLI 사용

  • PyPI에서 설치 가능함
pip install pdfsyntax
  • CLI의 기본 사용 형식은 다음과 같음
pdfsyntax COMMAND FILE
  • 소스에서 설치한 경우 더 긴 형식으로 실행할 수 있음
python3 -m pdfsyntax COMMAND FILE
  • 빠른 PDF 분석을 위한 주요 명령은 다음과 같음
    • overview: 구조와 메타데이터에 대한 텍스트 정보 출력
    • disasm: 파일 구조 덤프를 터미널에 출력
    • text: 스캔처럼 공간 배치를 유지한 추출 텍스트 출력
    • fonts: 사용된 폰트 목록 출력
    • browse: PDF 소스를 보기 좋게 출력하고 하이퍼링크를 추가한 정적 HTML을 생성해 내부 구조 탐색을 지원

API 사용 방식

  • PDFSyntax는 대부분 단순한 함수들로 구성됨
  • readfile로 PDF를 읽고 metadata로 메타데이터를 Python dict 형태로 얻을 수 있음
>>> from pdfsyntax import readfile, metadata
>>> doc = readfile("samples/simple_text_string.pdf")
>>> metadata(doc)
  • Doc 객체는 문서의 내부 상태를 저장하는 거의 유일한 전용 클래스임
    • 원본 파일에서 캐시되거나 메모이즈된 콘텐츠
    • 콘텐츠 추가·수정·삭제 변경 사항
    • 증분 업데이트로 추적되는 수정 내역
  • 같은 metadata 함수는 Doc 객체의 메서드로도 사용할 수 있음
>>> doc.metadata()
  • get_object, update_object 같은 저수준 함수로 문서 내부 객체에 직접 접근하고 조작할 수 있음
  • rotate 같은 고수준 함수도 제공됨
>>> from pdfsyntax import rotate, writefile
>>> doc180 = rotate(doc, 180)
  • 회전 예시에서는 원본 객체가 변경되지 않고, 진행 중인 방향 변경을 담은 새 객체가 만들어짐
  • 수정된 PDF는 writefile로 디스크에 쓸 수 있음
>>> writefile(doc180, "rotated_doc.pdf")
  • 결과 파일은 원본 콘텐츠 뒤에 새 섹션이 추가된 형태이며, 이 섹션을 잘라내면 변경을 되돌릴 수 있음

현재 상태와 기여 정책

  • 프로젝트는 작업 중이며 베타 품질 소프트웨어임
  • API는 언제든 변경될 수 있음
  • 다음 작업 목록에는 아래 항목이 포함됨
    • 페이지 자르기와 붙이기
    • 무손실 압축
    • 더 많은 필터
    • 텍스트 추출 개선
    • 레이아웃 감지를 통한 텍스트 추출 보강
  • PDFSyntax는 MIT 라이선스임
  • 현재는 외부 기여를 받지 않음
    • 개인 프로젝트이며 시간이 제한적임
    • 새 기능과 리팩터링 로드맵에 먼저 집중한 뒤 안정화되면 기여를 받을 예정임

함께 보면 좋은 글 β

GN⁺   [-]
Hacker News 의견들

  • 오래전에 여러 PDF에서 데이터를 추출하는 일을 맡았고, 페이지 위 문자 배치와 모든 요소의 경계 상자를 시각화하는 도구를 만들었음
    결국 프로젝트는 완전히 실패했고, 기대한 결과를 내지 못해 몇몇이 화를 냈음
    지금이라면 PDF에서 데이터를 뽑아내는 LLM 역량을 활용하는 쪽으로 100% 갔을 것임. 당시에는 그런 선택지가 없었음

    • 임의의 PDF에서 데이터를 파싱하는 건 저주받은 임무에 가까움. PDF에는 이미지도 들어갈 수 있으니 차라리 JPEG를 직접 대상으로 삼는 것과 비슷함
      기대치에 따라 OCR로 꽤 멀리 갈 수는 있지만, 내 경험상 항상 딱 필요한 만큼에는 못 미침
    • LLM은 페이지에서 추출한 문자들의 순서를 맞추는 데는 도움이 될 수 있지만, 실제 내용을 얻어내는 일은 여전히 어렵다
      여러 번 본 사례로, 텍스트의 글자가 ASCII 같은 매핑이 없는 커스텀 글꼴 글리프로 되어 있거나, CAD 출력물에서 특히 흔하듯 글자 모양을 선으로 그려 만든 경우가 있음
      그러면 추출할 식별 가능한 텍스트가 없어서 결국 페이지를 OCR로 다시 확인해야 함
    • 이전 직장에서 비슷한 일을 겪었는데, 규칙 기반 파싱 방식은 제대로 만들기 정말 까다롭고 엣지 케이스에서 자주 실패했음
      우리는 https://runtrellis.com/에서 LLM과 시각 언어 모델을 기반으로 PDF 처리 파이프라인을 처음부터 만들고 있으며, 까다로운 PDF에서도 거의 100%에 가까운 정확도를 봤음
      핵심은 규칙 기반 엔진과 참조 데이터를 함께 써서 결과를 교차 검증하는 것임
    • 오래전에 PDF에서 2D CAD 도면을 추출해 완전한 3D로 변환하는 일을 했는데, 꽤 재미있었음
    • pdfjs가 그런 작업을 모두 해주고 꽤 견고함. 최근에 10년치 은행 명세서에서 표 데이터를 추출하는 데 사용했음

  • 꽤 멋짐. 예전 직장에 이게 있었다면 많이 썼을 것 같음
    이상적으로는 https://lapo.it/asn1js/처럼 파일을 떨어뜨리면 모든 처리를 로컬에서 해주는 방식이면 좋겠음

  • PDF에서 데이터를 추출하는 코드를 다루는 “특권” 덕분에, 한동안 iText RUPS 무료 버전을 PDF 디버깅에 써왔음
    여기의 내부 검사 기능이 좀 더 강력해 보이니 아주 좋을 듯함. 한번 돌려볼 생각임

  • GitHub에 비슷한 프로젝트가 있었던 기억이 있음. 주어진 스키마로 임의의 바이너리 데이터를 시각화할 수 있었고, TCP/IP 예제가 있었던 것 같음

    • https://kaitai.io/일지도?
      그 역할에는 아주 좋아 보였지만, 마지막 프로젝트에서는 직렬화도 필요해서 쓰지 않았음
    • HexFiend에도 바이너리 데이터 시각화를 위한 템플릿 문법이 있음. Tcl 기반임
      https://github.com/HexFiend/HexFiend/blob/master/templates/T...
    • 이 맥락에서 “임의의”라는 말은 조심해야 함
      흥미롭게도 나는 그런 파일 형식 기술자를 시험해볼 때 PDF를 “Hello World”로 삼는데, PDF 명세가 워낙 괴상하기 때문임
      기술 언어가 PDF의 레이아웃을 정확히 표현할 수 있다면 확실히 잘 설계된 것이라고 볼 수 있음
      지금까지는 선언형 모드에서 빠져나와 “그다음 이 코드를 실행”할 수 있는 것들 말고는 그다지 운이 좋지 않았음

  • 이건 포렌식과 워터마크 찾기에도 편리하겠음

    • 흥미로워 보임. 잘 몰라서 그런데, 이걸 어떻게 워터마크 감지에 쓸 수 있음? 같은 방법으로 서명도 감지할 수 있을까?

  • 좋아 보임
    PDF의 모든 바이트가 표시되면 더 좋겠음. endobj와 xref는 보이지 않는 것 같음

    • 맞음, 곧 고치겠음

  • 이게 브라우저 라이브러리로 나오면 정말 좋겠음. 파일을 끌어다 놓고 내부를 볼 수 있으면 됨. 그래도 인상적임

    • 브라우저 확장을 말하는 건가? 무례하게 굴려는 건 아니고, 제대로 이해했는지 확인하려는 것임

  • 잘 만들었음. 매우 유용한 보안 미리보기 도구임. PDF는 골칫덩어리임

  • 시각화를 담당하는 UI 도구가 라이브러리인지 궁금함
    UI 형식이 정말 마음에 들어서, 비디오 바이트 스트림을 분해하고 디버깅하는 데도 쓰고 싶음
    수정: 실제로는 꽤 단순하네. CSS를 잘 활용했음! https://github.com/desgeeko/pdfsyntax/blob/main/docs/simple_...

    • 맞음. 단순성을 중요하게 보고, 기본 HTML과 CSS가 제공하는 상호작용이면 내 사용 사례에는 충분함 :)

  • 비슷한 맥락에서, 왜 PDF는 아직 대체되지 않았을까? XPS, DjVu, XHTML(EPUB)이 있지만 모두 서로 다른 사용 사례, 예를 들면 패키징된 HTML 파일 쪽을 겨냥하는 듯함
    내가 원하는 건 Adobe의 비대함 없이 다른 파일과 메타데이터를 임베드할 수 있는 단순한 문서 형식임
    페이지 안에서 하이퍼링크를 걸 수 있고, 글자 크기를 바꿔도 텍스트가 넘치지 않으며, 일관되게 인쇄할 수 있어야 함

    • PDF가 편집, 기기 내 읽기, 표현 정보가 아닌 의미 정보 추출에 “불행한” 형식이 된 이유는 Adobe의 죄나 비대함 때문은 아니라고 봄
      PDF는 데이터 형식이 아니라 페이지 기술 형식이라서, 서로 다른 운영체제·소프트웨어·프린터·정확한 종이 크기를 쓰더라도 같은 “페이지”를 인쇄할 수 있게 하는 필요에서 모든 결정이 나옴
      PDF가 오래 버티는 주된 이유는 많은 것이 문서 패러다임, 즉 “문서”를 “종이 여러 장의 묶음”으로 보는 방식 위에서 돌아가기 때문일 것임
      병원 진료 후 요약지부터 자동차 등록 문서까지, 이미 종이 위에 그럴듯하고 정확히 들어맞도록 선택된 특정 시각 표현을 갖고 있음
      HTML, 예를 들어 이미지와 CSS를 데이터 URL로 넣어 독립 실행 가능하게 만든 형식이나 ePub이 대부분 면에서 더 나을 수는 있음
      하지만 목표가 너무 달라서, 오늘날 PDF를 만드는 사람들에게 그런 전환을 설득하러 가면 기기마다 내용이 조금씩 다르게 보이고 설정에 따라 페이지 나눔까지 달라진다는 불만을 듣게 될 것임
      관련해서 흥미로운 건, Google Docs조차 인쇄되거나 PDF로 변환되는 경우가 절반보다 훨씬 적을 것 같은데도 기본값이 “페이지 없음” 모드가 아니라 페이지 모드라는 점임
      “페이지 없음” 모드는 일반 웹페이지처럼 창에 맞고 하나의 연속된 표면을 끝없이 스크롤하는 방식이라 훨씬 유용함
    • 사용 사례가 다름
      “텍스트가 넘치지 않게”라는 요구에는 많은 세부 사항이 따라옴
      PDF에서는 텍스트의 모든 글자·문자·글리프가 페이지 위, 때로는 페이지 밖의 정확한 x,y 위치를 가질 수 있음
      그래서 주변에 무엇이 있든 콘텐츠를 정밀 배치할 수 있음. PDF를 쓰는 애플리케이션이 항목을 올바르게 배치하고 글자 또는 단어 줄바꿈을 구현해야 함
      XPS가 PDF를 재구현하는 데 가장 가까웠지만, Microsoft가 다른 주체들의 충분한 지지를 얻지 못해 조용히 사라졌음
    • 최근까지 몰랐던 PDF의 흥미로운 점은 PDF가 PostScript의 부분집합이고, 그게 어느 정도 무거움의 원인이라는 것임
      PostScript는 특이하긴 해도 완전한 프로그래밍 언어지만, PDF는 그렇지 않음. 즉 튜링 완전하지 않음
      PDF는 제어 흐름을 지원하지 않아서, PostScript에서 단순한 루프로 표현할 수 있는 것도 PDF에서는 펼쳐서 일련의 단순 선언이나 표현식으로 저장해야 함
      장점은 PDF를 렌더링하는 데 완전한 프로그램 인터프리터가 필요 없다는 것임
    • 이런 대화가 시작되자마자 LaTeX 진영이 나타나고, 표준에 의미 있게 보탤 수 있는 모두가 그 논의에 막히기 때문임
    • 한 가지 이유는 다른 형식들 중 어느 것도 그대로는 상업 인쇄에 적합하지 않기 때문임
답변달기