PDF 문구 하나 바꾸려다 2쪽이 5쪽이 됐다
문구 하나를 조금 더 긴 문구로 바꿨더니, 바뀐 글자가 바로 뒤에 오는 쉼표와 다음 단어 위에 포개졌다는 신고가 들어왔다. 새 경로를 넣고 세 시간이 안 돼 그 겹침을 고치는 수정이 따라 들어갔다.
2026년 7월 초의 일이다. 커뮤니티용 텔레그램 봇에 PDF를 올리고 “A -> B”처럼 적으면 고친 PDF를 돌려주는 기능이 있다. 겹침을 만든 건 그날 저녁에 넣은 in-place 치환 경로였고, 그 경로는 같은 날 다른 문제 때문에 생겼다. 신고에서 출발해 거꾸로 적는다.
쉼표는 같은 span 안에 있었다
새 경로는 바꿀 문구를 찾아 그 글자만 지우고, 같은 자리에 새 문구를 그린다. 새 문구가 더 길면 뒤 글자와 부딪치지 않도록 가로로 줄여서 그린다. 얼마나 줄일지는 “같은 줄에서 다음 텍스트가 시작하는 x 좌표”로 정했다. 처음 코드는 이랬다(이름을 줄였다).
def next_text_x(page, cluster):
y = cluster[0].y0
right = max(r.x1 for r in cluster)
nxt = None
for span in iter_spans(page): # get_text("dict")의 모든 span
sb = fitz.Rect(span["bbox"])
if abs(sb.y0 - y) <= LINE_TOL and sb.x0 >= right - 0.5:
if nxt is None or sb.x0 < nxt:
nxt = sb.x0
return nxt # None이면 줄이지 않는다
매치 오른쪽에서 시작하는 span을 찾는다. 문제는 매치 뒤의 쉼표와 단어가 매치와 같은 span에 들어 있었다는 점이다. 그 span은 매치보다 왼쪽에서 시작하니 sb.x0 >= right 조건에 걸리지 않는다. 함수는 뒤에 아무것도 없다고 보고 None을 돌려줬고, 새 문구는 원래 폭 그대로 그려져 뒤 글자를 덮었다.
PyMuPDF 문서의 span 설명을 보면 이게 예외가 아니다. 한 줄은 span의 목록이고, 한 줄에 span이 여러 개가 되는 건 글꼴 속성이 다른 텍스트가 섞일 때뿐이라고 적혀 있다. 굵게나 기울임 없이 한 글꼴로 쓴 줄은 통째로 span 하나다. 처음 코드는 단어마다 span이 갈라진다고 가정한 셈이었다.
고친 코드는 “다음 텍스트가 어디서 시작하나”를 묻지 않는다. 그 줄에 매치 오른쪽 끝을 넘어가는 span이 하나라도 있으면, 한계선을 매치 자신의 오른쪽 끝으로 잡는다.
def limit_x(page, cluster):
y = cluster[0].y0
right = max(r.x1 for r in cluster)
for span in iter_spans(page):
sb = fitz.Rect(span["bbox"])
if abs(sb.y0 - y) <= LINE_TOL and sb.x1 > right + 0.5:
return right # 옛 문구의 폭 안에 맞춘다
return None # 줄 끝이면 원래 폭 그대로
지우는 건 매치된 글자뿐이라 뒤 글자는 원래 자리에 그대로 있다. 그러니 새 문구가 들어갈 수 있는 곳은 옛 문구가 차지하던 폭까지다. 매치가 줄이나 문단 끝에 있을 때만 여유가 있다고 보고 원래 폭으로 그린다. 신고된 문구는 이 수정 뒤 가로 배율 0.73으로 옛 자리에 들어갔고, 겹침이 사라졌고, 문서는 2쪽 그대로였다.
지우고 같은 baseline에 다시 그리기
겹침 이전에 이 경로가 하는 일은 이렇다. Page.search_for로 바꿀 문구의 사각형들을 찾는다. 한 번 나온 문구가 span이나 줄 경계에서 사각형 여러 개로 쪼개질 수 있고, 같은 문구가 한 쪽에 여러 번 나올 수도 있다. 그래서 세로 차이 3pt 안, 가로 간격 4pt 안인 사각형은 한 번 나온 것으로 묶었다.
묶음마다 겹치는 면적이 가장 큰 span을 찾아 크기, 색, 굵기, 첫 글자의 origin을 가져온다. origin의 y가 baseline이다. 색은 0xRRGGBB 정수라 비트를 나눠 RGB로 바꾼다. 굵기는 flags의 bit 4와 글꼴 이름에 “bold”가 들어 있는지를 같이 본다. 문서도 이 flags 비트는 글꼴이 틀린 값을 담고 있는 경우가 많다고 적어 두었다.
그다음 지운다.
for r in cluster:
page.add_redact_annot(r, fill=False) # 흰 덮개 없이 글자만
page.apply_redactions(
images=fitz.PDF_REDACT_IMAGE_NONE, # 이미지는 그대로
graphics=fitz.PDF_REDACT_LINE_ART_NONE, # 표 테두리, 상자 배경도 그대로
)
page.insert_text(
fitz.Point(x0, baseline_y), new_text,
fontsize=size, fontname="dvr", fontfile=font_path, color=rgb,
morph=(fitz.Point(x0, baseline_y), fitz.Matrix(scale, 1.0)),
)
add_redact_annot의 fill 기본값은 흰색이다. 기본값으로 두면 회색 상자 안의 문구를 바꿀 때 그 자리에 흰 직사각형이 생긴다. False를 주면 채우기 없이 글자만 빠진다. apply_redactions의 graphics 인자는 문서상 v1.23.27에서 들어왔다. 그보다 오래된 버전에서 TypeError가 나면 인자 없이 다시 부르도록 감쌌다.
가로 축소는 insert_text의 morph로 했다. 문서는 morph를 (고정점, 행렬) 쌍으로 정의하고, 이동 성분이 없는 행렬만 받는다. 고정점을 삽입 위치로 두고 Matrix(scale, 1.0)을 주면 baseline과 글자 높이는 그대로 두고 폭만 줄어든다. 배율이 1이면 morph 없이 그린다. 짧아지는 치환은 늘리지 않고 남는 자리를 빈칸으로 둔다.
글꼴은 정확히 맞추지 못했다. 봇이 WeasyPrint로 만든 PDF에는 DejaVu Serif가 들어가 있어서, 컨테이너의 DejaVu 파일로 그리면 봇이 만든 문서와는 맞는다. 다른 데서 온 PDF는 span의 글꼴 이름에 sans, arial, helvetica 같은 말이 있으면 DejaVu Sans로, 아니면 Serif로 그린다. 비슷하게만 맞춘다.
그 전에는 문서를 통째로 다시 만들고 있었다
in-place 경로가 생기기 전에는 모든 수정이 HTML 재구성으로 갔다. PDF에서 HTML을 다시 만들고, 문구를 바꾸고, WeasyPrint로 다시 렌더링한다. HTML을 다시 만드는 일은 모델이 한다. 이 경로는 문서 전체를 새로 조판한다. 글꼴 크기와 간격이 원본과 똑같이 나오지 않아서, 실제로 2쪽짜리 가로 문서가 5쪽으로 돌아왔다. 요청한 사람의 조건은 서식이 깨지지 않을 것, 2쪽이 3쪽이 되지 않을 것, 글자만 바뀔 것 세 가지였다.
그래서 요청을 둘로 나눴다. 수정 메모를 줄 단위로 보고 “A -> B”, “A 대신 B” 같은 꼴은 치환 쌍으로 뽑는다. 원문이 두 글자 이상이고, 원문과 새 문구가 다르고, <나 >가 없어야 한다. 나머지 줄은 남은 지시로 둔다. 치환 쌍이 있고 남은 지시가 없을 때만 in-place 경로로 가고, 모델은 부르지 않는다. 레이아웃을 바꾸라는 식의 지시가 한 줄이라도 섞이면 예전 HTML 경로로 간다.
PyMuPDF는 핸들러 안에서 import한다. 패키지가 없거나 in-place 처리 중에 예외가 나면 로그를 남기고 HTML 경로로 넘어간다. 원문을 글자 그대로 찾지 못한 치환은 결과 PDF의 캡션에 따로 적어, 띄어쓰기와 부호까지 PDF에 있는 그대로 다시 적어 달라고 안내한다. 고친 결과를 다시 고치는 경우에는 결과 PDF의 바이트를 받아 같은 경로를 한 번 더 탄다. 첫 배포 때 컨테이너에서 해 보니 2쪽은 2쪽으로 남았고, 회색 표 머리, 파란 제목, 상자 배경과 테두리가 그대로였고, 이어서 고치는 것도 됐다.
0.6 밑으로는 줄이지 않는다
가로 배율에는 하한이 있다. 0.6보다 좁히면 글자가 찌그러져 보여서, 그보다 더 줄여야 맞는 경우는 0.6에서 멈추고 조금 넘치게 둔다. 새 문구가 옛 문구보다 1.67배쯤 넘게 길면 지금도 뒤 글자에 약간 걸친다는 뜻이다. 줄을 밀지는 않으니 쪽수는 늘지 않는다. 이 경우를 따로 알려 주지는 않는다.
다음에 겹침 신고가 다시 오면 볼 곳이 하나 더 있다. 문서에 따르면 apply_redactions는 기본적으로 경계 상자가 redaction 사각형과 겹치는 글자를 모두 지운다. 검색 사각형이 옆 글자의 상자에 걸치면 그 글자까지 빠질 수 있다. 아직 그런 신고는 없었다.