add SAM2 box -> polygon script

[jveitchmichaelis]

Implements #460

I've added this as a standalone script that processes prediction outputs, rather than integrated into the pipeline. Uses box prompts rather than points, but we can experiment with other strategies. I played with an option that uses OAM-TCD masks as a refinement step which worked pretty well, but needs more experimentation to see if it's actually worth doing.

Takes a few seconds per 1024 image on my laptop which I think is pretty decent. I haven't tested on an NVIDIA GPU.

I haven't done/added any evaluation beyond unit tests. Will write docs once we agree on where the best place to put this is.

Some results from LIDAR labels:

Works fine for isolated trees and somewhat well for trees in groups. Here is an output from the script which uses the built-in polygon viz:

[codecov]

Codecov Report

❌ Patch coverage is 78.63248% with 25 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.04%. Comparing base (5aa5754) to head (f275688).
⚠️ Report is 8 commits behind head on main.

Files with missing lines	Patch %	Lines
src/deepforest/scripts/sam.py	77.35%	24 Missing ⚠️
src/deepforest/utilities.py	90.90%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1158      +/-   ##
==========================================
- Coverage   87.43%   87.04%   -0.39%     
==========================================
  Files          20       21       +1     
  Lines        2538     2655     +117     
==========================================
+ Hits         2219     2311      +92     
- Misses        319      344      +25     

Flag	Coverage Δ
unittests	87.04% <78.63%> (-0.39%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[bw4sz]

This is an important integration and something we have discussed for a long time #460. I'd like to see this merged and get the docs right about this. Here are somethings that are on my mind.

1. Should it be a standalone script or a function within the API? The majority of tools within DeepForest are functions, and its really only since 2.0 and the CLI that a standalone script is something that exists within the library. I think we should alteast also have a SAM2_polygons() function to be applied to the outputs of main.predict_*.
2. I think we'll need some documentation within user_guide/16_prediction.html to describe what's happening, the input parameters and potential ideas for how a user might improve the segmentations, or when it might work well/not.
3. How much testing should we do here? I think its okay to say, this is a common workflow, point in the docs to lots of papers using it, several in conjunction with DeepForest. I had thought in the past that the model was quite heavy and needed a big GPU, but this was pre-transformers integration.

[jveitchmichaelis]

1. Yes, I wasn't sure. On the one hand it could be integrated as a post-process step, but on the other we don't yet have a solid polygon pipeline. But it might make sense to have it as an API accessible function (a model method that takes a results dataframe).

2. I'll write some docs. Not clear exactly what options we can configure within transformers are most relevant.

3. I added some sanity checks (that you get decent polygons out), but we could add a more stringent test like take an easy open canopy image with polygon labels (which we can take bounding boxes from) and confirm that the box-sam-polygon workflow recovers the polygons reasonably well?

That might require actual benchmarking on a proper polygon dataset. There are other routes we can explore like prompting with a center + negative corners to try and encourage circular masks, or refinement with restor/tcd + deepforest boxes.