Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,154 @@
+---
+license: cc-by-4.0
+library_name: quantem-core
+pipeline_tag: image-segmentation
+tags:
+  - electron-microscopy
+  - image-segmentation
+  - organelle
+  - mitochondria
+  - vision-transformer
+  - napari
+---
+
+# QuantEM — organelle segmentation for electron microscopy
+
+Eight segmentation models covering **mitochondria, endoplasmic reticulum, nucleus and lipid
+droplets**, each in two encoder sizes:
+
+| Family | Encoder | Params | Notes |
+|---|---|--:|---|
+| **QuantEM** | ViT-B/16 | 86 M | Trained from scratch on an EM corpus using the DINOv3 recipe. |
+| **OmniEM** | ViT-L/14 | 302 M | Heads trained on the published OmniEM (EM-DINO) encoder. |
+
+Recommended defaults: **QuantEM for mitochondria; OmniEM for ER, nucleus and lipid droplets.**
+
+## Use
+
+These files are not loaded directly. Install the library, which resolves, downloads, verifies and
+assembles them for you:
+
+```bash
+pip install quantem-core
+```
+
+```python
+from quantem_em.api import load_model, segment
+
+model = load_model("quantem/mito")          # downloads on first use, then cached
+labels = segment(model, image, pixel_size_nm=8.0)
+```
+
+For a GUI, install the napari plugin instead — it wraps the same library with segmentation,
+proofreading, head-only fine-tuning, batch mode and morphometrics:
+
+```bash
+pip install napari-quantem
+```
+
+Pre-seed a shared or air-gapped cache with:
+
+```bash
+python -m quantem_em.weights download --all
+QUANTEM_MODEL_DIR=/srv/quantem python -m quantem_em.weights verify
+```
+
+## Files
+
+Encoders are split so nothing is downloaded twice. **The split is not uniform**, because the
+families adapt their encoders differently:
+
+* **OmniEM** uses LoRA, which never touches the base weights — so `omniem-vitl` is a complete
+  encoder genuinely shared by all four heads, and each head is only ~26 MB.
+* **QuantEM** mito/nucleus/LD fine-tune the **last four blocks**, which therefore differ per
+  organelle. `quantem-vitb-trunk` is blocks 0–7 plus embeddings and the final norm; blocks 8–11
+  ship inside each organelle file.
+* **`quantem-er` is self-contained.** It was adapted with `full`, replacing the whole encoder, so
+  it needs no trunk.
+
+| File | Size | Contents | SHA-256 |
+|---|--:|---|---|
+| `quantem-vitb-trunk.safetensors` | 227.7 MB | QuantEM ViT-B/16 blocks 0-7 + embeddings + final norm. Shared by the mitochondria, nucleus and lipid-droplet heads, whose own artifacts carry the fine-tuned blocks 8-11. | `637a8c321a7b2172…` |
+| `omniem-vitl.safetensors` | 1.2 GB | OmniEM (EM-DINO) ViT-L/14 encoder. Untouched by LoRA, so genuinely shared by all four OmniEM heads. | `d7f2dffe2ec23138…` |
+| `quantem-mito.safetensors` | 136.5 MB | model | `a897bf322872d1ae…` |
+| `quantem-nucleus.safetensors` | 136.5 MB | model | `d5152b6c2b5ccdbf…` |
+| `quantem-ld.safetensors` | 136.5 MB | model | `765d1a8e281edf7e…` |
+| `quantem-er.safetensors` | 465.0 MB | Self-contained: adapt=full replaces the entire encoder, so this needs no trunk. | `50bcdfedc497041f…` |
+| `omniem-mito.safetensors` | 25.7 MB | model | `7e5c2c8b6ffede26…` |
+| `omniem-nucleus.safetensors` | 25.7 MB | model | `3142057d3b36b482…` |
+| `omniem-ld.safetensors` | 25.7 MB | model | `ae5b0c356e0fb48d…` |
+| `omniem-er.safetensors` | 135.2 MB | model | `3e3a693ea757d500…` |
+
+Every file is verified against the SHA-256 above on download **and on every subsequent load**, so a
+truncated or altered file is detected rather than trusted.
+
+## Licence
+
+**The weights are released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).**
+Commercial use, redistribution and modification are permitted; the only condition is attribution —
+credit the QuantEM authors, link to the licence, and indicate if you made changes.
+
+The `quantem-core` and `napari-quantem` **code** is BSD-3-Clause, which is a separate licence on a
+separate thing.
+
+CC BY rather than a software licence because weights are not source code: the "source and binary
+form" language of BSD does not map onto a state dict. CC BY is also what most of the underlying
+annotation data uses, which keeps the attribution chain coherent.
+
+### Position on training data
+
+Training data for the released heads is CC0 or CC BY 4.0 with the exceptions below. Two sources
+carry copyleft rather than field-of-use terms:
+
+| Source | Licence | Share of that organelle's train+val crops |
+|---|---|--:|
+| DeepContact | GPL-3.0 (applied to data) | mito 5.6 %, ER 11.4 % |
+| ASEM / Incasem | CC BY-SA 4.0 | mito 2.5 %, ER 4.8 % |
+
+**Our position is that trained weights are not a derivative work or adaptation of the training
+images.** They are statistical parameters, not a reproduction or transformation of any particular
+image. We state this explicitly rather than leaving it implied, and we apply it consistently —
+we do not treat the weights as independent of the data here and as derived from it elsewhere.
+Attribution is given in full below regardless, because attribution is owed to every CC-licensed
+source whether or not ShareAlike is triggered.
+
+Two sources with research-use-only terms — **Lucchi++** (EPFL) and **Kasthuri++**
+(Harvard/Lichtman) — were present in earlier mitochondria runs and have been **removed**; the
+released mitochondria head is retrained without them. A field-of-use restriction binds regardless
+of how the derivative-work question is decided, so those could not be reasoned around.
+
+## Attribution
+
+Full per-source tables, with tile and crop counts and a DOI for every entry, are published as
+datasets alongside these weights:
+
+* **[`ArrojoeDrigoLab/quantem-organelle-model-sources`](https://huggingface.co/datasets/ArrojoeDrigoLab/quantem-organelle-model-sources)**
+  — the annotated ground truth behind these eight models, per organelle.
+* **[`ArrojoeDrigoLab/quantem-base-model-sources`](https://huggingface.co/datasets/ArrojoeDrigoLab/quantem-base-model-sources)**
+  — all 655 datasets in the corpus the base encoder was pretrained on.
+
+Those two tables are generated directly from the manuscript's supplementary tables, so they
+cannot drift from what was actually trained on. They are the authoritative list; this card
+deliberately does not keep a second copy.
+
+**Modifications.** All sources were tiled, cropped and in some cases resampled; annotations were
+consolidated onto a common organelle vocabulary. No source is redistributed here in its original
+form.
+
+**Pretraining corpus.** The QuantEM ViT-B encoder was pretrained on the wider EM corpus described
+in the manuscript — public repositories under their own terms, plus data contributed directly by
+27 authors under CC BY 4.0 for this purpose. Contributors are named in the manuscript
+acknowledgements and Supplementary Table 1.
+
+## Upstream components
+
+| Component | Licence | Notes |
+|---|---|---|
+| `timm` (DINOv3 / DINOv2 architecture code) | Apache-2.0 | `timm/models/eva.py` states its DINOv3 code is a modification of the EVA model and is Apache-2.0 like the rest of timm; only *Meta's weights* remain under the DINOv3 licence. **No Meta weights are used or redistributed here.** |
+| QuantEM ViT-B encoder | ours, CC BY 4.0 | Trained **from scratch** on our own EM corpus using the published DINOv3 recipe. No Meta checkpoint was used as initialisation and the released artifact contains no Meta tensors. |
+| OmniEM (EM-DINO) ViT-L encoder | code MIT (`pku-maleilab/omniem-package`) | The four OmniEM heads are built on the encoder published by Lei Ma's group at PKU; please cite OmniEM if you use them. The heads themselves are ours. |
+
+## Citation
+
+Acree *et al.*, *QuantEM: An optimized platform of vision transformer-based models for
+segmentation and analysis of electron microscopy data.* Citation details on publication.