Metadata-Version: 2.4
Name: medsam-lite-tools
Version: 0.1.0
Summary: LiteMedSAM segmentation training and inference tools.
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/bowang-lab/MedSAM
Project-URL: Source, https://github.com/bowang-lab/MedSAM/tree/LiteMedSAM
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: numpy>=1.23.0
Requires-Dist: timm>=0.9.0
Provides-Extra: train
Requires-Dist: monai>=1.3.0; extra == "train"
Requires-Dist: SimpleITK>=2.3.0; extra == "train"
Requires-Dist: nibabel>=5.2.0; extra == "train"
Requires-Dist: pandas>=2.0.0; extra == "train"
Requires-Dist: pyarrow>=15.0.0; extra == "train"
Requires-Dist: scikit-image>=0.22.0; extra == "train"
Requires-Dist: opencv-python>=4.8.0; extra == "train"
Requires-Dist: tqdm>=4.66.0; extra == "train"
Provides-Extra: test
Requires-Dist: build>=1.2.2; extra == "test"
Requires-Dist: pytest>=8.3.0; extra == "test"
Dynamic: license-file

# medsam-lite-tools

`medsam-lite-tools` is a LiteMedSAM segmentation package for model building, fine-tuning, inference, and Python-based experimentation.

It provides:

- a LiteMedSAM model builder with pretrained initialization
- a command-line training loop for preprocessed `.npz` segmentation data
- a command-line inference runner for `.npz` image samples
- Python APIs for training and prediction workflows

## Install

```powershell
pip install medsam-lite-tools
```

For training workflows with common medical-image utilities:

```powershell
pip install "medsam-lite-tools[train]"
```

## Build a Model

```python
from medsam_lite_tools import model

net = model(pretrained=True, root="./temp/")
```

`pretrained=True` builds the LiteMedSAM architecture with pretrained initialization and is the default starting point for fine-tuning. Use `pretrained=False` when training from scratch.

```python
from medsam_lite_tools import model

net = model(pretrained=False)
```

## Training

Training input is a directory of `.npz` files.

Each file should include:

- `image`, `img`, `data`, or `x`: image array
- `mask`, `label`, `seg`, `gt`, or `y`: binary mask array
- optional `box` or `bbox`: `[x_min, y_min, x_max, y_max]`

If no box is provided, the trainer computes one from the mask.

```powershell
medsam-lite-train ^
  --data-dir .\train_npz ^
  --output-dir .\runs\medsam_lite ^
  --epochs 5 ^
  --batch-size 2 ^
  --lr 1e-5 ^
  --checkpoint-root .\temp
```

The command starts from the pretrained LiteMedSAM initialization by default and writes `latest.pt` to the output directory.

The same workflow can be called from Python:

```python
from medsam_lite_tools import fit

net, history = fit(
    data_dir="./train_npz",
    output_dir="./runs/medsam_lite",
    epochs=5,
    batch_size=2,
    lr=1e-5,
    checkpoint_root="./temp",
)
```

## Inference

Inference input is a directory of `.npz` image samples. Each file should include `image`, `img`, `data`, or `x`. If `box` or `bbox` is present, it is used as the prompt box. Otherwise, the full 256 x 256 image area is used.

```powershell
medsam-lite-infer ^
  --input-dir .\test_npz ^
  --output-dir .\runs\medsam_lite_predictions ^
  --checkpoint .\runs\medsam_lite\latest.pt ^
  --root .\temp
```

The command writes one compressed `.npz` mask file per input sample.

Python usage:

```python
from medsam_lite_tools import model, predict_npz_dir

net = model(pretrained=True, root="./temp/")
outputs = predict_npz_dir(
    input_dir="./test_npz",
    output_dir="./runs/medsam_lite_predictions",
    checkpoint="./runs/medsam_lite/latest.pt",
    root="./temp",
)
print(outputs)
```

## Notes

- Model initialization does not require runtime network access.
- The training and inference APIs use LiteMedSAM pretrained initialization when `pretrained=True`.
- Existing initialization files under `root` are reused when their size and SHA-256 digest match the expected metadata.

## Attribution

The model architecture and initialization workflow are based on the `LiteMedSAM` branch of `bowang-lab/MedSAM`.

- Upstream repository: <https://github.com/bowang-lab/MedSAM/tree/LiteMedSAM>
- Upstream license: Apache License 2.0

The vendored code is limited to the LiteMedSAM model construction path needed for training and inference experiments.
