Add spatial-temporal metadata embeddings to CropModel

[bw4sz]

Summary

• Adds optional late-fusion spatial-temporal metadata (lat, lon, date) to CropModel for improved species classification
• Sinusoidal encoding of coordinates + day-of-year through a small MLP (~1.5% of image feature vector), concatenated with ResNet-50 features before the classifier
• Fully backward compatible — metadata is optional at both training and inference time; model gracefully degrades to image-only predictions when metadata is absent

Key changes

• SpatialTemporalEncoder: Sinusoidal positional encoding + MLP (6 → configurable dim, default 32)
• CropModel: Splits into backbone + metadata encoder + classifier when use_metadata=True
• MetadataImageFolder: Wraps ImageFolder with a CSV sidecar (filename,lat,lon,date) for training
• BoundingBoxDataset: Supports per-crop metadata dict for inference
• predict_tile: Accepts metadata={"lat": ..., "lon": ..., "date": "YYYY-MM-DD"}
• Config: use_metadata, metadata_dim, metadata_dropout
• 19 new tests covering encoder, model, datasets, checkpoint save/load, and full training integration
• Documentation added to CropModel user guide and configuration reference

Test plan

• All 19 new metadata tests pass (pytest tests/test_metadata_cropmodel.py)
• All 8 existing crop model tests pass (pytest tests/test_crop_model.py)
• Full test suite passes on CI
• Manual smoke test with real field data

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches core CropModel training/inference data flow and changes batch/forward signatures to support metadata; defaults remain unchanged, but incorrect metadata wiring or shape handling could break crop-model prediction/training in edge cases.

Overview
Adds optional spatial-temporal metadata (lat/lon/date) support to CropModel, including a new SpatialTemporalEncoder and a backbone+metadata+classifier path when cropmodel.use_metadata is enabled, while keeping image-only behavior as the default.

Training can now load per-image metadata from a sidecar CSV via CropModel.load_from_disk(..., metadata_csv=...), and inference can pass image-level metadata through deepforest.predict_tile(..., metadata=...) which is expanded to per-crop tensors and threaded through predict/BoundingBoxDataset.

Updates config/schema/docs to expose use_metadata, metadata_dim, and metadata_dropout, and adds a dedicated test suite covering encoder behavior, training/predict steps, dataset wrappers, and checkpoint save/load.

^{Written by Cursor Bugbot for commit c763c17. This will update automatically on new commits. Configure here.}

[bw4sz]

I changed something small, I don't agree with bugbot.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[bw4sz]

@jveitchmichaelis can you skim this. There was a lot of cursor generated code at the beginning and I'm starting to take ownership over it as it seems to be effective and well balanced when I tested it in the BOEM repo.

There are implementation pieces I'm not sure about, and then there are scientific things that merit further review. Like what happens if we see some that is not supposed to occur in a new case, I want to manually change a few test items to see if the metadata overrides the vision model. It's a small portion of the concat features but I will test it. In terms of engineering and our workflows, I am playing with this process of working with the agents to prototype something, check it out on a different project and then assume ownership of the PR for DeepForest. That hand-off is probably awkward. I want to see which things strike you as needing developer time. @ethanwhite just keeping you abreast as a trial pattern. I'm taking it out of WIP, but not triggering review yet?