# Kindly CholecT50-derived clinical-episode corpus

**A NON-COMMERCIAL research corpus. Annotations only — no video. CC BY-NC-SA 4.0.**

This is the first at-scale, downloadable, schema-conformant **episode corpus** for
the open [Kindly clinical-episode schema](../kindly-episode.schema-v0.1.json). It
reformats CAMMA's **published CholecT50 annotations** — specifically the
form-free, publicly-downloadable **CholecTriplet2022 challenge-validation** label
files — into the Kindly four-layer episode schema, so surgical-AI researchers can
see the schema working on **real** laparoscopic-cholecystectomy labels rather than
synthetic examples.

It was generated by running the shipped, open-source converter
`ate episode convert --from cholect50` (from `foodforthought-cli/`) on the public
label JSONs. Nothing here is captured, owned, or invented by Kindly.

## ⚖️ License, honesty, and what this is NOT

- **License: [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)**
  (Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International). This
  corpus is a **derivative** of CAMMA's CholecT50 annotations, which are licensed
  CC BY-NC-SA 4.0, so — per ShareAlike — it is released under the **same**
  license. See [`LICENSE.md`](./LICENSE.md).
  - **NonCommercial:** research use only. No commercial use.
  - **ShareAlike:** derivatives must carry the same license.
  - **Attribution:** you must cite the works below.
- **This is NOT a Kindly-owned, proprietary, or commercial asset.** Kindly
  Robotics did **not** capture, own, or license this data, and has **no**
  affiliation with CAMMA / the dataset authors.
- **This is NOT proprietary clinical capture.** It is a reformatting of CAMMA's
  **published** annotations into the open schema.
- **Annotations only — no video or imagery.** Only the derived label structure
  (phase segments, action-triplet intervals, instrument-presence transitions) is
  included. **No** CholecT50 video frames / images are downloaded, extracted, or
  redistributed here. The gated Cholec80/CholecT50 videos are **not** touched.
- **L4 (workflow-context) is intentionally EMPTY.** The public corpus does not
  annotate interruptions / rework / deviations / handoffs — that is the layer the
  Kindly schema adds, and it is **never fabricated**.

## 📚 Attribution (required — please cite)

Derived from public datasets by CAMMA (ICube, University of Strasbourg / IHU
Strasbourg), all CC BY-NC-SA 4.0:

1. **CholecT50** (action-triplet, phase, and instrument labels)
   C.I. Nwoye, T. Yu, C. Gonzalez, B. Seeliger, P. Mascagni, D. Mutter,
   J. Marescaux, N. Padoy. *Rendezvous: Attention Mechanisms for the Recognition
   of Surgical Action Triplets in Endoscopic Videos.* Medical Image Analysis
   78:102433, 2022. DOI: [10.1016/j.media.2022.102433](https://doi.org/10.1016/j.media.2022.102433) · arXiv:2109.03223

2. **CholecTriplet2022 challenge-validation set** (the exact label files converted here)
   C.I. Nwoye, T. Yu, S. Sharma, A. Murali, D. Alapatt, A. Vardazaryan, et al.,
   D. Mutter, N. Padoy. *CholecTriplet2022: Show me a tool and tell me the
   triplet: an endoscopic vision challenge for surgical action triplet
   detection.* arXiv:2204.14746, 2023.

3. **Cholec80 / EndoNet** (underlying videos + 7-phase workflow taxonomy)
   A.P. Twinanda, S. Shehata, D. Mutter, J. Marescaux, M. de Mathelin, N. Padoy.
   *EndoNet: A Deep Architecture for Recognition Tasks on Laparoscopic Videos.*
   IEEE Transactions on Medical Imaging 36(1):86-97, 2017.
   DOI: [10.1109/TMI.2016.2593957](https://doi.org/10.1109/TMI.2016.2593957)

Source repository: <https://github.com/CAMMA-public/cholect50>

## 📦 Contents

`5` episodes derived from the 5 challenge-validation clips (VID68, VID70, VID73,
VID74, VID75), each a valid Kindly episode (`schema_version 0.1.1`). Timings are
**real** (derived from the per-frame annotation frame indices at the dataset's
native 1 fps); the challenge-validation release samples frames sparsely, so
segment bounds reflect the actual annotated frame positions across the video.

| Episode | Source clip | Duration | L1 phases | L2 triplets | L3 presence | L4 |
|---|---|---:|---:|---:|---:|---:|
| `kr-cholect50-challenge-vid68` | VID68 | 1952 s | 7 | 179 | 67 | 0 |
| `kr-cholect50-challenge-vid70` | VID70 | 1174 s | 7 | 96 | 27 | 0 |
| `kr-cholect50-challenge-vid73` | VID73 | 1355 s | 7 | 94 | 49 | 0 |
| `kr-cholect50-challenge-vid74` | VID74 | 1633 s | 7 | 213 | 71 | 0 |
| `kr-cholect50-challenge-vid75` | VID75 | 1918 s | 6\* | 103 | 41 | 0 |
| **Total** | 5 clips | — | 34 | **685** | **255** | 0 |

\* VID75's annotations contain only 6 of the 7 phases (no `cleaning_and_coagulation`
segment is annotated in the source) — faithfully reflected, not padded.

- [`manifest.json`](./manifest.json) — machine-readable index (per-episode counts,
  phases, durations, license, provenance).
- [`episodes/`](./episodes/) — the episode JSONs.
- [`build_corpus.py`](./build_corpus.py) — the reproducible generator.

### Layer mapping

- **L1 (phase/step):** CholecT50 per-frame phase labels → merged phase segments.
- **L2 (action triplets):** CholecT50 `<instrument, verb, target>` triplets (with
  their ivtmetrics class ids). Only **real** actions are placed in L2;
  instrument-presence-only triplets (verb/target = null) are represented in L3.
- **L3 (object/instrument state):** per-frame instrument presence (6 instruments)
  → coarse `in_field` / `absent` transitions.
- **L4 (workflow-context):** empty (see above).

### Phase-label handling

Phase values are the CholecT50 published phase labels, snake_cased. The **only**
correction applied is the dataset's typo `carlot-triangle-dissection` →
`calot_triangle_dissection` (Calot's triangle, after J.-F. Calot). Phase 6 is kept
as the dataset labels it, `gallbladder_extraction` (equivalent to Cholec80's
`gallbladder_retraction`). The **exact source label string is preserved** in every
L1 segment's `note`.

## 🔁 How to reproduce

The corpus is regenerable from the public data — Kindly redistributes none of it.

```bash
# 1. Obtain the form-free public label files yourself (annotations live in the zip
#    alongside video frames; use ONLY the labels, and do not redistribute video):
curl -LO https://s3.unistra.fr/camma_public/datasets/cholect50/CholecT50-Challenge-Validation.zip
unzip -o CholecT50-Challenge-Validation.zip 'cholect50-challenge-val/labels/*.json'

# 2. Regenerate the corpus with the shipped converter:
python public/clinical/cholect50-corpus/build_corpus.py \
    --labels-dir cholect50-challenge-val/labels

# Or convert a single clip directly with the CLI:
ate episode convert --from cholect50 cholect50-challenge-val/labels/VID68.json -o VID68.json
ate episode validate VID68.json
```

Every episode in this corpus passes `ate episode validate`.

## De-identification

CholecT50 was released de-identified by CAMMA (out-of-body frames are blacked out
in the source). This corpus redistributes **no** video or imagery — only derived
label structure, which contains no PHI. Each episode therefore carries
`deid.status: verified` with `phi_residual_risk: none`.