bio-viz-film · Biological 3D Explainer Videos (v2)
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= | Effect | Best for |
|---|---|---|
clean | Pure 3D visuals, no webpage or text | Re-editing, voiceover, background footage |
lecture (default) | Dark academic version: step numbers + serif titles + textbook quotes, right-side pathway navigation, legends, bottom citation bar | Explainer videos, publication |
notes | Light handout version: rounded 3D frame on left, paper-like list of all steps on right (current step expanded with quote), legends, experimental data, citations | Lecture slides, in-class projection |
dashboard | Tracking 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" |
bench | Light-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 optimal | Twitter, Xiaohongshu (Little Red Book) web version |
| Custom | Create <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 1080x1920outputs 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.camShiftto 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 Say | Parameter | Options |
|---|---|---|
| "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=channels | At each new step, a pixel scan transitions to the next "false-color channel" (similar to fluorescence microscope channel switching) |
| "Large titles / TikTok style" | layout=reel | One large hook sentence per step, plus false-color channel tags and short disclaimer |
| "Vertical" | --size 1080x1920 | Camera 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'sT. - 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) andhidetest.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 providebrand / title / sub / notes(scrolling ticker, must be sourced facts) /clock(film seconds → physiological milliseconds) /conv(which signal is highlighted per step). For each step, writechip / 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), materialcapify, 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.mjsexports scene →blender_build.pyrebuilds in Blender with Cycles path tracing →record.mjs --overlay-dirgenerates 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--opmto use OPM database orientation.- Scene top-level
await fetch('./mol/*.json'), generate geometry withbeadGeo(). 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 webpagestory=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 webpagestory=synapse-en, about 50 seconds. Fact sheet and review atexamples/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).