Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -77,3 +77,11 @@ data/bioagents/uncertainty/
# script's docstring for the download line).
data/depmap/
data/gdsc/

# 3D lab: raw model downloads are sorted into web/lab3d/assets/models; never commit the originals
web/lab3d/assets/downloads/
# 3D lab: the earlier block-built version, kept locally only
web/lab3d/voxel/
# 3D lab: its textures are images, which the rules above would otherwise exclude
!web/lab3d/**/*.jpg
!web/lab3d/**/*.png
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,16 @@
# CellSim — Changelog

## Unreleased — a lab you walk into

**The 3D lab** (`web/lab3d/`, on the site at `/lab3d/`): a biology lab
in first person, with Minecraft-style controls and a hotbar. Onion,
cheek and pondweed slides are prepared step by step and focused at 4×,
10× and 40×; their cells are drawn at measured sizes, not simulated.
The culture dishes are simulated: `run_dish_stream` runs in a Pyodide
worker from the wheel the Lab installs, and the drops added in the lab
set the dose (two 50 µL drops of 10 µM paclitaxel in 5.1 mL give
0.196 µM). Graphics presets from Low (older laptops, 30 fps) to Ultra.

## 1.7.0 — a CDK4/6 inhibitor, and Rb as the mechanism

**Palbociclib** (`mechanism = "cdk46"`): blocks cyclin D–CDK4/6, so Rb
Expand Down
14 changes: 14 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,19 @@
simulator in Python. Open source, Apple-silicon and Linux, no GPU
required.**

[![The 3D lab: a microscope bench and an incubator, with daylight through the windows](web/lab3d/screenshot.jpg)](https://rockman6.github.io/CellSim-3D-Multicellular-Biology-Drug-Testing-Simulator/lab3d/)

**[Walk into the lab →](https://rockman6.github.io/CellSim-3D-Multicellular-Biology-Drug-Testing-Simulator/lab3d/)**
— a biology lab you explore in first person, in your browser. Prepare
slides of onion skin, your own cheek cells or a pondweed leaf and focus
the microscope on them. Or treat living lung cancer cells with
paclitaxel, doxorubicin or cisplatin, incubate them and compare them
with an untreated dish. Those cells are simulated by this engine, on
your own machine. Use a computer with a keyboard and mouse: WASD to
walk, left-click to take, right-click to use. Graphics presets run from
older laptops to fast graphics cards. Source and controls:
[`web/lab3d/`](web/lab3d/).

**[Run an experiment in your browser →](https://rockman6.github.io/CellSim-3D-Multicellular-Biology-Drug-Testing-Simulator/lab/)**
— pick cells, a drug and a schedule, press Run. The real engine runs on
your own machine; nothing to install.
Expand Down Expand Up @@ -195,6 +208,7 @@ benchmarks/ every input needed to reproduce a number in docs/VALIDATION.md
tests/ one folder per src/ module; each file is a standalone gate
scripts/ the `cellsim` CLI dispatcher, fetchers, benchmark runners, doctor
docs/ plan, validation, docking tutorial, archive of the 2026 campaign docs
web/ the site: lab3d/ (the 3D lab), lab/ (the Lab and Inside a cell), viewer/ and demo/
OLD/ frozen 2026 C++/Metal prototype, its 6 headless validators and scripts (see OLD/README.md)
```

Expand Down
17 changes: 17 additions & 0 deletions web/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,14 @@
.demo:hover { border-color: var(--accent); }
.demo b { display: block; font-weight: 600; margin-bottom: 1px; }
.demo span { color: var(--muted); font-size: 13px; }
.hero {
display: block; margin: 24px 0 8px; border: 1px solid var(--line); border-radius: var(--radius);
background: var(--panel); text-decoration: none; color: var(--ink); overflow: hidden;
}
.hero:hover { border-color: var(--accent); }
.hero img { display: block; width: 100%; height: auto; border-bottom: 1px solid var(--line); }
.hero b { display: block; font-size: 18px; font-weight: 600; margin: 12px 14px 3px; }
.hero span { display: block; color: var(--muted); font-size: 13.5px; margin: 0 14px 14px; }
.note {
border-left: 3px solid var(--accent); padding: 2px 0 2px 12px;
color: var(--muted); font-size: 13.5px; margin: 0 0 12px;
Expand All @@ -46,6 +54,15 @@ <h1>CellSim</h1>
inside it. Run them well-mixed and a dose-response curve is one simulation; run
them on a lattice and a spheroid grows a hypoxic rim and a necrotic core.</p>

<a class="hero" href="lab3d/">
<img src="lab3d/screenshot.jpg" alt="The 3D lab: a microscope bench and an incubator, with daylight through the windows" width="1400" height="860">
<b>Walk into the lab →</b>
<span>A biology lab you explore in first person. Prepare onion, cheek and
pondweed slides and focus the microscope on them, or treat living cancer cells
with a drug, incubate them and compare them with an untreated dish. Those cells
are simulated by this engine, in your browser. Use a computer with a keyboard and
mouse; the first culture dish takes about half a minute to start the engine.</span></a>

<h2>Run an experiment in your browser</h2>
<p><a class="demo" href="lab/" style="display:block;max-width:560px">
<b>Open the Lab →</b>
Expand Down
92 changes: 92 additions & 0 deletions web/lab3d/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# CellSim Lab

A biology lab you walk into in first person. Prepare slides of onion skin, cheek cells or a pondweed leaf, then focus a microscope on them. Or grow living A549 lung cancer cells, treat them with a drug and incubate them. The living cells are simulated by the Cell Sim engine (`cellsim.cell.dish`), running in the browser.

## Run it

Browsers block 3D models and the engine on pages opened straight from a file, so serve the `web` folder:

```bash
cd "Cell Sim/web"
python3 -m http.server 8000
```

Then open <http://localhost:8000/lab3d/>.

The engine uses the wheel in `../lab/wheel/` (the same one the Lab page uses). GitHub Pages builds it on every deploy. To build it locally:

```bash
cd "Cell Sim"
python -m pip wheel --no-deps --no-build-isolation -w web/lab/wheel .
cd web/lab/wheel && ls -t cellsim-*-py3-none-any.whl | head -1 > LATEST
```

The first time you look at a culture dish, the browser downloads Python (Pyodide, about 30 s). After that it is cached.

## Controls

| Key | Does |
|---|---|
| W A S D, mouse | Walk, look |
| Left click | Take the thing you look at into your pocket |
| Right click | Use or open the thing you look at; with an item in hand, use it on what you look at, or put it down |
| Hold right click | Lower a cover slip slowly (a quick tap drops it flat and traps air) |
| 1–9, scroll | Pick a hotbar slot |
| Q | Put down the item in your hand |
| E | Inventory |
| J | Lab journal |
| Space, Shift, Ctrl | Jump, sneak, sprint |
| Esc | Pause |
| F3 | Frame rate, draw calls and memory |

## The experiments

- **Onion skin cells:** goggles, wash your hands, slide on the white tile, cut the onion with the scalpel, peel the skin with the forceps, one drop of iodine, cover slip, stage, then focus at 4×, 10× and 40×.
- **Your cheek cells:** swab your cheek, smear it on the slide, put the swab in the disinfectant, then add methylene blue.
- **Pondweed leaf cells:** a drop of water first, then one leaf from the tank. At 400× the chloroplasts stream around each cell.
- **Living cancer cells:** take Dish A from the incubator and look at it, add drops of paclitaxel, doxorubicin or cisplatin, incubate, and compare with Dish B, the untreated control. The doses are real dilutions: two 50 µL drops of 10 µM paclitaxel in 5.1 mL of medium give 0.196 µM. The engine's cell counts appear in the journal.

## Graphics and battery

Settings → Graphics: **Auto** picks a preset from the graphics chip.

| Preset | Detail |
|---|---|
| Low | Older Macs and laptops on battery: 0.75× resolution, no shadows, no smoothing, one ceiling lamp, 30 fps |
| Medium | Shadows from the windows, two lamps |
| High | Sharper shadows, four lamps |
| Ultra | Full resolution, 4096 px shadows, all six lamps, no frame cap |

The game stops drawing when nothing moves, and the Cell Sim engine (about 150 MB of memory) only loads once a culture dish needs it.

## What's where

| Path | |
|---|---|
| `index.html`, `css/game.css` | Screens and HUD |
| `js/main.js` | Game loop, input, inventory, the microscope stage, incubator and drawers |
| `js/room.js` | The room, furniture, lights and colliders |
| `js/items.js` | Every item and what left- and right-click do with it |
| `js/props.js` | Equipment built in code: slides, bottles, beakers, dishes, the pondweed tank, tools |
| `js/liquids.js` | Volumes, colour mixing and drug dilution |
| `js/scope.js`, `js/specimens.js`, `js/culture.js` | The view through the eyepiece |
| `js/engine.js`, `js/engine-worker.js`, `js/lab_engine.py` | The Cell Sim engine, in a background worker |
| `js/tasks.js`, `js/journal.js` | Experiments and the lab journal |
| `assets/` | Models, textures and lighting (`downloads/` holds the raw Sketchfab files and is not committed) |

## Honest notes

- The living cells are the engine's: positions, cell-cycle phase, p53, caspase-3 and DNA damage come from `run_dish_stream`. Only their outlines are drawn here.
- The onion, cheek and pondweed slides are drawn at measured cell sizes. They are not simulated.

## Credits

- **Cell engine:** Cell Sim (MIT), in the browser via Pyodide.
- **3D engine:** three.js r160 (MIT).
- **Poly Haven (CC0):** yellow onion, metal stool, steel shelves, fluorescent lights, drawer cabinet, clipboard, stationery, wall clock, magnifying glass, binder notebook, metal office desk, floor tiles, painted plaster, and the hospital room HDRI.
- **Sketchfab (CC Attribution 4.0):**
- [Chemistry Lab Table](https://sketchfab.com/3d-models/chemistry-lab-table-fc5951d8af674da4bf55aef0693ff1d0) by Jawahar Yokesh
- [lab bench](https://sketchfab.com/3d-models/lab-bench-1ac2a62c52a848bbaf746146dc7253f8) by Konstantin_Keller (the incubator)
- [Compound Microscope](https://sketchfab.com/3d-models/compound-microscope-8709be06c5b24549b19bba7a1988a56f) by kg007
- [Door Classroom](https://sketchfab.com/3d-models/door-classroom-9-mb-fcc87f41b47f49a8941d2b6847246909) by Mehdi Shahsavan
- **Built in code:** the room, slides, cover slips, bottles, beakers, culture dishes, the pondweed tank, the lab tools, the safety goggles, the hand sanitizer and the window blinds.
Binary file added web/lab3d/assets/hdri/hospital_room_1k.hdr
Binary file not shown.
Binary file not shown.
Loading
Loading