[airmang]

바뀐 점

#448(그림자·빛남)에 이어, 그림을 만들 때 부드러운 가장자리와 반사를 줄 수 있다.

from hwpx.oxml import PictureReflection

doc.add_picture(data, "png", soft_edge=300, reflection=PictureReflection(size=0.5, distance=0))

인자	쓰는 곳	값
soft_edge	hp:effects/hp:softEdge/@radius	가장자리에서 안쪽으로 흐려지는 길이, HWPUNIT(0 이상 int)
reflection=PictureReflection(...)	hp:effects/hp:reflection	아래 표

PictureReflection 필드(기본값)	쓰는 곳	값
size(0.5)	hp:pos/@end	그림 높이 중 반사로 보일 부분, 0 초과 1 이하
distance(0)	@distance	그림 아래 틈, HWPUNIT(0 이상 int)
alpha_start(0.5), alpha_end(0.997)	hp:alpha/@start, @end	반사가 시작·끝나는 곳의 투명도(0 불투명~1 보이지 않음)
blur(50)	@radius	HWPUNIT(0 이상 int)

나머지 속성은 한/글 문서가 쓰는 값으로 고정한다.

• alignStyle="BOTTOM_LEFT", direction="90", fadeDirection="90", rotationStyle="0"
• skew 0 0, scale 1 -1, pos/@start 0

hp:effects 안의 순서는 스키마대로 그림자, 빛남, 부드러운 가장자리, 반사다.

한/글의 동작

• 위 범위의 값은 그대로 저장하고 그린다.
• 범위 밖의 값은 그대로 그리지 않는다. 그래서 문단이나 이진 항목을 더하기 전에 shape-picture-effect-value로 거부한다.
  • 음수 부드러운 가장자리는 0처럼 그린다.
  • 반사의 투명도는 범위 밖도 그대로 저장하지만 다르게 그린다.
  • 반사 크기 0은 아무것도 그리지 않는다.
• 차지하는 자리:
  • 부드러운 가장자리는 자리를 차지하지 않는다.
  • 반사는 대략 크기만큼의 그림 높이와 거리만큼 아래로 자리를 차지한다.
  • 쪽 수 추정은 반사 자리를 아직 세지 않는다(#449와 같음).

코드

• oxml/shape_position.py
  • PictureReflection을 더한다.
  • validate_picture_effects와 append_picture_effects가 soft_edge·reflection을 받는다. 기본값은 None이라 이전 호출은 그대로 동작한다.
• oxml/objects.py, _document/media.py, document.py: add_picture가 같은 인자를 받는다.
• oxml/__init__.py: PictureReflection을 내보낸다(hwpx.oxml.__all__ 136 → 137).
• errors.py·docs/error-codes.md: shape-picture-effect-value 설명에 부드러운 가장자리·반사를 더한다.
• docs/coverage-ledger.* 재생성: hp:softEdge·hp:reflection·hp:alpha를 코드가 쓴다.
• docs/support-matrix.md(동봉본), README.md·README_EN.md(알려진 제약, 예제 원장 해시), 변경 로그, tests/data/document_facade_surface.json.

테스트

tests/test_picture_adjustments.py:

• 한/글 저장본 picture_all_effects.hwpx(그림자·빛남·부드러운 가장자리 300·반사 기본값)의 hp:effects 아래 요소·속성과 같게 쓰는지 본다. 순서도 본다.
• 부드러운 가장자리 3가지·클래스가 아닌 반사 1가지와, 반사 값 8가지는 거부되고, 문단과 이진 항목이 늘지 않는다.

🤖 Generated with Claude Code

[airmang]

리뷰 결과: 막을 것은 없습니다. CI가 통과하면 병합합니다.

• 인자를 주지 않은 add_picture는 구역 XML이 고치기 전과 같습니다.
• hp:softEdge와 hp:reflection의 요소·속성 구성은 한/글에서 처음 만든 문서의 것과 같습니다. 반사의 고정 속성(BOTTOM_LEFT, 방향 90, 사라지는 방향 90, 축척 1/-1)도 그 문서와 같은 값입니다.
• 음수·실수·True 가장자리, 크기 0이나 1 초과, 범위 밖 투명도, 음수 거리·흐림, 클래스가 아닌 반사는 모두 거부되고, 거부될 때 문서에 이진 항목이 남지 않습니다.
• 커버리지 원장 변경은 새로 쓰는 세 요소의 none → api뿐입니다.
• 남은 것: 반사가 차지하는 배치 크기는 쪽 수 추정에 아직 반영되지 않습니다(PR 본문대로).