hwpx-restyle

샘플 HWPX 한 권의 서식으로 다른 보고서를 재조판하는 도구.

보고서의 한 장(예: 제1장)을 서식 기준(샘플)으로 두고, 다른 장의 텍스트·표 격자·그림 파일만 가져와 샘플과 같은 모양의 HWPX를 만든다. 한글(한컴오피스)이 없어도 생성은 되고, 검증(PDF 변환)에만 Windows + 한글이 필요하다.

원본.hwpx ──extract──▶ content.json + images/ ──build(샘플.hwpx)──▶ 재조판.hwpx ──pdf──▶ 검증

설치

Python 3.9 이상.

pip install -e .            # lxml, Pillow
pip install -e .[verify]    # PDF 썸네일 비교용 PyMuPDF

Related MCP server: MCP PDF

사용법

# 샘플 서식 분석(무엇을 원형으로 잡았는지 확인)
python -m hwpx_restyle inspect 샘플.hwpx

# 한 번에: 추출 → 재조판 → (옵션) PDF·썸네일
python -m hwpx_restyle run 샘플.hwpx 원본.hwpx 작업폴더 --pdf

# 단계별
python -m hwpx_restyle extract 원본.hwpx mid/
python -m hwpx_restyle build 샘플.hwpx mid/ 결과.hwpx --opts "{\"fig_h\": 29500}"
python -m hwpx_restyle pdf 결과.hwpx 결과.pdf          # Windows + 한글
python -m hwpx_restyle sheet 결과.pdf 썸네일접두어
python -m hwpx_restyle check mid/ 결과.hwpx           # 내용 보존 검사(한글 불필요)

쪽 맞춤: 결과 PDF를 읽어 빈 쪽(원본에서 온 쪽 나눔 때문)과 쪽 끝에 홀로 남은 제목·표 제목을 찾아 중간포맷의 쪽 나눔을 고친다. build → pdf → fit을 2~3번 반복한다.

python -m hwpx_restyle fit mid/ 결과.pdf

자세한 구조·원칙·함정은 docs/DEVELOPMENT.md.

check는 결과 hwpx를 다시 추출해 원본 추출본과 블록 단위(텍스트·표 격자·그림·장/절 번호)로 비교합니다. run은 자동으로 검사하고 report.json에 기록합니다.

다른 보고서 서식으로 옮기기: 내용(중간포맷)과 서식(샘플)이 분리돼 있으니, 추출은 한 번만 하고 샘플만 바꿔 build하면 된다.

python -m hwpx_restyle extract "B보고서 제4장.hwpx" mid_b4/
python -m hwpx_restyle build "A보고서 제1장.hwpx" mid_b4/ "제4장(A서식).hwpx"

.hwp(바이너리)는 먼저 tools/hwp2hwpx.ps1로 hwpx로 바꾼다.

중간포맷 (content.json)

사람이 직접 쓰거나 다른 프로그램(엑셀 등)에서 만들어도 된다. 예: examples/content.example.json

style은 원본 스타일 이름을 그대로 두면 된다. 샘플에 같은 이름이 없으면 ① 이름 계열(표번호·그림제목·단위…) ② 텍스트 모양(가., 1), ①, - …)으로 샘플 스타일에 대응시킨다.

조판 규칙

MCP 서버

같은 기능을 MCP 도구로 쓸 수 있다(Claude Desktop, Claude Code 등). stdio 전송.

pip install -e .[mcp]
hwpx-restyle-mcp            # 또는 python -m hwpx_restyle.mcp_server

{"mcpServers": {"hwpx-restyle": {"command": "hwpx-restyle-mcp"}}}

경로는 서버가 도는 PC의 절대경로로 준다.

한계 / 할 일

• 쪽 맞춤은 1단계(쪽 나눔 조정)만 있다. 2단계(자간·표 글자 크기로 한 문단을 한 쪽에 넣기)는 아직 없음

• 표 칸 안의 표(중첩 표)·그리기 개체는 글자로만 보존된다(누락은 없지만 구조는 잃음)

• 샘플에 없는 양식(예: 모서리 장식 그림틀)은 만들지 않고 가장 가까운 것으로 대신한다

• 자동 테스트는 아직 없다. 검증은 실제 보고서 여러 세트로 check + PDF 비교로 했다(자료는 저장소에 포함하지 않음)

라이선스

MIT