behind_glass/docs/qa-gobang-surface-2026-10-06/report.md

# 고방유리 표면과 투과 영상

이 문서는 첫 구현의 기록이다. 같은 날 사용자가 올린 300×300 확대 사진에 따른 후속 표면 보정과 현재 수치는 [후속 보고서](../qa-gobang-facets-2026-10-06/report.md)를 따른다.

2026-10-06 사용자 요청: 첨부 실물 고방유리처럼 반복 패턴에 맞춰 뒤쪽 사진이 굴절되는 표현을 구현한다. GPT 답변은 설명 자료로 검토했으며 유리문 상호작용 등의 추가 제안을 구현 지시로 취급하지 않았다.

## 적용

- 기본 패턴을 `고방유리 · 표면 굴절`로 바꿨다. Grid 20 / 굴곡 +1 / 광택 0.3 / Camera 0.5에서 시작한다. 주 화면의 패턴 선택에서 기존 Ref1 옵션 2(Grid 13, 색면 1)와 기존 촘촘 유리(Grid 24)로 전환할 수 있다. 사진 확대·팬은 바꾸지 않는다.
- `src/shaders/mosaic.frag`: 새로운 style 2 경로는 사각 셀의 평탄한 중심과 둥근 경사면을 반복 높이 함수로 정의한다. 셀 경계에서 높이와 첫 미분이 이어진다. 높이의 미분에서 얻은 동일 법선으로 굴절과 환경 반사를 계산한다. 별도 격자선이나 셀별 무작위 사진 크롭을 합성하지 않는다.
- 카메라 광선의 얕은 앞면 교점을 두 번 보정하고, 굴절률 1.5의 요철 앞면과 평탄한 뒷면을 거쳐 배경을 읽는다. 새 모드에는 기존의 최소 0.6 연출 광학 거리를 사용하지 않는다. 기존 visible-depth 교점 보정 함수를 재사용한다. 색면 atlas/palette/history는 새 모드에서 실행되지 않는다. 기존 Ref1/촘촘 유리의 광학 및 색면 셰이더 경로는 유지했다.
- `src/constants/glass.ts`: 높이/셀 크기 0.065, 평탄 중심 반폭 0.18셀, 굴절률 1.5, 기본 두께 0.008, 환경 반사 강도 0.65를 기록했다. 뒷면은 음의 굴곡도 수용하도록 기본 두께에 최대 셀 높이를 더해 배치한다. 실물 유리의 측정값이 아니라 장면 좌표의 초기 재질 설정이다.
- `src/main.ts`: 사진 미입력 시 넓은 명암 영역과 하나의 창 형태가 있는 중립 배경을 그린다. 배경에는 반복 격자가 없다. 업로드 전후 동일한 유리 셰이더가 사용되고 중립 배경 텍스처도 기존 teardown에서 dispose된다.
- `index.html`: 유리 패턴 선택을 주 화면으로 옮기고 현재 모드의 설명과 Grid 기본값을 맞췄다. 기존 비교 이미지와 수동 구도 조절을 유지했다.
- `src/depth/aiDepth.worker.ts`: 이미 설치된 Transformers.js 4.3의 출력 타입 `DepthEstimationOutput`을 기존 지역 타입 이름으로 import해 빌드 오류를 해결했다. 추론·정규화 알고리즘은 변경하지 않았다. 작업 전 존재한 package.json/package-lock.json 변경은 건드리지 않았다.
- 기존 axis-split 검사의 UI 기본값/선택 위치 기대값을 갱신했다. 기존 표면 반사 검사에는 Windows CRLF 정규화를 추가했다. 새 테스트 프레임워크나 의존성은 추가하지 않았다.

## 검증

검증 환경은 Windows의 Codex in-app browser다. 먼저 수작업 샘플을 Glass OFF로 확인한 후 사진과 Final 모드를 비교했다.

| 조건 | 확인 결과 |
| --- | --- |
| Glass OFF, 수작업 샘플 | 앞 표면 z 0.560, 유리 z 0.600, 간격 0.040 유지. 카메라 X 0→약 0.053에서 코 투영 X 520.448→516.916, 왼눈 493.625→490.661, 몸 453.585→451.358px로 서로 다른 시차 확인 |
| 사진 미입력 | 사각 경사면의 명암과 중립 배경의 굴절이 정지 화면에서 보임 |
| dog1, 자동 AI depth | AI 추정 완료 후 동일 사진·구도에서 고방유리와 Ref1 옵션 2 비교. 새 모드의 셀 내부 윤곽 늘어남/반복과 사각 경사면 확인 |
| dog1, Grid 13/20 | Grid 13에서 같은 크기의 기존 색면과 새 굴절을 비교. 기본 Grid 20의 더 작은 패턴도 확인 |
| 광택 0, 굴곡 +1 | 표면 반사가 사라져도 사진 윤곽의 굴절 유지 |
| 광택 0, 굴곡 0 | 반복적인 사진 변형이 사라지고 평탄 유리의 투과 영상으로 복귀 |
| 굴곡 −1 | 오목한 표면의 다른 굴절 결과 확인 |
| 드래그 | 패턴이 유리 좌표에 남고 뒤 영상과 반사가 시점에 반응함 |
| dog2, 자동 AI depth | 두 번째 사진에서도 같은 유리 재질과 AI depth 적용 성공 |
| 기존 Reeded / Frosted | 두 모드의 렌더링과 고방유리로 복귀 확인 |
| 1280×900 / 390×844 | 데스크톱·모바일 폭 출력 확인. 모바일 innerWidth 390, document.scrollWidth 375로 가로 넘침 없음 |
| 사진 구도 | dog1 AI 완료·모드 전환·모바일 크기 변경 뒤에도 확대 1 / 팬 X 0 / 팬 Y 0 |

브라우저 console error는 없었다. ANGLE 셰이더 컴파일러는 공유 depth 교점 반복의 텍스처 implicit derivative에 대한 warning을 출력했다. 이 경고와 모바일 실기기 성능 검증은 별도로 남는다.

기존 검사 9개가 통과했다: camera/history, depth evidence, depth refraction, Mosaic continuity, depth-distance, atlas dark sampling, axis split, surface reflection, window reveal coverage. 이들은 기존 비교 경로의 소스/수학/형상 검사이며 새 고방유리의 시각 품질은 위 실화면 검증으로 평가했다. Node 22에서 `.ts`를 import하는 검사는 `--experimental-strip-types`로 실행했다.

최종 TypeScript/Vite 빌드 통과: `npm.cmd run build -- --outDir test-results/gobang-build`. 최초 `npm.cmd run build`도 타입 호환 수정 후 통과했다. 기존 큰 번들 경고는 남는다. 빌드가 생성한 추적 dist 변경은 작업 전 상태로 복구하고 검증 산출물은 제거했다.

## 비교 이미지

- `empty-glass-desktop.png`: 사진 미입력
- `sample-no-glass.png`, `sample-no-glass-drag.png`: 수작업 depth의 실제 시차
- `dog1-ref1-option2-grid13.png`: 보존된 기존 옵션 2
- `dog1-gobang-grid13.png`, `dog1-gobang-grid20.png`: 새로운 표면 굴절
- `dog1-gobang-gloss0.png`, `dog1-gobang-flat-gloss0.png`: 반사와 굴절의 역할 분리
- `dog1-gobang-concave.png`, `dog1-gobang-drag.png`: 부호/시점 반응
- `dog1-gobang-mobile.png`, `dog2-gobang-grid20.png`: 모바일 폭 및 다른 사진

## 한계와 실행

사진의 depth는 상대 깊이다. 유리 형상은 첨부 스크린샷을 바탕으로 만든 절차적 근사이며 특정 제품의 실측 복원이 아니다. 앞면 교점은 얕은 높이장의 반복 근사이고, 배경 교점은 현재 시점에서 보이는 depth만 재사용한다. 가려진 영역을 복원하거나 다중 내부 반사·광학 caustics를 계산하지 않는다. 참고 사진과 완전히 동일한 재질이라는 판정, 영상 flicker 계측, 모바일 실기기 FPS 측정은 하지 않았다.

프로젝트 루트에서 `npm.cmd run dev -- --host 127.0.0.1 --port 5174`로 실행한다. 이번 작업의 로컬 미리보기는 `http://127.0.0.1:5174/`다. 사진은 브라우저 로컬에서 처리하며 외부 게시나 배포는 하지 않았다.