bio-viz-film · 생물 3D 강의 영상 (v2)은(는) 무엇을 하나요?
목표: 교수가 봐도 지적할 게 없고, 학생이 한 번에 이해하며, 화면이 상업적 수준. 정확성이 아름다움보다 우선합니다. 데이터나 과정을 조작하지 않습니다.
목차
template/site2/ ← 현재 엔진 (v2)
index.html 강의 레이아웃 (독창적: 어두운 학술 스타일, 세리프 제목, 오른쪽 경로 탐색)
engine.js 렌더러, 카메라, 타임라인, 후처리(피사계 심도 + 글로우), 강의 오버레이
lib.js 시드 랜덤, 인스턴스 생성, 동적 풀, 베이크 AO
scene-*.js 프로그램 방식 장면, export build(scene, seed) → { anchors, update(t,T), palette }
story-*.js 스토리 스크립트: 단계, 샷, 자막, 과정 시간 창, 범례, 출처
vendor/ three r170 + addons (postprocessing / environments 등)
template/site/ ← v1 구 엔진 (계기판 스타일, 세포/바이러스; 알려진 과학적 문제는 references/pitfalls.md 참조, 권장하지 않음)
template/tools/ record.mjs 프레임별 녹화 · sheet2.py 샘플 타일 · probe.mjs 레이 프로브 · hidetest.mjs 객체별 숨김
references/ accuracy-protocol.md (필독) · techniques.md · new-scene.md · science-checklist.md · pitfalls.md
examples/ secretion: 인민교육출판사 필수 1권 3.2 단원 '분비 단백질의 합성과 수송' 완전한 예시 + 5차 검토 기록
출력 형태 (레이아웃 선택 가능)
?layout= | 효과 | 적합한 용도 |
|---|---|---|
clean | 순수 3D 화면, 웹 또는 텍스트 없음 | 2차 편집, 더빙, 배경용 |
lecture (기본값) | 어두운 학술 버전: 단계 번호 + 세리프 제목 + 교과서 원문, 오른쪽 경로 탐색, 범례, 하단 출처 | 강의 영상, 게시용 |
notes | 밝은 강의 노트 버전: 왼쪽 3D 둥근 프레임, 오른쪽에 모든 단계 나열 (현재 단계 원문 펼침), 범례, 실험 데이터, 출처 | 교안, 수업 프로젝터 |
dashboard | 추적 계기판: 오른쪽 패널에 표시된 분자의 각 구획별 개수 실시간 표시 (모델 자체 카운트, 실험값 아님 명시) | 연구 발표, '과정' 시연 |
bench | 밝은 실험대 웹 페이지 (인기 계기판 스타일 대응): 상단 바 (시야, 단계, 모델 시계) + 진실성 있는 런닝 텍스트 + 프레임 있는 3D 창 (라벨은 십자선으로 3D 구조에 고정, 실시간 축척 막대) + 모델 카운트 막대 + 단계 막대 + 세 개의 작은 카드 (대표값 곡선 / 모델 카운트 곡선 / 교과서 도해). 세로 1080×1350 최적 | 트위터, 샤오홍슈 게시용 웹 버전 |
| 사용자 정의 | layouts/에 <이름>.js 생성, meta / css / html / mount / update 내보내기, ?layout=<이름> 호출 | 주제 또는 요구 사항에 맞춤 |
- story에
layout: 'notes'를 쓰면 기본 레이아웃을 설정할 수 있습니다.--size 1080x1920으로 세로 버전 출력 시 각 레이아웃은 자동으로 세로 배치로 전환됩니다. - 새 레이아웃 규칙:
- 화면의 모든 숫자는 진실해야 합니다 (출처 또는 모델 상태 기반).
- 참조 영상을 그대로 따라 하지 말고, 주제에 맞게 새로 디자인하세요.
- 3D 본체는
meta.camShift를 사용하여 텍스트 영역을 확보하세요.
쇼릴 모드 (Showreel) — 트래픽, 감동을 원할 때 사용
강의 버전과 동일한 과학적 내용을 사용하며, '표시 방법'만 변경합니다. 프롬프트에 직접 말하거나 매개변수를 사용할 수 있습니다:
| 사용자가 말할 수 있는 것 | 매개변수 | 선택 가능 값 |
|---|---|---|
| "쇼릴/놀라운 버전/세로 짧은 동영상 만들어 줘" | ?story=<주제>-reel (강의 story를 0.42배 시간 압축, 원샷 원테이크) | — |
| "스타일을 밝게/네온/학술/종이 스타일로" | look= | vivid 밝은 캔디 · neon 어두운 배경 네온 발광 · academic 어두운 학술 · paper 종이 |
| "색상을 캔디/아이스블루/선셋으로 변경" | palette= | textbook · candy · ice · sunset · neon |
| "스캔 색상 전환 효과 원해" | fx=channels | 각 새 단계에 도달할 때 픽셀 스캔 밴드로 다음 '가색 채널'로 전환 (형광 현미경 채널 전환 유사) |
| "큰 제목 / 틱톡 스타일" | layout=reel | 각 단계마다 큰 글씨 후크, 가색 채널 라벨 및 간단한 면책 조항 추가 |
| "세로 버전" | --size 1080x1920 | 세로 버전에서 카메라가 자동으로 1.7배 멀어짐 (portraitZoom) |
규칙:
- 가색은 색상만 변경하고 구조와 과정은 변경하지 않습니다. 화면에는 '색상은 가색'임을 항상 표시해야 합니다.
- 쇼릴 버전도 과학적 검토를 거쳐야 합니다.
녹화:
node tools/record.mjs site2 out/x_clean.mp4 --size 1920x1080 --dpr 2 --scale 1920x1080 --query "story=secretion&layout=clean"
node tools/record.mjs site2 out/x_lecture.mp4 --size 1920x1080 --dpr 2 --scale 1920x1080 --query "story=secretion"
--draft (1배, 30fps, 약 1/8 시간)로 미리보기 파일을 생성하여 사용자 확인 후 본편을 녹화합니다. 레코더는 잠금을 사용하여 두 프로세스가 동시에 동일한 파일에 쓰는 것을 방지합니다. 먼저 *.partial.mp4를 쓰고, 완료 후 이름을 변경합니다. 마지막으로 자동으로 프레임별 디코딩 검증을 수행하고 오류가 있으면 보고합니다.
--dpr 2 --scale 1920x1080의 의미: 먼저 2배 해상도로 렌더링한 다음 1080p로 축소, 이는 슈퍼샘플링 안티앨리어싱에 해당합니다. 4K 완성본을 원하면 --scale을 생략합니다.
프로세스 (각 단계는 건너뛸 수 없음)
1. 사실표 (화면보다 먼저) — references/accuracy-protocol.md에 따라 실행
- 교과서 주제: 먼저 교과서 원문을 찾아 자막의 기본 구조로 사용합니다. 자막은 교과서 수준의 결론만 작성하고, 대학 수준의 세부 사항은 사실표 비고에 넣습니다.
- 논문 주제: 초록과 그림 설명에서 논점을 추출하고, 각 샷은 해당 Figure에 대응하며, 출처를 표시합니다 (예: Fig.2b).
- 산출물:
review/사실표.md, 형식: 단계 | 자막 원문 | 근거(교과서 절/DOI) | 상태(확인됨/대기 중). 대기 중인 내용은 화면에 표시할 수 없습니다. - 동시에 금지 화면 목록을 작성하여 이 주제의 일반적인 오류를 나열합니다 (예: "리보솜이 소포체 내강으로 들어감", "단백질이 세포질에서 맨몸으로 떠다님").
2. 1차 독립 검토 (사실표 + 장면 디자인): 하위 에이전트를 시작하여 사실표, 스토리 스크립트, 장면 설명만 제공하고 항목별로 오류를 찾도록 요청합니다.
3. 장면 및 스토리 작성: references/new-scene.md 참조.
- 모든 과정은 t의 순수 함수로 작성합니다 (예:
update(t, T)). 시간 창은 story의T에 통합합니다. - 추적되는 분자는 발광 재질로 표시하고, 다른 분자는 어두운 재질로 표시합니다. 화면의 '표시' 의미는 실험과 일치해야 합니다.
- 크기는 상대적 순서만 유지하고 화면에 '실제 비율 아님'을 명시합니다. 시간 압축도 명시합니다.
4. 샘플 자체 점검: --stills를 사용하여 각 단계의 중간 프레임을 생성하고 타일로 조합하여 확인: 주요 이벤트가 화면 중앙에 있는지, 잘 보이는지, 구조에 간섭이나 구멍이 없는지 확인합니다.
- 의심스러운 어두운 블록이나 구멍이 발견되면
probe.mjs(레이 프로브)와hidetest.mjs(개별 객체 숨김)를 사용하여 추측하지 말고 위치를 파악합니다.
5. 2차 독립 검토 (완성 샘플): 하위 에이전트가 '세포 생물학 교수 + 과학 다큐멘터리 아트 디렉터' 역할을 수행하여 샘플, 자막, 과정 코드를 검토하고 반드시 수정해야 할 목록과 '교육에 직접 사용 가능한지'에 대한 결론을 제공합니다.
- 모든 '오류' 및 '오해의 소지가 있는' 수준의 문제가 수정된 경우에만 영상을 출력할 수 있습니다.
6. 영상 출력 및 전달:
- 전달물: 순수 화면 버전 + 강의 버전 두 개의 mp4 파일, 사실표 및 2차 검토 기록.
- 게시 시 중문 및 영문 카피를 첨부합니다. BGM을 혼합하지 않습니다.
웹 버전 (bench) 주요 사항
- story에
layout: 'bench'를 쓰고brand / title / sub / notes(런닝 텍스트, 반드시 출처가 있는 사실) / clock(필름 초 → 생리적 밀리초) / conv(각 단계가 강조하는 신호)를 제공하며, 각 단계에chip / badge / call(라벨: 앵커, 제목, 부제목, 요점)을 씁니다. - 페이지의 숫자는 세 가지 출처만 허용되며 카드 모서리에 표시해야 함:
MODEL(장면 인구 조사 카운트),TYPICAL(교과서 대표값),TEXTBOOK. 축척 막대와 시야는 카메라에서 실시간 계산됩니다. LIVE / 실시간 현미경 등 실제 데이터로 오인될 수 있는 표현을 쓰지 마십시오. - 모델 시계는 자막 및 곡선과 일치해야 합니다. 느리게 재생되는 배율은 실제 범위를 쓰십시오 (비선형이면 비선형이라고 쓰십시오).
근접 '슬라이스 모드' 와 막 두께
STORY.slab(t): 두 번째 전역 클리핑 평면 (z ≥ 값만 유지), 근접 시 장면을 약 50–100 nm 두께의 슬라이스로 절단하여 전자 현미경 절편처럼 깨끗하게 만듭니다.- 막은
shell()을 사용하여 두께가 있는 닫힌 이중층 (바깥쪽은 바깥 방향, 안쪽은 안쪽 방향, 5 nm)으로 만들고, 재질은capify이며 절단면은 단색 띠로 표시됩니다. 주요 이벤트 (융합공, 엔도사이토틱 피트)는 절단면에 배치하고 카메라는 거의 정면 위에 가까워서 Ω 윤곽을 볼 수 있습니다. - 원거리에서 분자/이온은 카메라 거리에 따라 확대 표시됩니다 (
__camDist). 페이지 하단에 '원거리 분자 확대'라고 표시합니다.
두 가지 영상 출력 경로 (자세한 내용은 references/two-routes.md 참조)
- 빠른 경로: three.js 실시간 렌더링 (N8AO 앰비언트 오클루전 추가), 49초 분량 영상 약 15분에 완성, 반복 및 일상적인 영상 출력에 사용.
- 전문 경로:
export_blender.mjs장면 내보내기 →blender_build.pyBlender에서 재구성, Cycles 패스 트레이싱 렌더링 →record.mjs --overlay-dir웹 인터페이스 레이어 생성 후 중첩. 로컬에서 약 17–20초/프레임, 최종 릴리스 버전에 사용. - 동시에 하나의 Blender 작업만 실행 가능, 두 개는 메모리 부족으로 즉시 충돌합니다.
분자 수준 '비즈 스타일' (단순화하지 않음: 실제 구조 사용)
tools/pdb2beads.py <PDB> site2/mol/<PDB>.json [--opm] [--group 체인]: 실제 원자 구조를 비즈 모델로 변환합니다. 막 단백질은--opm을 추가하여 OPM 데이터베이스의 막 내 방향을 사용합니다.- 장면 최상위
await fetch('./mol/*.json'),beadGeo()로 지오메트리 생성. 절단면 위의 비즈는 전체를 버리고 반쪽 껍질을 남기지 않습니다. - 배치 시 비즈 수준 충돌 감지를 수행하여 0 관통을 보장합니다.
node tools/check.mjs site2 "story=..."로 재확인합니다. - 카운트는 화학량론적으로 일관되어야 함 (예: 1 O₂는 PSII가 4포톤 흡수, PSI가 4포톤 흡수, 4전자 전달, 틸라코이드 내강으로 12 H⁺ 유입, 2 NADPH 생성, 약 2.6 ATP 생성에 해당). 모식적인 연속 애니메이션은 별도로 ILLUSTRATIVE라고 표시해야 합니다.
형태 원칙 (단순화하지 않음)
- 세포 소기관은 전자 현미경 실제 형태와 비율에 따라 모델링하고 규칙적인 기하학적 형태로 그리지 않습니다. 크기는 먼저 표를 찾아 (
references/morphology-acinar.md의 방식) 참조한 다음 코드를 작성합니다. - 세 가지 크기 차수 (세포 15 μm → 리보솜 25 nm)에 걸쳐 구조를 축소하지 않고 카메라가 연속적으로 줌인하도록 합니다 (로그 거리 보간). 분자 이벤트는 근접 샷에서 봅니다.
- 닫힌 구조 (과립, 미토콘드리아, 농축 소포, 핵)가 절단될 때 단면을 표시 (
capify), 빈 껍질을 남기지 않습니다.
레이아웃 원칙
- 레이아웃은 주제에 따라 독창적으로 디자인하고 참조 영상을 따라 하지 않습니다.
- 기본 스타일은 어두운 학술 스타일: 세리프 제목, 본문은 교과서 원문, 하나의 강조 색상 (추적 물질 색상과 동일) 사용.
- 화면에 나타나는 모든 숫자는 출처가 있어야 합니다. 가짜 계기판, 가짜 카운트, 가짜 곡선을 사용하지 않습니다.
- 인용 및 면책 조항은 하단에 항상 표시: 모식적 애니메이션 · 실제 비율 아님 · 시간 압축됨 · 출처.
완료된 예시
thylakoid: 엽록체 → 그라나 → 틸라코이드 막의 광반응, 9가지 실제 단백질 구조 (PSII-LHCII, b₆f, PSI, ATP 합성 효소, LHCII, PC, Fd, FNR, Rubisco), 영문 bench 웹 버전story=thylakoid-en, 빠른 경로와 전문 경로 모두 영상 출력 완료.synapse: 해마 글루타메이트성 시냅스 (축삭 비즈 → 버섯 모양 수지상 가시), 실제 비율 1 단위 = 20 nm, 활동 전위 → Ca²⁺ 유입 → 단일 소포 완전 붕괴 융합 → ~4,000 글루타메이트 확산 → AMPA 개방, Na⁺ 유입 → 별 아교 세포 흡수 → 클라트린 매개 엔도사이토시스 및 재장전. 영문 bench 웹 버전story=synapse-en, 약 50초. 사실표 및 검토는examples/synapse/참조.secretion: 기니피그 췌장 선포 세포, 분비 단백질이 유리 리보솜에서 세포 외 유출까지의 전 과정, 약 75초, 총 9단계, ³H-류신 실험 타임라인 포함 (3/17/117분, 교과서 데이터).