ENH: Add BubbleSAM detection method

[nidhinthomas-ai]

This merge request introduces a new library module, neat_ml/bubblesam, which wraps the Segment Anything‑2 (SAM‑2) model for detecting circular “bubble” features in microscopy images. It also adds an accompanying test suite with deterministic baseline image comparisons.

What’s inside

• BubbleSAM Blob Detection
  • neat_ml/bubblesam/SAM.py: Wrapper around SAM‑2 providing:
    • model construction via build_sam2(...) using a YAML config + checkpoint.
    • setup_cuda() helper to enable bfloat16/TF32 on Ampere‑class GPUs for speed.
    • generate_masks(...) to run SAM2AutomaticMaskGenerator on an RGB image and return masks sorted by area.
  • neat_ml/bubblesam/bubblesam.py End‑to‑end bubble detection utilities built on SAMModel
    • analyze_and_filter_masks(...) computes shape metrics (area, circularity, axes)
    • plot_filtered_masks(...) draws blue contours and green bounding boxes for retained regions.
    • process_image(...) runs the full SAM‑2 -> filter -> (optional) debug overlay/contours flow and persists artifacts/summary.
    • run_bubblesam(...) batch‑orchestrator returning one‑row‑per‑image summaries with median_radii_SAM and num_blobs_SAM.
• Running bubblesam detection
  Instructions for running bubblesam detection have been added to the README.md file

[adamwitmer]

Initial TODO items for reviewing this branch:

• read/understand diff/PR (read line-by-line, probing for weaknesses)
• check for unnecessary complexity; areas for improvement/simplification
• rebase branch against main (and push backup branch)
• fix issues with git lfs (i.e. image storage with zenodo https://github.com/lanl/ldrd_neat_ml_images)
• fix github CI
• run test-suite and check test coverage
• run branch according to README.md instructions
• copy remaining review comments from gitlab
• perform detailed code review
• address all review comments
• triple check diff
  • 1st check
  • 2nd check
  • 3rd check

[adamwitmer]

There are several files in this repo that are also included in PR #2, specifically detection.py, preprocessing.py and their testing modules, as well as references to OpenCV in the README.md. Depending on how dependent the BubbleSAM functions/tests are on these modules, they should either be removed here or rebased after merging PR #2 (removing here being preferable to avoid tedious conflicts)

[tylerjereddy]

Ok, I've provided a pretty detailed review here, good luck! This was presented for review pretty far past the original December 2025 deadline, and I probably can't provide reviews this detailed super regularly, so I do recommend presenting things for review roughly on time moving forward.

[tylerjereddy]

I'd say make sure you have tested instructions for running on Chicoma here before pinging me for another round of review.

[tylerjereddy]

Let's get proper instructions for running on Chicoma--you've had a few months to reproduce the paper results there now, so I think that's fair to ask for. And you need to run there again for Mihee soon on block copolymer images.

[adamwitmer]

I was able to run the workflow incantation described in #3 (comment) (with the full mask_settings) on Chicoma using the allocation for this LDRD. I allocated an interactive node with the following command:

salloc -p gpu -C gpu40 -N 1 -n 1 -t 1:00:00 --account=w25_fly-aug_g

and ran the workflow on a single GPU, which gave the following outputs:

[BubbleSAM]: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [25:30<00:00, 1530.90s/it]

                                      image_filepath  median_radii_SAM  num_blobs_SAM
0  /users/awitmer/.cache/test_images/images_raw.tiff          5.808687          11848

I also ran the same workflow incantation on a back-end node with -C gpu80 and points_per_batch: 256, which gave the following outputs:

[BubbleSAM]: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [24:51<00:00, 1491.52s/it]

                                      image_filepath  median_radii_SAM  num_blobs_SAM
0  /users/awitmer/.cache/test_images/images_raw.tiff          5.808687          11847

Both the iteration times and detection results are nearly identical between the two workflow runs, and the skimage post-processing steps still seem to be taking significant time on chicoma as well.

I pushed a commit to update the README with instructions on how to run the workflow on chicoma including download SAM2 checkpoints on the front-end node before running the workflow, and loading the cuda module with module load cudatoolkit/12.6.0

[adamwitmer]

@tylerjereddy I believe I have addressed all remaining review comments, and responded to comments requiring further clarification. Specifically, I added instructions for running the workflow on chicoma, as well as for using gpu accelerated skimage processing with cucim (which I tested on gp160, where the full test suite passes as well), and updated test_sam_internal_api to ensure desired behavior from the updated sam2.1 weights.

I also modified the workflow to use user defined settings from the yaml input file for providing mask_settings, area and circularity thresholds, sam2 weight parameter settings, and an option for performing detection on cpu or gpu. I updated issue #13 with a reference to the discussion at #3 (comment), detailing slow iteration times for bubblesam detection and some considerations for how to improve the speed of the workflow in relation to the task of detecting extremely small bubbles.

I re-read the diff again multiple times to check for additional improvements (I found several leftover -> None return types in test function signatures), and addressed those changes in individual commits. That being said, I think that this PR is ready for re-review, thanks.