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
42 changes: 26 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,21 +20,28 @@ collagen), epigenetics and cellular map. Every process is a real 3D model:

It runs in the browser with three.js.

### ▶ [Open the simulator](https://mecca-research.github.io/StemCellSimulator/)

The simulator is live at **<https://mecca-research.github.io/StemCellSimulator/>**.
It runs in any browser with WebGL 2 and needs no install.

<p align="center">
<img src="docs/images/colony-confocal.webp" width="49%" alt="Real 3D confocal stack next to its growing digital twin">
<img src="docs/images/signaling-physical.webp" width="49%" alt="Cut-away stem cell with Notch, Wnt and Hedgehog signalling">
<a href="https://mecca-research.github.io/StemCellSimulator/#colony"><img src="docs/images/colony-confocal.webp" width="49%" alt="Real 3D confocal stack next to its growing digital twin"></a>
<a href="https://mecca-research.github.io/StemCellSimulator/#signaling"><img src="docs/images/signaling-physical.webp" width="49%" alt="Cut-away stem cell with Notch, Wnt and Hedgehog signalling"></a>
</p>

## Run it
## Run it locally

```bash
npm run serve # any static server works; WebGL 2 required
# open http://localhost:8080
```

No build step and no network access are needed. three.js is vendored.
Deep links open a specific view, e.g. `#signaling?view=spheroid`,
`#proteins?view=collagen`, `#gallery?view=rbc`.
Deep links open a specific view, e.g.
[`#signaling?view=spheroid`](https://mecca-research.github.io/StemCellSimulator/#signaling?view=spheroid),
[`#proteins?view=collagen`](https://mecca-research.github.io/StemCellSimulator/#proteins?view=collagen),
[`#gallery?view=rbc`](https://mecca-research.github.io/StemCellSimulator/#gallery?view=rbc).

**Controls:**

Expand All @@ -60,19 +67,19 @@ Deep links open a specific view, e.g. `#signaling?view=spheroid`,
| **Micrograph gallery** | Each real reference image with an **animated variation** made from its own pixels, next to a 3D model of the same process. | Validation |

<p align="center">
<img src="docs/images/hematopoiesis-physical.webp" width="32%" alt="Bone-marrow niche">
<img src="docs/images/differentiation-physical.webp" width="32%" alt="Myoblast fusion">
<img src="docs/images/morphogenesis-physical.webp" width="32%" alt="Turing organoid">
<a href="https://mecca-research.github.io/StemCellSimulator/#hematopoiesis"><img src="docs/images/hematopoiesis-physical.webp" width="32%" alt="Bone-marrow niche"></a>
<a href="https://mecca-research.github.io/StemCellSimulator/#differentiation"><img src="docs/images/differentiation-physical.webp" width="32%" alt="Myoblast fusion"></a>
<a href="https://mecca-research.github.io/StemCellSimulator/#morphogenesis"><img src="docs/images/morphogenesis-physical.webp" width="32%" alt="Turing organoid"></a>
</p>
<p align="center">
<img src="docs/images/proteins-physical.webp" width="32%" alt="Hemoglobin assembly">
<img src="docs/images/landscape-physical.webp" width="32%" alt="Waddington landscape">
<img src="docs/images/kidney-histology.webp" width="32%" alt="Virtual H&amp;E kidney">
<a href="https://mecca-research.github.io/StemCellSimulator/#proteins"><img src="docs/images/proteins-physical.webp" width="32%" alt="Hemoglobin assembly"></a>
<a href="https://mecca-research.github.io/StemCellSimulator/#landscape"><img src="docs/images/landscape-physical.webp" width="32%" alt="Waddington landscape"></a>
<a href="https://mecca-research.github.io/StemCellSimulator/#kidney"><img src="docs/images/kidney-histology.webp" width="32%" alt="Virtual H&amp;E kidney"></a>
</p>
<p align="center">
<img src="docs/images/network-physical.webp" width="32%" alt="Reaction network, PCA embedding">
<img src="docs/images/atlas-physical.webp" width="32%" alt="Cellular map lineage tree">
<img src="docs/images/gallery-view-skin-physical.webp" width="32%" alt="Real H&amp;E skin with its animated variation and a 3D epidermis">
<a href="https://mecca-research.github.io/StemCellSimulator/#network"><img src="docs/images/network-physical.webp" width="32%" alt="Reaction network, PCA embedding"></a>
<a href="https://mecca-research.github.io/StemCellSimulator/#atlas"><img src="docs/images/atlas-physical.webp" width="32%" alt="Cellular map lineage tree"></a>
<a href="https://mecca-research.github.io/StemCellSimulator/#gallery?view=skin"><img src="docs/images/gallery-view-skin-physical.webp" width="32%" alt="Real H&amp;E skin with its animated variation and a 3D epidermis"></a>
</p>

### Three ways to look at every scene
Expand Down Expand Up @@ -141,8 +148,11 @@ node tests/e2e/smoke.mjs --all --modes
node tools/capture_previews.mjs
```

CI runs all of the above on every pull request. A GitHub Pages workflow publishes
the simulator from `main`; enable **Settings → Pages → Source: GitHub Actions** once.
CI runs all of the above on every pull request. The GitHub Pages workflow
publishes `main` to <https://mecca-research.github.io/StemCellSimulator/> on every
push. To smoke-test that exact bundle locally, assemble `_site/` as in
[`pages.yml`](.github/workflows/pages.yml) and run
`SITE_ROOT=_site node tests/e2e/smoke.mjs`.

## Layout

Expand Down
66 changes: 33 additions & 33 deletions assets/derived/organoids.json
Original file line number Diff line number Diff line change
Expand Up @@ -165,26 +165,26 @@
"x": 459,
"y": 121
},
{
"r": 13,
"x": 483,
"y": 384
},
{
"r": 13,
"x": 462,
"y": 342
},
{
"r": 10,
"x": 56,
"y": 408
"r": 13,
"x": 483,
"y": 384
},
{
"r": 10,
"x": 387,
"y": 161
},
{
"r": 10,
"x": 56,
"y": 408
},
{
"r": 14,
"x": 455,
Expand All @@ -210,26 +210,26 @@
"x": 258,
"y": 329
},
{
"r": 10,
"x": 564,
"y": 149
},
{
"r": 10,
"x": 354,
"y": 137
},
{
"r": 11,
"x": 389,
"y": 76
"r": 10,
"x": 564,
"y": 149
},
{
"r": 12,
"x": 245,
"y": 67
},
{
"r": 11,
"x": 389,
"y": 76
},
{
"r": 13,
"x": 561,
Expand Down Expand Up @@ -260,26 +260,26 @@
"x": 463,
"y": 111
},
{
"r": 11,
"x": 485,
"y": 493
},
{
"r": 11,
"x": 338,
"y": 254
},
{
"r": 10,
"x": 479,
"y": 430
"r": 11,
"x": 485,
"y": 493
},
{
"r": 10,
"x": 197,
"y": 425
},
{
"r": 10,
"x": 479,
"y": 430
},
{
"r": 18,
"x": 155,
Expand All @@ -297,13 +297,13 @@
},
{
"r": 10,
"x": 241,
"y": 110
"x": 414,
"y": 87
},
{
"r": 10,
"x": 414,
"y": 87
"x": 241,
"y": 110
},
{
"r": 9,
Expand Down Expand Up @@ -400,6 +400,11 @@
"x": 363,
"y": 431
},
{
"r": 9,
"x": 258,
"y": 160
},
{
"r": 9,
"x": 121,
Expand All @@ -410,11 +415,6 @@
"x": 622,
"y": 445
},
{
"r": 9,
"x": 258,
"y": 160
},
{
"r": 10,
"x": 217,
Expand Down
5 changes: 3 additions & 2 deletions tests/e2e/smoke.mjs
Original file line number Diff line number Diff line change
@@ -1,17 +1,18 @@
// Headless browser smoke test: every scene must load without errors, render a
// non-blank WebGL frame and keep simulating. Screenshots go to tests/e2e/out/.
// node tests/e2e/smoke.mjs [sceneId ...]
// SITE_ROOT=<dir> serves another directory, e.g. the assembled GitHub Pages site.
import { chromium } from 'playwright';
import { mkdir } from 'node:fs/promises';
import { existsSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';
import { dirname, join, resolve } from 'node:path';
import { serve } from './serve.mjs';
import { SCENES } from '../../js/scenes/index.js';
import { EXTRA_VIEWS } from './views.mjs';

const here = dirname(fileURLToPath(import.meta.url));
const root = join(here, '..', '..');
const root = process.env.SITE_ROOT ? resolve(process.env.SITE_ROOT) : join(here, '..', '..');
const outDir = join(here, 'out');
await mkdir(outDir, { recursive: true });

Expand Down
28 changes: 28 additions & 0 deletions tests/tools/test_pipeline.py
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,34 @@ def test_first_order_fit_recovers_parameters():
assert np.allclose(popt, [3.0, 1.2, 6.0], rtol=1e-4)


def test_hough_peaks_break_ties_the_same_way_whatever_the_order():
# two radii with equally strong peaks 3 px apart: only one may survive, and
# it must be the same one however the radii (and so the peaks) are ordered
h = np.zeros((3, 40, 40))
h[0, 20, 20] = h[1, 23, 21] = 1.0
h[2, 5, 30] = 0.8
radii = np.array([10, 12, 14])
ref = ba.hough_peaks(h, radii, min_distance=8, threshold=0.45, max_peaks=10)
assert [(int(x), int(y), int(r)) for _, x, y, r in zip(*ref)] == [(20, 20, 10), (30, 5, 14)]
for perm in ([2, 1, 0], [1, 0, 2], [1, 2, 0]):
got = ba.hough_peaks(h[perm], radii[perm], min_distance=8, threshold=0.45, max_peaks=10)
for a, b in zip(ref, got):
assert np.array_equal(a, b)


def test_select_organoids_does_not_depend_on_input_order():
rng = np.random.default_rng(3)
n = 60
acc = rng.integers(5, 9, n) / 10.0 # many exact ties
cx, cy = rng.integers(20, 180, n), rng.integers(20, 180, n)
rad = rng.integers(9, 15, n)
ref = ba.select_organoids(acc, cx, cy, rad, (200, 200))
assert 5 < len(ref) < n
for seed in range(5):
p = np.random.default_rng(seed).permutation(n)
assert ba.select_organoids(acc[p], cx[p], cy[p], rad[p], (200, 200)) == ref


# ----------------------------------------------------------------- committed assets
def test_hipsc_mesh_buffer_matches_metadata():
meta = json.loads((DERIVED / "hipsc_cells.json").read_text())
Expand Down
63 changes: 50 additions & 13 deletions tools/build_assets.py
Original file line number Diff line number Diff line change
Expand Up @@ -496,6 +496,53 @@ def build_rbc() -> dict:
return {"rbc": {k: {kk: vv for kk, vv in v.items() if not isinstance(vv, list)} for k, v in out.items()}}


def hough_peaks(hspaces: np.ndarray, radii: np.ndarray, min_distance: int, threshold: float,
max_peaks: int) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
"""Hough circle peaks that are identical on every CPU.

skimage's hough_circle_peaks ranks the peaks of all radii with an unstable
(SIMD) argsort before its cross-radius distance suppression, so equal
accumulator values come out in a CPU-dependent order (AVX2 and AVX-512
differ), and that order decides which of two nearby tied peaks survives.
Here the peaks are found one radius at a time, then ranked by
(accumulator desc, y, x, r) before the same suppression: a peak is dropped
if an earlier one lies within min_distance in both x and y.
"""
acc, cx, cy, rad = [], [], [], []
for h, r in zip(hspaces, radii):
a, x, y, _ = transform.hough_circle_peaks(h[None], [r], min_xdistance=min_distance,
min_ydistance=min_distance, threshold=threshold)
acc.append(a)
cx.append(x)
cy.append(y)
rad.append(np.full(len(a), r))
acc, cx, cy, rad = (np.concatenate(v) for v in (acc, cx, cy, rad))
keep = []
for i in np.lexsort((rad, cx, cy, -acc)):
if len(keep) == max_peaks:
break
if any(abs(cx[i] - cx[j]) <= min_distance and abs(cy[i] - cy[j]) <= min_distance for j in keep):
continue
keep.append(i)
return acc[keep], cx[keep], cy[keep], rad[keep]


def select_organoids(acc: np.ndarray, cx: np.ndarray, cy: np.ndarray, rad: np.ndarray,
shape: tuple[int, ...]) -> list[dict]:
"""Greedy pick of non-overlapping circles inside the well, strongest first;
ties are broken by (y, x, r), so the result does not depend on input order."""
centre = np.array([shape[1] / 2, shape[0] / 2])
keep = []
for i in np.lexsort((rad, cx, cy, -acc)):
p = np.array([cx[i], cy[i]])
if np.linalg.norm(p - centre) > 0.47 * shape[1]:
continue
if any(np.linalg.norm(p - np.array([cx[j], cy[j]])) < 0.8 * max(rad[i], rad[j]) for j in keep):
continue
keep.append(i)
return [{"x": int(cx[i]), "y": int(cy[i]), "r": int(rad[i])} for i in keep]


def build_organoids() -> dict:
im = Image.open(RAW / "orgaquant_3.jpg").convert("L")
width = 750
Expand All @@ -504,19 +551,9 @@ def build_organoids() -> dict:
flat = a / filters.gaussian(a, 40) # remove vignetting
edges = feature.canny(flat, sigma=2.0, low_threshold=0.03, high_threshold=0.08)
radii = np.arange(9, 46)
acc, cx, cy, rad = transform.hough_circle_peaks(transform.hough_circle(edges, radii), radii,
min_xdistance=8, min_ydistance=8,
threshold=0.45, total_num_peaks=400)
centre = np.array([a.shape[1] / 2, a.shape[0] / 2])
keep = []
for i in np.argsort(-acc):
p = np.array([cx[i], cy[i]])
if np.linalg.norm(p - centre) > 0.47 * a.shape[1]:
continue
if any(np.linalg.norm(p - np.array([cx[j], cy[j]])) < 0.8 * max(rad[i], rad[j]) for j in keep):
continue
keep.append(i)
circles = [{"x": int(cx[i]), "y": int(cy[i]), "r": int(rad[i])} for i in keep]
peaks = hough_peaks(transform.hough_circle(edges, radii), radii,
min_distance=8, threshold=0.45, max_peaks=400)
circles = select_organoids(*peaks, a.shape)
r = np.array([c["r"] for c in circles], float)
base = to_u8(pnorm(flat, 0.5, 99.5))
Image.fromarray(base).save(OUT / "organoids.jpg", quality=88)
Expand Down
Loading