Add FastSAM-based oyster counting & measurement pipeline

[sr320]

What & why

Adds a vision pipeline that counts oysters and measures each one's length and width in mm from overhead tray photos, automating the manual ImageJ workflow (place a point per oyster, measure with calipers) captured in the reference data.

Because the dataset is a single labelled image, the pipeline uses a pretrained FastSAM "segment everything" model (no task-specific training) plus a domain-specific filter, measurement, and calibration layer.

How it works (scripts/oyster_vision.py)

1. Segment every object with FastSAM within the tray ROI.
2. Filter to oysters by size / solidity / extent / aspect ratio, then de-duplicate overlapping masks with mask-IoU NMS.
3. Measure: length = maximum Feret (caliper) diameter of the mask; width = short side of the min-area rectangle.
4. Calibrate px→mm with a single constant fit (least squares through origin) against the human measurements.

CLIs

• scripts/calibrate.py — extracts ground truth from the ImageJ TIFF (POINT overlay = 84 human crosshairs), matches detections, fits px_per_mm, writes outputs/calibration.json + outputs/metrics.json.
• scripts/detect.py — runs any image → per-oyster predictions CSV + annotated overlay.

Results — reference image bag380 (84 oysters)

Metric	Value
Counted	80 / 84
Detection P / R / F1	0.90 / 0.86 / 0.88
Length error	MAE 4.6 mm (4.8%), r 0.82
Width error	MAE 4.7 mm (7.9%), r 0.73
Calibration	2.435 px/mm

Reviewer notes

• FastSAM weights (~24 MB) auto-download to models/ on first run and are git-ignored.
• Calibration is scene-specific — valid for this camera height/tray; new photos need a fiducial or fixed geometry (see METHODS.md).
• Known misses: ~12 mud-caked oysters that blend into the board; ~8 false positives (board texture + the 380 tag). Improvement paths documented in METHODS.md.
• Also removed a stray macOS .DS_Store from tracking and added it to .gitignore.

🤖 Generated with Claude Code