Metadata-Version: 2.4
Name: segprobe
Version: 0.2.0
Summary: Reproducible, model-agnostic prompt evaluation for medical segmentation.
Author: Elhaj Samitt Ebou
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/hajteyib/segprobe
Project-URL: Issues, https://github.com/hajteyib/segprobe/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# SegProbe

SegProbe makes box-prompt experiments reproducible across medical image
segmentation models. It generates prompt protocols, records the manual effort,
and evaluates slice-based or volumetric models through one small API.

Promptable models can change rank when the prompt protocol changes. SegProbe
makes that protocol and its manual budget part of the result.

![SegProbe overview](https://raw.githubusercontent.com/hajteyib/segprobe/main/docs/assets/segprobe-overview.png)

It started as code i used while testing MedSAM. i wanted to answer simple
questions without rewriting the evaluation each time:

- How many boxes must be drawn manually?
- What happens if boxes are sparse, larger, or slightly misplaced?
- Can the same protocol be compared across different models?

SegProbe has one runtime dependency: NumPy. It does not download a model or a
dataset.

## Install

```bash
python -m pip install segprobe
```

For development, install it from a local clone:

```bash
python -m pip install -e .
```

## Quick start

```python
from segprobe import evaluate, sparse_boxes

plan = sparse_boxes(target_mask, every=3, padding=5)


def predictor(volume, z_index, box_xyxy):
    image_slice = volume[z_index]
    return my_model.predict(image_slice, box=box_xyxy)


result = evaluate(predictor, image_volume, target_mask, plan)

print(result.dice)
print(result.manual_boxes)
print(result.generated_boxes)
```

The `predictor` function is the only model-specific part. It can call MedSAM,
SAM2, nnInteractive, or your own slice-based model.

For a volumetric model, the full plan is passed once. The boxes can also become
a second input channel:

```python
import numpy as np

from segprobe import evaluate_volume


def volume_predictor(volume, plan):
    box_prior = plan.to_prior_channel()
    model_input = np.stack([volume, box_prior], axis=0)
    return my_3d_model(model_input)


result = evaluate_volume(volume_predictor, image_volume, target_mask, plan)
```

This keeps the model adapter small. SegProbe does not decide how the image or
prior should be normalized.

`plan.to_crop_bounds(margin_mm=25)` returns a physical-margin crop around all
delivered boxes. `lift_slice_predictor(...)` can adapt an existing slice
callback to the volume interface.

## Prompt protocols

```python
from segprobe import global_box, slice_boxes, sparse_boxes

dense = slice_boxes(mask, padding=5)
global_prompt = global_box(mask, padding=5)
sparse = sparse_boxes(mask, every=3, padding=5)
```

| Protocol | Manual effort | Boxes sent to the model |
| --- | ---: | --- |
| `slice_boxes` | one per positive slice | one manual box on each slice |
| `global_box` | one per volume | the same box reused on all positive slices |
| `sparse_boxes` | one every N positive slices, plus the last | manual anchors and interpolated boxes |

Each plan reports `manual_boxes`, `generated_boxes`, and `manual_fraction`.
`plan.to_dict()` returns the boxes and protocol parameters as plain Python
values ready for JSON. `PromptPlan.from_dict()` restores the same plan later.

### Physical padding

Pixel padding is still the default. If volumes have different spacing, the
margin can instead be declared in millimetres:

```python
from segprobe import Geometry, slice_boxes

geometry = Geometry(mask.shape, spacing_zyx=(2.5, 0.8, 0.8))
plan = slice_boxes(mask, geometry=geometry, padding_mm=5)
```

The conversion to pixels is stored in `plan.params`. Shape and spacing always
use `(z, y, x)` order.

### Interpolate boxes you already have

You do not need a reference mask if the boxes were drawn manually or produced
by another tool:

```python
from segprobe import interpolate_boxes

plan = interpolate_boxes(
    {
        10: (40, 50, 90, 100),
        20: (45, 55, 96, 108),
    },
    shape_zyx=(30, 512, 512),
)
```

By default, this returns one box on every slice from the first anchor to the
last. Pass `slices=[10, 12, 14, 16, 18, 20]` to generate boxes only on selected
slices. The anchors stay marked as manual and the interpolated boxes as
generated.

### Sparse prompts

Here, only five boxes are drawn manually. The other fifteen are interpolated.

![Sparse box interpolation through a CT volume](https://raw.githubusercontent.com/hajteyib/segprobe/main/docs/assets/sparse-prompts.gif)

Blue boxes are manual anchors. Orange dashed boxes are generated between them.
The green line is the reference-mask contour.

## Prompt robustness

Box size and placement can change a promptable model's result. SegProbe can add
padding or apply deterministic perturbations, so the same stress test can be
run again with the same seed. A non-empty `sample_key` keeps the perturbations
different across cases, and the sampled box always overlaps its source box.

```python
from segprobe import jitter_plan

noisy = jitter_plan(
    dense,
    max_translate=5,
    max_expand=10,
    seed=42,
    sample_key="case-001",
)
```

![Box size, translation, and expansion](https://raw.githubusercontent.com/hajteyib/segprobe/main/docs/assets/prompt-geometry.gif)

## Public MedSAM example

[`examples/medsam_lidc.py`](examples/medsam_lidc.py) connects SegProbe to the
official [MedSAM ViT-B model](https://github.com/bowang-lab/MedSAM). It expects
one folder per case containing
`image.nii.gz` and `mask.nii.gz`.

Run it from an environment where MedSAM, PyTorch, NiBabel, and scikit-image are
available:

```bash
python examples/medsam_lidc.py \
  --cases-root /path/to/lidc_crops \
  --one-per-patient \
  --limit 5 \
  --medsam-repo /path/to/MedSAM \
  --checkpoint /path/to/medsam_vit_b.pth \
  --output-dir medsam_results \
  --device cpu
```

The script saves `results.csv` and `results.json` after every protocol. Running
the same command again resumes from the saved results.

We used it for a small public check with five LIDC-IDRI nodules, one per
patient. The run used the official MedSAM checkpoint, no private fine-tuning,
no postprocessing, and an oracle positive z-range from the reference mask.

### Prompt density with padding=5

| Protocol | Mean manual boxes | Mean generated boxes | Mean Dice ± SD |
| --- | ---: | ---: | ---: |
| Global | 1.0 | 16.0 | 0.372 ± 0.173 |
| Sparse every 5 slices | 4.4 | 12.6 | 0.515 ± 0.267 |
| Sparse every 3 slices | 7.0 | 10.0 | 0.508 ± 0.270 |
| Sparse every 2 slices | 9.2 | 7.8 | 0.510 ± 0.270 |
| Dense | 17.0 | 0.0 | 0.511 ± 0.271 |

In this small run, sparse prompting every five slices used about 74% fewer
manual boxes than dense prompting, with nearly the same mean Dice.

### Dense prompt geometry

| Box | Mean Dice ± SD |
| --- | ---: |
| Tight, `padding=0` | 0.843 ± 0.031 |
| `padding=5` | 0.511 ± 0.271 |
| Large, `padding=10` | 0.310 ± 0.224 |
| `padding=5` with deterministic jitter | 0.363 ± 0.263 |

The tight box is derived directly from the reference mask, so it is a strong
oracle prompt. These five cases are a reproducibility example, not a model
comparison or a clinical result.

## Inputs and image formats

SegProbe works with arrays, not a specific medical file format. CT, MRI, PET,
and other 3D images can use the same API after they are loaded into NumPy.

- The mask must have shape `(z, y, x)`.
- The image must start with the same dimensions: `(z, y, x)` or
  `(z, y, x, channels)`.
- Boxes use `(x_min, y_min, x_max, y_max)`, with exclusive maximum coordinates.

NIfTI, DICOM, NRRD, and other files can be loaded with tools such as NiBabel,
SimpleITK, or pydicom. File loading stays outside SegProbe so the core package
remains small and does not impose an imaging stack.

## Evaluation output

`evaluate` returns the predicted 3D mask together with:

- Dice and IoU;
- target and prediction voxel counts;
- manual and generated box counts;
- number of prompted slices.

The scalar values are available with `result.to_dict()` for a CSV or JSON
report.

`evaluate` and `evaluate_volume` accept a numeric `threshold`. Postprocessing
can be added as named steps, so raw and final scores stay separate:

```python
from segprobe import PostprocessStep, largest_connected_component

step = PostprocessStep("largest_component", largest_connected_component)
result = evaluate(predictor, image, target, plan, postprocess=[step])

print(result.raw_dice, result.dice)
```

## Run a cohort

`run_study` evaluates every case, protocol, and model combination. It writes an
atomic JSON result after each completed run, then skips completed combinations
when restarted.

```python
from segprobe import Case, Model, PromptProtocol, run_study, sparse_boxes

cases = [Case("case-001", image, target)]
protocols = [
    PromptProtocol(
        "sparse-3",
        lambda case: sparse_boxes(case.target, every=3, padding=5),
        params={"every": 3, "padding": 5},
    )
]
models = [Model("my-model", predictor, kind="slice", params={"weights": "v1"})]

results = run_study(
    cases,
    protocols,
    models,
    output_path="study.json",
    study_params={"cohort": "development-v1"},
)
```

The declared protocol and model parameters are part of the resume check. They
can also be frozen separately with `write_protocol_lock(...)` and checked with
`verify_protocol_lock(...)`. SegProbe cannot inspect hidden settings inside a
callback, so important settings and checkpoint identifiers should be included
in `params`.

`prompt_effort_curves(results)` groups the results by model and protocol. Each
point reports mean manual boxes, mean generated boxes, mean Dice or IoU, its
standard deviation, and the number of cases. The curve also provides normalized
area and the first mean budget reaching a requested score.

A complete synthetic example is available in
[`examples/study_usage.py`](examples/study_usage.py). Use pseudonymous case IDs:
the saved result rows contain them, while the study definition stores only a
combined digest.

## Scope

The mask-based prompt generators are made for controlled oracle-prompt
evaluation, not automatic lesion localization. `interpolate_boxes` can instead
use boxes supplied directly by a reader, detector, or annotation tool.

With the mask-based generators, only reference-positive slices receive a box,
so the positive z-range is known. Those results should be described as
prompt-effort or prompt-robustness experiments, not end-to-end detection
results.

The manual-box count is an effort proxy. It is not a measurement of annotation
time. SegProbe is a research evaluation tool and is not intended for clinical
decision-making.

## Development

```bash
python -m pip install -e ".[dev]"
ruff check .
ruff format --check .
pytest -q
python -m build
```

Tests use small synthetic masks. They do not download images, checkpoints, or
patient data.

## Citation

If SegProbe supports your work, please cite the software using
[`CITATION.cff`](CITATION.cff).

The images in this README use a cropped, windowed, and annotated case from the
public [LIDC-IDRI collection](https://www.cancerimagingarchive.net/collection/lidc-idri/):

> Armato III, S. G., McLennan, G., Bidaut, L., et al. (2015). Data From
> LIDC-IDRI. The Cancer Imaging Archive.
> [https://doi.org/10.7937/K9/TCIA.2015.LO9QL9SX](https://doi.org/10.7937/K9/TCIA.2015.LO9QL9SX)

LIDC-IDRI is available under the
[Creative Commons Attribution 3.0 license](https://creativecommons.org/licenses/by/3.0/).

## License

SegProbe is released under the [Apache-2.0 license](LICENSE).
