# 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:

```python
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

| metric | normal | hpylori_gastritis | intestinal_metaplasia | mixed |
|---|---|---|---|---|
| `ring_density_per_mm2` | 87 (39-160) | 93 (49-161) | 120 (77-174) | 115 (76-143) |
| `median_ring_area_um2` | 392 (313-520) | 399 (320-489) | 389 (315-481) | 417 (315-582) |
| `lumen_tissue_ratio` | 0.124 (0.036-0.261) | 0.145 (0.056-0.293) | 0.183 (0.057-0.373) | 0.131 (0.052-0.319) |
| `nuclear_density_per_mm2` | 12293 (9318-18854) | 10569 (9016-14673) | 11679 (9132-14990) | 11012 (8755-13757) |
| `stroma_fraction` | 0.129 (0.065-0.244) | 0.172 (0.087-0.293) | 0.197 (0.118-0.332) | 0.161 (0.098-0.311) |
| `ring_with_lumen_fraction` | 0.876 (0.380-1.000) | 0.765 (0.294-1.000) | 0.745 (0.289-1.000) | 0.775 (0.182-1.000) |
| `tissue_fraction` | 0.982 (0.963-0.996) | 0.984 (0.917-0.998) | 0.985 (0.928-0.998) | 0.987 (0.922-0.997) |
| `epithelium_band_fraction` | 0.871 (0.756-0.935) | 0.828 (0.707-0.913) | 0.803 (0.668-0.882) | 0.839 (0.689-0.902) |
| `median_nucleus_area_um2` | 14.7 (10.7-22.7) | 20.2 (12.8-24.0) | 18.9 (13.7-24.9) | 20.2 (15.0-25.0) |
| `background_fraction` | 0.000 (0.000-0.000) | 0.000 (0.000-0.004) | 0.000 (0.000-0.002) | 0.000 (0.000-0.002) |

### Real envelope, held-out only

| metric | normal | hpylori_gastritis | intestinal_metaplasia | mixed |
|---|---|---|---|---|
| `ring_density_per_mm2` | 101 (86-143) | 89 (61-124) | 120 (80-156) | 101 (76-115) |
| `median_ring_area_um2` | 442 (360-544) | 365 (331-470) | 438 (345-493) | 441 (341-548) |
| `lumen_tissue_ratio` | 0.125 (0.106-0.133) | 0.153 (0.121-0.289) | 0.162 (0.118-0.197) | 0.129 (0.089-0.204) |
| `nuclear_density_per_mm2` | 12913 (12185-17470) | 13183 (9480-17609) | 13237 (11893-14526) | 12051 (9093-13274) |
| `stroma_fraction` | 0.138 (0.098-0.240) | 0.207 (0.125-0.290) | 0.196 (0.114-0.299) | 0.150 (0.097-0.308) |

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:

| addition | parameters | what it does |
|---|---|---|
| pit / gland zoning | `pit_depth_frac`, `pit_depth_jitter`, `pit_transition`, `pit_outer_scale`, `pit_lumen_scale`, `gland_outer_scale`, `gland_lumen_scale` | `_depth_profile(z, tube)` returns outer- and lumen-radius multipliers, so a short-pit oxyntic gland, a long-pit antral gland and a hyperplastic gastritis pit come out of one code path |
| depth taper | `taper_with_depth`, `base_lumen_pinch` | tubes narrow towards the muscularis; visible in `along` cuts, as the brief requires |
| pit tortuosity | `pit_wobble_gain` | extra centreline wobble that decays below the pit zone (foveolar hyperplasia) |
| muscularis mucosae | `mm_thickness`, `mm_nuclei_per_mm2`, `mm_nuc_radius`, `mm_nuc_aspect` | everything below `slab_depth` becomes a fibrous band with elongated nuclei whose long axes lie in the xy plane, i.e. horizontal in the image. Labels 5/6 only |
| surface mucus | `surface_mucus_thickness`, `surface_mucus_irreg` | a wavy band of label 3 (`goblet_mucin`) sitting on the epithelium; where B1's organisms live |
| surface damage | `surface_damage_frac` | 62-um blocks of surface where the epithelial band is absent |
| lymphoid follicles | `follicles_per_mm2`, `follicle_radius`, `follicle_depth_frac`, `follicle_nuclei_per_mm2`, `follicle_nuc_radius`, `germinal_centre_frac` | 3-D balls of dense small nuclei with a paler germinal centre; glands that run into one are truncated above it |
| intraepithelial neutrophils | `intraepithelial_nuclei_per_mm2` | small dark nuclei placed inside pit epithelium (label 6, `cell_kind` = neutrophil) |
| oxyntic cell types | `parietal_frac`, `parietal_depth_frac`, `chief_frac`, `chief_depth_frac` | 2x2 blocks of the wall-cell grid merge into one large parietal cell (about 15 x 13 um) with a round central nucleus; chief cells at the gland base |
| nuclear dropout | `epi_nucleus_dropout` | cells whose nucleus misses the 3-um section, so the basal palisade is not a perfect ring |
| frame policy | `slice(..., frame=...)` | `full` (along: surface at top, muscularis at bottom), `upper` (oblique), `deep` (across), `surface` |
| cell kinds | `SliceResult.cell_kind` | new optional field, `KIND_NAMES` of 12 renderer hints. **The 9-label `LABEL_NAMES` vocabulary is unchanged and is the only thing a downstream model sees.** |

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.

| iter | change | inside | deviation |
|---|---|---|---|
| baseline | pre-A1 code, `--surface`, same metric, same size | 1.00 / 5 | 4.438 |
| 1-4 | (scored at 0.5 um/px -- invalid, discarded; see section 2) | - | - |
| 5-7 | first valid full-scale readings after the architecture rewrite: nuclei resized (semi-axes 3.15/2.20/2.40 -> 1.95/1.00/1.35 um before section inflation), gland packing tightened per category, per-cell cytoplasmic basophilia added (runs superseded before completing) | - | - |
| 8 | central oxyntic nuclei (`nuc_basal_frac` 0.22 -> 0.40 body, 0.24 -> 0.36 IM/mixed) | 3.00 / 5 | 2.133 |
| 9 | fine hematoxylin speckle over cytoplasm and stroma; gland calibres reduced | 3.07 / 5 | 1.558 |
| 10 | `epi_nucleus_dropout` 0.22; jittered lattice for stromal nuclei | 3.13 / 5 | 1.638 |
| 11 | `across` tilt 0-10 -> 4-16 deg; pit lumen scales cut (the `across` frame lands in the pit zone for gastritis and mixed); more lattice dropout; `epi_nucleus_dropout` 0.15 | 3.27 / 5 | 1.413 |
| 12 | per-category gland calibre trim | 3.13 / 5 | 1.272 |
| 13 (shipped) | palette rebalanced towards eosin after visual review; speckle gain 1.22 -> 0.46 | 3.20 / 5 (60 cartoons) | 1.643 |

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)

| category | subtype(s) | cut | n | `ring_density_per_mm2` | `median_ring_area_um2` | `lumen_tissue_ratio` | `nuclear_density_per_mm2` | `stroma_fraction` | inside |
|---|---|---|---|---|---|---|---|---|---|
| normal | antrum+body | across | 5 | **315** | **644** | 0.088 | 10034 | **0.302** | 2/5 |
| normal | antrum+body | along | 5 | 98 | 377 | 0.107 | 11812 | **0.308** | 4/5 |
| normal | antrum+body | oblique | 5 | **230** | **831** | 0.138 | 10101 | **0.313** | 2/5 |
| hpylori_gastritis | antrum | across | 5 | **247** | **558** | 0.077 | 12754 | 0.197 | 3/5 |
| hpylori_gastritis | antrum | along | 5 | 93 | **718** | 0.094 | 14228 | 0.217 | 4/5 |
| hpylori_gastritis | antrum | oblique | 5 | **172** | **669** | 0.129 | 10807 | 0.255 | 3/5 |
| intestinal_metaplasia | intest | across | 5 | **250** | **787** | 0.127 | 10053 | 0.300 | 3/5 |
| intestinal_metaplasia | intest | along | 5 | 105 | 381 | 0.107 | 12660 | 0.310 | 5/5 |
| intestinal_metaplasia | intest | oblique | 5 | 170 | **1019** | 0.140 | 10395 | 0.304 | 4/5 |
| mixed | mixed | across | 5 | **246** | **792** | 0.098 | 10744 | 0.281 | 3/5 |
| mixed | mixed | along | 5 | 85 | **597** | 0.098 | 13735 | 0.280 | 4/5 |
| mixed | mixed | oblique | 5 | **176** | **947** | 0.137 | 10155 | 0.308 | 3/5 |

### Cartoon set a1, reported-not-tuned

| category | subtype(s) | cut | n | `ring_with_lumen_fraction` | `tissue_fraction` | `epithelium_band_fraction` | `median_nucleus_area_um2` | `background_fraction` | inside |
|---|---|---|---|---|---|---|---|---|---|
| normal | antrum+body | across | 5 | 0.477 | 0.980 | **0.698** | 20.4 | **0.001** | 3/5 |
| normal | antrum+body | along | 5 | **0.232** | **0.939** | **0.692** | 16.9 | **0.040** | 1/5 |
| normal | antrum+body | oblique | 5 | 0.688 | **0.929** | **0.687** | 20.0 | **0.040** | 2/5 |
| hpylori_gastritis | antrum | across | 5 | 0.736 | 0.980 | 0.803 | 13.8 | 0.001 | 5/5 |
| hpylori_gastritis | antrum | along | 5 | 0.600 | 0.942 | 0.783 | 13.3 | **0.041** | 4/5 |
| hpylori_gastritis | antrum | oblique | 5 | 0.812 | 0.931 | 0.745 | 16.0 | **0.041** | 4/5 |
| intestinal_metaplasia | intest | across | 5 | 0.881 | 0.978 | 0.700 | 20.4 | 0.001 | 5/5 |
| intestinal_metaplasia | intest | along | 5 | **0.222** | 0.938 | 0.690 | 16.4 | **0.041** | 3/5 |
| intestinal_metaplasia | intest | oblique | 5 | 0.913 | 0.930 | 0.696 | 20.0 | **0.043** | 4/5 |
| mixed | mixed | across | 5 | 0.689 | 0.980 | 0.719 | 18.2 | 0.001 | 5/5 |
| mixed | mixed | along | 5 | 0.412 | 0.943 | 0.720 | **14.2** | **0.036** | 3/5 |
| mixed | mixed | oblique | 5 | 0.824 | 0.923 | 0.692 | 19.1 | **0.045** | 4/5 |

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):

| | inside | deviation (band-widths outside, summed over 5 metrics) |
|---|---|---|
| pre-A1 baseline (12 cartoons, same metric, same size) | 1.00 / 5 | 4.438 |
| **A1 set a1 (60 cartoons)** | **3.20 / 5** | **1.643** |
| normal (body + antrum) | 2.80 / 5 | 1.676 |
| hpylori_gastritis | 3.33 / 5 | 1.339 |
| intestinal_metaplasia | 3.60 / 5 | 2.065 |
| mixed | 3.07 / 5 | 1.490 |
| normal, body seeds only (n=6) | 3.00 / 5 | 1.697 |
| normal, antrum seeds only (n=9) | 2.67 / 5 | 1.662 |

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)

| fidelity | `ring_density_per_mm2` | `median_ring_area_um2` | `lumen_tissue_ratio` | `nuclear_density_per_mm2` | `stroma_fraction` | `tissue_fraction` | inside |
|---|---|---|---|---|---|---|---|
| f0 (n=5) | 229 | 465 | 0.145 | 8214 | 0.183 | 0.999 | 3/5 |
| f1 (n=5) | 269 | 766 | 0.142 | 8728 | 0.306 | 1.000 | 2/5 |
| f2 (n=5) | 250 | 787 | 0.127 | 10053 | 0.300 | 0.978 | 3/5 |
| f3 (n=5) | 252 | 759 | 0.122 | 10059 | 0.301 | 0.978 | 3/5 |

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)

| metric | b1 median | a1 gastritis oblique median | real 10-90% |
|---|---|---|---|
| `ring_density_per_mm2` | 130 | 172 | 49-161 |
| `median_ring_area_um2` | 798 | 669 | 320-489 |
| `lumen_tissue_ratio` | 0.205 | 0.129 | 0.056-0.293 |
| `nuclear_density_per_mm2` | 12300 | 10807 | 9016-14673 |
| `stroma_fraction` | 0.296 | 0.255 | 0.087-0.293 |
| `tissue_fraction` | 0.900 | 0.931 | 0.917-0.998 |
| `ring_with_lumen_fraction` | 0.900 | 0.812 | 0.294-1.000 |

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

```sh
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

| path | what |
|---|---|
| `code/tissue3d.py` | extended 3-D tissue model (per-category architecture, muscularis, follicles, surface mucus, cell kinds) |
| `code/render_cartoon.py` | renderer with the 0..3 fidelity ladder and five category presets |
| `code/render_set.py` | deterministic set renderer for a1 / d1 / e2 / b1, with SHA-256 manifests and `--verify` |
| `code/cartoon_metrics.py` | image-only morphometrics, identical path for real fields and cartoons |
| `code/ring_topology.py` | copy of the fullset ring metric (unchanged, md5 3fa4556d) |
| `code/sydney_qa.py`, `code/sydney_qa_v1.json` | copies another package placed in `code/`; byte-identical to the canonical SGH repo versions (md5 e771b5ea / aa8cdf2b). `cartoon_metrics.py` prefers these so the fleet can ship `code/` alone |
| `code/tune.py` | render-and-score loop against the real envelope |
| `code/contact_sheet.py`, `code/report_tables.py` | figure and tables for this file |
| `morphometrics/real-metrics.csv`, `morphometrics/real-envelope.json` | the real envelope |
| `morphometrics/baseline-cartoon-metrics.csv` | the pre-A1 cartoons, same metric |
| `morphometrics/cartoon-metrics.csv`, `morphometrics/cartoon-envelope.json` | the shipped cartoons |
| `cartoons/{a1,d1,e2,b1}/` | the rendered sets, each with `MANIFEST.sha256.json` |
| `cartoons/contact-sheet.png` | real field vs subtype vs three cuts, one row per category |