Spaces:
Running on Zero
Running on Zero
Download inference/conddiff_core.py from ALIUD1/braingen-backend: direct link, hf CLI and curl.
- Browser
- Download file 47.3 kB
-
https://huggingface.co/spaces/ALIUD1/braingen-backend/resolve/main/inference/conddiff_core.py
- Command line
-
hf download hf://spaces/ALIUD1/braingen-backend/inference/conddiff_core.py
-
curl -L -o conddiff_core.py https://huggingface.co/spaces/ALIUD1/braingen-backend/resolve/main/inference/conddiff_core.py
47.3 kB
| """conddiff_core.py -- the ONE definition of braingen_CondDiffuser_BraTS_v1's image maths. | |
| WHY THIS FILE EXISTS | |
| -------------------- | |
| Two completely different programs, running on two completely different machines, have to | |
| produce the SAME image for the same four dropdown choices: | |
| 1. the CLUSTER RENDERER (Great Lakes, GPU, 200 DDIM steps) which pre-renders the finite | |
| gallery of images the website ships, and | |
| 2. the WEB BACKEND (AWS Lightsail, 0.25 vCPU / 1 GB) which serves them, and which can also | |
| run the model live if it is ever given a machine that can afford to. | |
| If those two disagree by even one constant -- a different PROB_TH, a differently seeded random | |
| field, a Gaussian blur with a different boundary mode -- then the site is advertising a | |
| parameter it did not actually honour. The gallery would say "Frontal, Large" under a picture | |
| that the live path would have drawn somewhere else, at a different size, and nobody would ever | |
| see an error. That is a correctness failure, not a cosmetic one, and it is completely silent. | |
| The defence is that BOTH programs import their maths from this file, and this file exists at | |
| two paths that are BYTE-IDENTICAL: | |
| Summer2026/src/conddiff_core.py (research repo, cluster side) | |
| Brain-Image-Generator/backend/inference/conddiff_core.py (web repo, server side) | |
| Two copies rather than one shared package because the two repos deploy separately: the web | |
| repo is `COPY . .`-ed into a Docker image that has no access to the research repo, and the | |
| research repo runs inside a Slurm job that has no access to the web repo. A git submodule or a | |
| pip package would solve it more elegantly and would also mean the deployment can no longer be | |
| built from a single `docker build` of one repo. So: duplicate the file, and make the | |
| duplication CHECKABLE. | |
| # verify the two copies are identical before trusting any rendered gallery | |
| sha256sum Summer2026/src/conddiff_core.py \ | |
| Brain-Image-Generator/backend/inference/conddiff_core.py | |
| # PowerShell (forward slashes on purpose -- a backslash inside this docstring would be a | |
| # Python escape sequence, and PowerShell accepts "/" as a path separator anyway) | |
| Get-FileHash Summer2026/src/conddiff_core.py, | |
| Brain-Image-Generator/backend/inference/conddiff_core.py -Algorithm SHA256 | |
| The cluster renderer writes its copy's sha256 into the gallery manifest, and the backend can | |
| compare that against the sha256 of the file it is actually running. A divergence is then a | |
| loud, mechanical fact instead of an argument about whether two files "look the same". | |
| RULES FOR EDITING THIS FILE -- ALL THREE ARE LOAD-BEARING | |
| --------------------------------------------------------- | |
| 1. MODULE SCOPE IMPORTS numpy AND THE STANDARD LIBRARY, AND NOTHING ELSE. | |
| torch, diffusers, PIL and anything that reaches for a checkpoint are imported LAZILY, | |
| inside the one function that needs them. Reason: the web backend's image_generation.py | |
| imports this chain at the TOP of the file, next to the four working GAN modules. In gallery | |
| mode the server never runs the model at all, and it must be able to import this module | |
| without torch being exercised -- both because the micro instance cannot afford to page in | |
| ~341 MB of weights, and because an exception at import time here would take the five | |
| working GAN models offline with it. | |
| 2. NOTHING AT MODULE SCOPE MAY RAISE. No file reads, no env parsing that can throw, no | |
| asserts on the environment. Same reason as (1). | |
| 3. NO PATHS, NO os.getcwd(), NO os.environ, NO REPO LAYOUT ASSUMPTIONS. | |
| Paths differ between the two repos (the cluster reads /scratch, the container reads /app) | |
| and are the CALLER's business. Anything path-shaped belongs in conddiff_inference.py or in | |
| the renderer script, not here. This is what lets the same bytes import cleanly from either | |
| repo. | |
| WHAT IS DELIBERATELY *NOT* IN HERE | |
| ---------------------------------- | |
| * asset discovery, checkpoint loading, the strict=True load and the parameter-count | |
| assertion -> conddiff_inference.py (web) / the renderer (cluster); both need paths | |
| * device selection, thread count, DDIM step count -> deployment decisions | |
| * the conditioning bank manifest and slice admissibility -> the two banks have different | |
| formats (CSV on the server, JSON on the cluster) and different MIN_BRAIN policies | |
| * Supabase publishing, the database record -> web only | |
| The dividing line is: if changing it changes THE PICTURE, it lives here. If it only changes | |
| where bytes come from or where they go, it does not. | |
| PROVENANCE | |
| ---------- | |
| Everything numerical below is a faithful port of the research repo's scripts/augment_tumor.py | |
| (mask synthesis, the DDIM loop, the channel indexing, the [-1,1] <-> [0,1] rescaling) and | |
| scripts/06_captions_v2.py (the small/moderate/large and inferior/middle/superior vocabulary). | |
| The only intentional deviations from augment_tumor.py are: | |
| (a) AREA_FRAC is a parameter rather than a module constant, so the website's Tumour Size | |
| control can drive it (AREA_FRAC_BY_SIZE below), and | |
| (b) scipy.ndimage.gaussian_filter and scipy.ndimage.label are reimplemented in pure numpy | |
| (SECTION 2), so the deployed container does not need scipy. Both reimplementations | |
| reproduce scipy's DEFAULTS exactly; see their docstrings for the specific defaults and | |
| why each one matters. | |
| """ | |
| # --- standard library + numpy. NOTHING ELSE AT MODULE SCOPE. See rule (1) above. ------------- | |
| import io | |
| import numpy as np | |
| # ============================================================================================= | |
| # SECTION 1 -- CONSTANTS | |
| # | |
| # Every constant here is copied verbatim from the research repo. Changing any of them changes | |
| # the science, not the plumbing -- and changes it for BOTH the pre-rendered gallery and the | |
| # live path, which is exactly the point of the file. | |
| # ============================================================================================= | |
| # Lobe order is fixed by scripts/03_preprocess.py:10 in the research repo, because that is the | |
| # order the six atlas maps were stacked into channels 3..8 of every preprocessed slice. The | |
| # website's Lobe dropdown maps onto THIS index order; permuting it silently puts the lesion in | |
| # the wrong lobe, with no error and a perfectly plausible-looking picture. | |
| LOBES = ["frontal", "parietal", "temporal", "occipital", "cerebellum", "insula"] | |
| ATLAS0 = 3 # in the 9-channel stack, atlas lobe k lives at channel 3 + k | |
| # --- gates that decide whether a slice can host a lesion at all (augment_tumor.py:30-32) ---- | |
| PROB_TH = 0.4 # "inside this lobe" = atlas probability above this | |
| MIN_LOBE = 500 # the target lobe must be genuinely prominent in the chosen slice | |
| # WHY 0.4 AND NOT SOMETHING ELSE: 03_preprocess.py:55 does `atlas = atlas / atlas.max()` where | |
| # `atlas` is the stacked (6, 240, 240, 155) array. That is a SINGLE global scalar across all | |
| # six lobes and all 155 slices -- not a per-lobe max. So only whichever lobe holds the global | |
| # maximum ever reaches 1.0 and the others top out lower. PROB_TH is calibrated against exactly | |
| # that scaling. A bank built with any other atlas normalisation silently changes every lesion | |
| # size and every MIN_LOBE decision. | |
| # | |
| # (MIN_BRAIN -- the "is this a full mid-axial slice or a tiny inferior sliver" gate -- is | |
| # deliberately NOT here. It is the one threshold the two sides are allowed to disagree on: it | |
| # is COSMETIC, it is overridable by an env var on the server, and the cerebellum cells cannot | |
| # be filled without lowering it. It lives with the bank code on each side.) | |
| # --- tumour SIZE is RELATIVE to the lobe, not a fixed radius (augment_tumor.py:35-37) ------- | |
| AREA_FRAC_DEFAULT = (0.15, 0.35) # lesion area as a fraction of the lobe's area IN THIS SLICE | |
| CORE_FRAC = 0.30 # enhancing core as a fraction of the lesion's area | |
| MIN_AREA = 60 # px; below this a "tumour" is too small to be meaningful | |
| # --- tumour SHAPE is organic + atlas-conforming (augment_tumor.py:39-41) -------------------- | |
| COMPACT = 0.95 # >1 = looser/more sprawling blob, <1 = tighter around the seed | |
| NOISE_SIGMA = 6.0 # smoothing of the random field: larger = smoother, blobbier edges | |
| NOISE_AMP = 0.9 # 0 = perfect ellipse, ~1 = strongly irregular outline | |
| # --- the paper's published vocabulary (scripts/06_captions_v2.py:42,45) --------------------- | |
| # 1 px = 1 mm^2 at BraTS's 1 mm isotropic resolution, so these thresholds are ~mm^2. | |
| SMALL_MAX, LARGE_MIN = 500, 2000 | |
| INFERIOR_MAX, SUPERIOR_MIN = 60, 100 | |
| # --- mapping the website's four dropdowns onto the algorithm -------------------------------- | |
| # Note the web repo's existing convention, established at cgan_inference_v2.py:19: the params | |
| # KEY is British ("tumour") but the VALUE is American ("With Tumor"). These dicts are keyed by | |
| # the EXACT strings the frontend POSTs, so they must not be "tidied". | |
| UI_TUMOUR = {"With Tumor": True, "Without Tumor": False} | |
| UI_LOBE = {"Frontal": "frontal", "Parietal": "parietal", "Temporal": "temporal", | |
| "Occipital": "occipital", "Cerebellum": "cerebellum", "Insula": "insula"} | |
| UI_LEVEL = {"Inferior": "inferior", "Middle": "middle", "Superior": "superior"} | |
| UI_SIZE = {"Small": "small", "Moderate": "moderate", "Large": "large"} | |
| # The canonical orderings, derived from the dicts above rather than retyped, so a new dropdown | |
| # option cannot be added in one place and forgotten in the other. Used by iter_cells() to | |
| # enumerate the gallery and by the renderer to lay out its progress table. | |
| LEVELS = ["inferior", "middle", "superior"] | |
| SIZES = ["small", "moderate", "large"] | |
| # Tumour Size modulates AREA_FRAC -- the fraction of the LOBE's in-slice area the lesion | |
| # occupies. Keeping it relative (rather than an absolute pixel target) is what makes the | |
| # control robust: a small lobe simply cannot host an oversized lesion, so the hard containment | |
| # constraint in synth_mask can never be violated by an ambitious size request. | |
| # "moderate" is the paper's published default, AREA_FRAC = (0.15, 0.35). | |
| AREA_FRAC_BY_SIZE = { | |
| "small": (0.05, 0.12), | |
| "moderate": (0.15, 0.35), | |
| "large": (0.40, 0.60), | |
| } | |
| # ============================================================================================= | |
| # SECTION 2 -- SCIPY-FREE REIMPLEMENTATIONS OF THE TWO scipy.ndimage CALLS | |
| # | |
| # augment_tumor.py:21 imports gaussian_filter and label from scipy.ndimage. Those are the ONLY | |
| # two scipy calls anywhere on the inference path. Rather than add scipy to the web container | |
| # (~35 MB, plus a dependency-resolver run against numpy==1.24.3 in a shared image that five | |
| # working models depend on) they are reimplemented here in pure numpy. | |
| # | |
| # THE REASON THEY LIVE IN THE *SHARED* FILE RATHER THAN ONLY IN THE BACKEND: if the cluster | |
| # renderer kept calling scipy while the backend called these, the pre-rendered gallery and the | |
| # live path would be computing two different random fields from the same seed. The images | |
| # would both look fine and they would not be the same image. So the cluster gives up scipy too | |
| # and both sides run this code. Both functions are written to reproduce scipy's DEFAULTS | |
| # exactly, which is what makes that substitution safe. | |
| # ============================================================================================= | |
| def _gaussian_blur(img, sigma): | |
| """Isotropic Gaussian blur == scipy.ndimage.gaussian_filter(img, sigma) with defaults. | |
| WHY IT IS ONLY ~15 LINES: a 2-D Gaussian is SEPARABLE, i.e. | |
| G_2d(x, y) = G_1d(x) * G_1d(y) | |
| so blurring along axis 0 and then along axis 1 with the same 1-D kernel gives exactly the | |
| same result as a true 2-D convolution, at O(2r) work per pixel instead of O(r^2). | |
| Matching scipy's defaults, which is the whole point of writing this by hand: | |
| * radius = int(truncate * sigma + 0.5) with truncate = 4.0 -> for sigma=6 that is 24, | |
| i.e. a 49-tap kernel. Four standard deviations captures >99.99% of the mass. | |
| * kernel weights exp(-0.5 * (x/sigma)^2), then normalised to sum to 1 (so a constant | |
| image blurs to itself and the output keeps the input's overall scale). | |
| * boundary handling `mode='reflect'`, which in scipy means (d c b a | a b c d) -- the | |
| edge sample is DUPLICATED. numpy's np.pad calls that 'symmetric'; numpy's own | |
| 'reflect' is scipy's 'mirror' and is NOT the same thing. Getting this backwards | |
| changes the outermost ~24 pixels, which for us is the zero frame around the brain, so | |
| it would be invisible in a picture and wrong in the numbers. | |
| img : (H, W) float array | |
| sigma : float, standard deviation in pixels | |
| returns (H, W) float32 | |
| """ | |
| radius = int(4.0 * sigma + 0.5) # 24 for sigma = 6.0 | |
| x = np.arange(-radius, radius + 1, dtype=np.float64) # (2r+1,) tap offsets | |
| k = np.exp(-0.5 * (x / sigma) ** 2) # (2r+1,) unnormalised weights | |
| k /= k.sum() # normalise -> sums to 1.0 | |
| out = np.asarray(img, dtype=np.float64) # (H, W); accumulate in f64 | |
| for axis in (0, 1): # separable: one pass per axis | |
| pad_width = [(0, 0), (0, 0)] | |
| pad_width[axis] = (radius, radius) | |
| padded = np.pad(out, pad_width, mode="symmetric") # (H+2r, W) then (H, W+2r) | |
| acc = np.zeros_like(out) # (H, W) | |
| n = out.shape[axis] | |
| for i, w in enumerate(k): # slide the kernel, tap by tap | |
| sl = [slice(None), slice(None)] | |
| sl[axis] = slice(i, i + n) # window of length n at offset i | |
| acc += w * padded[tuple(sl)] | |
| out = acc | |
| return out.astype(np.float32) # (H, W) float32 | |
| def _largest_connected_component(blob): | |
| """Keep only the largest 4-connected component of a boolean mask. | |
| Replaces the scipy idiom at augment_tumor.py:95-98: | |
| lab, n = label(blob) | |
| if n > 1: | |
| sizes = np.bincount(lab.ravel()); sizes[0] = 0 | |
| blob = lab == sizes.argmax() | |
| WHY 4-CONNECTIVITY: scipy.ndimage.label's default structuring element is | |
| generate_binary_structure(2, 1), the plus-shape -- pixels touching only at a corner are | |
| NOT the same component. We use the same four neighbours (up, down, left, right). | |
| WHY THIS IS DONE WITH AN EXPLICIT STACK RATHER THAN VECTORISED numpy: the loop only ever | |
| visits pixels that are True, and the caller has already capped that at n_les (a few | |
| hundred to a few thousand pixels), so this is microseconds. A vectorised | |
| label-propagation would need O(blob diameter) full-array passes and is both slower and | |
| harder to read. | |
| NOTE ON TIE-BREAKING, because it is the kind of thing that quietly diverges: when two | |
| components are exactly the same size we keep the FIRST one encountered, and the encounter | |
| order is np.nonzero's row-major order. `>` (not `>=`) in the comparison below is what | |
| fixes that. scipy's own label+argmax idiom also keeps the lowest label, which is likewise | |
| row-major first, so the two agree on ties as well as on the common case. | |
| blob : (H, W) bool | |
| returns (H, W) bool -- the single largest component (or an all-False array if blob is empty) | |
| """ | |
| h, w = blob.shape | |
| seen = np.zeros((h, w), dtype=bool) # pixels already assigned to some component | |
| best = np.zeros((h, w), dtype=bool) # the biggest component found so far | |
| best_size = 0 | |
| ys, xs = np.nonzero(blob) # only True pixels can start a component | |
| for sy, sx in zip(ys.tolist(), xs.tolist()): | |
| if seen[sy, sx]: | |
| continue | |
| # --- flood fill this component with an explicit LIFO stack (no recursion: Python's | |
| # --- default recursion limit is 1000 and a lesion can be thousands of pixels) ------- | |
| stack = [(sy, sx)] | |
| seen[sy, sx] = True | |
| component = [(sy, sx)] | |
| while stack: | |
| cy, cx = stack.pop() | |
| for ny, nx in ((cy - 1, cx), (cy + 1, cx), (cy, cx - 1), (cy, cx + 1)): | |
| if 0 <= ny < h and 0 <= nx < w and blob[ny, nx] and not seen[ny, nx]: | |
| seen[ny, nx] = True | |
| stack.append((ny, nx)) | |
| component.append((ny, nx)) | |
| if len(component) > best_size: | |
| best_size = len(component) | |
| best = np.zeros((h, w), dtype=bool) | |
| cy_arr = np.fromiter((p[0] for p in component), dtype=np.intp, count=len(component)) | |
| cx_arr = np.fromiter((p[1] for p in component), dtype=np.intp, count=len(component)) | |
| best[cy_arr, cx_arr] = True | |
| return best | |
| # ============================================================================================= | |
| # SECTION 3 -- THE PAPER'S VOCABULARY AND THE UI -> ALGORITHM MAPPING | |
| # ============================================================================================= | |
| def size_word(n): | |
| """Paper's Small/Moderate/Large buckets by lesion AREA in px (06_captions_v2.py:57).""" | |
| return "small" if n < SMALL_MAX else ("large" if n > LARGE_MIN else "moderate") | |
| def level_word(z): | |
| """Paper's Inferior/Middle/Superior buckets by slice index z (06_captions_v2.py:61).""" | |
| return "inferior" if z < INFERIOR_MAX else ("superior" if z > SUPERIOR_MIN else "middle") | |
| def params_to_spec(tumour, lobe, slice_location, tumour_size): | |
| """Turn the four raw dropdown strings into a validated generation specification. | |
| THIS IS THE FUNNEL. Both the cluster renderer and the web backend go through it, so the | |
| renderer's idea of "cell (Frontal, Middle, Large)" and the backend's idea of the same | |
| request are the same object, produced by the same code. cell_id() below then names it. | |
| WHY THIS IS TOLERANT RATHER THAN STRICT: the frontend has five separate registration sites | |
| and it is entirely possible to ship a build where the model is selectable but one of its | |
| params is still an empty string. Every other model in the web backend does bare | |
| `params["tumour"]` indexing, which raises KeyError -> image_generation.py catches it -> | |
| the API returns HTTP 200 with an empty list -> the user sees a green "Success" toast and a | |
| blank viewer. Substituting a documented default and RECORDING the substitution is strictly | |
| more useful than that silence. | |
| Returns a dict: | |
| with_tumour : bool | |
| lobe : str | None -- canonical lowercase lobe name, None when no tumour | |
| lobe_idx : int | None -- index into LOBES, so the atlas channel is ATLAS0+lobe_idx | |
| level : str -- "inferior" | "middle" | "superior" | |
| size : str | None -- "small" | "moderate" | "large", None when no tumour | |
| substituted : list[str] -- names of any fields that fell back to a default | |
| """ | |
| substituted = [] | |
| with_tumour = UI_TUMOUR.get(tumour) | |
| if with_tumour is None: | |
| with_tumour = True # the site's own default | |
| substituted.append("tumour") | |
| level = UI_LEVEL.get(slice_location) | |
| if level is None: | |
| # sliceLocation is shared state with the cGAN models, whose Sagittal/Coronal | |
| # orientations can leave it at "Left"/"Anterior"/etc. Those are meaningless here (this | |
| # model is axial-only), so coerce to the middle of the brain rather than fail. | |
| level = "middle" | |
| substituted.append("slice_location") | |
| if not with_tumour: | |
| # Lobe and size are genuinely meaningless without a tumour: there is no lesion to | |
| # place and nothing to size. Return None rather than a misleading default so the | |
| # recorded params cannot claim we honoured a control we ignored. This is also what | |
| # collapses the parameter space from 2*6*3*3 = 108 to 57 real cells (see iter_cells). | |
| return {"with_tumour": False, "lobe": None, "lobe_idx": None, | |
| "level": level, "size": None, "substituted": substituted} | |
| lobe_key = UI_LOBE.get(lobe) | |
| if lobe_key is None: | |
| lobe_key = "frontal" | |
| substituted.append("lobe") | |
| size_key = UI_SIZE.get(tumour_size) | |
| if size_key is None: | |
| size_key = "moderate" | |
| substituted.append("tumour_size") | |
| return {"with_tumour": True, "lobe": lobe_key, "lobe_idx": LOBES.index(lobe_key), | |
| "level": level, "size": size_key, "substituted": substituted} | |
| # ============================================================================================= | |
| # SECTION 4 -- CELL IDENTITY: THE NAME A REQUEST AND A PRE-RENDERED IMAGE SHARE | |
| # | |
| # The whole gallery design rests on one observation: the user-visible parameter space is | |
| # FINITE and small. Conditioning does not come from the user, it comes from a fixed shipped | |
| # bank, so the only things a visitor can vary are the four dropdowns. That is | |
| # | |
| # Tumour(2) x Lobe(6) x Level(3) x Size(3) = 108 nominal combinations | |
| # | |
| # but Lobe and Size are meaningless when Tumour = "Without Tumor" (there is no lesion to place | |
| # and nothing to size -- params_to_spec returns None for both), so those 54 nominal | |
| # combinations collapse into 3 real ones, one per level. The real space is | |
| # | |
| # 6*3*3 = 54 with-tumour cells + 3 without-tumour cells = 57 cells | |
| # | |
| # 57 cells x K seed variants of a 256x256 grayscale PNG is a few megabytes. Rendering them | |
| # once on a GPU at the paper's full 200 steps and shipping the pictures is strictly better | |
| # than rendering them live on 0.25 vCPU at a degraded 50 steps -- better images, no torch at | |
| # request time, no 341 MB checkpoint in a 1 GB container, and no multi-minute request blocking | |
| # the uvicorn event loop while the health check times out. | |
| # | |
| # For that to work the renderer and the server must agree on the NAME of each cell, forever | |
| # and across machines. That is this function. | |
| # ============================================================================================= | |
| def cell_id(spec): | |
| """Stable filename-safe key for one cell of the parameter space. | |
| FORMAT (this is a contract; the gallery on disk is keyed by these strings): | |
| with tumour "with_<lobe>_<level>_<size>" e.g. "with_frontal_middle_moderate" | |
| without tumour "without_<level>" e.g. "without_middle" | |
| where <lobe> is one of LOBES, <level> one of LEVELS and <size> one of SIZES -- all | |
| lowercase ASCII, all already canonicalised by params_to_spec. The pieces are joined with | |
| "_" and no piece contains "_", so the string also parses back unambiguously by splitting. | |
| PROPERTIES THAT MATTER, AND WHY: | |
| * PURE. It is a function of the four user choices and nothing else -- no seed, no | |
| timestamp, no bank filename, no dict iteration order, no hash of anything. Rendering | |
| the gallery twice, on two machines, in two years, produces the same 57 names. A | |
| content hash (say sha256 of the spec) would also be stable but would be unreadable in | |
| a directory listing and would change if a field were ever added to the spec dict. | |
| * TOTAL over the space the UI can express: params_to_spec canonicalises unknown input to | |
| a default rather than raising, so every request maps to exactly one of the 57 names. | |
| * FILENAME-SAFE on every platform (lowercase letters and underscores only), because it | |
| is used directly as a directory name on Windows, Linux and inside the container, and | |
| as a JSON object key in the gallery manifest. | |
| * The "without" form deliberately OMITS lobe and size rather than writing | |
| "without_none_middle_none". Omitting them is the honest encoding: those controls were | |
| not honoured, so they are not in the name, and the same three files are correctly | |
| reused no matter what the greyed-out dropdowns happened to be showing. | |
| spec : the dict returned by params_to_spec() | |
| returns str | |
| """ | |
| if not spec["with_tumour"]: | |
| return "without_{}".format(spec["level"]) | |
| return "with_{}_{}_{}".format(spec["lobe"], spec["level"], spec["size"]) | |
| def iter_cells(): | |
| """Enumerate all 57 cells, in a fixed order, as (cell_id, ui_choices) pairs. | |
| WHY IT IS HERE AND NOT IN THE RENDERER: the renderer uses it to decide what to draw and | |
| the backend uses it to report which cells the shipped gallery is missing. If each side had | |
| its own loop they could disagree about how many cells exist -- which is precisely the | |
| "advertises a parameter it did not honour" failure this file was created to prevent. | |
| `ui_choices` is a dict of the ORIGINAL dropdown strings (American-spelled values, exactly | |
| what the frontend POSTs), so the renderer can feed them straight back through | |
| params_to_spec and the manifest can record what a cell means without decoding its name. | |
| Order: without-tumour cells first (3, by level), then with-tumour (54, lobe-major, then | |
| level, then size). Fixed order = a diffable manifest and a deterministic render log. | |
| yields (str, dict) | |
| """ | |
| # Reverse the UI dicts once so we can go canonical -> the exact string the frontend sends. | |
| lobe_ui = {v: k for k, v in UI_LOBE.items()} | |
| level_ui = {v: k for k, v in UI_LEVEL.items()} | |
| size_ui = {v: k for k, v in UI_SIZE.items()} | |
| for level in LEVELS: | |
| # Lobe and size are recorded as the site's defaults purely so the dict has all four | |
| # keys; params_to_spec throws them away for "Without Tumor" and cell_id never sees | |
| # them. Do NOT read meaning into them. | |
| yield ("without_{}".format(level), | |
| {"tumour": "Without Tumor", "lobe": "Frontal", | |
| "slice_location": level_ui[level], "tumour_size": "Moderate"}) | |
| for lobe in LOBES: | |
| for level in LEVELS: | |
| for size in SIZES: | |
| yield ("with_{}_{}_{}".format(lobe, level, size), | |
| {"tumour": "With Tumor", "lobe": lobe_ui[lobe], | |
| "slice_location": level_ui[level], "tumour_size": size_ui[size]}) | |
| # ============================================================================================= | |
| # SECTION 5 -- THE ATLAS-GUIDED MASK SYNTHESISER | |
| # Ported from scripts/augment_tumor.py:43-110. The algorithm is unchanged; the only edits are | |
| # (a) AREA_FRAC becomes a parameter so the website's Tumour Size control can drive it, and | |
| # (b) the two scipy calls are replaced by the numpy versions in SECTION 2. | |
| # ============================================================================================= | |
| def synth_mask(atlas_lobe, brain, rng, area_frac=AREA_FRAC_DEFAULT): | |
| """Grow an organic tumour that CONFORMS to the lobe and is SIZED relative to it. | |
| Instead of stamping a fixed circle, we score every pixel by | |
| atlas probability x compactness-around-a-seed x smooth random field | |
| and take the top-N pixels, where N is a fraction of the lobe's area in this slice. | |
| The atlas term makes the lesion hug the lobe's real shape; the random field makes the | |
| outline irregular like a real tumour; the compactness term keeps it a single mass. | |
| atlas_lobe : (256,256) float32, this slice's probability map for the CHOSEN lobe, in [0,1] | |
| brain : (256,256) bool, the brain footprint -- the caller computes it from the T1 | |
| channel as `stack[1] > 0.05`, NOT from FLAIR and NOT from the mask | |
| rng : numpy.random.Generator; the entire shape is a pure function of its state | |
| area_frac : (lo, hi) fraction-of-lobe-area range to draw the target lesion size from | |
| Returns (mask, (c0, c1)) or (None, None) on any of three failure conditions. | |
| `mask` is (256,256) float32 whose values are ONLY {0, 2, 3}: | |
| 0 = background, 2 = edema (the bright FLAIR halo), 3 = enhancing tumour core. | |
| Label 1 (necrotic) is NEVER emitted -- synthetic lesions are edema+core only, unlike real | |
| BraTS masks. These are RAW BraTS label values: channel 2 of the stack is the one channel | |
| that is NOT in [0,1] (03_preprocess.py:72 puts the segmentation in unnormalised), so | |
| rescaling it to [0,1] would put the model badly off-distribution. | |
| """ | |
| lobe = (atlas_lobe > PROB_TH) & brain # the lobe's footprint in THIS slice | |
| n_lobe = int(lobe.sum()) | |
| if n_lobe < MIN_LOBE: | |
| # The atlas may claim this lobe, but the patient's slice does not contain enough of | |
| # it to host a believable lesion. Caller decides what to do. | |
| return None, None | |
| # --- 1. seed: a point well inside the lobe (sampled by atlas probability) --------------- | |
| # NOT uniform. Weighting by the atlas probability makes seeds nucleate in the lobe's core | |
| # rather than on its ragged margin, so the lesion does not habitually straddle a boundary. | |
| ys, xs = np.nonzero(lobe) # (n_lobe,), (n_lobe,) | |
| w = atlas_lobe[ys, xs].astype(np.float64) # float64 and renormalised | |
| w = w / w.sum() # because rng.choice(p=...) | |
| j = int(rng.choice(len(ys), p=w)) # demands an EXACT sum of 1 | |
| c0, c1 = int(ys[j]), int(xs[j]) # seed pixel (axis0, axis1) | |
| # --- 2. target size: a fraction of THIS lobe's area -> big lobe, big tumour ------------- | |
| n_les = int(rng.uniform(*area_frac) * n_lobe) | |
| if n_les < MIN_AREA: | |
| return None, None | |
| # --- 3. score field = atlas x compactness x irregularity -------------------------------- | |
| idx0 = np.arange(256, dtype=np.float32)[:, None] # (256,1) row index | |
| idx1 = np.arange(256, dtype=np.float32)[None, :] # (1,256) col index | |
| dist = np.sqrt((idx0 - c0) ** 2 + (idx1 - c1) ** 2) # (256,256) distance from the seed | |
| r_eq = np.sqrt(n_les / np.pi) # radius a circle of that area would have | |
| compact = np.exp(-(dist / (COMPACT * r_eq)) ** 2) # smooth falloff -> keeps it one mass | |
| # A smoothed random field is what makes the outline organic. sigma=6 px sets the | |
| # wavelength of the wobble; NOISE_AMP=0.9 scales it to a ~[0.55, 1.45] multiplier, so it | |
| # perturbs the boundary without ever being able to flip the sign of the score. | |
| noise = _gaussian_blur(rng.standard_normal((256, 256)).astype(np.float32), NOISE_SIGMA) | |
| noise = (noise - noise.min()) / (noise.max() - noise.min() + 1e-8) # -> [0,1] | |
| irregular = 1.0 + NOISE_AMP * (noise - 0.5) # ~[0.55,1.45] multiplier | |
| score = atlas_lobe.astype(np.float32) * compact * irregular # (256,256) | |
| score[~lobe] = 0.0 # HARD constraint: never leave the lobe | |
| # --- 4. take the top-N scoring pixels = the lesion -------------------------------------- | |
| # argpartition is O(n) (it only guarantees the top n_les are in the last n_les slots, in no | |
| # particular order), which is all we need and much cheaper than a full sort. Taking a fixed | |
| # COUNT rather than thresholding the score means the area is exact by construction instead | |
| # of being whatever a threshold happened to produce. | |
| flat = score.ravel() # (65536,) | |
| n_les = min(n_les, int((flat > 0).sum())) # cannot want more pixels than exist | |
| if n_les < MIN_AREA: | |
| return None, None | |
| top = np.argpartition(flat, -n_les)[-n_les:] # indices of the N highest scores | |
| blob = np.zeros(256 * 256, bool); blob[top] = True | |
| blob = blob.reshape(256, 256) # (256,256) bool | |
| # --- 5. keep only the largest connected piece (no scattered islands) --------------------- | |
| # The random field can carve the top-N set into a main mass plus a few specks. A real | |
| # lesion is one object. NOTE this step can shrink the lesion BELOW the requested n_les -- | |
| # discarded islands are not replaced -- which is why the realised area is measured and | |
| # reported rather than assumed. | |
| blob = _largest_connected_component(blob) | |
| # --- 6. core = the highest-scoring pixels INSIDE the lesion ------------------------------ | |
| m = np.zeros((256, 256), np.float32) | |
| m[blob] = 2 # label 2 = edema (bright FLAIR halo) | |
| inside = score * blob # scores, zeroed outside the lesion | |
| n_core = max(1, int(CORE_FRAC * blob.sum())) | |
| core_idx = np.argpartition(inside.ravel(), -n_core)[-n_core:] | |
| core = np.zeros(256 * 256, bool); core[core_idx] = True | |
| # `& blob` re-guards the assignment: argpartition breaks ties arbitrarily and could hand | |
| # back an index whose score is 0 outside the lesion. | |
| m[core.reshape(256, 256) & blob] = 3 # label 3 = enhancing tumour core | |
| m[~brain] = 0 # never spill outside the brain | |
| # Cheap invariant, expensive bug: the model was trained on raw BraTS labels and channel 2 | |
| # is the only channel not in [0,1]. If this ever fails, something rescaled the mask. | |
| assert set(np.unique(m).tolist()) <= {0.0, 2.0, 3.0}, "mask must carry only labels {0,2,3}" | |
| return m, (c0, c1) | |
| def synth_mask_sized(atlas_lobe, brain, rng, size_key, max_tries=12): | |
| """synth_mask with the website's Small/Moderate/Large control wired in. | |
| Two things are going on here. | |
| (1) THE PRIMARY MAPPING is size -> AREA_FRAC band (AREA_FRAC_BY_SIZE). This keeps the | |
| paper's relative-to-lobe design, which is what guarantees the lesion always fits | |
| inside the lobe. | |
| (2) A BOUNDED REJECTION LOOP then tries to make the website's word mean the same thing the | |
| paper's captions mean. 06_captions_v2.py defines small/moderate/large by ABSOLUTE | |
| area in px (<500 / 500-2000 / >2000), so we redraw up to `max_tries` times until the | |
| REALISED area lands in that band. If it never does -- which happens legitimately, e.g. | |
| a large lesion cannot fit in a small lobe -- we keep the attempt whose area was | |
| closest and set size_in_band=False. An honest recorded mismatch is much better than a | |
| 500 error, and much better than silently mislabelling. | |
| THE `stats` DICT IS PART OF THE HONESTY CONTRACT. Whatever comes back here is what the web | |
| backend records in the database as what actually happened, and it is what the cluster | |
| renderer writes into the gallery manifest so that a pre-rendered image can still report | |
| its true realised lesion area months later. Do not add a field here that the caller cannot | |
| verify, and do not remove one -- the gallery manifest schema mirrors it. | |
| Returns (mask, (c0,c1), stats). Raises ValueError only if EVERY attempt returned | |
| (None, None), i.e. the lobe is genuinely absent from this slice -- which the caller's | |
| slice-admissibility check should already have excluded, so it means the conditioning bank | |
| and its manifest disagree. | |
| """ | |
| lo_hi = AREA_FRAC_BY_SIZE[size_key] | |
| # The paper's absolute band for this word, as a half-open interval in pixels. | |
| if size_key == "small": | |
| band = (MIN_AREA, SMALL_MAX) # [60, 500) | |
| elif size_key == "large": | |
| band = (LARGE_MIN + 1, np.inf) # (2000, inf) | |
| else: | |
| band = (SMALL_MAX, LARGE_MIN + 1) # [500, 2000] | |
| best = None # (distance_from_band, mask, centre, lesion_px) | |
| tries = 0 | |
| for tries in range(1, max_tries + 1): | |
| m, centre = synth_mask(atlas_lobe, brain, rng, area_frac=lo_hi) | |
| if m is None: | |
| continue | |
| lesion_px = int((m > 0).sum()) | |
| if band[0] <= lesion_px < band[1]: | |
| best = (0.0, m, centre, lesion_px) | |
| break | |
| # Distance to the nearest edge of the band, so "closest attempt" is well defined. | |
| dist = band[0] - lesion_px if lesion_px < band[0] else lesion_px - (band[1] - 1) | |
| if best is None or dist < best[0]: | |
| best = (float(dist), m, centre, lesion_px) | |
| if best is None: | |
| raise ValueError( | |
| "could not grow a synthetic lesion on this slice -- the chosen lobe is not " | |
| "sufficiently present in it. This means the conditioning bank's manifest " | |
| "disagrees with the slice data; rebuild the bank." | |
| ) | |
| dist, m, centre, lesion_px = best | |
| n_lobe = int(((atlas_lobe > PROB_TH) & brain).sum()) | |
| stats = { | |
| "lesion_px": lesion_px, | |
| "core_px": int((m == 3).sum()), | |
| "lobe_px": n_lobe, | |
| # what fraction of the lobe the lesion actually ended up covering | |
| "coverage": round(lesion_px / n_lobe, 4) if n_lobe else 0.0, | |
| "centre_axis0": int(centre[0]), | |
| "centre_axis1": int(centre[1]), | |
| "tries": int(tries), | |
| "size_requested": size_key, | |
| "size_realized": size_word(lesion_px), | |
| "size_in_band": bool(dist == 0.0), | |
| } | |
| return m, centre, stats | |
| # ============================================================================================= | |
| # SECTION 6 -- THE CONDITIONING TENSOR AND THE DDIM REVERSE LOOP | |
| # | |
| # torch is imported INSIDE these two functions, never at module scope. In gallery mode the web | |
| # backend imports this file and never calls either of them, so the container never pays for | |
| # torch -- see rule (1) in the module docstring. | |
| # ============================================================================================= | |
| def build_cond(stack, mask, device="cpu"): | |
| """Assemble the 8-channel conditioning tensor the U-Net expects. | |
| THE OFF-BY-ONE THAT BITES EVERYONE: the model's input is | |
| torch.cat([noisy_flair, cond], dim=1) | |
| where `cond = stack[1:9]`. That slice re-indexes everything by -1, so INSIDE cond: | |
| cond index 0 == stack channel 1 == T1 | |
| cond index 1 == stack channel 2 == tumour mask <- NOT cond[2] | |
| cond index 2+k == stack channel 3+k == atlas lobe k | |
| This is why sample.py:29 and eval_grid.py:51 in the research repo read the mask as cond[1]. | |
| After the concatenation the model's own channel numbering lines back up with the stack's | |
| (0=noisy FLAIR, 1=T1, 2=mask, 3..8=atlas), which is what in_channels=9 was trained on. | |
| stack : (9,256,256) float32, straight from the conditioning bank | |
| mask : (256,256) float32 with labels {0,2,3}, or an all-zero array for "Without Tumor" | |
| device : torch device string -- "cpu" on the web container (torch==2.0.1+cpu), "cuda" on | |
| Great Lakes. Passed in rather than decided here because device selection is a | |
| DEPLOYMENT decision and this file must not make any (rule 3), and because reading | |
| torch.cuda.is_available() at module scope would import torch at module scope. | |
| Returns a torch tensor of shape (1,8,256,256) on `device`. | |
| NOTE THE CONDITIONING IS NOT RESCALED. train.py:33-34 maps only the FLAIR TARGET to | |
| [-1,1] (`target = target * 2 - 1`); the conditioning gets `cond = cond.to(DEVICE)` with no | |
| arithmetic at all. Feeding a 2*cond-1 tensor here would be a silent, extremely | |
| plausible-looking bug -- the output would still look like a brain, just a worse one. | |
| """ | |
| import torch # lazy: see the section header | |
| out = stack[1:9].copy() # (8,256,256) -- copy, never mutate | |
| out[1] = mask.astype(np.float32) # cond index 1 == stack ch 2 == mask | |
| assert out.shape == (8, 256, 256) and out.dtype == np.float32 | |
| return torch.from_numpy(out).unsqueeze(0).to(device) # (1,8,256,256) | |
| def render_flair(model, sched, cond, seed): | |
| """The DDIM reverse-diffusion loop. This is where the image is actually made. | |
| Transcribed from augment_tumor.py:151-156 with the shapes spelled out. | |
| The idea: start from pure Gaussian noise in the FLAIR channel, and repeatedly ask the | |
| network "given this noisy image and this conditioning, what noise do you think is in | |
| here?", then have the scheduler subtract a calibrated share of that prediction. After | |
| `steps` iterations the noise is gone and a FLAIR is left. | |
| model : the UNet2DModel, in eval mode, already on the same device as `cond` | |
| sched : the DDIMScheduler, already set_timesteps(steps) | |
| cond : (1,8,256,256) float32 -- CONSTANT for the whole loop. Its .device is what the | |
| initial noise is drawn on, so there is no device argument to get out of sync with | |
| it; a mismatch would be a torch error rather than a wrong picture. | |
| seed : int; seeds the initial noise so a generation is exactly reproducible | |
| Returns (256,256) float32 in [0,1]. | |
| STEP COUNT IS THE CALLER'S: it is baked into `sched` by set_timesteps(). The cluster | |
| renderer uses the paper's 200; a live web deployment would use fewer. That is the ONE | |
| quality knob the two paths are allowed to differ on, and it is recorded per image | |
| (params["ddim_steps"]) precisely so the difference is never silent. | |
| """ | |
| import torch # lazy: see the section header | |
| # One seed in, both randomness sources derived from it. augment_tumor.py gets this half | |
| # right and half wrong for a web service: line 116 hard-seeds the MASK rng to 0 (so every | |
| # call would draw the identical tumour) while line 151 leaves the diffusion noise | |
| # UNSEEDED (so no image can ever be reproduced). Here the caller derives the numpy | |
| # Generator and this torch Generator from the same integer, and that integer is recorded | |
| # with the image -- which is what makes any image on the site regenerable. | |
| device = cond.device | |
| g = torch.Generator(device=device).manual_seed(int(seed)) | |
| x = torch.randn(cond.shape[0], 1, 256, 256, generator=g, device=device) # (1,1,256,256) | |
| for t in sched.timesteps: # 0-dim int64 tensors, descending | |
| with torch.no_grad(): # no autograd graph -> less memory | |
| model_in = torch.cat([x, cond], dim=1) # (1,1,..) + (1,8,..) -> (1,9,256,256) | |
| # `.sample` unwraps the UNet2DOutput dataclass -- model(...) does NOT return a | |
| # raw tensor. Same idea for `.prev_sample` on DDIMSchedulerOutput below. | |
| npred = model(model_in, t).sample # (1,1,256,256) predicted epsilon | |
| x = sched.step(npred, t, x).prev_sample # (1,1,256,256) one step less noisy | |
| # Undo training's target scaling. train.py:33 does `target = target * 2 - 1` to map the | |
| # [0,1] FLAIR into [-1,1] for the model, so the exact inverse is (x + 1) / 2. The clip | |
| # catches the small overshoot DDIM can leave at the extremes. | |
| return np.clip((x[0, 0].cpu().numpy() + 1) / 2, 0, 1).astype(np.float32) # (256,256) | |
| # ============================================================================================= | |
| # SECTION 7 -- PNG ENCODING | |
| # | |
| # This is in the shared file for the same reason everything else is: the gallery PNG is | |
| # encoded ONCE, on the cluster, and served for months. If the live path encoded with a | |
| # different orientation or a different intensity mapping, the same request would produce a | |
| # visibly different picture depending on which mode the server happened to be in. | |
| # ============================================================================================= | |
| def to_png_bytes(arr, kind="flair"): | |
| """Encode a (256,256) array as PNG bytes, in the research repo's display orientation. | |
| ORIENTATION. Every figure in the research repo is drawn as | |
| ax.imshow(arr.T, cmap="gray", origin="lower", vmin=0, vmax=1) | |
| (sample.py:47, eval_grid.py:84, augment_tumor.py:165, check_atlas_fit.py:79). `origin= | |
| "lower"` puts row 0 at the BOTTOM, whereas PIL puts row 0 at the top -- so the equivalent | |
| array for PIL is np.flipud(arr.T). Skipping this yields a 90-degree-rotated brain relative | |
| to every figure in the paper. Array axis 0 is therefore the image's horizontal axis and | |
| axis 1 the vertical. (Related, if a Left/Right control is ever added: the convention is | |
| radiological, MIDLINE_AXIS0 = 128 and image-left is patient-RIGHT.) | |
| KNOWN DIVERGENCE: the four GAN models on the site hand raw arrays to PIL with no such | |
| transform, so this model's output will be oriented differently from theirs in the same | |
| viewer. That is a deliberate choice in favour of matching the paper; it is worth a note in | |
| the model's UI copy. | |
| INTENSITY. We return BYTES, not a numpy array, and that is load-bearing. | |
| supabase_storage.py:87-95 takes the numpy branch and does a PER-IMAGE MIN-MAX STRETCH | |
| before encoding, which destroys absolute FLAIR intensity and can exaggerate or flatten | |
| lesion contrast unpredictably from one generation to the next. Passing bytes takes the | |
| `else` branch at supabase_storage.py:96-98, which uploads them untouched. So the site shows | |
| exactly the fixed vmin=0, vmax=1 mapping the paper uses, and two generations are | |
| comparable. Do not "simplify" this into passing an array. | |
| arr : (256,256) float32 | |
| kind : "flair" -> [0,1] intensities mapped linearly onto 0..255 | |
| "seg" -> BraTS labels {0,2,3} mapped onto {0,170,255} by an explicit lookup, so | |
| the mask renders identically whether or not a core is present (a min-max | |
| stretch of a core-less mask would map edema to pure white). | |
| Returns PNG bytes. The cluster renderer writes them straight to a .png file; the web | |
| backend hands them to Supabase. Same bytes either way. | |
| """ | |
| from PIL import Image # lazy, to keep module scope numpy-only | |
| a = np.asarray(arr) | |
| if kind == "seg": | |
| out = np.zeros(a.shape, dtype=np.uint8) | |
| lab = np.rint(a).astype(np.int16) # labels are stored as floats | |
| out[lab == 2] = 170 # edema -> mid grey | |
| out[lab == 3] = 255 # enhancing -> white | |
| else: | |
| out = (np.clip(a, 0.0, 1.0) * 255.0).astype(np.uint8) | |
| # np.ascontiguousarray because PIL needs a C-contiguous buffer and .T produces a view with | |
| # transposed strides. | |
| img = Image.fromarray(np.ascontiguousarray(np.flipud(out.T)), mode="L") | |
| buf = io.BytesIO() | |
| img.save(buf, format="PNG") | |
| return buf.getvalue() | |