PyMuPDF 기반 PDF Annotation 좌표 최적화를 통한 페이지 번호 자동 정렬 CLI 구현

pdf-pagenum: Fix Messy macOS Preview Page Numbers in PDFs from the CLI

Xin Zhang2026년 6월 17일4분intermediate

AI 요약

Context

macOS Preview의 Text Annotation 도구가 제공하지 않는 Batch Processing 및 Auto-Centering 기능으로 인한 수동 작업의 비효율성 발생. 특히 Portrait와 Landscape 페이지가 혼재된 대규모 PDF 문서에서 일관된 레이아웃 유지를 위한 자동화 도구 필요성 대두.

Technical Solution

PyMuPDF를 활용한 각 페이지의 Text Block 및 Image Bounding Box 추출로 실제 본문 영역(Body Content)의 하단 경계 식별
Regular Expression 기반의 Pattern Matching을 통해 FreeText Annotation 중 페이지 번호에 해당하는 객체만 선택적으로 필터링
폰트 렌더링 기반의 실제 문자열 너비(Exact Bounding Dimensions) 측정으로 단순 추측이 아닌 수학적 수평 중앙 정렬 좌표 계산
(page_center - text_width/2, below_content + margin) 공식을 적용한 좌표 재배치 및 가독성 확보를 위한 White Background Fill 적용
natsort 라이브러리를 도입하여 파일 시스템의 Lexicographical Order가 아닌 인간 중심의 Natural Sorting으로 파일 처리 순서 보장
PDF의 원본 기하학적 구조(Page Geometry)를 유지하기 위해 Resize를 금지하고 좌표 값만 수정하는 불변성 원칙 적용

실천 포인트

- PDF 좌표계 제어 시 단순 중앙값이 아닌 본문 Bounding Box를 먼저 계산하여 Content Overlap 방지 - 문자열 정렬 구현 시 폰트 메트릭을 직접 측정하여 렌더링 오차 제거 - 다수의 파일 처리 파이프라인 설계 시 natsort와 같은 자연어 정렬 로직 검토 - 문서 구조 변경이 하위 워크플로우에 미치는 영향을 고려하여 Page Dimension 변경을 배제한 데이터 수정 전략 채택

태그

#Bounding Box #Coordinate System #Annotation #PyMuPDF #CLI

원문 읽기