---
name: hwpx-picture
description: HWPX 문서 내 그림 객체 교체, 증명사진/서명 배치 및 패키지 무결성 준수에 사용.
---

# HWPX 그림 객체 교체 및 무결성 스킬

이 스킬은 HWPX 문서 내의 이미지 및 그림 객체(증명사진, 자필 서명, 직인, 도장 등)를 식별하고, 플레이스홀더 영역에 새로운 이미지를 안전하게 교체·삽입하는 전용 도메인 스킬입니다.
최상위 메타 라우터(`hwpx-document`)로부터 그림 객체 교체 및 무결성 관리 작업을 위임받아 실행합니다.

## 1. 도구 선택

현재 연결된 도구가 지원하는 그림 연산을 확인하여 사용합니다. 지침 읽기·파일 확인 같은 읽기 전용 작업은 가능합니다. 지원되지 않는 이미지 작업은 그 항목만 설명하고, 독립적으로 가능한 요청까지 중단하지 않습니다. 직접 XML 변경으로 도구 검사를 우회하지 않습니다.

## 2. 플레이스홀더 Geometry 보존 원칙 (Geometry Preservation)

기존 서식에 마련된 사진 또는 서명 플레이스홀더를 신규 이미지 자산으로 교체(`replace_picture_asset`)할 때, 원본 문서의 기하학적 속성을 100% 보존해야 합니다:

- **너비 및 높이 (Dimensions)**: 원본 플레이스홀더 프레임의 가로/세로 규격을 그대로 유지합니다.
- **배치 위치 (Placement & Coordinates)**: 표 셀 또는 문단 내 상대적·절대적 위치 좌표(오프셋)를 변형하지 않습니다.
- **본문 배치 모드 (Text Wrapping)**: 본문과의 배치 방식(어울림, 자리차지, 글 뒤, 글 앞 등)을 원본 서식과 동일하게 보존합니다.
- **여백 및 외곽선 (Margins & Borders)**: 상하좌우 여백과 테두리 선 스타일을 원본 그대로 유지합니다.
- **비율 유지 (Aspect Ratio Fit)**: 입력 이미지의 가로세로 비율이 플레이스홀더 규격과 일치하지 않는 경우, 찌그러짐(왜곡) 없이 중앙 정렬 및 비율 맞춤(Fit/Center)으로 안착시킵니다.

## 3. 패키지 무결성 준수 (Package & Manifest Synchronization)

HWPX는 개방형 ZIP 기반 패키지 규격으로, 그림 자산의 처리는 패키지 내부의 완벽한 상호 동기화를 필요로 합니다:

- **`BinData/` 디렉터리 동기화**:
  - 실제 이미지 바이너리는 패키지 내 `BinData/` 디렉터리에 고유한 식별자 및 유효한 확장자(예: `image1.png`, `image2.jpg`)로 저장됩니다.
- **`Contents/content.hpf` 매니페스트 동기화**:
  - 패키지 내 모든 자산은 `content.hpf`의 `<manifest>` 섹션에 정확한 미디어 타입(MIME)과 파일 경로로 등록되어야 합니다.
  - 지원 포맷: PNG (`image/png`), JPEG (`image/jpeg`) 등 표준 래스터 이미지 포맷.
- **본문 XML (`Contents/section0.xml`) 참조 무결성**:
  - 본문 내 그림 요소(`<hp:pic>`)의 바이너리 참조 식별자(`binDataID`)가 `content.hpf` 및 `BinData/` 파일과 1:1로 정확히 일치해야 합니다.
- **고아/누락 자산 원천 방지**:
  - 고아 자산(Orphaned Asset): 바이너리가 `BinData/`에 존재하지만 매니페스트에 등록되지 않은 경우.
  - 누락 참조(Dangling Reference): XML에서 바이너리를 참조하지만 실제 `BinData/`에 파일이 누락되어 조판 엔진 크래시를 유발하는 경우.
  - FastMCP 무결성 검증 엔진은 이러한 고아 및 누락 참조를 엄격히 감지하여 차단합니다.

## 4. 작업 파이프라인 연계 요령

1. `analyze_document`를 통해 대상 서식의 사진/서명 플레이스홀더 유무 및 위치를 식별합니다.
2. 교체할 이미지 파일의 경로, 해상도 및 포맷 유효성을 확인합니다.
3. geometry 보존 규칙을 준수하여 편집 계획(`create_edit_plan`)에 자산 교체 작업을 통합 수립합니다.
4. 사용자 승인 후 `approve_edit_plan` -> `apply_edit_plan`을 통해 안전하게 패키지에 반영합니다.
5. 적용 후 `hwpx-verification`으로 전환하여 렌더링 및 Vision 검토를 거쳐 이미지가 왜곡 없이 올바르게 배치되었는지 시각 확인합니다.