Communitygithub.com

bio-viz-film · 생물 3D 강의 영상 (v2)

세포 생물학, 바이러스학, 분자 생물학 지식을 교수급, 상용 가능한 3D 해설 영상으로 제작합니다. Three.js 프로그래밍 방식의 단면 장면 + 영화 수준 렌더링(피사계 심도, 글로우, 베이크 AO)을 사용하여 '단계별'로 실제 과정(예: 분비 단백질 합성 및 수송, 세포 외 유출, 바이러스 침입)을 시연합니다. 순수 영상(텍스트 없음) 또는 독창적인 해설 레이아웃(단계 제목, 교과서 원문, 경로 탐색, 범례, 출처)을 출력할 수 있습니다. 과학적 정확성 절차(사실표, 금지 화면 목록, 2중 독립 검토)가 내장되어 있습니다.

bio-viz-film · 생물 3D 강의 영상 (v2)란 무엇인가요?

bio-viz-film은 세포 생물학, 바이러스학, 분자 생물학의 지식을 교수급 정확성과 상업적 수준의 영상미를 갖춘 3D 해설 영상으로 변환하는 AI 에이전트 스킬입니다. 이 스킬은 Three.js를 기반으로 한 프로그래밍 방식의 단면 장면과 영화 같은 렌더링(피사계 심도, 글로우, 베이크 AO)을 사용하여 '단계별'로 실제 생물학적 과정(예: 분비 단백질 합성 및 수송, 세포 외 유출, 바이러스 침입)을 시연합니다. 사용자는 '세포/바이러스/세포 소기관 애니메이션을 만들어 줘', '이 교과서 장을 애니메이션으로 만들어 줘', '논문/발표/교육용 생물 3D 영상', '분비 단백질/세포 외 유출/유사 분열/바이러스 침입 애니메이션' 등의 프롬프트로 작업을 요청할 수 있습니다. 출력 형태는 순수 3D 영상, 강의용(어두운 학술 스타일), 노트용, 대시보드, 벤치(소셜 미디어 친화적) 등 다양하며, 선택 가능한 스타일과 팔레트를 제공합니다. 가장 중요한 특징은 과학적 정확성을 보장하기 위한 엄격한 프로토콜입니다. 사실표 작성, 금지 화면 목록 작성, 2중 독립 검토(과학 + 화면)를 필수로 거치며, '정확성이 아름다움보다 우선'합니다. Cursor, Claude Code, Codex와 같은 AI 에이전트 도구와 함께 사용하도록 설계되었으며, 시스템은 교과서, 논문, 실험 데이터를 기반으로 사실을 검증하고, 오해의 소지가 있는 시각적 표현을 방지합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/moluyao/bio-viz-film/tree/HEAD

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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.py Blender에서 재구성, 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분, 교과서 데이터).

관련 스킬