---

name: data-preparation description: "Prepare Medical-SAM-Adapter data, checkpoints, and CUDA prerequisites, then validate a registered 2D or 3D sample contract before training or evaluation." metadata: disco-role: operating disable-model-invocation: true license: GPL 3.0

Data preparation

Use this route when a Medical-SAM-Adapter run has uncertain input files, registered dataset name, sample shape, prompt metadata, checkpoint, dependency, or GPU/memory requirements. This route is a read-only preflight: it never downloads data or weights, edits a dataset, imports the repository to inspect a sample, or launches training/evaluation.

Start at the root Medical-SAM-Adapter route when the user has not chosen a workflow. After the inputs pass this route, hand model and command choices to training, or hand checkpoint scoring and metric questions to evaluation. Do not use this route for the standalone detector workflow; that belongs to MobileSAMv2 inference.

Required preflight sequence

1. Freeze the caller-owned paths. Record data_path, checkpoint paths, output paths, and the selected CUDA device explicitly. A path is ready only when the expected file or directory is readable. Do not infer a data root from a checkpoint filename or from the current working directory.

2. Choose the exact dispatcher spelling. The source compares names literally: isic, decathlon, REFUGE, LIDC, DDTI, Brat, STARE, kits, WBC, segrap, toothfairy, atlas, pendal, and lnq. Read dataset layouts; changing case changes the branch or produces an unsupported-dataset path.

3. Check the adapter layout before opening a loader. Confirm the required CSV, image/mask pair, volume, NRRD, NumPy, pickle, or MONAI split files for one representative case. Missing files, an unmatched stem, or a missing rater is a data error, not a reason to substitute a different registry name.

4. Check the runtime gate. Actual training and evaluation require a CUDA-capable PyTorch runtime. Verify CUDA availability, the selected device, one CUDA allocation, python -m pip check, and the dependency for the selected adapter. CPU parsing or metadata validation is diagnostic only; it does not verify the workflow. See checkpoints and environment.

5. Check checkpoint roles without deserializing untrusted files. -sam_ckpt is the base SAM-family input for checkpoint-consuming builders; -weights is a saved adapter/resume record. Both must be explicit readable files and must match the selected network and encoder. Never download a missing file or treat a basename as compatibility evidence.

6. Export one sample declaration and validate it. From the installed skill root, run the bundled read-only helper:

   python sub-skills/data-preparation/scripts/validate_sample_contract.py \
     --sample sample.json --format auto --dataset isic
   

   Use --help for the JSON/NPZ schema. A nonzero status blocks the run. A zero status proves only declared fields, ranks, channel/depth relationships, prompt coordinates, and optional chunk bounds; it does not decode NIfTI/NRRD, run MONAI transforms, load a checkpoint, or execute CUDA.

7. Apply dimensional and mask checks. A per-sample image is [C,H,W] for 2D or [C,H,W,D] for 3D; DataLoader adds [B,...] later. The label has the same rank and corresponding spatial axes. The source permits H/W to be resized separately to image_size and out_size, but depth and slice alignment must never change. Follow the data contract.

8. Choose memory controls before launch. For 2D lower -b and -image_size. For MONAI 3D lower -b, -chunk, -num_sample, and evaluation -evl_chunk; keep -roi_size compatible with the transformed in-plane data. Then route to training or evaluation rather than launching from this skill.

Sample contract at a glance

A custom dataset item must provide:

{
    "image": numeric [C,H,W] or [C,H,W,D],
    "label": numeric mask with the same rank and aligned spatial axes,
    "p_label": 0/1 prompt label(s),
    "pt": [x,y], [N,2], or one [x,y] point per 3D slice,
    "image_meta_dict": {"filename_or_obj": "stable-case-name"}  # recommended
}

The README calls image_meta_dict optional, but the current training and validation loops access filename_or_obj while naming visualizations. Include it for the unmodified core path. box and multi_rater are optional adapter fields; the core prompt call passes boxes=None, so neither replaces the required label/pt contract.

For 2D built-in adapters, images are normally RGB [3,H,W]; REFUGE returns two mask channels in cup-then-disc order. Direct 3D adapters normally return [1,H,W,D] image and mask; the 3D loop generates one prompt per depth slice and repeats image slices to three channels before SAM. MONAI Decathlon/BTCV data is loaded channel-first and transformed before the crop/chunk checks. Empty masks may produce a negative prompt label (0) and a fallback point; inspect that case instead of silently treating it as a valid foreground annotation.

-multimask_output is a decoder output/class-count setting, not a way to create missing labels. The original SAM branch requests multiple masks when its value is greater than one; EfficientSAM and MobileSAM branches force a single output. Keep it aligned with label channels and route the model decision to training.

Scope boundary and limits

This route owns data layouts, exact registry names, custom sample fields, prompt/mask shape preflight, checkpoint/environment prerequisites, and memory risk. It does not own optimizer/adaptation internals, metric formulas, or standalone object-aware detector operation. Concrete failures and source-level limits are collected in troubleshooting.