Correct public tutorial and inference documentation

README.md

@@ -18,7 +18,7 @@ tags:
 - Website and in-browser demo: [flexray.csail.mit.edu](https://flexray.csail.mit.edu/)
 - Code: [github.com/VictorButoi/FleXray](https://github.com/VictorButoi/FleXray)
 - Data: [`VictorButoi/flexray-data`](https://huggingface.co/datasets/VictorButoi/flexray-data)
-- Tutorial: [Colab notebook](https://colab.research.google.com/drive/1MNIeN9LN-tY8wAifWSolxmFZi3Q0BlVX)
+- Tutorial: [Colab notebook](https://colab.research.google.com/drive/1jMBoOyV8PkRThHi3i6QIMjolmNoRE0cD)
 - Paper: *FleXray: Universal Clinical X-ray Segmentation* (coming soon)
 
 FleXray is a single 2D UNet that segments anatomy from standard radiographs
@@ -43,13 +43,15 @@ from fxr.inference import FleXraySegmenter
 
 segmenter = FleXraySegmenter.from_pretrained("VictorButoi/flexray")
 prediction = segmenter.predict("./image.png", threshold=0.5)
-prediction.masks          # uint8, CxHxW thresholded masks
-prediction.probabilities  # float32, CxHxW sigmoid probabilities
-prediction.logits         # float32, CxHxW raw scores
+prediction.masks          # uint8, BxCxHxW thresholded masks
+prediction.probabilities  # float32, BxCxHxW sigmoid probabilities
+prediction.logits         # float32, BxCxHxW raw scores
 ```
 
 `flexify` writes `<name>_masks.npy`, `<name>_probabilities.npy`, and
-`<name>_logits.npy` per image. Channel order follows `label_schema.json`.
+`<name>_logits.npy` per image, each shaped `CxHxW`. The Python API keeps
+the batch dimension (`B=1` for a single image). Channel order follows
+`label_schema.json`.
 Pass `--binary LABEL` (for example `--binary femurs`) to write one label. See
 [docs/inference.md](https://github.com/VictorButoi/FleXray/blob/main/docs/inference.md)
 for the full CLI and Python API.
@@ -87,39 +89,48 @@ member = FleXraySegmenter.from_pretrained(
 ```
 
 The website demo exposes the same choices as quality modes: **Low** runs the
-flagship once, **Normal** runs the flagship with 16-pass TTA, **High** runs the
-five-model ensemble once, and **X-High** runs the ensemble with 16-pass TTA.
+flagship once, **Normal** runs the flagship with 8-pass TTA, **High** runs the
+five-model ensemble once, and **X-High** runs the ensemble with 8-pass TTA.
 The members are also listed in
 [MODEL_ZOO.md](https://github.com/VictorButoi/FleXray/blob/main/MODEL_ZOO.md).
 
 ## Test-time augmentation
 
-We typically run FleXray with test-time augmentation (TTA) rather than a single
-forward pass; `--tta-samples 16` (or `predict(..., tta_samples=16)`) is the
-setting behind reported results and the demo's Normal / X-High modes.
+The reported results use 16 passes per model (`--tta-samples 16` or
+`predict(..., tta_samples=16)`). The browser demo uses 8 passes per model in
+Normal and X-High modes; its current settings are published in the
+[demo manifest](https://flexray.csail.mit.edu/demo/demo_manifest.json).
 
 `tta_samples=N` runs one un-augmented pass plus `N - 1` randomly augmented
-passes and averages them in probability space (mean of sigmoid outputs, then
-converted back to logits). The augmentation chain is fixed in
-[`fxr.inference.tta`](https://github.com/VictorButoi/FleXray/blob/main/src/fxr/inference/tta.py)
-and the browser demo mirrors it exactly:
+passes and averages their sigmoid probabilities, then converts that mean
+back to logits. The package and browser implement the released `tta_v3`
+chain in this order:
 
-| Transform | Probability | Range |
+| Transform | Probability | Parameters |
 | --- | --- | --- |
-| Horizontal flip (exactly inverted on the logits before merging) | 0.5 | - |
-| Gamma | 0.5 | gamma 0.9-1.1, gain 0.9-1.1 |
-| Intensity scale (additive) | 0.5 | -0.1 to 0.1 |
-| Brightness | 0.5 | 0.8-1.2 |
-| Sharpness | 0.5 | 0.6-1.4 |
-| Invert | 0.5 | - |
-| Contrast | 0.5 | 0.7-1.3 |
-
-The flip is the only geometric transform; intensity transforms do not move
-pixels and are not inverted. Augmented views are drawn from the global torch
-RNG (`torch.manual_seed` for reproducibility). With an ensemble, every view is
-drawn once and run through every member, so `M` members with `tta_samples=N`
-cost `M x N` forward passes (80 for the full ensemble at N=16). `tta_samples<=1`
-reproduces the plain single pass.
+| Horizontal flip | 0.5 | Exactly inverted on the prediction before averaging |
+| Invert intensities | 0.5 | `1 - image` |
+| CLAHE | 0.1 | Clip limit 1.0-2.0; 8 x 8 grid |
+| Gamma | 0.25 | Gamma 0.9-1.1; gain 0.9-1.1; mutually exclusive with CLAHE |
+| Contrast | 0.25 | Multiply intensities by 0.7-1.3 and clamp to [0, 1] |
+| Sharpness | 0.5 | Factor 0.7-1.3 |
+| Gaussian noise | 0.25 | Standard deviation 0.01 |
+
+The flip is the only geometric transform; intensity transforms are not
+inverted. The CLAHE/gamma branch leaves the image unchanged with probability
+0.65. See the
+[Python implementation](https://github.com/VictorButoi/FleXray/blob/main/src/fxr/inference/tta.py)
+and [browser implementation](https://flexray.csail.mit.edu/demo/tta.js).
+
+Use `predict(..., tta_samples=16, seed=42)` to reproduce the Python
+augmentation draws without changing the global torch RNG. With no seed,
+draws use the global torch RNG. The browser uses its own random-number
+source, so matching augmentation settings do not imply identical random views.
+
+With an ensemble, each view is drawn once and run through every member.
+`M` models and `N` passes therefore require `M x N` forward passes: 80 for
+the five-model ensemble at N=16, or 40 for the browser's X-High mode at N=8.
+`tta_samples<=1` disables augmentation.
 
 ## Input contract
 
@@ -183,8 +194,8 @@ Every dataset's license, redistribution status, and download pointer is
 documented in the
 [`VictorButoi/flexray-data`](https://huggingface.co/datasets/VictorButoi/flexray-data)
 card. That repository ships the real X-ray sources whose licenses permit
-redistribution, already packed in the FleXray protocol, the MURA masks, and
-the FluXray database.
+redistribution as image/mask pairs with packaging manifests, the MURA masks,
+and the FluXray database.
 
 ## Evaluation
 
@@ -222,7 +233,8 @@ clinical diagnosis, treatment planning, or patient-care decisions.
 - `members/<name>/checksums.json`: SHA256 checksums of the bundle files.
 - `members/<name>/onnx/flexray-<name>-256-fp16.onnx`: fp16 ONNX export
   (opset 18, sigmoid baked in) used by the in-browser demo; parity-checked
-  against the PyTorch weights by `tools/export_web_demo.py`.
+  against the PyTorch weights by `scripts.release.export_web_demo` in the
+  release tooling.
 
 ## Licenses