A1-TISSUE result

Work package A1-TISSUE of the SGH synthetic gastric histology programme (operations/research/sgh-program-20260908/PLAN.md), 8 September 2026.

Engineering evidence only. Nothing here is a clinical claim, and none of these numbers say a cartoon or a generated field is diagnostically valid. All morphometrics are image-only measurements produced by the same code path for real fields and for cartoons.

1. What was wrong

operations/research/pixcell-topology-slot-20260906/code/render_cartoon.py built one gland shape for all four categories -- the intestinal-metaplasia tube -- and separated the categories with two numbers:

CATEGORY_PARAMS = {
    "normal":                {"goblet_frac": 0.0,  "stroma_nuclei_per_mm2": 3500.0},
    "hpylori_gastritis":     {"goblet_frac": 0.0,  "stroma_nuclei_per_mm2": 9000.0},
    "intestinal_metaplasia": {"goblet_frac": 0.45, "stroma_nuclei_per_mm2": 4300.0},
    "mixed":                 {"goblet_frac": 0.40, "stroma_nuclei_per_mm2": 8000.0},
}

Two further defects found while measuring it:

• goblet_frac = 0.0 did not produce zero goblet cells. The per-tube draw was clip(normal(0.0, 0.12), 0.0, 0.21), whose mean is about 0.048, so every "normal" and "gastritis" cartoon carried roughly 5% goblet cells. Fixed: goblet_frac <= 1e-6 now short-circuits to exactly zero.
• With --surface, an across cut put the plane at z = 5 +/- 3 um, i.e. straddling the mean mucosal surface. 45.4% of every surface-on across cartoon was empty background. Real fields have background_fraction = 0.000 (median, all four categories).

2. Measurement first: code/cartoon_metrics.py

code/cartoon_metrics.py measures any 0.25 um/px PNG -- real field or cartoon -- with one code path:

• ring_topology imported from operations/research/pixcell-fullset-20260908/code/ring_topology.py (copied to code/ring_topology.py; the fleet ships code/), configured with research/sgh-synthetic-histopathology/config/sydney_qa_v1.json;
• tissue_fraction, background_fraction, lumen_tissue_ratio, nuclear_density_per_mm2, stroma_fraction, epithelium_band_fraction, nuclear_area_fraction, median_nucleus_area_um2, nuclear_density_abs_per_mm2, all on the same analysis-resolution grid ring_topology uses.

Definitions worth stating because they decide what "inside the envelope" means:

• lumen_tissue_ratio = area of pale components (mean grey > lumen_brightness_floor = 220, each at least minimum_lumen_area_um2 = 80 um2), excluding non-tissue that is connected to the image border, divided by tissue area. The border exclusion is what stops a cartoon's empty space above the surface from counting as lumen. The first attempt ("pale holes in the tissue mask") returned 0.000 for every real field, because real fields are 98% tissue and have no holes; it was replaced before any tuning.
• stroma_fraction = tissue not inside the closed epithelial band = 1 - epithelium_band_fraction.
• Caveat on nuclear_density_per_mm2. The sydney nuclear threshold is the 72nd percentile of hematoxylin within the image, so exactly 28% of tissue is "nuclear" in every field by construction and nuclear_area_fraction carries no information. The density therefore measures how finely that fixed 28% is broken up -- effectively nucleus size -- not absolute cellularity. It is still a like-for-like real-vs-cartoon comparison, which is what A1 needs, and it is the metric the brief names. nuclear_density_abs_per_mm2 (fixed threshold 0.30) is reported alongside and never tuned.

A methodological trap worth recording. The first three tuning iterations were run at 2048x1024 / 0.5 um/px to go four times faster. Those numbers were wrong: ring_topology takes micrometres_per_pixel from sydney_qa_v1.json (0.25) rather than from the image, so a 0.5 um/px render is scored with 4x-too-small pixel areas -- every density 4x too high, every area 4x too small. All numbers below are full-size 4096x2048 at 0.25 um/px. code/tune.py now refuses to imply the shortcut is comparable.

3. The real envelope

Real envelope: median (10-90%), train + held-out

Real envelope, held-out only

Sample: 24 train + 4-6 held-out fields per category from research/sgh-synthetic-histopathology/.artifacts/pixcell-fields-v1/wide/{train,heldout}/<cat>/*mpp0.25.png (n = 28 normal, 30 each for the other three). Per-field rows: morphometrics/real-metrics.csv; envelope: morphometrics/real-envelope.json.

Three things the envelope says that shaped the model:

1. Real fields are 98% tissue and have essentially no background. The E1 requirement to render the surface with empty space above it therefore pushes every surface-bearing cartoon below the real tissue_fraction band unless the empty band is kept thin. It is now 19 um plus the surface mucus thickness.
2. median_ring_area_um2 is 389-417 um2 (22 um across) in every category. A "ring" is not a whole gland: it is a hole in the closed hematoxylin mask, and most of them are inter-nuclear and intra-cytoplasmic gaps.
3. The categories separate mainly on ring_density (normal 87, IM 120) and stroma_fraction (normal 0.129, gastritis 0.172, IM 0.197), not on cellularity as measured by the percentile-thresholded nuclear density.

4. What was built

4.1 code/tissue3d.py

Extended copy of the topology-slot model. New machinery, all optional and defaulting to the previous behaviour where a default exists:

Also: plane_basis now forces E2[2] >= 0, so depth always increases downwards and the surface is at the top of the image; cKDTree.query runs with workers=1 for reproducibility; stromal nuclei are placed on a jittered lattice rather than a Poisson scatter (_jittered_lattice) -- real cells have hard cores, and a Poisson scatter leaves voids that the ring metric counts as gland lumens.

4.2 code/render_cartoon.py

• render(res, seed, mpp, blur_px, fidelity=2) -- the signature is extended by keyword only; fidelity is the E2 ladder:
• 0 flat label colours plus the cell-kind palette, no texture, no blur;
• 1 + basement-membrane rim, per-nucleus colour jitter, 0.5 px blur;
• 2 the full cartoon renderer (default, and what every existing call gets);
• 3 + simulated optical blur with slight chromatic defocus, nuclear chromatin grain, cytoplasm granularity, a slow hematoxylin:eosin drift across the field and post-optics shot noise.
• CATEGORY_PARAMS now has five presets: normal_body, normal_antrum, hpylori_gastritis, intestinal_metaplasia, mixed. --category normal resolves to body or antrum by seed parity (NORMAL_SUBTYPES[seed % 2]: even seed -> body, odd seed -> antrum) and the choice is recorded in the JSON sidecar as preset and subtype.
• Cell-kind-aware palette: parietal cells are large and eosinophilic, chief cells basophilic, foveolar/surface cells pale mucinous, the muscularis a denser pink band, follicles slightly bluer, surface mucus a pale wisp.
• save_all writes <stem>.json (was <stem>_geometry.json) and save_label_png uses Image.frombytes("P", (w, h), labels.tobytes()) + putpalette.

4.3 code/render_set.py

--set {a1,d1,e2,b1} --out <dir>, plus --verify which re-renders into <out>.verify and compares SHA-256 against the manifest already in <out>.

Determinism: every draw comes from numpy.random.default_rng seeded from the cartoon seed (model seed; cut plane seed*7919 + cut index; renderer seed*104729 + 17), and the nearest-tube query runs single-threaded. Each set directory carries MANIFEST.sha256.json. Verified on this machine: --verify on b1 (15 files) and d1 (30 files, including the rot180 outputs) reported 0 mismatched, 0 missing. Cross-set identity was checked with shasum -a 256: the five d1 non-rotated cartoons and label maps are byte-identical to their a1 counterparts, and all five e2 _f2 cartoons and label maps are byte-identical to a1's, as the brief requires. The rot180 arrays are exactly a1[::-1, ::-1] for both the cartoon and the label map. Versions on this machine: numpy 2.4.4, scipy 1.17.1, Pillow 12.1.0 -- the VM must match for byte identity.

5. Tuning: what moved and why

Each iteration is one full re-render of 5 presets x seed 11 x 3 cuts at 4096x2048, scored against the category's 10-90% band on the five tuned metrics (ring_density_per_mm2, median_ring_area_um2, lumen_tissue_ratio, nuclear_density_per_mm2, stroma_fraction). ring_with_lumen_fraction is reported but not tuned: a cartoon's lumens are hollow by construction. "deviation" is the total distance outside the band, in band-widths, summed over the five metrics -- 0 means every metric is inside.

Iterations 8-12 are one seed x 5 presets x 3 cuts (15 cartoons); the shipped row is the whole a1 set (60 cartoons), so it is scored on 4x more material and is not exactly comparable to the rows above it. The palette rebalance in iteration 13 cost about 0.3 band-widths of deviation and is the concession described below.

Iteration logs lived in the session scratchpad and are not preserved; every number in section 6 is reproducible from the committed sets with the commands in section 8.

The three changes that did the work

1. Lumen optical density. A cartoon lumen was (250, 246, 250): optical density 0.075, below the sydney tissue floor of 0.15, so it was scored as not tissue. Real gland lumens always carry some stain -- in real fields 96-99% of pale pixels are also tissue. Setting the lumen to (242, 232, 242) (OD 0.198, mean grey 238.7) makes it pale-but-tissue, which is what moved tissue_fraction from 0.54-0.86 to 0.92-0.99 and lumen_tissue_ratio from 0.34-0.45 into the real band.

2. How the hematoxylin is spread, not how much there is. Because the nuclear threshold is a percentile, the closed epithelial band depends entirely on the spatial distribution of the darkest 28%. The pre-A1 cartoon put all of it in clean geometric nuclei, so the 6-um closing reached only 57-63% of tissue where a real field reaches 86%; the rest was scored as stroma, and stroma_fraction came out at 0.45-0.54 against a real 0.13-0.20. Adding a fine (0.78 um) hematoxylin speckle over cytoplasm and stroma plus per-cell cytoplasmic basophilia raised the band to 0.75-0.85.

3. Jittered lattice instead of Poisson for stromal nuclei. A Poisson scatter at realistic density leaves voids of 400-600 um2 that the ring metric counts as gland lumens; ~70% of a pre-A1 cartoon's rings came from the lamina propria, not from glands. On a jittered lattice at the same density those voids disappear.

Two changes that were tried and reverted

• Patchy (clustered) lamina-propria cellularity (stroma_patchiness, retained in TissueParams but 0 everywhere). Real infiltrate is patchy, but the sparse patches each became a countable hole: ring density roughly doubled (IM across 382 -> 634/mm2) and stroma_fraction rose from 0.28 to 0.42. Reverted.
• Driving the stain speckle hard enough to reach a 0.86 band. At speckle gain 1.22 the band reached 0.83 but visual review showed the cartoons had gone uniformly blue-purple: mean RGB (191, 144, 192) against a real (211, 130, 196) / (221, 176, 213). That is metric chasing that damages the artefact the generator has to condition on, so the gain was cut to 0.46 and the whole palette rebalanced towards eosin, giving up about 0.08 of band fraction. This is the single largest deliberate concession in the package.

6. Where the shipped cartoons land

Cartoon set a1: median over 5 seeds (bold = outside the 10-90% band)

Cartoon set a1, reported-not-tuned

Per-cartoon rows: morphometrics/cartoon-metrics.csv; per-category/cut envelopes: morphometrics/cartoon-envelope.json.

Scored per cartoon over the whole a1 set (60 cartoons, 5 tuned metrics each):

40 of the 60 category x cut x metric cells in the table above are inside the 10-90% band. along cuts are much the closest (17/20 cells inside; intestinal metaplasia along is 5/5); across and oblique carry nearly all the remaining error, and in both it is the same two metrics: ring density and median ring area. Every category is inside the band on lumen_tissue_ratio and nuclear_density_per_mm2 for all three cuts.

E2 fidelity ladder (intestinal_metaplasia, across, median over 5 seeds)

The ladder behaves as intended. f0 (flat label colours, no texture, no blur) has a much lower nuclear_density_per_mm2 (8214 vs 10053 -- without the fine stain speckle the thresholded nuclear mask is only the geometric nuclei) and a much lower stroma_fraction (0.183 vs 0.300). f1 adds the basement rim and per-nucleus jitter. f2 is the shipped renderer. f3 is metrically almost identical to f2, because its optics, chromatin grain and stain drift change texture, not composition -- which is what E2 needs: the ladder varies cartoon realism while holding the imposed geometry and its morphometrics nearly fixed at the top of the ladder.

B1 organism-bearing surfaces (hpylori_gastritis, oblique, median over 5 seeds)

The b1 override widens the surface mucus band from 4.0% to 6.5% of the field (median over 5 seeds, range 6.1-8.0%) and the lumen label from 8.5% to 12.2%: the pits are open and there is a continuous luminal mucus layer for organisms to sit in. The cost is tissue_fraction 0.900, just below the real p10 of 0.917, because the mucus band and the empty space above it are not tissue. b1 is 3/5 inside, deviation 1.83.

7. Known gaps

1. across and oblique ring density is above the band in every category (medians 230-315/mm2 against real p90s of 143-174; the real maxima are 192-266). The cause is structural and understood: in a cartoon each gland profile contributes exactly one fully enclosed pale interior, and the cartoon has 280-750 gland profiles per mm2. Real fields register only 39-174 rings/mm2 from a comparable gland density, because real gland interiors are filled in by cytoplasmic hematoxylin and their nuclear contours are frequently broken. Three mitigations were applied (fine stain speckle, per-cell cytoplasmic basophilia, epi_nucleus_dropout); together they took IM across from 438 to 250/mm2, but the gap is not closed. Closing it properly needs either a projected 3-um slab (superimposed structures) instead of an infinitely thin plane, or a cytoplasm model with sub-cellular basophilic and mucinous compartments.
2. median_ring_area_um2 on oblique runs 669-1019 um2 against a real p90 of 480-582. An oblique cut turns a gland into an elongated oval whose interior is longer than a circular profile's; real oblique-ish fields do not show this, for the same reason as (1).
3. stroma_fraction for normal is 0.302-0.313 against a real 0.065-0.244: the closed epithelial band reaches 0.69 of tissue where a real normal field reaches 0.87. This is the deliberate concession recorded in section 5 -- the speckle gain that would close it turned the cartoons uniformly blue-purple. Gastritis (band 0.75-0.80) is inside its band; normal, IM and mixed are not.
4. The E1 empty band costs tissue_fraction. Real fields have background_fraction = 0.000 (median, all four categories) because they are cut from inside the mucosa. Any cartoon rendered with the surface in frame has 3.6-4.5% background, putting tissue_fraction at 0.92-0.94 on along and oblique -- at or just below the real p10 for normal (0.963). This follows from the E1 requirement, not from a modelling error, and it is why the empty band was trimmed to 19 um plus the mucus thickness.
5. across cuts show neither the surface nor the muscularis, by geometry. A 512-um-tall plane at 4-16 degrees to the tube axis spans 0-135 um of depth; it cannot contain both a surface and mid-mucosal gland rings. along cuts (tilt 82-88.5 deg) span the full -21..488 um and show the empty space, the surface epithelium, tapering tubes and a 44-48 um muscularis band; oblique cuts span about -22..370 um and show the surface but not the muscularis. A further wrinkle inherited from the original plane_basis: it falls back to an arbitrary in-plane basis below about 10.4 degrees of tilt, so across cartoons drawn at 4-10 deg are strictly tangential (depth_top_um == depth_bottom_um) while those at 10-16 deg have a real depth gradient. Both appear in set a1.
6. Mucosal thickness is 440 um plus a 48 um muscularis, chosen so a full thickness fits the 512-um frame the brief specifies. Real gastric mucosa is often 500-800 um, so the model sits at the thin end of normal antral thickness; making it thicker would crop the muscularis out of every along cut.
7. nuclear_density_per_mm2 on along cuts sits at the ceiling for gastritis and mixed (medians 14228 and 13735 against p90s of 14673 and 13757 -- inside, but only just; single seeds reach 17-18k).
8. The auxiliary cell_kind map is not exported. Parietal versus chief versus foveolar versus muscularis versus follicle exist only as renderer colour; the label PNG a downstream structure adapter (F2) reads has exactly 9 classes, as required. Intraepithelial neutrophils reuse label 6 (stroma_nucleus) and the surface mucus band reuses label 3 (goblet_mucin). Both keep the vocabulary fixed but mean a consumer of the label map cannot tell a neutrophil from a lymphocyte, or luminal mucus from a goblet vacuole.
9. Section thickness is emulated by inflating primitives, not by projecting a slab. Real 3-um sections superimpose structures from different depths; the cartoon evaluates an infinitely thin plane. This is the most likely single cause of gap (1).
10. stroma_patchiness is implemented but 0 everywhere. Real inflammatory infiltrate is patchy; the parameter is retained for anyone who wants to revisit it under a different hole-counting metric.
11. Tuning used the combined train + held-out envelope (<cat>|all) so the band came from 28-30 fields rather than 4-6. The held-out-only envelope is printed above for comparison: it is tighter and shifted upward on ring density, so the reported "inside" counts would be modestly worse against held-out alone. Held-out fields were used for nothing except that envelope and the contact sheet's left-hand column.
12. No pathologist has seen any of this. The categories are named after the HiESD labels of the fields they were tuned against; nothing here establishes that a cartoon, or anything generated from it, is diagnostically correct. Yash is the structured visual reviewer for this programme and has not yet reviewed the contact sheet.

8. Exact commands

cd [local]/sgh-program-20260908

# 1. real envelope (118 fields, ~2 min)
python3 code/cartoon_metrics.py --real --split both \
    --out morphometrics/real-metrics.csv --summary morphometrics/real-envelope.json

# 2. render the four sets (~14 s per cartoon on this Mac; 95 cartoons)
python3 code/render_set.py --set a1 --out cartoons/a1
python3 code/render_set.py --set d1 --out cartoons/d1
python3 code/render_set.py --set e2 --out cartoons/e2
python3 code/render_set.py --set b1 --out cartoons/b1

# 3. byte-for-byte reproducibility check (re-renders into cartoons/<set>.verify)
python3 code/render_set.py --set b1 --out cartoons/b1 --verify

# 4. measure every rendered cartoon
python3 code/cartoon_metrics.py --cartoons cartoons \
    --out morphometrics/cartoon-metrics.csv --summary morphometrics/cartoon-envelope.json

# 5. contact sheet and the tables in this file
python3 code/contact_sheet.py --out cartoons/contact-sheet.png
python3 code/report_tables.py

# single cartoon, any category / cut / fidelity
python3 code/render_cartoon.py --category normal --seed 12 --cut along --out /tmp/x
python3 code/render_cartoon.py --category hpylori_gastritis --seed 21 --cut oblique --fidelity 3 --out /tmp/x

# parameter sweep against the envelope (what section 5 was produced with)
python3 code/tune.py --seeds 11 --cuts across along oblique

9. Files

Download public Markdown export