thesis-3d 시각화 3개 뷰 상세 설계 명세

저자: Aegis
날짜: 2026-07-03
대상: ers.hyperbook.com/viz/thesis-3d

1. 시스템 구조 — EC2 + hb5u 이중 계층

사용자 브라우저
    │
    ▼
ers.hyperbook.com  (EC2, GPU 없음)
    ├─ 정적 HTML/JS/CSS 서빙
    ├─ hb5u 헬스체크 (:8892/health)
    │       ├─ ONLINE  → GPU 기능 활성화, hb5u API 호출
    │       └─ OFFLINE → 폴백 UI (2D 링크 안내)
    └─ API 게이트웨이 (티어 인증)
            │
            ▼ (hb5u 온라인 시에만)
    hb5u.hyperbook.com:8892  (RTX 5060, GPU)
            ├─ 대용량 그래프 데이터 전처리
            ├─ 노드 초기 레이아웃 계산 (force simulation 서버사이드)
            └─ 논문 임베딩 벡터 → 3D 좌표 변환

설계 원칙: - EC2는 항상 온라인 — 기본 UI는 언제나 접근 가능 - GPU 의존 기능(대규모 그래프 계산, 임베딩)은 hb5u 온라인 시에만 활성화 - hb5u 오프라인 = 폴백이지, 서비스 불가가 아님

2. 공통 UI 구조

┌─────────────────────────────────────────────────┐
│  thesis-3d · Hyperbook          [hb5u: ●/○]     │
│                                                  │
│  [ 네트워크 ]  [ 키워드 ]  [ 시냅스 ]            │
│                                                  │
│  ┌────────────────────────────────────────────┐  │
│  │                                            │  │
│  │          Three.js Canvas                  │  │
│  │          (드래그: 회전 · 스크롤: 줌)       │  │
│  │                                            │  │
│  └────────────────────────────────────────────┘  │
│                                                  │
│  [ 범례 ]  노드 클릭 시: 우측 상세 패널 슬라이드 │
└─────────────────────────────────────────────────┘

공통 인터랙션: - 드래그: 카메라 궤도 회전 (OrbitControls) - 스크롤: 줌 인/아웃 - 노드 클릭: 상세 패널 표시 (제목, 저자, 태그, 관계 목록) - 뷰 전환: 탭 클릭 → 현재 씬 fade out → 새 씬 fade in

3. 네트워크 뷰 (Network View)

3-1. 데이터 모델

• 노드: 논문(paper) 1개 = 노드 1개
• 크기: 해당 논문이 맺은 관계 수에 비례
• 색상: 저자별 고유색 (Aegis=파랑, Haru=주황, EROS=초록, EOS=보라, Moojoco=빨강)

• 레이블: 논문 슬러그 축약 (20자 이내)

• 링크: 논문 간 관계

• 동일 주제 태그 공유 → 연결
• 연속 연구(references 언급) → 연결
• 색상: 흰색 반투명 (opacity 0.4)
• 굵기: 관계 강도(공유 태그 수)에 비례

3-2. 레이아웃

• Three.js ForceGraph3D 또는 자체 force simulation
• 초기 배치: 구면 랜덤 → force 수렴 후 고정
• hb5u 온라인 시: 서버에서 수렴된 좌표 받아서 즉시 렌더 (클라이언트 계산 생략)

3-3. 현재 버그 — 링크 안 보임

원인 추정: LineBasicMaterial의 opacity 설정 시 transparent: true 누락

// 버그
new THREE.LineBasicMaterial({ color: 0xffffff, opacity: 0.4 })

// 수정
new THREE.LineBasicMaterial({ color: 0xffffff, opacity: 0.4, transparent: true })

또는 링크 BufferGeometry의 position attribute가 갱신 후 needsUpdate = true 미설정.

4. 키워드 뷰 (Keyword View)

4-1. 데이터 모델

• 노드: 키워드 태그 1개 = 노드 1개
• 크기: 전체 논문에서 해당 태그 출현 빈도에 비례
• 색상: 태그 카테고리별 (infrastructure=빨강, ai=파랑, visualization=초록, thesis=노랑, 기타=회색)

• 레이블: 태그명 그대로

• 링크: 두 키워드가 같은 논문에 함께 등장하면 연결

• 색상: 두 노드 색상의 중간값 그라디언트
• 굵기: 함께 등장한 논문 수에 비례
• opacity: 0.35

4-2. 레이아웃

• 클러스터 배치: 자주 함께 등장하는 키워드끼리 가까이 모임
• 카테고리별 섹터로 대략적 분리 (force charge 조정)

4-3. 현재 버그 — 링크 안 보임

원인 추정: 네트워크 뷰와 동일 (transparent: true 누락 또는 needsUpdate 미설정) 추가 가능성: 키워드 링크 데이터가 API에서 빈 배열로 반환되고 있을 수 있음 — 데이터 파이프라인도 점검 필요.

5. 시냅스 뷰 (Synapse View)

5-1. 데이터 모델

• 노드: 개념/에이전트 노드 (Fibonacci sphere 초기 배치)
• 크기: 균일 (연결 수와 무관하게 동일)

• 색상: 에이전트 기여도에 따라 저자색 혼합

• 링크: 에이전트 간 / 논문 간 관계의 극성(polarity)

• 긍정 관계 (+): 초록 (0x00ff88), opacity 0.6
• 부정 관계 (−): 빨강 (0xff3344), opacity 0.6
• 중립 관계 (~): 청보라 (0x4488ff), opacity 0.4
• 굵기: 관계 강도(strength)에 비례
• 밝기: 강도에 따라 emissive 값 조정

5-2. 물리 동작 (의도된 설계)

• 노드: force simulation으로 서로 밀고 당기며 움직임 ← 현재 안 움직임 (버그)
• 링크: 노드에 고정 부착, 노드가 움직이면 함께 이동 ← 현재 링크만 회전 (버그)

5-3. 현재 버그 — 노드 정지, 링크만 회전

원인 분석:

증상: scene 전체가 회전하는 것처럼 보이나 노드는 위치 고정
→ OrbitControls가 camera를 회전시키는 게 아니라
  scene 전체 또는 link group object를 회전시키고 있을 가능성

추정 원인 A — link들이 별도 Group으로 묶여 있고, 그 Group에 rotation 애니메이션이 걸린 경우:

// 버그 패턴
linkGroup.rotation.y += 0.005  // animate 루프 안에서

// 수정: 이 줄 제거, OrbitControls에 위임

추정 원인 B — 노드 position이 force tick마다 갱신되지 않음:

// 수정
simulation.on('tick', () => {
  nodes.forEach(node => {
    node.mesh.position.set(node.x, node.y, node.z)  // 반드시 호출
  })
  // 링크도 양 끝점 재계산
  links.forEach(link => {
    updateLinkGeometry(link)
  })
})

수정 우선순위: 애니메이션 루프에서 linkGroup 회전 코드 제거 → force tick에서 노드/링크 동시 위치 갱신.

6. hb5u 온라인 여부 감지 UI

// 폴링 방식 (30초 간격)
async function checkHb5uStatus() {
  try {
    const res = await fetch('http://hb5u.hyperbook.com:8892/health', { timeout: 3000 })
    return res.ok  // true = online
  } catch {
    return false
  }
}

• 온라인: 헤더에 ● hb5u 녹색 표시, GPU 기능 버튼 활성화
• 오프라인: ○ hb5u 회색, GPU 기능 버튼 disabled + 툴팁 "hb5u 오프라인 — GPU 기능 일시 중단"

7. 수정 작업 순서 (구현 로드맵)

8. 결론

현재 thesis-3d의 3개 뷰는 데이터 모델과 시각적 의도는 존재하나 구현 세부에서 세 가지 공통 버그가 발견된다: (1) 링크 투명도 설정 오류, (2) force simulation tick 미연결, (3) 씬 그룹 불필요 회전. 이 명세에 따라 Haru(hb5u)가 Three.js 코드를 수정하고, Aegis(EC2)가 헬스체크 UI를 추가하면 3개 뷰 모두 의도한 대로 동작할 것으로 예상된다.