Doc Number: Korea JTC1/SC2 k2677_881_export_vba_chunks_to_png.py_manual.txt
Date: 2026.06.11.
Author: SHIN, SangHyun
================================================================================
KS X 1001 VBA Chunks PNG Exporter (export_vba_chunks_to_png.py) 사용 설명서
================================================================================
본 문서는 KS X 1001 표준 기호 및 코드표 엑셀 파일(KSX1001_excel.xls)로부터
페이지 조각(Chunk) 단위로 고품질 PNG 이미지를 자동 추출하는 스크립트인
`export_vba_chunks_to_png.py` 파일의 개요, 요구사항, 작동 원리 및 사용법을 설명합니다.
--------------------------------------------------------------------------------
1. 개요 (Overview)
--------------------------------------------------------------------------------
이 스크립트는 엑셀 파일 내의 여러 시트(기호표, 기호명, 한글표, 한자표, 부속서, 동형표)에
작성된 정형화된 코드 테이블을 사전에 정의된 규칙에 따라 조각(Chunk) 단위로 분할하여
PNG 이미지 파일로 저장하는 자동화 도구입니다.
단순히 화면을 캡처하는 것이 아니라, 엑셀 COM 자동화와 이미지 보정 알고리즘을 결합하여
다음과 같은 고품질 인쇄 수준의 이미지 산출물을 보장합니다.
- 표의 바깥쪽 테두리선과 PNG 이미지 테두리 간의 불필요한 겹침 제거
- 표의 끝선(하단 및 우측 선)이 잘리지 않도록 캔버스 크기 미세 패딩 적용
- 부속서 이미지들의 하단 여백 높이를 특정 기준 이미지와 동일하게 자동 통일(정규화)
--------------------------------------------------------------------------------
2. 요구 사항 및 설치 (Prerequisites & Installation)
--------------------------------------------------------------------------------
본 스크립트는 Windows 환경의 엑셀 프로그램과 연동하여 실행됩니다.
■ 필수 환경:
- OS: Windows (COM API 연동을 위해 필수)
- MS Excel: Microsoft Excel 프로그램 설치 필요
- Python: 3.x 버전
■ 필수 파이썬 라이브러리 설치:
명령 프롬프트(CMD) 또는 PowerShell에서 아래 명령어로 라이브러리를 설치합니다.
> pip install pywin32 Pillow
- pywin32: 엑셀 COM 객체 조작을 위한 win32com, pythoncom 라이브러리 제공
- Pillow (PIL): 추출된 PNG 이미지 분석 및 여백 정규화 처리를 위해 사용
--------------------------------------------------------------------------------
3. 주요 기능 및 작동 원리
--------------------------------------------------------------------------------
(1) 시트별 조각 분할 로직 (Chunk Extraction Logic)
- 기호표/기호명: 기호표 9개 파트(각 35행)와 각 파트에 종속된 기호명(50행씩, 각 파트별
지정된 페이지 수: [4, 2, 2, 2, 2, 2, 4, 4, 2] 페이지)을 번갈아가며 순서대로 추출합니다.
- 한글표: 총 9개 조각(각 35행씩, 19개 열)으로 분할 추출합니다.
- 한자표: 총 26개 조각(각 35행씩, 25개 열)으로 분할 추출합니다.
- 부속서: 사전에 지정된 15개 행 범위(annex_a_ranges)를 바탕으로 데이터가 있는 마지막
행까지만 엄격하게 잘라내어 추출합니다.
- 동형표: 총 3개 조각으로 분할하여 추출합니다. 마지막 조각은 M93:S93 영역을 병합하고
가운데 정렬하는 등의 전처리가 자동 수행됩니다.
(2) 고품질 이미지 캡처 기술
- 외곽선 임시 제거 (_strip_outer_borders_for_capture):
추출 영역의 바깥쪽 테두리 테두리선이 PNG 테두리와 만나 지저분하게 뭉개지는 것을 막기 위해,
캡처 직전에 가장자리 테두리를 지우고 캡처 완료 후 원상복구합니다 (부속서 제외).
- 더미 여백 열 삽입/너비 조작 (Spacer Column):
테이블의 좌우 경계선 안쪽 그리드가 깔끔하게 캡처되도록 데이터 오른쪽에 임시로 너비 0.13짜리
얇은 더미 열을 지정(또는 삽입)하여 캡처 범위를 확장합니다.
- 차트 패딩 적용 (Chart Padding):
Excel의 CopyPicture 복사 영역보다 가로 2pt, 세로 4pt만큼 더 여유가 있는 임시 차트 객체를 생성해
그림을 붙여넣고 내보내어, 표의 하단 및 우측 선이 잘리는 문제를 원천 차단합니다.
- 하단 여백 정규화 (_normalize_annex_bottom_margins):
부속서 이미지들의 경우, 11번째 이미지('04_부속서_011_부속서.png')의 흰색 하단 여백을
기준으로 삼아 모든 부속서 PNG 파일의 하단 여백을 픽셀 단위로 동일하게 맞춥니다.
- 자동 재시도 및 검증 (_export_range_once & export_range_to_png):
엑셀의 클립보드 오류 등으로 하얗게 비어 있는 비정상 PNG 파일(8KB 미만)이 생성되면,
최대 3회까지 클립보드 복사 및 붙여넣기를 재시도하여 실패율을 극대화하여 낮춥니다.
--------------------------------------------------------------------------------
4. 사용 방법 (Usage Guide)
--------------------------------------------------------------------------------
스크립트가 위치한 폴더에 입력 대상 엑셀 파일인 `KSX1001_excel.xls`가 존재해야 합니다.
■ 전체 시트 추출 (기본 실행)
모든 시트의 조각을 자동으로 이미지화하여 `vba_chunk_images` 폴더에 저장합니다.
> python export_vba_chunks_to_png.py
■ 디버깅 및 테스트 모드 실행
프로그램이 올바르게 실행되는지 혹은 특정 시트의 레이아웃이 잘 생성되는지 검증하기 위한 옵션입니다.
1) 기호표 테스트 추출
- 기호표의 첫 번째 조각만 샘플로 추출하여 정상 작동 여부를 테스트합니다.
> python export_vba_chunks_to_png.py --test-giho
2) 기호명/부속서 테스트 추출
- 기호명과 부속서 시트의 일부 영역을 추출하여 더미 열과 테두리가 알맞게 적용되는지 확인합니다.
> python export_vba_chunks_to_png.py --test-both
3) 동형표 테스트 추출
- 동형표 마지막 표의 특정 전처리(M93:S93 병합)가 제대로 반영되는지 확인합니다.
> python export_vba_chunks_to_png.py --test-donghyeong
--------------------------------------------------------------------------------
5. 주의 사항 및 문제 해결 (Troubleshooting)
--------------------------------------------------------------------------------
- 엑셀 경고창 대기 상태:
엑셀 파일이 열리면서 매크로 경고나 링크 업데이트 관련 알림창이 팝업되면 스크립트가 대기 상태에
빠질 수 있습니다. 가급적 스크립트 실행 전 사용 중인 다른 엑셀 작업을 정리해 두는 것을 권장합니다.
- 클립보드 충돌 오류:
스크립트는 엑셀의 클립보드(CopyPicture) 기능을 내부적으로 사용합니다. 스크립트가 실행되는 도중에는
다른 텍스트나 이미지를 복사(Ctrl+C)하지 않도록 해주시기 바랍니다. 복사 시도가 겹칠 경우 이미지에
빈 공백이 생기거나 캡처에 실패할 수 있습니다.
- 파일 및 폴더 위치:
기본적으로 `export_vba_chunks_to_png.py` 파일과 같은 디렉토리에 `KSX1001_excel.xls` 파일이
위치해야 하며, 결과물은 같은 경로 아래 `vba_chunk_images` 폴더에 생성됩니다.
================================================================================