Communitygithub.com

bio-viz-film · Biological 3D Explainer Videos (v2)

Transform cell biology, virology, and molecular biology concepts (textbook chapters, paper figures, experimental processes) into professor-approved, commercially viable 3D explainer videos: Three.js procedural cutaway scenes + cinematic rendering (depth of field, bloom, baked AO), demonstrating real processes step-by-step (e.g., secretory protein synthesis and transport, exocytosis, viral entry). Output either pure visuals (no text) or original lecture layouts (step titles, textbook quotes, pathway navigation, legends, citations). Built-in scientific accuracy workflow: fact sheets with sources → forbidden imagery list → two rounds of independent review (science + visuals).

What is bio-viz-film · Biological 3D Explainer Videos (v2)?

This skill converts complex biology topics into high-quality 3D explainer videos using a custom Three.js engine with cinematic post-processing. It supports multiple output layouts—from pure visual feeds to academic lecture templates—and enforces a rigorous scientific accuracy protocol involving fact-checking, forbidden imagery lists, and two independent review cycles. The system can generate videos for classroom teaching, research presentations, or social media (e.g., TikTok/小红书 vertical format) with options for stylistic themes (vivid, neon, academic, paper). It includes a 'showreel' mode for visually stunning, fast-paced shorts. The engine handles molecular-level detail with real PDB structures, scales across three orders of magnitude (from cells to ribosomes), and provides tools for frame-by-frame recording, still collage checks, and ray probe debugging. It is designed for users who say 'make a cell/virus/organelle animation,' 'turn this textbook chapter into an animation,' 'create a 3D biology video for a paper/thesis/teaching,' or 'animate secretion/exocytosis/mitosis/viral entry.'

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/moluyao/bio-viz-film/tree/HEAD

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

What does bio-viz-film · Biological 3D Explainer Videos (v2) do?

Goal: So accurate that professors find no fault, so clear that students understand in one viewing, and visually polished to a commercial standard. Accuracy takes precedence over aesthetics; never fabricate data or processes.

Table of Contents

template/site2/   ← Current engine (v2)
  index.html        Lecture layout (original: dark academic style, serif titles, right-side pathway navigation)
  engine.js         Renderer, camera, timeline, post-processing (depth of field + bloom), lecture overlay
  lib.js            Seeded random, instanced geometry, dynamic pools, baked AO
  scene-*.js        Procedural scene, exports build(scene, seed) → { anchors, update(t,T), palette }
  story-*.js        Story script: steps, camera shots, subtitles, process time windows, legends, citations
  vendor/           Three r170 + addons (postprocessing / environments etc.)
template/site/    ← v1 legacy engine (dashboard style, cells/viruses; known scientific issues in references/pitfalls.md, not recommended)
template/tools/   record.mjs frame-by-frame recording · sheet2.py sample collage · probe.mjs ray probe · hidetest.mjs per-object exclusion
references/       accuracy-protocol.md (must read) · techniques.md · new-scene.md · science-checklist.md · pitfalls.md
examples/         secretion: Complete example from PEP Biology Textbook, Volume 1, Section 3.2 "Synthesis and Transport of Secretory Proteins" + five-round review records

Output Formats (Layout Options)

?layout=EffectBest for
cleanPure 3D visuals, no webpage or textRe-editing, voiceover, background footage
lecture (default)Dark academic version: step numbers + serif titles + textbook quotes, right-side pathway navigation, legends, bottom citation barExplainer videos, publication
notesLight handout version: rounded 3D frame on left, paper-like list of all steps on right (current step expanded with quote), legends, experimental data, citationsLecture slides, in-class projection
dashboardTracking dashboard: right panel shows real-time counts of labeled molecules in each compartment (from model's own counting, explicitly noted as not experimental values)Research presentations, demonstrating "process"
benchLight-themed experimental webpage (similar to popular dashboard style): top bar (field of view, step count, model clock) + scrolling true knowledge facts + framed 3D window (labels pinned with crosshairs on 3D structures, real-time scale bar) + model count bars + step bar + three small info cards (typical value curve / model count curve / textbook diagram). Vertical 1080×1350 optimalTwitter, Xiaohongshu (Little Red Book) web version
CustomCreate <name>.js in layouts/, export meta / css / html / mount / update, call with ?layout=<name>Per-topic or per-request customization
  • A story can set layout: 'notes' as its default; --size 1080x1920 outputs vertical, all layouts auto-switch to vertical arrangement.
  • New layout rules:
    • Every number on screen must be real (from sources or model state);
    • Do not copy reference videos; design layouts fresh per topic;
    • The 3D subject uses meta.camShift to make room for text areas.

Showreel Mode – For Traffic and Visual Impact

Uses the same scientific content as the lecture version, only changes "how it's presented." Can be invoked directly in prompts or via parameters:

You SayParameterOptions
"Make a showreel / stunning version / vertical short"?story=<topic>-reel (compresses lecture story to 0.42x, one continuous shot)—
"Style bright / neon / academic / paper"look=vivid bright candy · neon dark neon glow · academic dark academic · paper paper texture
"Change colors to candy / ice blue / sunset"palette=textbook · candy · ice · sunset · neon
"Use that scanning color transition"fx=channelsAt each new step, a pixel scan transitions to the next "false-color channel" (similar to fluorescence microscope channel switching)
"Large titles / TikTok style"layout=reelOne large hook sentence per step, plus false-color channel tags and short disclaimer
"Vertical"--size 1080x1920Camera automatically pulls back 1.7x for portrait mode (portraitZoom)

Rules:

  • False-color only changes colors, never structure or process; a note saying "colors are false-color" must be permanently on screen.
  • Showreel versions must also undergo scientific review.

Recording:

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 (1x, 30fps, ~1/8 time) produces a preview for client approval before full recording. The recorder locks to prevent two processes writing to the same file; writes *.partial.mp4 first, renames only upon completion; finally, automatically decodes frame by frame for validation, reporting any errors. --dpr 2 --scale 1920x1080 means: render at 2x resolution, then downscale to 1080p, effectively supersampling anti-aliasing. For 4K output, omit --scale.

Workflow (Each Step Mandatory)

1. Fact Sheet (Before Any Visuals) – Follow references/accuracy-protocol.md

  • Textbook topics: First find the original textbook sentences; use them as the subtitle backbone. Subtitles only include textbook-level conclusions; university-level details go into fact sheet notes.
  • Paper topics: Extract arguments from abstract and figure captions; each shot corresponds to a Figure, annotate with source (e.g., Fig. 2b).
  • Output: review/fact-sheet.md, organized as Step | Subtitle Original Text | Source (Textbook Section/DOI) | Status (Verified/Pending). Content marked Pending cannot be shown on screen.
  • Also write a Forbidden Imagery List, listing common errors for the topic (e.g., "ribosomes entering the ER lumen," "proteins floating naked in the cytoplasm").

2. First Independent Review (Fact Sheet + Scene Design): Spawn a sub-agent that receives only the fact sheet, story script, and scene description; ask it to find any errors line by line.

3. Write Scenes and Story – See references/new-scene.md.

  • Write every process as a pure function of t (e.g., update(t, T)); time windows are all in the story's T.
  • Tracked molecules use emissive materials; others use dark materials. The "labeling" meaning on screen must match the experiment.
  • Preserve only relative size ordering; state "not to real scale" on screen. Also state time compression.

4. Self-Check with Stills – Use --stills to output one frame per step, then collage-stitch them for review: Are key events at screen center? Are they clearly visible? Any structural intersections or holes?

  • If suspicious dark patches or holes appear, use probe.mjs (ray probe) and hidetest.mjs (hide objects one by one) to pinpoint the cause, not guess.

5. Second Independent Review (Final Still Frames) – A sub-agent acting as "Cell Biology Professor + Science Documentary Art Director" reviews the stills, subtitles, and process code, producing a required-fix list and a verdict on "suitable for direct teaching."

  • Only proceed to final rendering after all "error" and "misleading" issues are fixed.

6. Final Output and Delivery

  • Deliverables: Pure-visual version + lecture version, both as mp4, plus the fact sheet and both review records.
  • Publish with English and Chinese copy; do not mix BGM.

Web Version (bench) Essentials

  • In story, write layout: 'bench' and provide brand / title / sub / notes (scrolling ticker, must be sourced facts) / clock (film seconds → physiological milliseconds) / conv (which signal is highlighted per step). For each step, write chip / badge / call (annotation: anchor, title, subtitle, key points).
  • Numbers on the page are allowed from only three sources, indicated in card corner badges: MODEL (scene census count), TYPICAL (textbook typical values), TEXTBOOK. The scale bar and field of view are computed from the camera in real time. Never write LIVE / real-time microscopy or similar phrases that could be mistaken for real data.
  • Model clock must be consistent with subtitles and curves; state the slowdown factor in real range (if nonlinear, state nonlinear).

Close-Up "Slice Mode" and Membrane Thickness

  • STORY.slab(t): Second global clipping plane (keeps only z ≥ value); in close-up, cuts the scene into slices about 50–100 nm thick, as clean as an EM slice.
  • Membranes are built with shell() as closed double layers (outer layer facing out, inner layer facing in, 5 nm), material capify, cross-section shown as solid-colored bands; key events (fusion pore, clathrin-coated pit) are placed on the cutting plane, camera nearly top-down, so the Ω shape is visible.
  • In wide shots, molecules/ions are scaled up by camera distance (__camDist); footer states "molecules enlarged in distant view."

Two Rendering Routes (See references/two-routes.md for Details)

  • Fast Route: Three.js real-time rendering (with N8AO ambient occlusion), a 49-second clip finishes in about 15 minutes, used for iteration and daily output.
  • Professional Route: export_blender.mjs exports scene → blender_build.py rebuilds in Blender with Cycles path tracing → record.mjs --overlay-dir generates the web UI layer and composites. Locally ~17–20 seconds per frame, used for final release versions.
  • Only one Blender task can run at a time; two will exhaust memory and crash immediately.

Molecular "Bead-Style" (No Simplification: Use Real Structures)

  • tools/pdb2beads.py <PDB> site2/mol/<PDB>.json [--opm] [--group chain]: Convert real atomic structures into bead models. For membrane proteins, add --opm to use OPM database orientation.
  • Scene top-level await fetch('./mol/*.json'), generate geometry with beadGeo(). Beads above the clipping plane are discarded entirely, leaving no half-shells.
  • Collision detection at bead level ensures zero interpenetration; run node tools/check.mjs site2 "story=..." for verification.
  • Counts must be stoichiometrically self-consistent (e.g., 1 O₂ corresponds to PSII absorbing 4 photons, PSI absorbing 4 photons, transferring 4 electrons, importing 12 H⁺ into the thylakoid lumen, generating 2 NADPH, approximately 2.6 ATP). Illustrative continuous animations must be separately labeled ILLUSTRATIVE.

Morphology Principles (No Simplification)

  • Organelles are modeled from real EM morphology and proportions, not as regular geometric shapes. Look up dimensions in tables first (e.g., references/morphology-acinar.md), then code.
  • Across three orders of magnitude (cell 15 μm → ribosome 25 nm), do not scale structures; instead let the camera push in continuously (logarithmic distance interpolation), placing molecular events in close-up view.
  • Closed structures (granules, mitochondria, secretory vesicles, nucleus) show solid cross-sections (capify) when sliced, leaving no empty shells.

Layout Principles

  • Layouts are original to the topic; do not copy reference videos.
  • Default style is dark academic: serif titles, body text is original textbook sentences, with one accent color (same as tracer color).
  • Every number appearing on screen must have a source. Do not use fake dashboards, fake counts, or fake curves.
  • Citations and disclaimers are permanently in the bottom bar: Illustrative animation · Not to scale · Time compressed · Source cited.

Completed Examples

  • thylakoid: Chloroplast → grana → light reactions on thylakoid membrane, 9 real protein structures (PSII-LHCII, b₆f, PSI, ATP synthase, LHCII, PC, Fd, FNR, Rubisco), English bench webpage story=thylakoid-en, has been produced via both fast and professional routes.
  • synapse: Hippocampal glutamatergic synapse (axonal varicosities → mushroom-shaped dendritic spine), real scale 1 unit = 20 nm, action potential → Ca²⁺ influx → single vesicle complete collapse fusion → ~4,000 glutamate diffusion → AMPA opening, Na⁺ influx → astrocyte uptake → clathrin-mediated endocytosis and repriming. English bench webpage story=synapse-en, about 50 seconds. Fact sheet and review at examples/synapse/.
  • secretion: Guinea pig pancreatic acinar cells, full process of secretory protein from free ribosomes to exocytosis, about 75 seconds, 9 steps, with ³H-leucine experimental timeline (3/17/117 minutes, textbook data).

Related Skills