본문으로 건너뛰기
시골프로그래머의 블로그
블로그 메뉴

한/글 문서를 쪽별 이미지와 PDF로 내보내는 콘솔 도구 — HWPExport

HWP 문서를 쪽마다 PNG·JPG 같은 이미지로, 또는 PDF 한 파일로 내보내는 Windows 콘솔 도구입니다. JSON 출력과 원인별 종료 코드가 있어 스크립트와 AI 에이전트에서 부르기 좋습니다.

풀빛컴퓨팅4분 읽기#오픈소스#C#HWP#문서 변환

HWP 문서를 화면 그대로 이미지로 뽑아야 할 때가 있습니다. 미리보기를 만들거나, 이미지를 읽는 AI 모델에 문서를 넘기거나, 보관용 PDF를 만들 때입니다. HWP 형식을 그려 주는 공개 렌더링 라이브러리가 없어서, 결국 한/글을 직접 움직여야 합니다. 그런데 한/글 자동화는 대화상자 하나에 멈추고, 두 작업이 겹치면 실패합니다.

HWPExport는 이 과정을 명령 한 줄로 묶은 Windows 콘솔 도구입니다. 한/글이 등록하는 OLE 자동화 개체 HWPFrame.HwpObject를 불러 쪽을 그리거나 PDF로 저장합니다.

무엇을 하나

HWPExportC.exe report.hwp out -f png -d 150     # 쪽마다 PNG 한 장
HWPExportC.exe report.hwp out -f pdf            # 문서 전체를 PDF 한 파일로
HWPExportC.exe report.hwp out -f png --json     # 자동화용 JSON 출력
출력 만드는 방법
BMP, GIF 한/글의 CreatePageImage가 바로 만듦
PNG, JPG 임시 BMP로 그린 뒤 변환(C판은 GDI+, Delphi판은 VCL)
PDF 한/글의 SaveAs로 한 파일 저장

이미지 파일 이름은 <원본이름>_p0001.png처럼 네 자리 쪽 번호가 붙습니다.

옵션

옵션 기본값 설명
-s <n> 1 시작 쪽(1부터)
-e <n> 끝 마지막 쪽
-f <fmt> bmp bmp gif png jpg pdf
-d <n> 300 해상도(DPI)
-q <n> 90 JPEG 품질, 1~100
--json 끔 결과를 JSON으로 출력
--timeout <n> 300 제한 시간(초), 0이면 끔
--wait <n> 300 다른 실행이 끝나기를 기다리는 시간(초)

--json을 주면 성공 여부, 만든 파일의 절대 경로 목록, 오류 코드와 메시지가 한 형태로 나옵니다. 인자를 잘못 줘도 같은 JSON 형태로 답하고, 출력은 늘 UTF-8입니다. 종료 코드는 원인별로 0부터 12까지 나뉘어 있어(3은 한/글 미설치, 11은 시간 초과, 12는 다른 실행 중) 호출하는 쪽에서 갈라 처리하기 쉽습니다. Python에서 subprocess로 부르는 예제와 Claude Code의 CLAUDE.md에 적어 둘 안내문 예시는 저장소 README에 정리해 두었습니다.

한/글 자동화에서 걸린 문제들

만들면서 부딪힌 함정이 꽤 많았습니다. 이 도구를 쓰지 않고 한/글을 직접 자동화할 때도 참고가 될 만한 것들입니다.

  • 대화상자에 걸리면 호출이 끝나지 않습니다. "상위 버전에서 작성한 문서입니다" 경고가 대표적입니다. SetMessageBoxMode로 자동 응답을 걸어야 하는데, 인자는 비트 마스크가 아니라 상자 종류마다 4비트씩 응답 코드를 넣는 값입니다(0x00466511). 잘못 넣으면 오류 없이 무시됩니다. 그래서 제한 시간을 두고, 넘기면 이 도구가 띄운 한/글 프로세스만 끝냅니다.
  • 두 작업을 동시에 돌릴 수 없습니다. 이름 있는 뮤텍스(Local\HWPExport.SingleInstance)로 줄을 세웁니다.
  • 서비스나 세션 0에서는 동작하지 않습니다. 로그인된 데스크톱이 있어야 합니다.
  • 한/글이 만든 BMP의 해상도 헤더가 엉터리입니다. 그대로 두면 탐색기 미리보기에서 쪽이 옆으로 눌려 보여서, 요청한 DPI로 헤더를 고쳐 씁니다.

파일에 접근할 때 뜨는 보안 확인 창은 한/글이 공식으로 제공하는 방법인 승인 모듈 DLL로 막습니다. 1.5KB짜리 FilePathCheckerModule.dll을 실행 파일 옆에 두면 시작할 때 HKCU에 알아서 등록하므로 관리자 권한이 필요 없습니다.

C판과 Delphi판

같은 기능을 C와 Delphi로 두 번 만들었고, 옵션과 종료 코드가 같습니다. Delphi판은 기존 Delphi 프로젝트에 유닛이나 패키지로 넣어 쓰라고 둔 것이고, 고치려면 Delphi 13 상용 라이선스가 필요합니다. 고치거나 늘릴 생각이라면 무료 Visual Studio Build Tools로 빌드되는 C판(src/c/)을 쓰는 편이 낫습니다. 크기도 약 165KB로 Delphi판(약 2.3MB)보다 작습니다.

.\build.ps1 -Target C              # C only (no Delphi license needed)

미리 빌드한 파일은 릴리스에 있습니다. 실행 파일 하나와 FilePathCheckerModule.dll만 복사하면 됩니다.

알아 둘 점

한/글 설치와 라이선스

PC에 한/글(한컴오피스)이 설치되어 있어야 합니다. HWPExport는 PolyForm Noncommercial 1.0.0 라이선스라 비상업적 용도로만 쓸 수 있고, 상업적으로 쓰려면 저작권자와 따로 협의해야 합니다. 한/글 자체의 라이선스는 별개입니다.

  • Windows 10/11에서 동작합니다.
  • 승인 모듈은 한/글 프로세스와 비트 수가 같아야 합니다. 기본은 32비트(한컴오피스 2020 기준)이고, 64비트 한/글이면 .\build.ps1 -ModulePlatform Win64로 다시 빌드합니다.

소스와 자세한 설명은 GitHub 저장소에 있습니다.

함께 읽으면 좋은 글