SegProbe

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

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

python -m pip install segprobe

For development, install it from a local clone:

python -m pip install -e .

Quick start

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.

Prompt protocols

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)

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.

Interpolate boxes you already have

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

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.

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.

from segprobe import jitter_plan

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

Public MedSAM example

examples/medsam_lidc.py connects SegProbe to the official MedSAM ViT-B model. 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:

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

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

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.

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

python -m pip install -e ".[dev]"
ruff 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.

The images in this README use a cropped, windowed, and annotated case from the public LIDC-IDRI collection:

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

LIDC-IDRI is available under the Creative Commons Attribution 3.0 license.

License

SegProbe is released under the Apache-2.0 license.