Communitygithub.com

bio-viz-film

將細胞生物學、病毒學、分子生物學知識點(課本章節、論文模型圖、實驗過程)製作成教授級、可商用的 3D 解說影片:Three.js 程序化剖面場景 + 電影級渲染(景深、輝光、烘焙 AO),按「步驟」演示真實過程。

bio-viz-film 是什麼?

此技能是專為開發者與 AI 代理打造的強大工具,用於將複雜的分子與細胞生物學概念轉化為高品質、科學準確的 3D 解說影片。它基於 Three.js 引擎,支援程序化場景生成、電影級後期效果(如景深和輝光)以及多種輸出格式,從純畫面影片到包含原創排版(步驟標題、課本原文、通路導航、圖例、出處)的學術風格解說,一應俱全。其核心設計哲學是「科學準確性優先於美觀」,內建嚴格的審查流程:先建立附有出處的事實表,再明令禁止不當畫面,最後經過兩輪獨立審查(科學與視覺)。此技能適用於 Claude Code、Cursor 等支援工具使用/代理的編碼環境,用戶只需描述需求(如「製作一個分泌蛋白的動畫」),AI 代理即可按照精確的步驟(事實表 → 場景設計 → 審查 → 渲染)生成可商用影片。支援快速路線(Three.js 即時渲染)與專業路線(匯出至 Blender 進行路徑追蹤渲染),以滿足迭代與最終發佈的不同需求。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/moluyao/bio-viz-film/tree/HEAD

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

bio-viz-film · 生物 3D 解說片(v2)

目標:教授看了挑不出錯,學生看了一遍就懂,畫面達到商用水準。準確性優先於好看;不編數據、不編過程。

目錄

template/site2/   ← 當前引擎(v2)
  index.html        解說版式(原創:深色學術風,襯線標題,右側通路導航)
  engine.js         渲染器、相機、時間線、後期(景深 + 輝光),解說疊層
  lib.js            種子隨機、實例化構建、動態池、烘焙 AO
  scene-*.js        程序化場景,導出 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《分泌蛋白的合成和運輸》完整示例 + 五輪審查記錄

輸出形態(版式可選)

?layout=效果適合
clean純 3D 畫面,沒有任何網頁或文字二次剪輯、配音、做背景
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. 第一輪獨立審查(事實表 + 場景設計):起一個子智能體,只給它事實表、故事腳本和場景說明,要求它逐條挑錯。

3. 寫場景與故事:見 references/new-scene.md。

  • 每個過程都寫成 t 的純函數(例如 update(t, T)),時間窗統一放在 story 的 T 裡。
  • 被追蹤的分子用發光材質表示,其他分子用暗色材質,畫面上的「標記」含義要和實驗一致。
  • 大小只保留相對順序,並在畫面上寫明「非真實比例」。時間壓縮也要寫明。

4. 樣張自檢:用 --stills 出每一步的中間幀,拼成拼圖檢查:關鍵事件在不在畫面中心、看不看得清,結構有沒有穿插或空洞。

  • 發現可疑的暗塊或空洞,用 probe.mjs(射線探針)和 hidetest.mjs(逐個隱藏物體)定位,不要靠猜。

5. 第二輪獨立審查(成片樣張):子智能體扮演「細胞生物學教授 + 科普片美術總監」,審樣張、字幕和過程代碼,給出必須改的清單和「能否直接用於教學」的結論。

  • 只有改完所有「錯誤」和「誤導」級的問題,才能出片。

6. 出片與交付:

  • 交付物:純畫面版 + 講解版兩條 mp4,加上事實表和兩輪審查記錄。
  • 發佈時附中英文文案;不混 BGM。

網頁版(bench)要點

  • story 裡寫 layout: 'bench',並提供 brand / title / sub / notes(跑馬燈,必須是有出處的事實)/ clock(膠片秒→生理毫秒)/ conv(每步高亮哪種信號),每步寫 chip / badge / call(標註:錨點、標題、副標題、要點)。
  • 頁面上的數字只允許三種來源,並在卡片角標註明:MODEL(場景 census 計數)、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 min,課本數據)。

相關技能