Write the flagship model card: ensemble members, TTA recipe, data release link

README.md

@@ -1,47 +1,246 @@
 ---
 license: cc-by-nc-4.0
 library_name: pytorch
+pipeline_tag: image-segmentation
+datasets:
+  - VictorButoi/flexray-data
 tags:
   - medical-image-segmentation
   - x-ray
+  - radiograph
+  - anatomy
   - flexray
 ---
 
-# VictorButoi/flexray-base
+# FleXray: `flexray-base`
 
-This is a FleXray segmentation model bundle. Fill in the public release details
-before upload.
+- Website and in-browser demo: [victorbutoi.github.io/FleXray](https://victorbutoi.github.io/FleXray/)
+- 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)
+- Paper: *FleXray: Flexible Full-Body X-ray Segmentation* (coming soon)
 
-## Intended Use
+`flexray-base` is the **flagship FleXray model**: a single 2D UNet that segments
+anatomy from standard radiographs across body regions, projections, and
+acquisition settings. It predicts 60 anatomical structures (plus background) as
+independent sigmoid channels at 256 x 256 resolution and is the default bundle
+loaded by `flexify` and `FleXraySegmenter.from_pretrained`.
 
-Describe the intended research use, input image requirements, output labels, and
-medical-use limitations. This model is not cleared for clinical diagnosis or
-patient-care decisions.
+It is also one member of a five-model ensemble; see
+[The FleXray ensemble](#the-flexray-ensemble) for the other four and
+[Test-time augmentation](#test-time-augmentation) for the inference recipe we
+use for reported results.
 
-## Training Data
+## Quick start
 
-Document every training dataset, source modality, license, preprocessing step,
-and inclusion or exclusion criterion.
+```bash
+python -m pip install flexray
+flexify --input ./image.png --output-dir ./predictions
+```
+
+```python
+from fxr.inference import FleXraySegmenter
+
+segmenter = FleXraySegmenter.from_pretrained("VictorButoi/flexray-base")
+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
+```
+
+`flexify` writes `<name>_masks.npy`, `<name>_probabilities.npy`, and
+`<name>_logits.npy` per 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.
+
+## The FleXray ensemble
+
+The flagship was trained with a 0.375 FluXray proportion in the training mix.
+Four sibling models share its architecture, label schema, preprocessing, and
+training recipe and differ only in that proportion:
+
+| Model ID | FluXray proportion | Role |
+| --- | --- | --- |
+| `VictorButoi/flexray-base-flux000` | 0.0 | ensemble member |
+| `VictorButoi/flexray-base-flux025` | 0.25 | ensemble member |
+| **`VictorButoi/flexray-base`** | **0.375** | **flagship (this repository)** |
+| `VictorButoi/flexray-base-flux050` | 0.5 | ensemble member |
+| `VictorButoi/flexray-base-flux075` | 0.75 | ensemble member |
+
+Because the members share one output space, any subset can be averaged in
+probability space:
+
+```bash
+flexify --model-id VictorButoi/flexray-base \
+        --model-id VictorButoi/flexray-base-flux000 \
+        --model-id VictorButoi/flexray-base-flux025 \
+        --model-id VictorButoi/flexray-base-flux050 \
+        --model-id VictorButoi/flexray-base-flux075 \
+        --tta-samples 16 --input ./image.png --output-dir ./predictions
+```
+
+```python
+segmenter = FleXraySegmenter.from_pretrained([
+    "VictorButoi/flexray-base",
+    "VictorButoi/flexray-base-flux000",
+    "VictorButoi/flexray-base-flux025",
+    "VictorButoi/flexray-base-flux050",
+    "VictorButoi/flexray-base-flux075",
+])
+prediction = segmenter.predict("./image.png", tta_samples=16)
+```
+
+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.
+Release status of each member is tracked 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.
+
+`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:
+
+| Transform | Probability | Range |
+| --- | --- | --- |
+| 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.
+
+## Input contract
+
+`preprocessing.json` is applied automatically by the public loaders:
+
+- grayscale input (RGB is converted), any 8-bit or 16-bit PNG / JPEG / TIFF / BMP
+- per-image percentile min-max normalization to `[0, 1]` (0.5th / 99.5th
+  percentiles, `eps = 1e-8`)
+- zero-pad to a square, then resize to 256 x 256
+- outputs are `multilabel` sigmoid probabilities; masks use threshold 0.5
+
+Outputs are at the 256 x 256 model resolution; the CLI and Python API do not
+resample back to the original image size.
+
+## Output labels
+
+61 channels: `background` at index 0, then 60 anatomical structures in the
+order stored in `label_schema.json` (protocol `all_structures_flexray_v4`):
+
+- **Skull / shoulder girdle:** skull, scapulae, clavicles
+- **Upper limb:** humeri, radii, ulnae, carpals, metacarpals, phalanges
+- **Lower limb:** femurs, patellae, tibiae, fibulae, tarsals, metatarsals, toes
+- **Thorax:** rib_1 - rib_12, sternum
+- **Spine:** vertebra_c1 - c7, t1 - t12, l1 - l5, sacrum
+- **Pelvis:** hips
+- **Soft tissue:** lungs, heart, liver, spleen, kidneys
+
+Paired structures are merged (for example `femurs` covers both sides);
+laterality is not predicted.
+
+## Architecture
+
+`fxr.models.UNet`, 2D, 1 input channel, 61 output channels; filters
+`[64, 128, 256, 512, 512, 720, 1024]`, 3 convolutions per block, residual
+blocks with instance norm, `align_corners=True` upsampling. The full
+architecture is in `config.yml`.
+
+## Training data
+
+The model was trained on three source types unified under the FleXray label
+protocol (mixing proportions in parentheses):
+
+- **Real X-ray masks:** HandBones (0.01), FootBones (0.01), MURA forearm
+  (0.01) and MURA humerus (0.01) with our own annotations.
+- **Generated FluXray images (0.375):** digitally reconstructed radiographs from
+  the MOOSE CTs, generatively edited toward real X-ray appearance, with exact
+  overlapping masks for every protocol structure.
+- **Online CT->DRR rendering:** MOOSE / ENHANCE-PET 1.6k (0.375), Shoulder-CT
+  (0.05), HaN-Seg (0.05), PedsCT (0.04), RSNA cervical-spine fracture CTs
+  (0.04), and ElbowCT (0.03), rendered to DRRs at random poses during training
+  with per-label attenuation jitter.
+
+Training used AdamW (lr 3e-4, cosine schedule), a Dice + binary cross-entropy
+loss routed per dataset (partially labeled sources ignore unlabeled channels),
+and separate augmentation presets for CT-derived and X-ray inputs. The exact
+recipe is `fxr/configs/training/base.yml` in the code release.
+
+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, plus the MURA masks;
+the FluXray database is released alongside it.
 
 ## Evaluation
 
-Report evaluation datasets, metrics, confidence intervals where available, and
-known failure modes.
+FleXray was evaluated on nine real-radiograph datasets held out from training
+(ElbowLat, HipRay, LowerLimbs, MendeleyCXR, MTDDH, DarwinCVD19, DeepFluoro,
+RAM-W600, VinDr-Rib), spanning lungs, ribs, peripheral bones, spine, and
+pelvis. Against generalist baselines (FluoroSAM, TotalSegmentator2D, PAXray)
+it achieves the highest macro Dice in every comparison (9 of 9). Per-dataset
+numbers and confidence intervals are in the paper; the benchmark figure is on
+the [project website](https://victorbutoi.github.io/FleXray/#results).
+Evaluation ignores ground-truth labels covering less than 0.1% of the image.
+
+## Intended use and limitations
+
+Research use only. FleXray is **not a medical device** and is not cleared for
+clinical diagnosis, treatment planning, or patient-care decisions.
+
+- Targets conventional radiographs; dental and mammographic images are out of
+  scope.
+- Predicts anatomy, not pathology.
+- No laterality (left/right) and no uncertainty estimates.
+- Performance on acquisition settings, views, or populations far from the
+  training sources has not been validated.
 
 ## Files
 
 - `model.safetensors`: exported model weights.
-- `config.yml`: model architecture config.
+- `config.yml`: architecture and protocol config consumed by `from_pretrained`.
 - `label_schema.json`: ordered output labels.
 - `preprocessing.json`: public preprocessing contract.
-- `checksums.json`: SHA256 checksums.
+- `checksums.json`: SHA256 checksums of the bundle files.
+- `onnx/flexray-base-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`.
 
 ## Licenses
 
-Code license: MIT
-
-Weights license: CC-BY-NC-4.0
+- Code: MIT
+- Weights: CC-BY-NC-4.0
 
 ## Citation
 
-Cite FleXray and any datasets used to train this model.
+```bibtex
+@software{butoi2026flexray,
+  title = {FleXray: Flexible Full-Body X-ray Segmentation},
+  author = {Butoi, Victor Ion and Gopalakrishnan, Vivek and
+            Guttag, John V. and Dalca, Adrian V. and Dey, Neel},
+  year = {2026},
+  license = {MIT},
+  url = {https://github.com/VictorButoi/FleXray}
+}
+```
+
+Please also cite the source datasets listed in the
+[`flexray-data`](https://huggingface.co/datasets/VictorButoi/flexray-data) card
+for any dataset you use.

checksums.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "files": {
-    "README.md": "59f705f7ab0923400d9b89bbfb91527e61e39883ab31655e44d6be017e3a00ef",
+    "README.md": "e6e5c17b8ece40c296e1fd40d92774a44d6bb6fb1e5452b94f00533ebddf694f",
     "config.yml": "7c7d52b2404d5e3cb5347036feac994ab8b8a18dd6bef5cfa47b749077af727a",
     "label_schema.json": "c8fa61b6585fc4043e2c51ba1f53271f9313cdae8d812479449b8a2a0ba12d7a",
     "model.safetensors": "716ce3a8fb2a6abe22b2f2188fd596ddc4642b273fb0d336d629448154fc6d24",