feat(picture): adjust a new picture's image and give it a border

[airmang]

바뀐 점

그림을 만들 때(doc.add_picture, HwpxOxmlParagraph.add_picture) 그림 효과와 테두리를 줄 수 있다. 전에는 hc:img에 늘 기본값(밝기·대비 0, 원래 그림, 불투명)을 쓰고 테두리를 쓰지 않았다.

인자	쓰는 곳	값
brightness	hc:img/@bright	-100~100 (기본 0)
contrast	hc:img/@contrast	-100~100 (기본 0)
effect	hc:img/@effect	REAL_PIC(기본)·GRAY_SCALE·BLACK_WHITE, 대소문자 무관
alpha	hc:img/@alpha	투명도 0(불투명, 기본)~255(보이지 않음)
line_color	hp:lineShape/@color	주면 실선 테두리를 hc:img 바로 뒤에 둔다(한/글이 저장하는 자리)
line_width	hp:lineShape/@width	HWPUNIT, 기본 33

한/글의 동작

• 위 범위의 값은 한/글이 그대로 저장하고 그린다. 밝기 -100은 검게, 100은 하얗게, 회색조·흑백, 투명도 128은 반쯤 비치게, 255는 보이지 않게 그린다. 테두리는 주어진 색과 굵기로 그린다.
• 범위 밖은 그대로 그리지 않는다.
  • 밝기는 끝값처럼 그린다.
  • 대비 101은 색을 뒤집어 그리고, -101은 회색으로 그린다.
  • 투명도 256은 0으로 저장한다.
  • 다른 효과 이름(PATTERN8x8 등)은 REAL_PIC으로 저장한다.
• 그래서 범위 밖의 값은 문단이나 이진 항목을 더하기 전에 거부한다.
  • 새 오류 코드 shape-picture-image-value: 밝기·대비·투명도·효과
  • 새 오류 코드 shape-picture-border-value: 테두리 굵기
  • 색은 기존 style-color-invalid

코드

• oxml/shape_position.py: PICTURE_EFFECTS, validate_picture_image, validate_picture_border.
• oxml/objects.py: _create_picture_element가 새 인자를 받는다. HwpxOxmlParagraph.add_picture의 구현을 다른 개체 함수들처럼 이 파일로 옮겼다(_paragraph_add_picture, 클래스 속성으로 붙임). paragraph.py는 1,600줄 상한에 닿아 있었다.
• _document/media.py, document.py: 문서 수준 add_picture가 같은 인자를 받고, 그림을 더하기 전에 검사한다.
• errors.py·docs/error-codes.md: 두 오류 코드.
• docs/support-matrix.md(동봉본 동기화): 그림 행에 효과·테두리 지원과 미지원(그림자 등 hp:effects, 자르기, 회전)을 적는다.
• tests/data/document_facade_surface.json: add_picture 서명 갱신. tests/data/error_census.json: 옮긴 ValueError 하나를 oxml/paragraph.py에서 oxml/objects.py로 센다.
• 변경 로그 항목을 더한다.

Refs #52

테스트

tests/test_picture_adjustments.py(새 파일):

• 기본값은 예전과 같다(효과 없음, 테두리 없음).
• 한/글 저장본 picture_adjusted_and_bordered.hwpx(밝기 20, 대비 -30, 회색조, 투명도 64, 테두리 141)와 같은 값을 쓰고, 테두리가 hc:img 바로 뒤에 온다.
• 문단 수준 add_picture도 같은 인자를 받고, 효과는 대소문자를 가리지 않는다.
• 범위 밖 12가지는 해당 코드로 거부되고, 문단과 이진 항목이 늘지 않는다.

🤖 Generated with Claude Code

[airmang]

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

확인한 것

• 인자를 주지 않은 add_picture는 고치기 전과 구역 XML이 바이트 단위로 같습니다(id 제외).
• brightness=101·alpha=256·effect="SEPIA"·잘못된 색은 문서를 바꾸기 전에 거부됩니다.
• 한/글로 열어 보면 테두리 색·굵기가 그대로 그려지고, 다시 저장해도 값이 유지됩니다.

막지 않는 것(후속으로 좋음)

1. hp:lineShape의 자리: 이 PR은 hc:img 바로 뒤에 둡니다. python-hwpx는 hc:img를 imgDim 뒤에 쓰므로(… imgRect, imgClip, inMargin, imgDim, img, lineShape, effects), 한/글 저장본 어느 형식과도 순서가 다릅니다. 한/글 저장본은 img를 앞에 두는 형식이면 img, lineShape, imgRect …, img를 imgDim 뒤에 두는 형식이면 renderingInfo, lineShape, imgRect, … imgDim, img이고, 번들 스키마(PictureType)도 lineShape를 imgRect 바로 앞에 둡니다. 한/글은 두 자리를 똑같이 읽고 같은 그림을 그리며 검증기도 둘 다 통과하지만, imgRect 바로 앞이 스키마와 같은 형식의 한/글 저장본에 맞습니다(docstring의 "as Hancom saves it"도 그에 맞게).
2. line_width는 line_color가 있을 때만 검사합니다. line_width=-1만 주면 조용히 무시됩니다. 색이 없어도 검사하면 잘못된 호출을 일찍 알 수 있습니다.