관련 이슈

Refs #975
Related #976

요약

이 PR은 #975의 원래 문제였던 PageBackground/BorderFill 이미지가 fill mode를 무시하고 페이지 전체로 stretch 렌더링되는 문제를 수정합니다.

작업 중 추가로 확인된 effect=RealPic, brightness=-50, contrast=70 색상 워터마크 preset도 함께 정합했습니다. 이 preset은 #976 계열의 effect != RealPic JPEG grayscale/baked watermark와 다르게, 한컴 뷰어에서 색상을 보존한 밝은 워터마크 톤으로 보입니다.

따라서 변경 범위는 아래 두 축으로 분리됩니다.

1. PageBackground/BorderFill 이미지의 ImageFillMode 정합
2. RealPic 색상 워터마크 preset의 한컴 뷰어 톤 정합

왜 변경했나

#975 재현 샘플의 BorderFill image는 dump 기준으로 mode=Center를 보존하고 있었습니다.

border_fill[2] fill_type=Image image(bin_id=3, mode=Center, brightness=-50, contrast=70, effect=0)

하지만 SVG/Web Canvas의 PageBackground 경로가 ImageFillMode를 사용하지 않고 항상 bbox 전체 렌더링을 해서, 원본 512x512 워터마크가 페이지 전체로 늘어났습니다.

또한 effect=RealPic, brightness=-50, contrast=70인 색상 이미지 워터마크는 한컴 뷰어가 단순 brightness/contrast CSS filter나 #976 JPEG baked watermark와 다른 톤으로 처리합니다. 이 PR은 해당 preset을 별도 감지해 SVG와 Web Canvas가 같은 픽셀 변환 결과를 쓰도록 맞춥니다.

변경 내용

1. PageBackground 이미지 fill mode 정합

• PageBackgroundImage에 brightness, contrast, effect를 보존하도록 확장
• style resolver / layout / render tree 경로에서 BorderFill ImageFill의 tone 속성을 누락 없이 전달
• SVG PageBackground 렌더링을 render_page_background_image() helper로 분리
• PageBackground 이미지도 일반 ImageNode와 같은 fill mode 의미를 사용
  • FitToSize | None: 대상 bbox 전체 렌더링
  • Center 등 위치 모드: 원본 이미지 픽셀 크기 기준 배치
  • tile 계열: 기존 tiled image helper 재사용
• Web Canvas PageBackground 경로도 draw_image_with_fill_mode()를 재사용
• PageBackground non-RealPic watermark opacity 조건을 ImageNode와 같은 tone 속성 기반으로 정합

2. RealPic 색상 워터마크 preset 정합

• effect=RealPic, brightness=-50, contrast=70 조합을 색상 워터마크 tone preset으로 판정
• 기존 brightness/contrast 필터 및 #976의 non-RealPic JPEG baked watermark 경로와 분리
• SVG와 Web Canvas가 같은 image_resolver 기반 PNG bake helper를 사용하도록 정리
• 브라우저별 SVG/CSS filter 정밀도 차이를 줄이기 위해 decode 가능한 이미지는 tone 변환을 PNG 픽셀에 직접 bake
• PageBackground와 셀/도형 배경 ImageFill을 분리해 opacity/tone을 적용
  • PageBackground RealPic watermark: page용 opacity/tone
  • 셀/도형 배경 RealPic watermark: fill용 opacity/tone
• Web Canvas 셀/도형 배경 ImageFill 경로도 fill용 RealPic helper/opacity를 직접 사용하도록 정합
• bake 실패 시에만 기존 SVG/CSS filter fallback 사용

현재 적용 값은 파일명 분기가 아니라 동일 RealPic 색상 워터마크 preset 전체에 대한 공통값입니다.

REAL_PICTURE_WATERMARK_PAGE_OPACITY = 0.26
REAL_PICTURE_WATERMARK_FILL_OPACITY = 0.15

saturation = 0.91646104
contrast   = 0.93125103
brightness = 1.80

matrix = [
  [0.9897169325,  0.1297721480, -0.0666075849],
  [0.0236280401,  1.0778421442, -0.0471323620],
  [0.0002888270, -0.0075596780,  1.0728328592],
]
bias = [-0.0504989415, -0.0462952328, -0.0573305296]

chroma_gain = 3.0
white_blend = 0.0

fill_chroma_gain = 0.42
fill_white_blend = 0.16

LEGACY_IMAGE_WATERMARK_OPACITY = 0.17

3. SVG 경로 정합

메인테이너 피드백에 맞춰 SVG 경로도 같이 정리했습니다.

• RealPic tone bake helper를 src/renderer/image_resolver.rs로 이동/통합
• SVG PageBackground도 RealPic tone-baked PNG를 사용
• SVG 셀/도형 배경 ImageFill도 RealPic fill tone-baked PNG를 사용
• SVG의 non-RealPic JPEG watermark baked path와 RealPic color watermark path를 분리
• PCX white area transparency 처리를 image resolver 쪽으로 통합해 Canvas/SVG 차이를 줄임
• SVG PageBackground helper도 PCX → PNG 변환을 사용해 흰색 투명 처리를 일관 적용
• SVG PageBackground non-RealPic watermark도 brightness/contrast 기반 legacy opacity를 적용
• SVG 단위 테스트에 PageBackground fill mode, RealPic page watermark, RealPic fill watermark 케이스 추가

메인테이너 피드백 반영 상태

#1019 (comment) 기준으로 아래 항목을 반영했습니다.

• 최신 devel 기준 rebase (upstream/devel@5a1c645a)
• RealPic watermark helper를 svg.rs가 아니라 image_resolver.rs로 이동/통합
• SVG PageBackground 경로에 watermark effect/opacity/tone bake 적용
• SVG 배경 ImageFill 경로에 fill watermark effect/opacity/tone bake 적용
• SVG white area transparency 처리 경로 정리 (ImageNode + PageBackground PCX)
• 새 fixture를 samples/에 추가해 복학원서(Task #938: 복학원서 JPEG 워터마크 배경 사각형 제거 및 톤 보정 #976) + RealPic preset 발동 fixture 회귀 가드 보강

추가 fixture는 아래 파일로 samples/에 포함했습니다.

• samples/복학원서.hwp — Task #938: 복학원서 JPEG 워터마크 배경 사각형 제거 및 톤 보정 #976/복학원서.hwp s0:pi=0 의 BehindText 그림 컨트롤 출력 누락 #514/복학원서 워터마크 투명 배경이 사각 영역으로 렌더링됨 #938 PCX + non-RealPic JPEG baked watermark 경로
• samples/143E433F503322BD33.hwp — PageBackground 이미지 fill_mode(Center 등)가 전체 페이지 늘림으로 렌더링됨 #975 PageBackground RealPic preset 경로
• samples/253E164F57A1BC6934-empty.hwp — 추가 RealPic preset 2쪽 fixture

범위 제외

• 파일명 기반 분기는 넣지 않았습니다.
• 한컴 내부의 공식 워터마크 색 변환 알고리즘을 확정한 것은 아닙니다. 현재 값은 RealPic 색상 워터마크 샘플과 macOS 한컴 뷰어 watermark-only 캡처 기준의 근사값입니다.
• effect != RealPic 워터마크 및 #976의 JPEG baked watermark 경로는 유지하되, 이번 RealPic 색상 워터마크 경로와 분리했습니다.
• 253E164F57A1BC6934.hwp export 중 보이는 table overflow 경고는 기존 레이아웃 overflow이며, 워터마크 색상/배치 보정 범위가 아닙니다.

테스트

최신 devel rebase 후 재확인:

• cargo fmt --all -- --check
• cargo test --lib renderer::svg::tests
• cargo test --test issue_1019 --test issue_514 --test issue_938 --test issue_1156_rowbreak_fragment_fit
• cargo check --target wasm32-unknown-unknown --lib
• git diff --check

최신 rebase 직전 같은 PR 브랜치에서 확인:

• cargo test --lib realpic_watermark --offline
• cargo test --test svg_snapshot --offline
• cargo test --lib --offline
• cargo check --target wasm32-unknown-unknown --lib --offline
• docker-compose --env-file .env.docker run --rm wasm

통과한 주요 결과:

• cargo test --lib renderer::svg::tests: 31 passed
• cargo test --test issue_1019 --test issue_514 --test issue_938 --test issue_1156_rowbreak_fragment_fit: 11 passed
• cargo check --target wasm32-unknown-unknown --lib: passed
• cargo test --lib realpic_watermark --offline: 2 passed
• cargo test --test svg_snapshot --offline: 8 passed
• cargo test --lib --offline: 1312 passed; 0 failed; 2 ignored
• WASM build: pkg/rhwp_bg.wasm 갱신 완료

시각 검증

143E433F503322BD33.hwp

Before (upstream/devel)	After (this PR)	한컴 뷰어 Mac

253E164F57A1BC6934-empty.hwp

Page	Before (upstream/devel)	After (this PR)	한컴 뷰어 Mac
1
2

문서

• mydocs/plans/task_m100_975.md
• mydocs/plans/task_m100_975_impl.md
• mydocs/working/task_m100_975_stage1.md
• mydocs/working/task_m100_975_stage3.md
• mydocs/working/task_m100_975_stage4.md
• mydocs/report/task_m100_975_report.md