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

# 고방유리 질감 재검토 및 마지막 작업 복원

2026-10-06

## 사용자 요청과 이번 적용 범위

지정된 대화의 마지막 완료 작업을 되돌리고, 첨부 이미지와 설명을 기준으로 고방유리의 표면 질감을 재검토한다. 사진을 올리기 전에도 모자이크 유리 패턴이 명확하게 보여야 한다는 요구를 다음 구현의 필수 완료 기준으로 삼는다.

이번 코드 변경은 마지막 작업의 실행 취소에 한정한다. 아래 표면 재설계는 검토안이며 아직 구현하지 않았다. 따라서 사진 업로드 전 패턴 가시성이 개선됐다고 보고하지 않는다.

## 복원 근거와 변경 파일

대화에서 확인한 마지막 완료 작업은 굴절된 사진 디테일을 색면에 42% 다시 섞고, 기본 셀 법선의 기울기를 1.2배로 늘린 실험이다. `../qa-glass-material/report.md`에도 두 변경이 기록되어 있다. 현재 셰이더와 해당 작업 직전의 `../qa-glass-material/baseline-mosaic.frag`를 직접 비교해 이 두 변경과 uniform 선언 외의 차이가 없음을 확인한 뒤 복원했다.

| 파일 | 복원 내용 |
| --- | --- |
| `src/shaders/mosaic.frag` | `uTransmissionDetail`, `uCellLensScale`과 관련 계산을 제거하고 작업 직전 셰이더로 복원 |
| `src/main.ts` | 해당 상수의 import와 두 uniform 연결만 제거 |
| `src/constants/glass.ts` | 마지막 작업에서 추가된 두 상수 제거. 기존 환경 반사 강도 0.12 유지 |
| `scripts/test-mosaic-continuity.mjs` | 법선 배율 추가 전의 계산과 셰이더 계약으로 복원. 연속성 판정 기준은 유지 |
| `scripts/test-glass-transmission.mjs` | 취소된 42% 혼합을 강제하던 마지막 작업의 신규 검사 제거 |

복원 직전의 위 다섯 파일은 `before-rollback/`에 보존했다. 과거 실험 보고서와 비교 이미지는 삭제하지 않고 보고서 상단에 적용 취소 상태를 표시했다. 이전 작업의 depth 보정, 어두운 색면 대표색 선택, 환경 반사, 창틀, 수동 사진 구도, UI 설정은 변경하지 않았다.

프로젝트에서 `git status`와 `git log`는 “not a git repository”로 실패했다. 따라서 commit 단위의 reset/revert를 사용하지 않았으며, 대화의 변경 기록과 로컬 백업을 근거로 해당 변경만 역적용했다.

## 첨부 자료를 바탕으로 한 판단

원하는 결과는 사진 앞에 고방유리판이 놓여 있는 모습이다. 첨부 이미지의 사각 패턴은 작은 칸의 경사면과 가장자리에 생기는 밝고 어두운 변화가 반복되어 읽힌다. 사진의 색면과 별개로 그 표면이 인식되는지가 우선 평가 대상이다.

사진의 depth는 유리 뒤 장면의 앞뒤 배치를 담당하고, 유리 표면의 height/normal은 유리 자체의 요철을 담당하도록 구분해야 한다. 이 구분은 사용자가 첨부한 설명의 설계 근거이며, 이번 작업에서 AI 모델이나 depth 경로를 교체할 이유는 없다.

### 현재 코드에서 확인한 원인

1. **빈 화면의 투과 대상이 단색이다.** `src/main.ts`의 `emptyTex`는 1×1 단색 텍스처이며 `scene.background`도 단색이다. 같은 색을 굴절해 읽는 위치만 바꾸면 유리의 사각 패턴을 강하게 드러내기 어렵다. 렌더링 루프는 사진을 올리기 전에도 Final을 그리므로, 유리가 아예 렌더링되지 않는 문제로 단정해서는 안 된다.
2. **기본 셀은 완만한 사인 기울기다.** `evaluateCell()`의 기본 Mosaic 법선은 사인 함수 기반이다. 현재 반사는 같은 법선을 사용하지만 공통 직사각 광원과 부드러운 환경 그라데이션으로 구성되어 있다. 첨부 이미지의 평탄한 면과 좁은 가장자리 변화가 충분히 표현되는지는 별도 시각 검증이 필요하다.
3. **기존 환경 반사 비중이 작다.** 초기 설정에서 환경 반사 가중치는 `0.12 × 0.3 × (0.35 + 0.65 × fresnel) × surfaceReflectionWeight`다. 표면이 정면을 향하는 곳의 Fresnel을 약 0.04로 놓으면 외곽 감쇠 전에도 약 0.0135다. 이 값은 코드상 합성 계수이며 화면 밝기 변화율이나 가시성을 측정한 값은 아니다.
4. **42% 혼합은 사진 쪽 변화였다.** 취소한 혼합은 굴절 샘플의 세부 정보를 다시 보여준다. 사진이 없는 상태의 표면 요철과 반사 환경을 새로 구성하는 변경은 아니었다. 셀 기울기만 1.2배로 늘리는 것도 사용자가 지적한 질감을 직접 해결했다고 볼 수 없다.

## 다음 구현안

기존 2-pass 구조와 공통 장면 좌표를 유지하면서 유리 재질을 독립적으로 검증하는 방향을 권한다.

- **유리 표면:** 사각 셀의 비교적 평탄한 중심, 좁은 경사면, 연속적인 경계를 정의한 반복 height에서 법선을 만든다. 동일 법선을 굴절과 반사에 공유하고, 격자는 유리 좌표에 고정한다. 사진이나 시점에 따라 셀별로 임의의 다른 장면을 배정하지 않는다.
- **사진 전 화면:** 사용자 사진 대신 명암이 있는 중립 배경을 유리 뒤에 배치하고, 공통의 정적인 반사 환경을 제공한다. 배경에는 유리 격자를 직접 그리지 않는다. 유리 표면을 통과하거나 반사한 결과로 패턴이 나타나야 한다. 사진을 올리면 뒤 장면만 교체하고 같은 유리 재질을 유지한다.
- **합성 순서:** 사진 색면 처리 이후에 유리 표면 반사를 합성해 표면 정보가 색면 대표색에 흡수되지 않게 한다. 현재 코드도 이 순서를 사용하므로 순서 자체를 새로 고치는 대신 실제 표면/환경 표현을 보강하는 데 집중한다. 기존 42% 사진 혼합은 다시 도입하지 않는다.
- **Depth 연동:** 평면 사진과 빈 유리에서 표면을 먼저 평가한 후, 기존 depth 보정과 연결해 유리와 피사체 간격에 따른 굴절 차이를 확인한다. 사진 확대·팬·크롭 자동 변경은 하지 않는다. 유리 곡면을 바꾸면 공통 법선과 UV 연속성도 함께 다시 검증한다.

사진 없이 보이는 유리만을 위해 별도의 CSS 격자나 업로드 후 사라지는 장식 그림을 추가하는 방식은 이 검토안의 목표를 충족하지 않는다.

## 다음 구현의 완료 기준

| 조건 | 확인할 결과 |
| --- | --- |
| 사진 미업로드, 기본 설정 | 사각 셀의 경사면과 반사가 정지 화면에서도 분명하게 구별됨 |
| 같은 설정에서 사진 업로드 전후 | 같은 유리판의 패턴이 유지되고 뒤 장면만 바뀜 |
| 드래그 | 격자는 유리 좌표에 남고 내부 굴절과 반사가 시점에 반응함 |
| 광택 0 | 투과 대상에 명암이 있을 때 곡면에 의한 굴절이 남음. 완전 단색 배경에서 강한 격자 가시성을 보장하는 기준으로 사용하지 않음 |
| Glass OFF / Final | 먼저 지정 샘플의 깊이 시차를 확인하고, Final에서 같은 장면과 구도를 유지함 |
| 모바일 폭 390px / 데스크톱 | 동일 재질과 설정으로 표시되며 가로 넘침과 셰이더 실행 오류가 없음 |

## 실행한 검증과 남은 검증

- 복원된 Mosaic 셰이더가 마지막 작업 전 백업과 일치함을 Node assertion으로 확인했다.
- 기존 `scripts/test-*.mjs` 9개를 실행해 전부 통과했다. 카메라/history, depth 증거·굴절, Mosaic 연속성·거리, 어두운 색면 표본·축 분할, 표면 반사, 창틀 범위 검사다. 이들은 소스/수학/형상 검사이며 GPU 시각 품질 검증을 대신하지 않는다.
- `npm.cmd run build`에서 TypeScript 단계는 통과했으나 Vite 단계가 `EPERM: operation not permitted, realpath 'D:\project\behind_glass\src\style.css'`로 실패했다. 진단 결과 일반 읽기와 JS realpath는 가능하지만 `fs.realpathSync.native`는 main.ts, style.css, mosaic.frag 모두에서 EPERM을 반환했다.
- 샌드박스 밖 빌드를 요청했으나 자동 승인 검토가 사용량 한도로 완료되지 않아 명령은 실행되지 않았다. 안전하지 않다는 판정이 아니며, 승인 검토를 우회하지 않았다.
- 로컬 5174 미리보기는 접속에 실패했다. 이번 작업에서 브라우저/GPU 실행, 사진 전후 화면 비교, 실제 모바일 성능을 검증하지 않았다. 빌드 재검증과 실화면 검증이 남아 있다.

승인 검토가 가능한 환경에서 프로젝트 루트의 `npm.cmd run build`로 빌드를 다시 확인하고, `npm.cmd run dev -- --host 127.0.0.1 --port 5174`로 로컬 미리보기를 실행할 수 있다. 다음 구현안의 화면 개선은 아직 적용되지 않았다.