PNCAD 실사 렌더링 설계 (design-photoreal)

• 작성: [코디] 26.10.12(월) · 근거 = 조사 R1(렌더러·훅·위험) · R2(환경맵·톤맵·그림자·AO·경로추적 실측) · R3(칼라→재질·텍스처)
• 범위: A 설계 상세 + A 작업단위. B 는 사전설계, C 는 후보 비교만. 운영 배포 없음(테스트 배포까지).
• 행번호 = C:\dev\pncad\app.html 5657행(401,680B) 기준. 편집은 문자열 앵커로 한다.

1. 목표 · 현황 (사실 5줄)

1. 목표 = 가구 3D 화면의 «실사 느낌»을 돈 0원·서버 GPU 없이 최대화. 렌더는 전부 클라이언트(사무실 PC 내장 GPU · 미니PC N100급).
2. 메인 렌더러(app.html 1130)는 톤매핑 없음(NoToneMapping)·그림자 꺼짐·환경맵 없음·AO 없음·텍스처 0개. 조명은 Hemisphere 1.15 + Directional 1.5(1149-1151). three@0.160.0(importmap 879-884).
3. 재질은 colorMat(hex,door)(1185-1190) 단색 MeshStandardMaterial roughness .85. 색은 cmHex(code)(수동 hex 또는 CM_PAL 무채색 8단 순환). 칠하는 곳 = rebuild() 1628행 m.material = colorMat(cmHex(code),door).
4. 렌더 루프(5578-5583)는 유휴에도 매 프레임 renderer.render. 썸네일은 별도 GL 컨텍스트 tRen(1880), 편집기(editor.js)도 자체 렌더러 → 메인 실사 모드가 둘에 영향 없음.
5. 헤드리스 E2E = SwiftShader 소프트웨어 WebGL2, 비보안 컨텍스트 → fps·GPU 전용 버그 검증 불가. 측정은 이 PC(Radeon 780M)만 있고 N100 은 미측정.

2. 3단계 안 비교

추천 = A 지금 → B 다음 → C 선택. - 이유1: A 는 비용 0·위험 가장 낮고(토글 OFF = 종전 룩 불변, 지연 로드) 매일 쓰는 화면 전체에 효과가 간다. B·C 의 재질·텍스처 자산도 A 에서 만든 것을 재사용한다. - 이유2: B 는 GPU 백엔드별 깨짐(D3D11)이 실측돼 사무실 PC 실기 확인이 선행돼야 하고, C 는 정확도(치수) 문제로 «참고용 연출 이미지» 용도로만 의미가 있다. 근거가 달라지면(예: 사무실 PC 가 Vulkan/GL 안정, 고객이 연출 이미지를 원함) B 를 먼저 하고 C1 은 B 결과 PNG 위에 얹는다.

3. A 상세 설계

3-1. 모듈 구조

• 새 파일 C:\dev\pncad\photo.js (ES module). 정적 import 하지 않는다 → app.html 이 첫 «실사 ON» 때만 await import('./photo.js'). 효과: ① OFF 일 때 네트워크·메모리·셰이더 비용 0 ② photo.js 가 배포에서 빠지거나 CDN 이 막혀도 화면 전체가 빈 채로 죽지 않고 catch 로 «실사 불가» 처리(jointui.js 선례의 «모듈 링크 실패 = 화면 빔» 회피).
• importmap 추가 없음. photo.js 는 기존 매핑 그대로 three · three/addons/... 를 import (동적 import 한 모듈에도 importmap 적용): js import * as THREE from 'three'; import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js'; import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js'; import { RenderPass } from 'three/addons/postprocessing/RenderPass.js'; import { GTAOPass } from 'three/addons/postprocessing/GTAOPass.js'; import { OutputPass } from 'three/addons/postprocessing/OutputPass.js';
• 전역명 충돌 금지: photo.js 안에서 Environment·Texture·Image·Option·CSS·Node·Event 등을 최상위 이름으로 쓰지 않는다. 접두 PH_/ph. app.html 쪽 신규 이름은 PH(모듈 핸들)·showReal·setReal 만.
• 공개 API: createPhoto(ctx) → { on, set(v), paint(mesh,code,door,hexFallback), afterRebuild(), shadowDirty(), dirty(), frame(), resize(w,h), info() }.
• ctx (app.html 이 넘김): { renderer, scene, camera, hemi, sun, grid, gBody, gDoor, gZone, gWall, gDim, gMark, gSel, cmHexOf(code), manualOf(code), cmOn(), WALL_MAT, lineMats:[EDGE,DIM_MAT,GAP_MAT,MARK_MAT,WALL_EDGE,...SEL_M], selMats, hiMats, rebuild, resize, dprCap }. manualOf(code) = SCENE.colorMap.on && SCENE.colorMap.map[code] 원값.

3-2. app.html 최소 삽입점 (R1 hooks 그대로)

setReal (H9):

async function setReal(v){
  try {
    if (v && !PH) PH = (await import('./photo.js')).createPhoto(ctx);
  } catch (e) { console.error('photo.js load failed', e); showReal = false; syncRealBtn(); return; }   // 화면은 종전 그대로
  showReal = v; foldSet('app.real', v);          // true 만 저장, 통째 setItem 금지
  if (PH) PH.set(v);                              // 내부에서 hiMats.clear() + 환경/그림자/픽셀비 토글 + rebuild() + ctx.resize()
}

3-3. 실사 ON/OFF 일괄 상태 (photo.js set(v))

renderer.shadowMap.enabled/type 은 첫 ON 때 한 번만 true / PCFSoftShadowMap 으로 세팅하고 그대로 둔다(그림자 광원이 없으면 셰이더에 그림자 코드가 안 들어감 → OFF 비용 0). 그때 cmMats·WALL_MAT 등 기존 캐시 재질에 needsUpdate=true 1회. 이후 ON/OFF 는 sun.castShadow 토글만(three 가 조명 해시로 프로그램 자동 재선택, 두 번째부터 컴파일 0).

3-4. 환경맵 · 톤매핑 (코드 + 수치)

const pm = new THREE.PMREMGenerator(renderer);
const room = new RoomEnvironment(renderer);          // renderer 인자 필수(없으면 강도 5 → 암흑, 있으면 900)
envTex = pm.fromScene(room, 0.04).texture;           // sigma 0.04
room.dispose(); pm.dispose();
scene.background = null;                             // alpha 캔버스 유지(#view CSS 그라디언트가 배경)
renderer.toneMapping = THREE.ACESFilmicToneMapping;  // r160 에 Neutral 없음. AgX(=6)는 대안
renderer.toneMappingExposure = 1.15;

• r160 에는 scene.environmentIntensity 없음 → 재질별 envMapIntensity (finMats 0.45, 벽 0.2).
• 합격 수치(R2 육안): sun 2.2 · envMapIntensity 0.45 · hemi 0.12. 노출 0.9 에서 #F2F2F2 가 200~222 로 탁해짐 → 1.15 시작, U5 에서 «흰 부재 평균 픽셀이 OFF 의 85% 이상» 이 되게 1.1~1.3 안에서 조정. 안 되면 AgX.
• composer 경로에서는 톤매핑·sRGB 변환이 마지막 OutputPass 가 renderer.toneMapping 을 읽어 적용한다. 즉 renderer 에 설정 + OutputPass 가 마지막.
• useLegacyLights 건드리지 않는다(deprecated 경고). 조명 단위는 이미 물리 단위.

3-5. 그림자 · 바닥 접촉그림자

const SUN_DIR = new THREE.Vector3(2000,3200,2600).normalize();   // 종전 sun 방향 유지
function fitShadow(){
  const b = new THREE.Box3().setFromObject(gBody);
  if (b.isEmpty()) { sun.castShadow = false; return; }
  const s = b.getBoundingSphere(new THREE.Sphere()), R = Math.max(s.radius, 500), C = s.center;   // mm
  sun.position.copy(C).addScaledVector(SUN_DIR, R*1.5);
  sun.target.position.copy(C); sun.target.updateMatrixWorld();
  const c = sun.shadow.camera;
  c.left=-R; c.right=R; c.top=R; c.bottom=-R; c.near=R*0.4; c.far=R*2.6; c.updateProjectionMatrix();  // 변경 후 필수
  sun.castShadow = true;
  floor.position.set(C.x, 1, C.z); const f = Math.max(9000, R*6); floor.scale.set(f,1,f);
  renderer.shadowMap.needsUpdate = true; dirty();
}
// 초기화 1회
sun.shadow.mapSize.set(tier.shadow, tier.shadow);      // high 2048 / low 1024
sun.shadow.bias = -0.0002; sun.shadow.normalBias = 1.5; // mm 단위
renderer.shadowMap.autoUpdate = false;                  // 정지 장면: 리빌드·이동 때만 needsUpdate
// 바닥 접촉그림자: gBody/gDoor/gZone 밖, scene 직속 새 그룹
const g = new THREE.PlaneGeometry(1,1); g.rotateX(-Math.PI/2);
const floor = new THREE.Mesh(g, new THREE.ShadowMaterial({ opacity: 0.28 }));
floor.receiveShadow = true; floor.raycast = () => {};   // 픽킹·cursorPoint 에 안 걸림
const gFloor = new THREE.Group(); gFloor.name = 'gFloor'; gFloor.add(floor); scene.add(gFloor);

• PCFSoftShadowMap 은 shadow.radius 무시(고정 커널). 부드럽기 조절 필요 시 PCFShadowMap + radius. VSM 은 쓰지 않음.
• 부재: paint() 안에서 비도어만 castShadow = receiveShadow = true. 도어(투명 .82)·존 박스·벽·선은 false(castShadow 가 알파를 무시해 불투명 그림자가 생김).
• 그림자 메모리: 2048² ≈16MB, 1024² ≈4MB(추정).
• 10m 규모 전체 장면은 미실측 → U5 에서 live_scene_33 으로 acne/뜬그림자 육안 확인, bias 조정.

3-6. AO (GTAOPass) · 합성 · 안티앨리어싱

const rt = new THREE.WebGLRenderTarget(cssW, cssH, { type: THREE.HalfFloatType, samples: tier.msaa });  // MSAA 는 RT 에만
composer = new EffectComposer(renderer, rt);
composer.setPixelRatio(renderer.getPixelRatio()); composer.setSize(cssW, cssH);   // CSS 크기 기준(이중 스케일 방지)
composer.addPass(new RenderPass(scene, camera));
gtao = new GTAOPass(scene, camera, cssW, cssH); composer.addPass(gtao);
composer.addPass(new OutputPass());                       // 톤매핑+sRGB 는 여기서
gtao.updateGtaoMaterial({ radius: 200, distanceExponent: 1.5, thickness: 250, scale: 1.4,
                          samples: tier.aoSamples, distanceFallOff: 1, screenSpaceRadius: false });
gtao.updatePdMaterial({ lumaPhi: 10, depthPhi: 2, normalPhi: 3, radius: 6, rings: 2, samples: tier.pdSamples });

• 단위 함정: radius/thickness 는 mm. 기본값(thickness 1)이면 AO 가 전 화소 순백(에러 없음). 위 값은 R2 에서 동작 확인.
• G-버퍼 패스가 투명·오버레이를 불투명으로 그려 AO 를 더럽힘 → 패치(R2 코드 + 그룹 단위 숨김): js const _ov = gtao.overrideVisibility.bind(gtao); gtao.overrideVisibility = function(){ _ov(); // 전 객체 visible 을 캐시에 저장한 뒤 [gZone, gWall, gDim, gMark, gSel, gFloor].forEach(g => g.visible = false); this.scene.traverse(o => { const m = o.material; if (o.isMesh && (o.isLineSegments2 || (m && m.transparent))) o.visible = false; }); // 도어 포함 }; // restoreVisibility 가 캐시로 복구 (Raycaster 용 gZone 은 패스 동안만 숨기고 복구 — 규칙 «gZone visible 유지» 준수.)
• 한계 수용: 벽 평면이 투명이라 AO 에서 빠져 «벽-장 접합부» 벽 쪽은 안 어두워짐. 접촉그림자 + 장 내부 AO 로 충분.
• 안티앨리어싱: renderer antialias:true 는 composer RT 에 효과 없음 → 위 samples MSAA(high 4 / low 2). HalfFloat+MSAA 는 EXT_color_buffer_float 필요 — 없거나 composer 생성 실패 시 직접 렌더 폴백(try/catch → mode='direct': renderer.render + 선 재질 toneMapped:false 로 색 보호).
• 알파: alpha:true 캔버스 + RGBA HalfFloat → 코너 픽셀 rgba 0,0,0,0 유지(R2 검증).
• 선택 오버레이 분리: gSel(주황 선·점)이 RT 안에서 그려지면 OutputPass 의 ACES 를 한 번 더 맞아 변색 → 합성 패스에서는 gSel.visible=false, 합성 후 오버레이 패스: js gSel.visible = selVis; const vis = scene.children.map(o => o.visible); scene.children.forEach(o => { if (o !== gSel && !o.isLight) o.visible = false; }); renderer.autoClear = false; renderer.render(scene, camera); renderer.autoClear = true; scene.children.forEach((o,i) => o.visible = vis[i]); SEL_M 은 H4 로 toneMapped:false(화면 직접 렌더라 색공간 변환은 종전과 동일), SEL_DOT 은 청크가 없어 sRGB 그대로. gDim/gMark/엣지 선은 깊이 가림을 지켜야 해서 합성 패스에 두고 ACES 영향(약한 명암·채도 변화)은 수용 — U5 육안 확인, 거슬리면 선 색을 ON 때만 보정.

3-7. 유휴 비용 0 · 조작 중 경량화 (photo.frame())

function frame(){
  const now = performance.now();
  if (camKeyChanged()) { lastMove = now; need = true; }          // 카메라 위치·회전·fov·aspect·near/far 지문. Shift+휠 직접 회전도 잡힘
  const settled = now - lastMove >= 150;
  if (!need && !(settled && !aoDone) && now - lastRender < 250) return;   // 하트비트 4fps: 누락된 dirty 소스도 250ms 내 자가치유
  gtao.enabled = settled && tier.ao;  aoDone = settled;           // 조작 중 AO off, 멈추고 150ms 뒤 1프레임 AO
  renderComposerAndOverlay();  need = false; lastRender = now; stats.composerFrames++;
}

• 정지 시 렌더 4fps 이하(종전 60fps 상시 대비 대폭 절감). 명시 dirty 소스: rebuild·resize·토글·드래그·선택·텍스처 로드 완료.
• 티어: pickTier(gl) — UNMASKED_RENDERER 가 SwiftShader|Intel.*(UHD|HD Graphics)|Basic Render 면 low(shadow 1024 · pr 1.0 · AO 샘플 8 · MSAA 2), 아니면 high(2048 · 1.5 · 16 · 4). ?realq=low|high URL 파라미터로 강제(E2E 용).
• 측정(780M, 900×560): composer ≈1.4~1.9ms, +GTAO ≈4~6ms. 1080p 는 ×4.1. N100 은 미측정(10배+ 추정) → low 티어에서 AO 는 «정지 1프레임»만.
• photo.info() 는 frameMsAvg(최근 60프레임 평균)를 노출 → 실기에서 PC2 로 읽어 측정.

3-8. 재질 · 텍스처 (코드 조각은 4장 데이터와 연결)

• 캐시 키 변경: colorMat/cmMats 는 불변. 실사 재질은 별도 finMats Map(photo.js 내부), 키 = `${archetype||'-'}|${hex}|${rough}|${door?1:0}`. 같은 색인데 아키타입/광택이 다르면 별 재질. OFF 로 돌아가면 cmMats 그대로 쓰므로 종전 룩 보장.
• 부재 UV(BoxGeometry 면별 0~1 → 부재 크기에 늘어남) 해결 — paint() 에서 지오메트리에 mm 비례 UV 를 굽는다(R2 검증 코드): js const FACE_UV_AXES = [[2,1],[2,1],[0,2],[0,2],[0,1],[0,1]]; // 축 0=x폭 1=y높이 2=z깊이 (px,nx,py,ny,pz,nz) function bakeWoodUV(geo, dims, grainAxis, tile, offU, offV){ const uv = geo.attributes.uv; for (let f=0; f<6; f++){ const [au,av] = FACE_UV_AXES[f]; for (let i=0; i<4; i++){ const k=f*4+i, u=uv.getX(k), v=uv.getY(k); let U,V; if (grainAxis === av) { U = v*dims[av]/tile[0]; V = u*dims[au]/tile[1]; } // 결 축이 v → 90° 회전 else { U = u*dims[au]/tile[0]; V = v*dims[av]/tile[1]; } uv.setXY(k, U+offU, V+offV); } } uv.needsUpdate = true; geo.userData.baked = true; return geo; } dims = geo.parameters(width,height,depth) 또는 boundingBox 크기, grainAxis = 가장 긴 변. offU/offV = 부재 위치 해시(반복 무늬 방지, 재빌드해도 안정). ExtrudeGeometry(라운드) 는 UV 가 이미 mm → 전체를 1/tile 로 스케일만. miterMesh 도 Box 로 취급(꼭짓점 이동분 UV 오차는 수용).
• 결 방향이 세로인 이미지(oak_veneer_01·walnut_veneer)는 텍스처 객체에 center.set(.5,.5); rotation=Math.PI/2 를 줘서 «U 축 = 결»로 통일.
• 텍스처: colorSpace=SRGBColorSpace, RepeatWrapping, 밉맵, anisotropy=min(4, max). 로드는 TextureLoader(상대경로 tex/…), 아키타입당 1회 캐시. 로드 전·실패 시 아키타입 hex 단색, 성공 시 material.map=tex; color.set(0xffffff); needsUpdate=true; dirty().
• 재질 종류: MeshStandardMaterial{ color, map, roughness, metalness:0, envMapIntensity:.45 }. 도어: 텍스처 끄고 lighten(hex,.12) 단색, transparent:true, opacity:.82, depthWrite:false, castShadow false.
• 텍스처는 메인 GL 컨텍스트에만 올라감(≤7장, 1K 밉 포함 ≈5.6MB/장). tRen·편집기와 무관.
• hiMat() 은 base.clone() 시점 스냅샷이라 토글 시 hiMats.clear() + rebuild() 로 낡은 클론 제거.

3-9. R1 risks 전부 대응

4. 재질 매핑

4-1. 아키타입 12종 (R3)

4-2. data/finish-map.json 스키마 (C:\dev\pncad\data\finish-map.json)

{
  "v": 1,
  "archetypes": {
    "oak":   { "label": "오크", "kind": "wood",  "hex": "#A27F58", "tex": "oak_veneer_01_1k.jpg", "tileMm": 1830, "grain": "v", "rough": 0.55 },
    "white": { "label": "화이트", "kind": "solid", "hex": "#F2F2F2", "tex": null, "rough": 0.6 }
  },
  "exact": {
    "N501":    { "a": "oak",      "hex": "#AB9B72", "src": "colorchip" },
    "N505":    { "a": "dark_wood","hex": "#33261F", "src": "colorchip" },
    "N781":    { "a": "walnut",   "hex": "#806755", "src": "colorchip" },
    "N209":    { "a": "gray",     "hex": "#6A6C6B", "src": "colorchip" },
    "N228":    { "a": "white",    "hex": "#F7F9F6", "src": "colorchip" },
    "N239":    { "a": "ivory",    "hex": "#A4A291", "src": "colorchip" },
    "N420":    { "a": "gray",     "hex": "#D5D6D0", "src": "colorchip" },
    "N421":    { "a": "white",    "hex": "#DDDED2", "src": "colorchip" },
    "N445":    { "a": "charcoal", "hex": "#5B5751", "src": "colorchip" },
    "N448":    { "a": "gray",     "hex": "#C4C3B9", "src": "colorchip" },
    "효산N401": { "a": "concrete", "hex": "#828380", "src": "colorchip" }
  },
  "rules": [
    { "re": "블랙오크|다크오크|SMOKE", "a": "dark_wood" },
    { "re": "그레이\\s*우드|GREY\\s*OAK|애쉬\\s*그레이", "a": "grey_wood" },
    { "re": "라이트오크|WHITE\\s*OAK|메이플|MAPLE|\\bASH\\b", "a": "light_oak" },
    { "re": "월넛|WALNUT|다크브라운|^BR\\d", "a": "walnut" },
    { "re": "오크|OAK|티크|TEAK|체리|훈증", "a": "oak" },
    { "re": "콘크리트|CONCRETE|시멘트", "a": "concrete" },
    { "re": "대리석|MARBLE", "a": "marble" },
    { "re": "차콜|CHARCOAL|진그레이|다크그레이|다크니켈|다크실버|^CH\\d", "a": "charcoal" },
    { "re": "블랙|BLACK|^BL\\d", "a": "black" },
    { "re": "그레이|GRAY|GREY|PLATINUM|실버|니켈|^GY\\d", "a": "gray" },
    { "re": "아이보리|IVORY|크림|베이지|^IV\\d", "a": "ivory" },
    { "re": "화이트|WHITE|CHALK|백색|^WH\\d", "a": "white" }
  ],
  "rough": [
    { "re": "HG|유광|GLOSS", "r": 0.18 },
    { "re": "반광", "r": 0.4 },
    { "re": "무광|MATT|MT\\b|M$", "r": 0.7 }
  ],
  "fallback": null
}

• 모든 re 는 iu 플래그. 규칙은 위에서 아래 첫 일치(나무·구체 규칙이 색상어보다 먼저: «WHITE OAK» 가 white 로 새는 것 방지).
• 조회 순서: 키 정규화(trim · 대문자 · 공백 접기) → exact 에서 ① 전체 ② \s*\(.*\)$ 꼬리 제거(N239(SC)→N239) ③ / 앞 첫 칼라 → 없으면 rules 를 같은 3키 순으로 → 없으면 null.
• null = 미판별 → 종전 cmHex(code) 색(CM_PAL 순환)으로 단색 PBR. 근거 없는 목재결을 붙이지 않는다(마스터 869코드 중 이름으로 판별 가능한 건 ≈16%, 페페 26.10.9 «마감재별 색 구분» 요구 유지).
• 1단계 제외: @chip 규칙(N2xx·S###=SOLID 인데 색 불명 → 미판별), 상위 사용 코드 수동 지정(예: HS0868GP) — 근거 없는 추정 매핑 금지, 후속(8장).
• rough 규칙은 판별된 모든 코드에 덮어쓰기(아키타입 rough 보다 우선).

4-3. 수동 hex 와 공존 규칙 (추천대로)

1. SCENE.colorMap.map[코드] 가 hex 문자열이면 그 단색이 이긴다(텍스처 끔, 옛 작업본 그대로). 이중 틴트 방지.
2. 수동값이 없고 finish-map 이 판별하면 아키타입 텍스처/색.
3. 판별 불가면 cmHex(code)(CM_PAL) 단색 PBR.
4. cmOnOf() 가 «색 구분 꺼짐» 상태면 finish 적용 안 함(흰색 단색 PBR). 구현자는 1175-1190·1626-1628 을 읽어 의미를 확인하고 U3 에서 확정.
5. 아키타입 수동 선택 UI({a:'oak'} 객체값, renderColorMap 4563 확장)는 이번 범위 제외 — web-designer 상담·직렬화(4676 keep·4579 cmSet·hexOk 1175) 변경이 필요해 후속. 이번엔 문자열 hex 만 존재하므로 저장 포맷 변경 없음.
6. 기본 «실사» 꺼짐 = 안전 롤아웃. 켠 사용자만 finish 적용.

4-4. 텍스처 파일 목록 (전부 CC0 · 1K · JPEG q80 재인코딩 ≈ 합 1MB)

• 노멀맵은 1단계 제외(IBL+albedo 만으로 충분, 용량 절약).
• 배포 대상은 위 7장만(--all 예비 3장은 로컬 보관, FILES 미등록).

4-5. tools/fetch_textures.py 사양 (C:\dev\pncad\tools\fetch_textures.py)

• 실행: 미니PC 에서 cd C:\dev\pncad && PYTHONUTF8=1 python tools/fetch_textures.py [--all] [--force] [--check].
• 저장 위치 = C:\dev\pncad\tex\ (정본). C:\dev\pfs\web\pncad\tex\ 로는 sync_to_pfs.py 가 복사한다 — pfs web/pncad 직접 수정 금지 규칙(정본 → sync → 배포) 때문. 서빙은 기존 라우트 /production/pncad/<asset>(default_controller.py L92, 로그인 뒤). /static/ 에는 두지 않는다(로그인 없이 열림).
• 입력 = 스크립트 내부 SOURCES 표(4-4). 의존 = 표준 라이브러리(urllib, zipfile, hashlib, json) + Pillow.
• 동작: 1. 요청마다 User-Agent: Mozilla/5.0 (pncad-fetch) (ambientCG 는 기본 UA 403). 재시도 3회, 타임아웃 30초. 2. Poly Haven: JPG 직접 다운로드. ambientCG: zip 받아 *_Color.jpg 만 추출. 3. Pillow 로 열어 최대 변 1024 유지, quality=80, optimize=True 재인코딩 → tex/<name>_1k.jpg. 4. 이미 있으면 건너뜀(--force 로 재다운로드). 5. 검증: 첫 바이트 FF D8, 크기 20~400KB, 이미지 평균색이 finish-map.json 아키타입 hex 와 채널별 ±14 이내, 7장 합계 ≤ 1.2MB. 하나라도 실패 시 종료코드 1. 6. tex/SOURCES.json 기록: {file, url, license:"CC0-1.0", author, sha256, bytes, meanHex, fetchedAt}. 7. --check = 다운로드 없이 위 5번 검증만.
• 출력: 한국어 한 줄 요약(성공 n/실패 n, 합계 KB). 로그 UTF-8(sys.stdout.reconfigure).
• sync FILES 3곳 등록은 U6: tools/sync_to_pfs.py L20-31 · tools/_deploy_hash.py L7 · tools/_verify_deploy.py L16 에 photo.js · data/finish-map.json · tex/<7장>.jpg 를 같은 순서로 추가(서브디렉터리 tex/ 복사 시 makedirs 여부는 U6 에서 확인·보강).
• 캐시: 서버가 자산에 Cache-Control: no-cache(ETag) → 로드마다 304 왕복. 이번엔 pfs 코드 변경 없이 수용(8장).

5. B 사전 설계 (경로추적 스틸) — 1쪽

• 핀(실행 검증됨, r160): three-gpu-pathtracer@0.0.17 + three-mesh-bvh@0.7.0(peer 정확히 0.7.0). 0.0.24 이상은 three>=0.180 이라 불가, 0.0.18~0.0.23 은 API 상이·미검증.
• 로드 방식: importmap 에 3줄 추가 — "three/examples/jsm/"(=기존 addons 와 병행), "three-mesh-bvh"(…@0.7.0/build/index.module.js), "three-gpu-pathtracer"(…@0.0.17/build/index.module.js). 새 모듈 pathtrace.js 를 «렌더» 버튼 클릭 때만 await import() → 평소 비용 0. 본 PNG 용 별도 WebGLRenderer({preserveDrawingBuffer:true}) 오프스크린(메인 renderer 상태와 분리).
• 씬 변환: 경로추적은 mm 원본 직투입이 미검증 → 미터 스케일 복제 씬(S=0.001)에 부재 메시만 복제(재질·텍스처 공유), 카메라 near 0.05 / far 60, DirectionalLight 3 + GradientEquirectTexture(top #fff / bottom #9a9a9a) 환경, bounces 5, environmentIntensity 0.6. 1차는 도어 제외(투명 .82 미검증).
• 흐름: ① «렌더» 클릭 → 모달(해상도 1600×1000 기본 / 2x, 목표 샘플 128·256) ② «준비 중» 표시 후 rAF 2회 대기(첫 update 의 셰이더 컴파일이 메인스레드를 막음) ③ ptRenderer.update() 를 rAF 마다 호출, 카메라 변경 없음 → 샘플 누적 진행률 표시 + «중지» ④ 목표 샘플 도달 → canvas.toBlob('image/png') 같은 태스크에서 → pncad-<작업본번호>-<YYYYMMDD-HHmm>.png 다운로드.
• D3D11 방어(실측 근거): UNMASKED_RENDERER 가 Direct3D11 이면 setDefine('FEATURE_RUSSIAN_ROULETTE',0)(컴파일 45→10초), 첫 8샘플 뒤 target 평균 휘도 > 0.98 이면 FEATURE_MIS=0 + reset() 폴백(직접광 약해지나 정상 화면). 첫 update 전에 «첫 컴파일은 10~40초 걸립니다» 안내.
• 예상 시간(780M, 선형 외삽, 미실측): Vulkan 12샘플/s@900×560 → 1600×1000 에서 ≈3.8샘플/s → 256샘플 ≈70초. D3D11+MIS off ≈16샘플/s. N100 은 10배+ 느릴 것으로 추정(분 단위) → 목표 샘플 기본 128.
• 전제 확인 순서: A 테스트 배포 후 사무실 PC 에서 chrome://gpu 로 ANGLE 백엔드 확인 → 필요 시 chrome://flags/#use-angle 안내. 서버 GPU 없음·비용 0 유지.

6. 작업단위 표 (A)

worktree: cd C:\dev\pncad && git worktree add -b photo _wt_photo HEAD → /pncad/_wt_photo/app.html 로 서빙(8799). 같은 날 다른 세션(pncad 보완·기능 제안)이 C:\dev\pncad 를 만지므로 app.html 을 건드리는 단위는 모두 worktree.

의존: U1∥U2 → U3∥U4 → U5 → U6 → U7. 합계 ≈8시간, 병렬 시 ≈5.5시간. U7 전에 pfs 쪽 push 는 테스트 배포 한정(운영 승인 게이트는 그대로).

7. E2E 계획 — C:\dev\pncad\tools\_e2e_photo.py [local|test|prod]

골격은 _e2e_3dui.py 1-60행·보조(chk·handler·boot·open_scene)·메인 블록 복사. 서버 쓰기 0(writes) 유지, Playwright try/finally br.close(). 스크린샷 → C:\dev\_work\pncad-photo-1012\*.png(접미 ''|_test|_prod). prod 는 읽기 전용이고 이번엔 실행 대상 아님(photo.js 미배포).

• 회귀: _e2e_3dui.py [local|test] all(런1~6) 기준선과 동일 PASS. vbar 7개로 바뀌는 9-1~9-4·런6 Ctrl+1~6 기대값만 갱신(U4).
• 한계(고정 기재): 헤드리스 = SwiftShader·비보안 컨텍스트라 fps/GPU 버그 검증 불가. 실기(사무실 PC·미니PC)는 PC2.real().frameMsAvg 를 «OFF · ON 정지 · ON 조작 중» 3값으로 수동 측정해 이 문서 8장 후속에 기록.
• test 실행 조건: U7 배포 후, C:\dev\.secrets\pfs_login.env 의 PFS_TEST_* 로그인(값 출력 금지), 작업본은 운영 GET 사본 C:\dev\_work\pncad-spec-1008\live_scene_33.json route.

8. 미결 · 확인 항목 (결정은 전부 «추천으로 진행»)

페페 지시 «선택은 추천대로», 운영배포는 추후 → 아래는 질문이 아니라 추천 확정 사항이다.