thesis-3d 한글 라벨 — 의도와 현실의 괴리 분석
초록
이번 세션에서 구현한 CSS2DRenderer 기반 한글 라벨이 '이상하게' 보이는 원인을 수치로 분석한다. 좌표 밀도·라벨 누락·오프셋 불일치·overlay 정렬 4가지 구체적 버그를 기록하고 수정 방향을 제시한다.
의도했던 장면
thesis-3d를 열면 각 노드 바로 위에 한글 이름이 항상 떠있는 장면을 원했다.
세계모델 강화학습 로봇조작
● ● ●
CSS2DRenderer는 그 수단이었다 — WebGL 캔버스 위에 투명 HTML 레이어를 얹어 <div>를 3D 좌표에 고정하는 Three.js 확장 렌더러.
실제 결과: "너무 이상하게 나오는데"
사령관 피드백. 원인을 수치로 분석한다.
버그 1 — 키워드 뷰 좌표 밀도 과다
hb5u가 반환하는 키워드 노드 좌표 범위:
x: -2.12 ~ 0.69 (폭 2.82 단위)
y: -0.53 ~ 1.56 (폭 2.09 단위)
z: -1.77 ~ 0.51 (폭 2.28 단위)
카메라는 z=20, FOV=60. 이 때 1 3D단위 = 83px.
105개 노드가 2.82 × 2.09 × 2.28 공간에 몰려있으면: - 평균 노드 간격: 0.60 단위 = 50px - 라벨 font-size: 11px
50px 격자에 11px 글자 105개 → 완전 겹침. 보이는 게 글자 더미다.
수정: 카메라 거리를 7~8로 당기거나, 노드 수 임계값 초과 시 라벨 미표시.
버그 2 — 한글 매핑 누락 노드 72개
키워드 뷰 105개 노드 중 72개(69%)가 한글 라벨 없음. 이유:
id=eros label=eros ← 순수 영어 ID, 한글 매핑 없음
id=vla label=vla
id=roops label=roops
id=thesis-3d label=thesis-3d
id=css2d-renderer label=css2drenderer(css2d-renderer) ← 이상한 형식
/api/tags/labels는 한글(영어) 형식 태그에서 생성된 매핑만 갖고 있다. 순수 영어로만 제출된 개념은 한글 이름이 없다.
마지막 줄의 css2drenderer(css2d-renderer)는 더 심각하다. 한글(영어) 자리에 한글 대신 css2drenderer(영어)가 들어간 태그 → label 필드에 원형 그대로 노출.
수정: 한글 라벨 없는 노드는 영어 슬러그 표시(현행) 대신 라벨 숨기기 또는 별도 스타일 처리.
버그 3 — y 오프셋 뷰별 불일치
addLabel(mesh, text)에서 라벨 위치:
obj.position.set(0, 0.6, 0); // 노드 위 0.6 단위
| 뷰 | 좌표 범위 | 노드 반지름 | 0.6단위(px) | 적정 오프셋 |
|---|---|---|---|---|
| 키워드 | ±1.5 | 0.3 | 50px | 너무 큼 |
| 시냅스 | ±75 | 0.25~0.8 | 50px | 노드 크기와 무관 |
두 뷰의 좌표 스케일이 25배 차이나는데 같은 오프셋을 쓴다.
수정: obj.position.set(0, r * 1.5, 0) — 노드 반지름 r에 비례한 오프셋.
버그 4 — CSS2DRenderer overlay 정렬
labelRenderer.domElement.style.position = "absolute";
labelRenderer.domElement.style.top = "0";
labelRenderer.domElement.style.left = "0";
document.body.appendChild(labelRenderer.domElement);
<body>에 position: absolute로 붙이면 body가 position: static일 때 뷰포트 기준이 아닌 문서 기준 좌표가 된다. <canvas>는 100vw × 100vh로 body를 채우지만 CSS2D overlay는 스크롤 오프셋이 있을 때 밀린다.
또한 #ui 버튼들이 z-index: 10인데 labelRenderer element에는 z-index 없음 → 라벨이 버튼 위로 올라올 수 있다.
수정:
body { position: relative; } /* 또는 */
labelRenderer.domElement.style.zIndex = "1";
canvas.parentElement.style.position = "relative";
canvas.parentElement.appendChild(labelRenderer.domElement);
요약표
| 버그 | 증상 | 근본 원인 | 수정 난이도 |
|---|---|---|---|
| 밀도 과다 | 글자 더미 | 좌표 범위 2.8, 노드 105개 | 중 (카메라 조정 or 임계값) |
| 한글 매핑 누락 | 영어 슬러그 노출 | /api/tags/labels 미등록 | 하 (숨기기 처리) |
| y 오프셋 불일치 | 라벨 위치 이상 | 뷰별 스케일 25배 차이 무시 | 하 (r 비례 오프셋) |
| overlay 정렬 | 라벨 위치 어긋남 | body position 미설정 | 하 (CSS 1줄) |
Moojoco에게
이 분석이 다음 개선의 출발점이다. 데이터 API(/api/thesis-3d/synapses, /api/thesis-3d/layout)는 한글 라벨 포함 상태로 준비되어 있다. 위 4개 버그를 수정하면 의도했던 장면에 도달할 수 있다.
CSS2DRenderer 뼈대는 살아있다 — 렌더링 파이프라인은 작동한다. 밀도·오프셋·정렬만 잡으면 된다.