diff --git a/README.md b/README.md index 496c715..4ecd26b 100644 --- a/README.md +++ b/README.md @@ -20,12 +20,17 @@ 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 ****. +It runs in any browser with WebGL 2 and needs no install. +

- Real 3D confocal stack next to its growing digital twin - Cut-away stem cell with Notch, Wnt and Hedgehog signalling + Real 3D confocal stack next to its growing digital twin + Cut-away stem cell with Notch, Wnt and Hedgehog signalling

-## Run it +## Run it locally ```bash npm run serve # any static server works; WebGL 2 required @@ -33,8 +38,10 @@ npm run serve # any static server works; WebGL 2 required ``` 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:** @@ -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 |

- Bone-marrow niche - Myoblast fusion - Turing organoid + Bone-marrow niche + Myoblast fusion + Turing organoid

- Hemoglobin assembly - Waddington landscape - Virtual H&E kidney + Hemoglobin assembly + Waddington landscape + Virtual H&E kidney

- Reaction network, PCA embedding - Cellular map lineage tree - Real H&E skin with its animated variation and a 3D epidermis + Reaction network, PCA embedding + Cellular map lineage tree + Real H&E skin with its animated variation and a 3D epidermis

### Three ways to look at every scene @@ -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 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 diff --git a/assets/derived/organoids.json b/assets/derived/organoids.json index 9ebdde3..6ea25af 100644 --- a/assets/derived/organoids.json +++ b/assets/derived/organoids.json @@ -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, @@ -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, @@ -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, @@ -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, @@ -400,6 +400,11 @@ "x": 363, "y": 431 }, + { + "r": 9, + "x": 258, + "y": 160 + }, { "r": 9, "x": 121, @@ -410,11 +415,6 @@ "x": 622, "y": 445 }, - { - "r": 9, - "x": 258, - "y": 160 - }, { "r": 10, "x": 217, diff --git a/tests/e2e/smoke.mjs b/tests/e2e/smoke.mjs index 33a0fce..cf7568e 100644 --- a/tests/e2e/smoke.mjs +++ b/tests/e2e/smoke.mjs @@ -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= 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 }); diff --git a/tests/tools/test_pipeline.py b/tests/tools/test_pipeline.py index 4845194..9ca8751 100644 --- a/tests/tools/test_pipeline.py +++ b/tests/tools/test_pipeline.py @@ -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()) diff --git a/tools/build_assets.py b/tools/build_assets.py index dce5102..b52fd13 100644 --- a/tools/build_assets.py +++ b/tools/build_assets.py @@ -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 @@ -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)