Batch classification predictions in worker for GPU efficiency

[Copilot]

Worker code from PR #94 classifies each detection crop individually (batch size = 1), resulting in N GPU calls for N detections. This creates high kernel launch and memory transfer overhead.

Implementation

Batches all crops together following the same pattern used by the DB queue and API pipelines:

# Before: N GPU calls
for dresp in detector.results:
    crop = crop.unsqueeze(0)
    classifier_out = classifier.predict_batch(crop)

# After: 1 GPU call
crops = []
for dresp in detector.results:
    crop_pil = torchvision.transforms.ToPILImage()(crop)
    crop_transformed = classifier.get_transforms()(crop_pil)  # Resize to uniform size
    crops.append(crop_transformed)

if crops:
    batched_crops = torch.stack(crops)
    classifier_out = classifier.predict_batch(batched_crops)

Transforms resize each crop to the model's fixed input_size before batching, so torch.stack() works without padding.

Changes

• trapdata/cli/worker.py: Collect crops, apply transforms, batch classify
• trapdata/api/models/classification.py: Add reset() and update_detection_classification() methods
• trapdata/api/models/localization.py: Add reset() method
• trapdata/cli/base.py: Add worker CLI command
• trapdata/settings.py: Add Antenna API settings (base_url, auth_token, batch_size)
• trapdata/api/: Add REST dataset, schemas, and supporting code for Antenna integration

Edge Cases

• Skip detections with invalid bounding boxes (y1 ≥ y2 or x1 ≥ x2)
• Handle empty crops list before stacking
• Avoid division by zero when batch has no valid images

Testing

• trapdata/cli/tests/test_worker_batching.py: Verifies predict_batch called once with batch size = N
• trapdata/api/tests/test_worker.py: Integration tests for REST worker

Expected Impact

For images with 10+ detections: N× reduction in GPU overhead from single batched call vs N individual calls.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Worker: Batch classification predictions for GPU efficiency</issue_title>
<issue_description>## Summary

The worker currently classifies each detection crop one at a time in a loop, which is inefficient on GPU. Crops can be batched together for a single forward pass.

Question: the classification step in the existing dataloader & classification pipeline already batches crops (defaults to 100 or 200). How does it do it without resizing or padding? Review the existing pipeline (the one that reads from the local DB queue and does batch processing).

Current behavior

In trapdata/cli/worker.py:212-229, each detection is processed individually:

for idx, dresp in enumerate(detector.results):
    # ... crop the image ...
    crop = crop.unsqueeze(0)  # batch size = 1
    classifier_out = classifier.predict_batch(crop)  # single item
    # ...

This causes:

• High per-call overhead (GPU memory transfers, kernel launches)
• Poor GPU utilization with batch size = 1
• Slower processing, especially for images with many detections

Proposed solution

Collect all crops first, then classify in a single batched call:

# Collect all crops
crops = []
for dresp in detector.results:
    crop = image_tensor[:, int(bbox.y1):int(bbox.y2), int(bbox.x1):int(bbox.x2)]
    crops.append(crop)

# Batch and classify all at once
if crops:
    # May need padding/resizing for uniform tensor sizes
    batched_crops = torch.stack(crops)  
    classifier_out = classifier.predict_batch(batched_crops)
    # ... map predictions back to detections ...

Considerations

• Crops may have different sizes - need to resize or pad to uniform dimensions
• Memory constraints - may need to sub-batch if too many detections
• Need benchmarking to measure actual improvement
• Should verify classification accuracy is unchanged after batching

Related

• Flagged by Copilot in PR Worker implementation for processing images in the Antenna task queue (PSv2) #94 review
• CLAUDE.md notes "Batch processing is critical"

Test plan

• Benchmark current vs batched implementation on sample images
• Verify classification results are identical
• Test with images containing many detections (10+, 50+)
• Test memory usage with large batches</issue_description>

<agent_instructions>Question: the classification step in the existing dataloader & classification pipeline already batches crops (defaults to 100 or 200). How does it do it without resizing or padding? Review the existing pipeline (the one that reads from the local DB queue and does batch processing).</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Worker: Batch classification predictions for GPU efficiency #103

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[mihow]

Covered by #110