Spaces:

AIOmarRehan
/

medtrace

Running

App Files Files Community

medtrace / README.md

AIOmarRehan

Update README.md

782e018 verified 2 days ago

preview code

Raw

History Blame Contribute Delete

53.1 kB

	---
	title: MEDTRACE 🔬
	emoji: 🧠
	colorFrom: indigo
	colorTo: blue
	sdk: static
	app_file: index.html
	license: mit
	short_description: Longitudinal AI for brain-MRI disease evolution
	models:
	- AIOmarRehan/medtrace-brats-segresnet
	datasets:
	- AIOmarRehan/medtrace-rhuh-gbm-derived
	tags:
	- medical-imaging
	- mri
	- brain-tumour
	- segmentation
	- longitudinal
	- cornerstone3d
	- vtk
	---

	[The Medium Article](https://medium.com/@ai.omar.rehan/medtrac-longitudinal-ai-for-brain-mri-analysis-tracking-disease-evolution-over-time-05808ebed764)

	---

	<div align="center">

	<img src="GIF/Brain.gif" alt="MEDTRACE: longitudinal brain MRI analysis" width="460" />

	# MEDTRACE

	### Longitudinal AI for brain-MRI disease evolution

	An interactive, evidence-linked map of how a brain tumour changes over time.

	<br />

	![Stage](https://img.shields.io/badge/build-stages%200--5%20complete-0f766e?style=for-the-badge)
	![Tests](https://img.shields.io/badge/checks-345%20unit%20%2B%20351%20browser-155e75?style=for-the-badge)
	![Dice](https://img.shields.io/badge/test%20Dice-0.894%20mean-1e40af?style=for-the-badge)
	![Patients](https://img.shields.io/badge/real%20patients-209-4c1d95?style=for-the-badge)

	![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)
	![FastAPI](https://img.shields.io/badge/FastAPI-modular%20monolith-009688?logo=fastapi&logoColor=white)
	![PyTorch](https://img.shields.io/badge/PyTorch-2.10-EE4C2C?logo=pytorch&logoColor=white)
	![MONAI](https://img.shields.io/badge/MONAI-1.6-00A0B0)
	![Next.js](https://img.shields.io/badge/Next.js-15.5-000000?logo=nextdotjs&logoColor=white)
	![React](https://img.shields.io/badge/React-19.1-61DAFB?logo=react&logoColor=black)
	![Cornerstone3D](https://img.shields.io/badge/Cornerstone3D-5.7-0ea5e9)
	![vtk.js](https://img.shields.io/badge/vtk.js-36.4-6366f1)
	![PostgreSQL](https://img.shields.io/badge/PostgreSQL-17-4169E1?logo=postgresql&logoColor=white)
	![Docker](https://img.shields.io/badge/Docker%20Compose-5%20services-2496ED?logo=docker&logoColor=white)

	</div>

	> [!WARNING]
	> Research prototype. Not a medical device.
	> MEDTRACE is not intended for diagnosis, treatment planning, or any clinical decision. It has
	> not been clinically validated. It reports measured change only, never a diagnosis, grade,
	> progression judgement, treatment recommendation, or prognosis. All clinical decisions remain
	> with qualified healthcare professionals. Built exclusively on public, de-identified research
	> data.


	> [!NOTE]
	> What this hosted demo serves. 28 glioblastoma patients from
	> [RHUH-GBM](https://doi.org/10.7937/4545-c905), 3 timepoints each, under CC BY 4.0. The figures
	> below describe the full local build across LUMIERE and BraTS 2023, which are covered by data use
	> agreements that grant use but not redistribution, so they are not published here.
	>
	> There is no server. This is a Static Space: the interface and its recorded responses are served
	> from this repository, imaging is range-fetched from the
	> [dataset repository](https://huggingface.co/datasets/AIOmarRehan/medtrace-rhuh-gbm-derived), and
	> both renderers run on your GPU. Nothing is computed on request.
	>
	> The linked model is published alongside this demo, not run by it. Every outline and every
	> measurement shown comes from the expert-corrected segmentations that ship with RHUH-GBM. That is
	> deliberate: RHUH-GBM is post-operative and post-treatment, and the model was trained on
	> pre-operative scans only, so the one dataset published here is the one regime the model was not
	> trained for. The model card gives the reasoning and the numbers behind it.
	>
	> [Model](https://huggingface.co/AIOmarRehan/medtrace-brats-segresnet) ·
	> [Dataset](https://huggingface.co/datasets/AIOmarRehan/medtrace-rhuh-gbm-derived) ·
	> [Code](https://github.com/AIOmarRehan/medtrace)

	---

	<div align="center">

	<table>
	<tr>
	<td align="center"><b>209</b><br />real patients</td>
	<td align="center"><b>874</b><br />MRI studies</td>
	<td align="center"><b>3,431</b><br />image series</td>
	<td align="center"><b>1,153</b><br />disease observations</td>
	</tr>
	<tr>
	<td align="center"><b>772</b><br />tracked lesions</td>
	<td align="center"><b>6,499</b><br />measurements</td>
	<td align="center"><b>599</b><br />atlas volumes</td>
	<td align="center"><b>59.9</b><br />3D fps measured</td>
	</tr>
	</table>

	</div>

	---

	## Contents

	<table>
	<tr>
	<td valign="top" width="33%">

	Understanding it
	- [The clinical problem](#the-clinical-problem)
	- [What MEDTRACE answers](#what-medtrace-answers)
	- [The workstation](#the-workstation)
	- [Analysis pipeline](#analysis-pipeline)

	</td>
	<td valign="top" width="33%">

	How it works
	- [Domain model](#domain-model-observations-not-images)
	- [AI segmentation](#ai-segmentation)
	- [Training notebook](#the-training-notebook)
	- [Validation & results](#validation--results)
	- [Measurement & change](#measurement-matching-and-change)
	- [3D disease evolution](#3d-disease-evolution)
	- [Evidence engine](#the-evidence-engine)

	</td>
	<td valign="top" width="33%">

	Running it
	- [Architecture](#architecture)
	- [Technology stack](#technology-stack)
	- [Datasets](#datasets)
	- [Verification](#verification)
	- [Getting started](#getting-started)

	</td>
	</tr>
	</table>

	---

	## The clinical problem

	A patient with a brain tumour is imaged repeatedly: before surgery, after surgery, during
	radiotherapy and chemotherapy, then at follow-up for years. **Clinical decisions are made by
	comparing these examinations, not by reading any one of them.**

	Today that comparison is largely manual:

	```
	radiologist opens prior study ──► reads previous report ──► scrolls both studies side by side
	──► re-measures the lesion by hand ──► mentally reconstructs the patient's history
	```

	Most medical-imaging AI does not help, because it analyses one scan at one moment.
	Longitudinal comparison is a recognised underdeveloped area of medical imaging AI, and it is
	exactly where the clinical decision actually happens.

	MEDTRACE exists to answer one question:

	<div align="center">

	### What changed in this patient between examinations?

	</div>

	---

	## What MEDTRACE answers

	Every screen exists to serve one of five questions. Nothing else is in scope.

	\| Question \| How MEDTRACE answers it \|
	\|---\|---\|
	\| What changed? \| Quantified, with units and direction: volume, diameter, surface area, growth rate \|
	\| Where did it change? \| Highlighted in the image, per lesion, in 2D and 3D \|
	\| When did it change? \| Located on the disease timeline, with the interval in days \|
	\| How confident are we? \| Per pipeline stage, with the reason in plain language \|
	\| Why do you believe that? \| The evidence, one click away \|

	The signature interaction is the time scrubber. Dragging it moves imaging, segmentation,
	measurements, clinical events, the 3D surface and the evidence panel together.

	> [!NOTE]
	> An observation without evidence cannot exist in MEDTRACE. This is enforced in the service
	> layer, not by convention. It is why the system can always answer "why".

	---

	## The workstation

	<div align="center">

	<img src="docs/screenshots/01-workstation.png" alt="MEDTRACE clinical workstation" width="100%" />

	*The clinical workstation: patient timeline, synchronised prior/current comparison, measured
	findings, and the AI evidence strip.*

	</div>

	<table>
	<tr>
	<td width="50%" valign="top">

	### 2D comparison

	<img src="docs/screenshots/02-2d-comparison.png" alt="Synchronised prior and current study" width="100%" />

	Prior and current study side by side, linked by fractional depth rather than world
	coordinates, because unregistered studies differ by tens of millimetres and copying a camera
	between them can place it outside the other volume entirely.

	<img src="GIF/gif-04-slice-sync.gif" alt="Scrolling one pane moves the other with it" width="100%" />

	Scroll one pane and the other follows.

	</td>
	<td width="50%" valign="top">

	### Segmentation overlay

	<img src="docs/screenshots/03-segmentation-overlay.png" alt="Tumour mask overlaid on native image" width="100%" />

	The tumour mask drawn in the series' own voxel grid, reoriented from the NIfTI affines with
	no resampling. Outline by default, fill on demand.

	</td>
	</tr>
	</table>

	---

	## Analysis pipeline

	Deliberately a pipeline of specialised stages, not one large model. **Every stage emits its
	prediction, its confidence, its quality flags and its model version.**

	```mermaid
	%%{init: {"theme":"base","themeVariables":{"fontSize":"15px","textColor":"#1e293b","nodeTextColor":"#1e293b","lineColor":"#475569","edgeLabelBackground":"#ffffff"},"flowchart":{"nodeSpacing":34,"rankSpacing":50,"padding":10}}}%%
	flowchart LR
	A[("MRI studies")] --> B["Quality control"]
	B --> C["Segmentation"]
	C --> D["Lesion detection"]
	D --> E["Registration"]
	E --> F["Lesion matching"]
	F --> G["Change detection"]
	G --> H[("DiseaseObservation")]
	H --> I["Disease timeline"]
	H --> J["3D evolution map"]
	H --> K["Evidence engine"]

	classDef src fill:#e0f2fe,stroke:#0284c7,stroke-width:1px,color:#0c4a6e
	classDef stage fill:#ffffff,stroke:#64748b,stroke-width:1px,color:#1e293b
	classDef core fill:#ccfbf1,stroke:#0d9488,stroke-width:2px,color:#134e4a
	classDef view fill:#e0e7ff,stroke:#4f46e5,stroke-width:1px,color:#312e81

	class A src
	class B,C,D,E,F,G stage
	class H core
	class I,J,K view
	```

	<details>
	<summary><b>What each stage actually does</b></summary>

	<br />

	\| Stage \| Implementation \| Output \|
	\|---\|---\|---\|
	\| Quality control \| Rule-based validation of sequences, voxel spacing, orientation, protocol drift between timepoints \| `QualityFlag[]` per study \|
	\| Segmentation \| MONAI `SegResNet`, 18.8 M parameters, 4 sequences in → 3 overlapping compartments out \| Tumour compartment masks \|
	\| Lesion detection \| Connected-component extraction per compartment, with a measurability floor \| `Lesion` candidates \|
	\| Registration \| SimpleITK rigid then affine; atlas-space masks need none, native-space ones do \| Transform + score \|
	\| Lesion matching \| Similarity scoring over overlap (Dice), centroid distance, proximity and volume similarity \| `Lesion` identity across time \|
	\| Change detection \| Volumetric and morphological comparison with uncertainty propagation \| Absolute + relative change, growth rate \|
	\| Trajectory \| Longitudinal feature vectors per lesion across all timepoints \| Per-lesion history \|
	\| Evidence engine \| Structured findings → validated answer → linked evidence \| `AIObservation` + `EvidenceItem[]` \|

	</details>

	---

	## Domain model: observations, not images

	The core domain object is `DiseaseObservation`, not `MRI`. The timeline, the analytics, the
	AI answers and the audit trail are all views over observations.

	```mermaid
	%%{init: {"theme":"base","themeVariables":{"fontSize":"15px","textColor":"#1e293b","nodeTextColor":"#1e293b","lineColor":"#475569","edgeLabelBackground":"#ffffff"}}}%%
	erDiagram
	PATIENT \|\|--o{ STUDY : "timepoints"
	PATIENT \|\|--o{ LESION : "identity"
	PATIENT \|\|--o{ CLINICAL_EVENT : "treatment"
	PATIENT \|\|--o{ AI_OBSERVATION : "answers"
	STUDY \|\|--o{ SERIES : "sequences"
	STUDY \|\|--o\| STUDY_QUALITY : "validation"
	STUDY \|\|--o{ SEGMENTATION : "masks"
	STUDY \|\|--o{ LESION_OBSERVATION : "observed in"
	LESION \|\|--o{ LESION_OBSERVATION : "observed at"
	LESION_OBSERVATION \|\|--o{ MEASUREMENT : "quantified by"
	LESION_OBSERVATION \|\|--o{ EVIDENCE_ITEM : "supports"
	AI_OBSERVATION \|\|--o{ EVIDENCE_ITEM : "must cite"
	MODEL_RUN \|\|--o{ LESION_OBSERVATION : "produced"
	MODEL_RUN \|\|--o{ AI_OBSERVATION : "produced"
	```

	A `Lesion` belongs to a patient, not a study, and that is what makes a per-lesion trajectory
	possible, and it is precisely what a conventional viewer or segmentation tool does not provide.

	<details>
	<summary><b>The 14-table schema</b></summary>

	<br />

	`patients` · `studies` · `series` · `study_quality` · `registrations` · `segmentations` ·
	`lesions` · `lesion_observations` · `measurements` · `clinical_events` · `model_runs` ·
	`ai_observations` · `evidence_items` · `audit_events`

	Managed with SQLAlchemy + Alembic. PostgreSQL stores metadata only. Imaging stays on the
	filesystem and is served through a path-allowlisted endpoint, never by a database blob.

	</details>

	---

	## AI segmentation

	A 3D `SegResNet` trained from scratch on BraTS 2023 GLI, on a Kaggle Tesla T4.

	```mermaid
	%%{init: {"theme":"base","themeVariables":{"fontSize":"15px","clusterBkg":"#f1f5f9","clusterBorder":"#94a3b8","textColor":"#1e293b","nodeTextColor":"#1e293b","lineColor":"#475569","edgeLabelBackground":"#ffffff"},"flowchart":{"nodeSpacing":34,"rankSpacing":58,"padding":10}}}%%
	flowchart LR
	subgraph IN ["4 co-registered sequences"]
	direction TB
	A1["T1c"]
	A2["T1n"]
	A3["T2-FLAIR"]
	A4["T2w"]
	end

	B["Normalise"]
	C["Crop"]
	D["SegResNet 3D"]
	E["Sliding window"]

	subgraph OUT ["3 overlapping compartments"]
	direction TB
	F1["TC"]
	F2["WT"]
	F3["ET"]
	end

	G["Threshold"]
	H["BraTS labels"]

	A1 --> B
	A2 --> B
	A3 --> B
	A4 --> B
	B --> C --> D --> E
	E --> F1
	E --> F2
	E --> F3
	F1 --> G
	F2 --> G
	F3 --> G
	G --> H

	classDef seq fill:#e0f2fe,stroke:#0284c7,stroke-width:1px,color:#0c4a6e
	classDef step fill:#ffffff,stroke:#64748b,stroke-width:1px,color:#1e293b
	classDef model fill:#ccfbf1,stroke:#0d9488,stroke-width:2px,color:#134e4a
	classDef out fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95

	class A1,A2,A3,A4 seq
	class B,C,E,G,H step
	class D model
	class F1,F2,F3 out
	```

	\| Step \| What happens \|
	\|---\|---\|
	\| T1c · T1n · T2-FLAIR · T2w \| Four sequences, in this exact channel order \|
	\| Normalise \| Per case, per channel, zero mean unit variance over non-zero voxels only \|
	\| Crop \| To the non-zero bounding box of the summed channels, 4-voxel margin \|
	\| SegResNet 3D \| MONAI `SegResNet`, 18,798,627 parameters, 32 init filters, blocks down `[1,2,2,4]` \|
	\| Sliding window \| 128³ patches, 0.5 overlap, gaussian blending \|
	\| TC · WT · ET \| Independent sigmoid per channel, so the three compartments overlap rather than compete \|
	\| Threshold \| 0.5, plus an enhancing-tumour floor of 200 voxels \|
	\| BraTS labels \| Written WT→2, then TC→1, then ET→3, in that order \|

	> [!IMPORTANT]
	> Channel order is not recoverable from the weights. `[t1c, t1n, t2f, t2w]` is part of the
	> model contract, recorded in `ml/artifacts/model_card.json`. Wrong order → wrong output → *no
	> error*. This is the kind of silent failure the model card exists to prevent.

	### Held-out test performance

	186 cases from 169 subjects never seen in training or tuning. Splits are computed at
	subject level, because BraTS contains 1,251 cases from only 1,133 subjects, so a random split over
	cases would leak the same patient into train and test.

	\| Compartment \| Dice (mean) \| Dice (median) \| HD95 (median) \| Sensitivity \| Precision \| Dice (mean) on a 0 to 1 scale \|
	\|---\|---:\|---:\|---:\|---:\|---:\|:---\|
	\| Whole tumour \| 0.9216 \| 0.9489 \| 2.45 mm \| 0.9248 \| 0.9236 \| ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▱▱ \|
	\| Tumour core \| 0.9078 \| 0.9563 \| 2.00 mm \| 0.9166 \| 0.9170 \| ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▱▱ \|
	\| Enhancing tumour \| 0.8520 \| 0.8984 \| 1.41 mm \| 0.8833 \| 0.8487 \| ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▱▱▱ \|
	\| Mean of the three \| 0.8938 \| - \| - \| - \| - \| ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▱▱ \|

	> [!TIP]
	> Test scored higher than validation (0.8938 vs 0.8899 mean Dice). Since both epoch
	> selection and post-processing tuning used the validation split, the validation figures are
	> optimistic by construction, so the test figures are the honest ones, and they did not degrade.

	<details>
	<summary><b>Training configuration and honest limitations</b></summary>

	<br />

	\| Setting \| Value \|
	\|---\|---\|
	\| Architecture \| `monai.networks.nets.SegResNet`, 3D, 32 init filters, blocks down `[1,2,2,4]` \|
	\| Loss \| `DiceFocalLoss(sigmoid=True, squared_pred=True, batch=True)` \|
	\| Optimiser \| AdamW, lr 2e-4, wd 1e-5, `CosineAnnealingLR` \|
	\| Precision \| AMP float16 on Tesla T4 \|
	\| Patch sampling \| 128³, 80% centred on whole tumour, 20% uniform \|
	\| Augmentation \| Random axis flips, intensity scale ±10%, intensity shift ±10% \|
	\| Epochs \| 37 of 60 completed (host RAM exhausted); epoch 32 selected on validation mean Dice \|
	\| Seed \| `20260813` for both split and training \|

	Stated limitations (from the model card):

	- Trained on pre-operative adult glioma only. Post-treatment appearances, such as resection
	cavities, radiation change, are not represented.
	- Requires all four sequences. Behaviour with a missing sequence is untested.
	- Assumes BraTS preprocessing: skull-stripped, co-registered, 1 mm isotropic.
	- Measures agreement with one annotation protocol on one dataset. That is not a measure of
	clinical accuracy.

	</details>

	---

	## The training notebook

	The model was trained in a single notebook on a Kaggle Tesla T4, and it is in the repository with
	its outputs intact: [`ml/notebooks/brats_segmentation_training_output.ipynb`](ml/notebooks/brats_segmentation_training_output.ipynb).
	GitHub renders it, so every number below can be traced to the cell that printed it. The clean
	unexecuted version is [`brats_segmentation_training.ipynb`](ml/notebooks/brats_segmentation_training.ipynb).

	Nineteen numbered stages, from configuration through to verifying the exported weights actually
	load. Twenty-two code cells, twenty-one of them executed.

	### What the data looked like before any model existed

	<div align="center">

	<img src="docs/notebook/01-tumour-volume-distribution.png" alt="Tumour volume distributions across the BraTS 2023 GLI training split" width="100%" />

	</div>

	Across 1,251 cases the whole tumour has a median volume of 89.3 cm3 and a range of 2.8 to 361.8
	cm3. The compartments are far smaller: enhancing tumour has a median of 17.3 cm3, and its minimum
	is zero, which is why the export applies a 200 voxel floor rather than reporting a
	one-voxel enhancing region as a finding.

	The single most consequential line the notebook printed:

	```
	tumour occupies 1.07% of all voxels
	-> uniform random patches would be almost pure background; sampling must be biased
	```

	That measurement is the reason patch sampling is 80% centred on the whole tumour and 20% uniform.
	It was not a hyperparameter guess.

	<div align="center">

	<img src="docs/notebook/02-sequences-and-labels.png" alt="The four co-registered sequences with the reference labels overlaid" width="100%" />

	</div>

	The four sequences for one case with the reference labels on T1C. Looking at the actual images is
	how the channel order was confirmed, and channel order is not recoverable from the weights: get it
	wrong and the model produces a plausible, wrong answer with no error anywhere.

	### Training

	<div align="center">

	<img src="docs/notebook/03-training-curve.png" alt="Training loss and validation Dice per epoch, with the selected epoch marked" width="100%" />

	</div>

	Loss on the left, per-region validation Dice on the right, with the selected epoch marked. Thirty
	seven of a planned sixty epochs completed before host RAM was exhausted, and **epoch 32 was
	selected on mean validation Dice at 0.8867**. The curve is what justifies stopping there rather
	than at the last epoch: validation had flattened well before the run ended.

	### The test set, run once

	<div align="center">

	<img src="docs/notebook/04-test-dice-distribution.png" alt="Test Dice per region, and Dice against tumour size" width="100%" />

	</div>

	186 cases from 169 subjects, held out at subject level. Per-region Dice on the left, Dice against
	tumour size on the right, and that right-hand panel is the honest one: agreement collapses on the
	smallest tumours, where a few voxels of disagreement dominate the metric.

	\| Split comparison \| Validation \| Test \| Gap \|
	\|---\|---:\|---:\|---:\|
	\| Mean Dice \| 0.8899 \| 0.8938 \| -0.0039 \|

	The test score is marginally higher than validation. There is no overfitting to report, and the
	generalisation gap is smaller than the run-to-run noise.

	\| Region \| Cases below 0.5 Dice \| Cases with empty ground truth \|
	\|---\|---:\|---:\|
	\| Whole tumour \| 2 of 186 \| 0 \|
	\| Tumour core \| 5 of 186 \| 1 \|
	\| Enhancing tumour \| 8 of 186 \| 5 \|

	### The cases it got wrong

	Most projects show the best cases. The notebook prints the worst four, because those are the ones
	that say something.

	<table>
	<tr>
	<td width="50%" valign="top">

	<img src="docs/notebook/05-worst-test-case-1.png" alt="Worst test case by whole-tumour Dice" width="100%" />

	`BraTS-GLI-00675-001`, whole tumour Dice 0.000, yet tumour core and enhancing tumour both
	1.000. A whole tumour score of zero alongside perfect compartments is a labelling edge case,
	not a model that cannot see the tumour.

	</td>
	<td width="50%" valign="top">

	<img src="docs/notebook/06-worst-test-case-2.png" alt="Second worst test case by whole-tumour Dice" width="100%" />

	`BraTS-GLI-00493-000`, whole tumour Dice 0.184 on 34,451 labelled voxels, while core reaches
	0.924 and enhancing 0.883. The oedema boundary is the disagreement, which is the least
	reproducible boundary between human annotators too.

	</td>
	</tr>
	</table>

	> [!NOTE]
	> The worst case is where the enhancing floor and the quality gate earn their place. A study that
	> produces a result like this is flagged rather than reported as a confident measurement, and
	> nothing from this model reaches the measurement pipeline at all. See
	> [Validation & results](#validation--results) for why.

	Regenerate the figures from the notebook at any time:

	```bash
	make export-notebook-figures
	```

	## Validation & results

	### The decision not to ship the model into the measurement pipeline

	The trained model scores 0.894 mean Dice on held-out BraTS. It is deliberately not used for
	MEDTRACE's measurements, and the reason is measurement, not caution.

	Run against DeepBraTumIA on 12 randomly chosen real LUMIERE studies
	(`ml/scripts/compare_on_lumiere.py`):

	\| Region \| Median Dice \| Studies below 0.5 \| Median Dice on a 0 to 1 scale \|
	\|---\|---:\|---:\|:---\|
	\| Whole tumour \| 0.923 \| 0 of 12 \| ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▱▱ \|
	\| Tumour core \| 0.816 \| 1 of 12 \| ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▱▱▱▱ \|
	\| Enhancing tumour \| 0.486 \| 6 of 12 \| ▰▰▰▰▰▰▰▰▰▰▱▱▱▱▱▱▱▱▱▱ \|

	Splitting by how much enhancement is actually present shows this is not a uniform weakness:

	\| DeepBraTumIA enhancing volume \| n \| Median ET Dice \| Our volume vs theirs \|
	\|---\|---:\|---:\|---:\|
	\| Bulky, ≥ 5 cm³ \| 5 \| 0.861 \| 1.03× \|
	\| Small, < 5 cm³ \| 7 \| 0.193 \| ~4× \|

	The cause was predicted before the comparison was run. BraTS is pre-operative glioma, where
	enhancing tumour is a thick contrast-avid ring. LUMIERE is post-treatment: resection margins,
	radiation change and post-surgical enhancement all enhance, and none of it appears in BraTS. The
	model has never been shown a brain that has been operated on.

	> [!CAUTION]
	> Enhancing tumour is the compartment MEDTRACE measures and reports change on. Swapping the
	> pipeline over would inflate every enhancing volume, worst on exactly the small lesions where a
	> change of a few tenths of a cm³ decides whether progression is reported. So the pipeline keeps
	> DeepBraTumIA's masks, and this comparison is documented as *agreement between two automated
	> tools*, not as accuracy.

	---

	## Measurement, matching and change

	### Measurement chosen by measurement

	Surface area is computed by marching cubes over a signed distance field, not over the binary
	mask directly. The estimator was selected by comparison against analytic shapes: it degrades far
	more gracefully with anisotropic voxels, and this data spans 0.36 mm to 6.0 mm slice spacing.

	The reported surface area is the area of the mesh shipped to the 3D viewer, verified to
	within 0.009% across 1,153 meshes, so the number in the findings panel and the surface on screen
	cannot disagree.

	### Cross-time lesion matching

	```mermaid
	%%{init: {"theme":"base","themeVariables":{"fontSize":"15px","textColor":"#1e293b","nodeTextColor":"#1e293b","lineColor":"#475569","edgeLabelBackground":"#ffffff"},"flowchart":{"nodeSpacing":40,"rankSpacing":55,"padding":10}}}%%
	flowchart LR
	P["Prior lesions"] --> S{"Score each pair"}
	C["Current lesions"] --> S

	S --> O["Overlap Dice"]
	S --> D["Centroid distance"]
	S --> X["Proximity"]
	S --> V["Volume similarity"]

	O --> M["Optimal assignment"]
	D --> M
	X --> M
	V --> M

	M --> R1["Matched"]
	M --> R2["New lesion"]
	M --> R3["Disappeared"]
	M --> R4["Uncertain"]

	classDef inp fill:#e0f2fe,stroke:#0284c7,stroke-width:1px,color:#0c4a6e
	classDef comp fill:#ffffff,stroke:#64748b,stroke-width:1px,color:#1e293b
	classDef dec fill:#ccfbf1,stroke:#0d9488,stroke-width:2px,color:#134e4a
	classDef good fill:#dcfce7,stroke:#16a34a,stroke-width:1px,color:#14532d
	classDef warn fill:#ffedd5,stroke:#ea580c,stroke-width:2px,color:#7c2d12

	class P,C inp
	class O,D,X,V comp
	class S,M dec
	class R1,R2,R3 good
	class R4 warn
	```

	\| Outcome \| Meaning \|
	\|---\|---\|
	\| Matched \| Keeps the same `Lesion` id, so the trajectory continues \|
	\| New lesion \| An unmatched current lesion, so a new `Lesion` identity is created \|
	\| Disappeared \| An unmatched prior lesion, recorded as an absence, not silently dropped \|
	\| Uncertain \| `MATCH_UNCERTAIN`, `WEAK_SCORE` or `AMBIGUOUS_ALTERNATIVE`. The finding is de-emphasised and the 3D surface stays grey \|

	A doubtful correspondence is never presented as a confident one. `MATCH_UNCERTAIN`,
	`WEAK_SCORE` and `AMBIGUOUS_ALTERNATIVE` de-emphasise the finding in the panel and force the 3D
	surface to render grey rather than in a change colour, because a colour that says "growing" is
	a claim, and it must not be made when the lesion it is compared against may be a different
	lesion.

	### Change with propagated uncertainty

	<div align="center">

	<img src="docs/screenshots/04-findings-panel.png" alt="Findings panel with measured change and confidence" width="80%" />

	Measured change per lesion, with confidence and the reason it is reduced.

	</div>

	Confidence is reported per pipeline stage, and an answer's confidence is the minimum
	across the observations it rests on, never an average. A confident segmentation combined with an
	uncertain registration produces an uncertain change measurement, and averaging would let the
	reliable measurement hide the unreliable one.

	Eleven quality flags feed this, each translated into plain language: *"the two studies used
	different acquisition protocols", "slice thickness was large enough to affect volume
	measurement", "another lesion scored almost as well as this correspondence"*.

	---

	## 3D disease evolution

	<div align="center">

	<img src="GIF/gif-01-timeline-3d.gif" alt="Dragging the time scrubber updates the 3D disease map" width="90%" />

	Dragging the time scrubber: the lesion surface, the measurements and the evidence move together.

	<br />

	<img src="GIF/gif-02-3d-rotate.gif" alt="Rotating the volume-rendered head" width="90%" />

	Rotation follows the pointer, and the head stays solid from every angle.

	</div>

	### The head is volume-rendered, and that was a hard-won decision

	The brain context was originally a surface extracted from the skull-strip mask. It was
	reported as having holes five separate times. Each round found something real: open edges from a
	crop that borrowed its margin from the source volume, front-face culling that erased deep
	concavities, a camera whose view-up was parallel to its view direction, lesions left unlit by a
	single headlight. Each round fixed it, measured the rendered image as clean, and the report still stood.

	> [!NOTE]
	> A surface leaves only two options, and **each has a failure mode invisible to a software
	> rasteriser**. Translucent, and the result depends on blending order and multisample resolve,
	> which vary by driver. Opaque with the near wall culled, and it is a hollow bowl that hides the
	> anatomy it exists to show. The checks ran under SwiftShader; the defect lived on the GPU.

	The head is now the patient's own skull-stripped contrast-enhanced T1, ray-cast as a volume.
	There is no surface to close, no winding, no culling, no blending order, so *a gap in the anatomy is
	not expressible*. And it is the real anatomy at full 1 mm resolution rather than a smoothed
	approximation of its outer boundary.

	\| Measurement \| Measured on the Intel Iris Plus iGPU \|
	\|---\|---\|
	\| Median frame \| 16.7 ms → 59.9 fps (16.7 ms is the vsync interval, so the renderer is not the limit) \|
	\| 95th percentile frame \| 16.8 ms \|
	\| First frame after load \| 4.0 s \|
	\| Main thread after a 60-step drag \| 2 ms \|

	Benchmarked on real hardware rather than in software, because software rendering is exactly how
	five rounds of a rendering defect stayed invisible. Run it yourself: `make benchmark-3d`.

	<table>
	<tr>
	<td width="50%" valign="top">

	<img src="docs/screenshots/05-3d-evolution.png" alt="3D disease evolution view" width="100%" />

	Coloured by measured change. Red > +25%, blue < −25%, green stable, **grey for a baseline or
	a doubtful match**. The prior timepoint is drawn as a wireframe.

	</td>
	<td width="50%" valign="top">

	<img src="docs/screenshots/06-3d-lesion-selected.png" alt="Single lesion selected in 3D" width="100%" />

	Selecting a lesion highlights it simultaneously in the 2D panes, the findings list and the 3D
	view. Lesion meshes are never smoothed, because that mesh is the source of the reported surface area.

	</td>
	</tr>
	</table>

	<details>
	<summary><b>Why the lesions stay as surfaces while the head is a volume</b></summary>

	<br />

	The lesions are the measured objects. Each needs its own colour for its own change, and a
	surface is the honest way to draw a boundary that came from a mask. They are extracted at full
	resolution (median 71 KB, max 715 KB per mesh) and shipped as binary PLY with per-vertex normals.

	`ml/scripts/check_mesh_integrity.py` verifies the shipped bytes rather than synthetic spheres:
	unit-length normals, outward orientation, triangle winding consistent with them, zero open edges,
	zero non-manifold edges, one connected component.

	</details>

	---

	## The evidence engine

	Five fixed clinical questions, answered from measurements already in the database, validated
	before delivery, and stored with the evidence that supports them.

	```mermaid
	%%{init: {"theme":"base","themeVariables":{"fontSize":"15px","actorFontSize":"15px","noteFontSize":"14px","messageFontSize":"14px","textColor":"#1e293b","actorTextColor":"#1e293b","noteTextColor":"#1e293b","signalTextColor":"#1e293b","actorBkg":"#e0f2fe","actorBorder":"#0284c7","noteBkgColor":"#fef3c7","noteBorderColor":"#d97706","labelBoxBkgColor":"#e0f2fe","labelTextColor":"#1e293b"}}}%%
	sequenceDiagram
	autonumber
	actor U as Clinician
	participant F as findings
	participant A as answers
	participant L as LLM
	participant S as SafetyGuard
	participant D as Database

	U->>F: Ask one of five questions
	F->>D: Read recorded measurements
	D-->>F: Observations, confidence, flags
	F->>F: Assemble structured findings
	Note over F: No evidence means no observation
	F->>A: Compose deterministic answer
	A-->>S: Ground truth
	F->>L: Same findings, ask for prose
	L-->>S: Draft, or nothing at all
	S->>S: Forbidden claim? Invented number?
	S-->>U: Answer, evidence, confidence
	S->>D: Persist and audit
	```

	> [!IMPORTANT]
	> The model never sees pixels, never computes a number, and never has the last word.
	> `answers.py` composes the answer from findings alone with no model involved, and that sentence is
	> the ground truth. A language model may make it more readable; it may not make it different.

	<div align="center">

	<img src="docs/screenshots/07-evidence-panel.png" alt="AI evidence panel with an answer and evidence chips" width="90%" />

	<br />

	<img src="GIF/gif-03-show-me-why.gif" alt="From an answer to its evidence to the study it came from" width="90%" />

	Every answer carries its evidence, and every piece of evidence navigates to the study it came from.

	</div>

	An actual answer, generated from real measurements:

	> No measured enhancing volume changed by more than 25% between week-019-2 and week-033, 98 days
	> apart. 1 lesion changed by less: L06 measures 4.2 mm³, decreased by 5.7%. 5 lesions had no
	> prior to compare against… **Confidence 0.64; slice thickness was large enough to affect volume
	> measurement.**

	### SafetyGuard

	Implements a fixed table of permitted and forbidden statements, and nothing beyond it. What a medical
	tool may and may not state is not an engineering decision.

	\| Check \| Outcome \|
	\|---\|---\|
	\| Diagnosis, tumour type or grade \| Draft discarded → measurement delivered \|
	\| Progression, response, improvement, recurrence \| Draft discarded → measurement delivered \|
	\| Treatment recommendation \| Draft discarded → measurement delivered \|
	\| Prognosis or survival \| Draft discarded → measurement delivered \|
	\| Clinical urgency \| Draft discarded → measurement delivered \|
	\| A number not present in the structured findings \| Draft discarded → measurement delivered \|
	\| A lesion or study not in the evidence set \| Draft discarded → measurement delivered \|
	\| No linked evidence \| Blocked, nothing delivered \|
	\| Confidence below 0.6 \| Delivered, marked low, reason in plain language \|
	\| Quality flags on the inputs \| Delivered, flags surfaced alongside \|

	The regular expressions are deliberately coarse and are not treated as a semantic filter. A
	pattern cannot understand a sentence, so the guarantee comes from the deterministic fallback, not
	from the cleverness of the patterns. A blocked draft is kept, because a block is a signal
	about the pipeline rather than just a filtered string.

	<details>
	<summary><b>A worked example</b></summary>

	<br />

	```
	LLM draft: "The tumour is malignant and has progressed."
	SafetyGuard: MODIFIED, diagnostic or grading claim; progression or response judgement
	Delivered: "The segmented enhancing volume increased from 12.2 cm³ to 19.7 cm³
	(+61.5%) between 2025-06-12 and 2025-09-04."
	```

	Two false positives were found by measurement and fixed: a timepoint called `week-012` parses as
	the number −12, and a lesion called `L01` as 1, so identifiers are stripped before the numeric
	scan. Rounding is not fabrication. 19.7 written as 20 is accepted, 42 is not.

	</details>

	### Reproducibility and audit

	`findings_hash` digests the question and the entire findings payload. Asking the same question
	about unchanged findings returns the stored answer rather than generating a second one, so a
	past statement stays reconstructable. Every generation writes an `AuditEvent` carrying the model
	version, the input hash, the output hash and the safety outcome, with the patient referenced by
	UUID and no findings in the detail.

	---

	## Architecture

	```mermaid
	%%{init: {"theme":"base","themeVariables":{"fontSize":"15px","clusterBkg":"#f8fafc","clusterBorder":"#94a3b8","textColor":"#1e293b","nodeTextColor":"#1e293b","lineColor":"#475569","edgeLabelBackground":"#ffffff"},"flowchart":{"nodeSpacing":40,"rankSpacing":62,"padding":12}}}%%
	flowchart TB
	subgraph BROWSER ["Browser"]
	W["Next.js · React"]
	CS["Cornerstone3D"]
	VTK["vtk.js"]
	end

	subgraph APILAYER ["FastAPI modular monolith"]
	R["Routers"]
	AN["Analysis"]
	EV["Evidence engine"]
	IG["Ingestion"]
	end

	subgraph MLLAYER ["ml, separate package"]
	MM["medtrace_ml"]
	ART["artifacts"]
	end

	subgraph SVC ["Docker Compose"]
	PG[("PostgreSQL")]
	MIO[("MinIO")]
	ORT[("Orthanc")]
	RD[("Redis")]
	end

	FS[("Filesystem")]

	W --- CS
	W --- VTK
	W -->\|"REST · PLY · NIfTI"\| R
	R --> AN
	R --> EV
	R --> IG
	AN --> MM
	EV --> MM
	IG --> MM
	MM --- ART
	AN --> PG
	IG --> PG
	EV --> PG
	IG --> ORT
	AN --> MIO
	R --> RD
	R -->\|"path allowlist"\| FS

	classDef ui fill:#e0f2fe,stroke:#0284c7,stroke-width:1px,color:#0c4a6e
	classDef api fill:#ccfbf1,stroke:#0d9488,stroke-width:1px,color:#134e4a
	classDef ml fill:#e0e7ff,stroke:#4f46e5,stroke-width:1px,color:#312e81
	classDef svc fill:#f3e8ff,stroke:#9333ea,stroke-width:1px,color:#581c87
	classDef fs fill:#fef3c7,stroke:#d97706,stroke-width:1px,color:#78350f

	class W,CS,VTK ui
	class R,AN,EV,IG api
	class MM,ART ml
	class PG,MIO,ORT,RD svc
	class FS fs
	```

	<table>
	<tr><td valign="top" width="25%">

	Browser

	- `Next.js · React`: Zustand, TanStack Query
	- `Cornerstone3D`: 2D volumes + labelmaps
	- `vtk.js`: 3D volume ray-cast

	</td><td valign="top" width="25%">

	FastAPI

	- `Routers`: patients, studies, timeline, files, evidence
	- `Analysis`: pipeline orchestration
	- `Evidence engine`: findings, safety, audit
	- `Ingestion`: BraTS, LUMIERE, quality control

	</td><td valign="top" width="25%">

	ml, a separate package

	- `medtrace_ml`: measure, matching, change, mesh, volume, labels
	- `artifacts`: weights, TorchScript, model card

	</td><td valign="top" width="25%">

	Services

	- `PostgreSQL`: metadata only
	- `MinIO`: object storage
	- `Orthanc`: DICOM
	- `Redis`: cache
	- `Filesystem`: `data/raw`, `data/derived`

	</td></tr>
	</table>

	ML code stays out of application code. The application depends on model contracts, never on
	training code. Two Python packages, `medtrace-api` and `medtrace-ml`, with the API importing the
	latter but never the reverse.

	<div align="center">

	<img src="docs/screenshots/10-api-docs.png" alt="MEDTRACE OpenAPI documentation" width="90%" />

	*Every endpoint is typed end to end: Pydantic v2 on the server, generated TypeScript contracts in
	the browser.*

	</div>

	<details>
	<summary><b>Repository layout</b></summary>

	<br />

	```
	medtrace/
	├── apps/
	│ ├── api/ FastAPI modular monolith
	│ │ ├── alembic/versions/ schema migrations
	│ │ ├── medtrace/
	│ │ │ ├── analysis/ the measurement pipeline
	│ │ │ ├── domain/ models.py, enums.py
	│ │ │ ├── evidence/ findings · answers · llm · safety · service
	│ │ │ ├── ingestion/ BraTS and LUMIERE readers, quality control
	│ │ │ └── routers/
	│ │ ├── scripts/ one-off data operations
	│ │ └── tests/
	│ └── web/ Next.js clinical workstation
	│ ├── scripts/ browser verification and the 3D benchmark
	│ └── src/{app,components,lib,store}
	├── ml/
	│ ├── medtrace_ml/ measure · lesions · matching · change · trajectory
	│ │ registration · mesh · volume · labels
	│ ├── notebooks/ training notebook, its generator and its checks
	│ ├── scripts/ dataset preparation, model and mesh verification
	│ ├── artifacts/ trained weights, TorchScript, model card
	│ └── reports/ evaluation and agreement CSVs
	├── packages/ reserved for shared contracts
	├── infrastructure/ MLflow image, database init
	├── data/
	│ ├── raw/ the datasets
	│ ├── derived/ generated meshes and atlas volumes
	│ └── kaggle/ upload staging, manifest and splits kept
	└── docs/screenshots/ interface captures used in this README
	```

	</details>

	---

	## Technology stack

	<table>
	<tr><td valign="top" width="50%">

	Frontend

	\| Layer \| Choice \|
	\|---\|---\|
	\| Framework \| Next.js 15.5 · React 19.1 \|
	\| Language \| TypeScript 5.9 (strict) \|
	\| Styling \| Tailwind CSS 4 \|
	\| Client state \| Zustand 5 \|
	\| Server state \| TanStack Query 5 \|
	\| 2D viewer \| Cornerstone3D 5.7 \|
	\| 3D renderer \| vtk.js 36.4 \|

	Backend

	\| Layer \| Choice \|
	\|---\|---\|
	\| API \| FastAPI · Pydantic v2 \|
	\| ORM \| SQLAlchemy 2 · Alembic \|
	\| Database \| PostgreSQL 17 \|
	\| Object storage \| MinIO \|
	\| DICOM \| Orthanc 24.10 \|
	\| Cache \| Redis 7 \|

	</td><td valign="top" width="50%">

	Machine learning

	\| Layer \| Choice \|
	\|---\|---\|
	\| Framework \| PyTorch 2.10 (cu128) \|
	\| Medical DL \| MONAI 1.6 \|
	\| Registration \| SimpleITK \|
	\| Imaging I/O \| nibabel · NumPy · SciPy \|
	\| Meshing \| scikit-image marching cubes \|
	\| Training \| Kaggle Tesla T4 \|
	\| LLM \| MedGemma (text-only) behind a provider adapter \|

	Engineering

	\| Layer \| Choice \|
	\|---\|---\|
	\| Infrastructure \| Docker Compose, 5 services \|
	\| Testing \| Pytest · Vitest · Playwright \|
	\| Linting \| Ruff · ESLint \|
	\| CI \| GitHub Actions \|

	</td></tr>
	</table>

	> [!NOTE]
	> On the LLM: the default configuration is `MEDTRACE_LLM_PROVIDER=none`, and that is a
	> working configuration rather than a disabled one. MedGemma-27B does not fit on the
	> development GPU, and the five clinical questions must be answerable regardless, so the
	> deterministic composer answers them. Point `MEDTRACE_LLM_BASE_URL` at a vLLM, Ollama or
	> llama.cpp endpoint and it will rephrase; if that endpoint is unreachable you lose wording, not
	> correctness.

	---

	## Datasets

	Public, de-identified research data only. No real hospital patient data enters this repository
	under any circumstances.

	\| Dataset \| Role \| Scale ingested \|
	\|---\|---\|---\|
	\| BraTS 2023 GLI \| Segmentation training and held-out evaluation \| 1,251 cases from 1,133 subjects · 118 with two labelled timepoints \|
	\| LUMIERE \| The longitudinal dataset: timeline, matching, trajectory \| 91 patients · 638 timepoints · 2,487 series \|

	LUMIERE's acquisition metadata records **three field strengths, 21 scanner models and slice
	thickness from 0.8 mm to 6.0 mm**, so quality control and confidence reporting are built against
	measured heterogeneity rather than imagined inputs.

	<details>
	<summary><b>Data we hold and deliberately will not use</b></summary>

	<br />

	LUMIERE ships survival time in weeks, IDH status and MGMT methylation for all 91 patients.
	That makes outcome and molecular prediction technically possible with the data already on disk.

	We are not building it. Prognosis is forbidden by the safety policy this project holds itself to, and a
	measurement system must be trustworthy before prediction built on top of it means anything. This
	is recorded as a deliberate decision rather than an oversight, so the temptation is resolved once
	instead of repeatedly.

	LUMIERE's expert RANO ratings for 616 timepoints are likewise used only as a reference
	standard for evaluation. Never a training target, never surfaced as a MEDTRACE output.

	</details>

	---

	## Verification

	Nothing here is asserted without measurement. 696 automated checks.

	\| Suite \| Checks \| What it proves \|
	\|---\|---:\|---\|
	\| `pytest` API \| 155 \| Contracts, ingestion, quality control, pipeline output, SafetyGuard \|
	\| `pytest` ML \| 168 \| Measurement, matching, change, meshing, volume windowing, label mappings \|
	\| `vitest` web \| 17 \| Camera conventions, hole detection geometry \|
	\| `verify-study-linkage` \| 189 \| Every pane displays the study it claims, at every timepoint \|
	\| `verify-evidence` \| 42 \| Answers carry evidence, cite only measured numbers, and navigate \|
	\| `verify-evolution` \| 37 \| The 3D view draws the right surfaces, in one coordinate frame \|
	\| `verify-workstation` \| 19 \| The clinical shell, the scrubber, and the intended-use notice \|
	\| `verify-brain-shell` \| 15 \| No holes in the rendered head, at five viewing angles \|
	\| `verify-overlay` \| 15 \| The 2D tumour overlay draws the right mask \|
	\| `verify-slice-sync` \| 14 \| The two panes really scroll together, and stop when unlinked \|
	\| `verify-findings` \| 8 \| The UI shows real measured findings, not seeded numbers \|

	<details>
	<summary><b>Why the browser checks exist at all</b></summary>

	<br />

	Because instrumentation has been wrong more than once, and each time it was wrong in a way that
	passed:

	- A hole detector that counted the gaps between the legend's text glyphs, because an element
	screenshot captures whatever is drawn over the element.
	- The same check running on the patient the app opens on, which has a single 96-pixel lesion, and
	and passing with zero holes while the defect was obvious on a patient with twelve.
	- A watertightness test that only ever ran at stride 1, while the shipped meshes used stride 2.
	- A "fit view" check that measured the brain instead of the lesion.

	Expected values are taken from the API, not from the page. The hole detector now lives in its
	own module with its own unit tests, because three wrong versions of a check is enough.

	</details>

	---

	## Getting started

	### Prerequisites

	\| Requirement \| Needed \|
	\|---\|---\|
	\| Docker Desktop \| Running, with the Linux engine \|
	\| Python \| ≥ 3.11 (resolved against 3.14) \|
	\| Node.js \| ≥ 20 (tested on 24) \|
	\| Disk \| ~50 GB for both datasets \|

	### First-time setup

	```bash
	cp .env.example .env

	make up # PostgreSQL, Redis, MinIO, Orthanc, MLflow
	make install # API venv + ML venv + web dependencies
	make migrate # create the schema
	make seed # synthetic demonstration patient (labelled synthetic in the UI)
	```

	Then ingest and analyse. This is the slow part:

	```bash
	make ingest-lumiere # 91 patients, 638 timepoints
	make ingest-brats # 118 subjects with two labelled timepoints
	make analyse # the full measurement pipeline (~20 min)
	make link-masks # reorient each series' mask for the 2D overlay
	```

	### Running it

	Three terminals, in this order:

	```bash
	# 1. services
	docker compose up -d

	# 2. API
	cd apps/api
	.venv/Scripts/python.exe -m uvicorn medtrace.main:app --host 127.0.0.1 --port 8000

	# 3. web (production build, see the note below)
	cd apps/web
	npm run start
	```

	\| Service \| Address \|
	\|---\|---\|
	\| Workstation \| http://localhost:3000 \|
	\| API documentation \| http://localhost:8000/docs \|
	\| Health check \| http://localhost:8000/health \|
	\| Orthanc \| http://localhost:8042 \|
	\| MinIO console \| http://localhost:9101 \|

	Stop cleanly: `Ctrl+C` in the web and API terminals, then `docker compose stop`.

	> [!TIP]
	> Use `npm run start`, not `npm run dev`. Volume rendering is the heaviest part of MEDTRACE, and
	> development mode's HMR, source maps and double-invoked effects consume memory the renderer
	> needs. Never run `npm run build` while a dev server is running, because they share `.next`.
	>
	> The viewer caps its cache at 500 MB and six resident volumes, shows its footprint in the
	> toolbar, and offers a `reset viewer` control if the graphics context is ever lost.

	> [!WARNING]
	> No authentication. The API is unauthenticated and binds to `127.0.0.1` only, with
	> development credentials from `.env`. It is for local use. Do not expose it.

	<details>
	<summary><b>Optional commands</b></summary>

	<br />

	```bash
	# Tests
	cd apps/api && .venv/Scripts/python.exe -m pytest -q # 155
	cd ml && ../apps/api/.venv/Scripts/python.exe -m pytest -q # 168
	cd apps/web && npm run test # 22 unit

	# Browser verification (needs both servers running)
	make verify # every browser suite
	make verify-evidence # the AI evidence engine
	make verify-brain-shell # no holes in the rendered head
	make benchmark-3d # 3D frame rate on the real GPU

	# Quality
	make lint # Ruff + ESLint
	make typecheck # tsc --noEmit

	# Data and model inspection
	make inspect p=Patient-006 # per-lesion trajectories
	make quality-report # what quality control found
	make check-mesh-integrity # normals, winding, watertightness of shipped meshes
	make check-volume-pockets # no enclosed pockets of air inside the 3D display volumes
	make verify-meshes # every stored mesh against its observation
	make check-readme-diagrams # render this README's diagrams, check no label overflows
	```

	Ports are shifted off the defaults, PostgreSQL on 5433 and MinIO console on 9101, so the stack
	does not collide with locally installed services.

	</details>

	---

	## Build status

	\| Stage \| Scope \| State \|
	\|---\|---\|:---:\|
	\| 0 \| Clinical problem, scope, safety boundaries, evaluation plan, architecture, dataset cards \| Done \|
	\| 1 \| Docker Compose infrastructure, FastAPI, 14-table observation model, clinical workstation \| Done \|
	\| 2 \| Dataset ingestion, quality control, Cornerstone3D medical viewer, slice synchronisation \| Done \|
	\| 3 \| Measurement, lesion extraction, registration, cross-time matching, change detection, trajectory \| Done \|
	\| 4 \| 3D disease evolution, volume rendering, surface extraction tied to the time scrubber \| Done \|
	\| 5 \| Evidence engine, SafetyGuard, five clinical questions, audit trail \| Done \|

	Deliberately not built: MLOps automation (DVC, MLflow registry integration, Great
	Expectations), authentication and role-based access, deformable registration, progression
	classification, prognosis. The first is a project decision; the rest are scoped to later versions.

	---

	## Honesty as a design principle

	MEDTRACE is presented as a prototype, because that is what it is. Understanding why clinical
	validation matters, and saying so plainly, is a strength when talking to clinicians, not a
	weakness to hide behind confident language.

	Every number in this README is measured and reproducible from the repository. Where a result is
	unflattering, it is stated: the model's enhancing-tumour agreement on post-treatment data is
	poor, and that is why it is not in the measurement pipeline.

	---

	<div align="center">

	Datasets: BraTS 2023 GLI and LUMIERE, used under their respective research licences.
	LUMIERE is non-commercial.

	<br />

	MEDTRACE reports measured change. It does not diagnose.

	</div>

	---

	<div align="center">

	### Omar Rehan

	[![Portfolio](https://img.shields.io/badge/Portfolio-000000?style=for-the-badge&logo=vercel&logoColor=white)](https://omar-rehan.vercel.app/)
	[![GitHub](https://img.shields.io/badge/GitHub-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/AIOmarRehan)
	[![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white)](https://linkedin.com/in/omar-rehan-47b98636a)
	[![Hugging Face](https://img.shields.io/badge/Hugging%20Face-FFD21E?style=for-the-badge&logo=huggingface&logoColor=000000)](https://huggingface.co/AIOmarRehan)

	[![Kaggle](https://img.shields.io/badge/Kaggle-20BEFF?style=for-the-badge&logo=kaggle&logoColor=white)](https://kaggle.com/aiomarrehan)
	[![Medium](https://img.shields.io/badge/Medium-000000?style=for-the-badge&logo=medium&logoColor=white)](https://medium.com/@ai.omar.rehan)
	[![Tableau Public](https://img.shields.io/badge/Tableau%20Public-E97627?style=for-the-badge&logo=tableau&logoColor=white)](https://public.tableau.com/app/profile/omar.rehan)

	</div>