Add README, training/inference code, and trained DINOv2-small pose-classifier checkpoint

Uploads:
- README.md (Imageomics model-card template, populated from the code)
- pose_classifier.py - inference wrapper (ViewPointClassifier)
- train_pose_classifier.py - training script
- POSE_CLASSIFIER_GUIDE.md - user guide with pose-class reference
- checkpoints/best_pose_model.pth - trained DINOv2-small + MLP head weights (~88 MB, LFS)

Note: README YAML frontmatter still needs `license:` and (optionally) `datasets:` filled in.

POSE_CLASSIFIER_GUIDE.md

@@ -0,0 +1,287 @@
+# Pose Classifier Guide
+
+## Overview
+
+The pose classifier predicts the orientation of animals (zebras, giraffes, etc.) relative to the camera position from aerial drone footage. This is critical for navigation and behavior analysis.
+
+## 8-Class Pose Classification System
+
+### Pose Classes
+
+The classifier identifies **8 discrete pose orientations** arranged in a circle around the animal:
+
+1. **front** - Animal facing directly toward camera
+2. **front-left** - Animal facing camera, angled to the left (~45°)
+3. **left** - Animal's left side visible, perpendicular to camera
+4. **back-left** - Animal facing away, angled to the left (~45°)
+5. **back** - Animal facing directly away from camera
+6. **back-right** - Animal facing away, angled to the right (~45°)
+7. **right** - Animal's right side visible, perpendicular to camera
+8. **front-right** - Animal facing camera, angled to the right (~45°)
+
+### Visual Reference
+
+![Pose Reference Diagram](pose_labels/_reference.png)
+
+The diagram shows the 8 pose classes arranged in a circle. The camera is positioned at the bottom, and the animal (zebra) is in the center. Each orange dot represents one of the 8 possible pose classifications.
+
+## Example Poses
+
+### Front Pose
+**Label:** `front`
+
+The animal is facing directly toward the camera, with the head and front body visible.
+
+![Front Pose Example](pose_labels/front/mpala_session_1_DJI_0002_partition_1_DJI_0002_000171_c0_004.jpg)
+
+---
+
+### Front-Left Pose
+**Label:** `front-left`
+
+The animal is facing toward the camera but angled to its left (camera's right), showing both the front and left side.
+
+![Front-Left Pose Example](pose_labels/front-left/mpala_session_1_DJI_0002_partition_1_DJI_0002_000471_c0_005.jpg)
+
+---
+
+### Front-Right Pose
+**Label:** `front-right`
+
+The animal is facing toward the camera but angled to its right (camera's left), showing both the front and right side.
+
+![Front-Right Pose Example](pose_labels/front-right/mpala_session_2_DJI_0006_partition_2_DJI_0006_006552_c0_004.jpg)
+
+---
+
+### Left Pose
+**Label:** `left`
+
+The animal's left side is visible, perpendicular to the camera. This is a pure profile view.
+
+![Left Pose Example](pose_labels/left/mpala_session_1_DJI_0002_partition_1_DJI_0002_000321_c1_001.jpg)
+
+---
+
+### Right Pose
+**Label:** `right`
+
+The animal's right side is visible, perpendicular to the camera. This is a pure profile view from the opposite side.
+
+![Right Pose Example](pose_labels/right/mpala_session_1_DJI_0002_partition_1_DJI_0002_000171_c0_002.jpg)
+
+---
+
+### Back-Left Pose
+**Label:** `back-left`
+
+The animal is facing away from the camera but angled to its left, showing the rear-left quarter.
+
+![Back-Left Pose Example](pose_labels/back-left/mpala_session_1_DJI_0002_partition_1_DJI_0002_000171_c1_001.jpg)
+
+---
+
+### Back-Right Pose
+**Label:** `back-right`
+
+The animal is facing away from the camera but angled to its right, showing the rear-right quarter.
+
+![Back-Right Pose Example](pose_labels/back-right/mpala_session_1_DJI_0002_partition_1_DJI_0002_000171_c1_000.jpg)
+
+---
+
+### Back Pose
+**Label:** `back`
+
+The animal is facing directly away from the camera, with the rear and back visible.
+
+![Back Pose Example](pose_labels/back/mpala_session_1_DJI_0002_partition_1_DJI_0002_000321_c1_000.jpg)
+
+---
+
+## Model Architecture
+
+### DINOv2 + MLP Head
+
+The pose classifier uses a **frozen DINOv2 backbone** with a **trainable MLP classification head**:
+
+```
+Input Image (224×224)
+    ↓
+DINOv2 Vision Transformer (frozen)
+    - Small: 384-dim features
+    - Base: 768-dim features
+    - Large: 1024-dim features
+    ↓
+MLP Head (trainable)
+    - LayerNorm
+    - Linear(feat_dim -> 256) + GELU + Dropout(0.3)
+    - Linear(256 -> 128) + GELU + Dropout(0.3)
+    - Linear(128 -> 8)
+    ↓
+Output Logits (8 classes)
+```
+
+### Why DINOv2?
+
+- **Self-supervised learning** on diverse images provides strong visual features
+- **Frozen backbone** reduces training time and prevents overfitting
+- **Small memory footprint** suitable for deployment
+- **Robust to varying image quality** from aerial footage
+
+## Training Pipeline
+
+### Data Organization
+
+Training data is organized in folder structure:
+```
+pose_labels/
+  _reference.png          # Visual guide
+  front/                  # Front-facing animals
+  front-left/             # Front-left quarter
+  left/                   # Left profile
+  back-left/              # Back-left quarter
+  back/                   # Back-facing animals
+  back-right/             # Back-right quarter
+  right/                  # Right profile
+  front-right/            # Front-right quarter
+```
+
+Or via CSV files with columns: `image_path, pose`
+
+### Data Augmentation
+
+**Geometric Augmentation with Label Swapping:**
+- Horizontal flip applied with 50% probability
+- When flipped, pose labels are swapped according to symmetry:
+  - `left` <-> `right`
+  - `front-left` <-> `front-right`
+  - `back-left` <-> `back-right`
+  - `front` and `back` remain unchanged
+
+**Color/Transform Augmentation:**
+- Random crop (256px -> 224px)
+- Color jitter: brightness (±30%), contrast (±30%), saturation (±20%)
+- Random rotation (±15°)
+
+**Class Balancing:**
+- Weighted random sampler ensures equal representation of all 8 classes during training
+
+### Training Configuration
+
+```bash
+python train_pose_classifier.py \
+    --data_dir ./pose_labels \
+    --model_size small \
+    --epochs 30 \
+    --batch_size 32 \
+    --lr 1e-3
+```
+
+**Key Parameters:**
+- **Model size**: `small`, `base`, or `large` (DINOv2 variant)
+- **Optimizer**: AdamW with weight decay 0.01
+- **Loss**: CrossEntropyLoss with label smoothing (0.1)
+- **Scheduler**: CosineAnnealingLR
+- **Mixed precision**: Automatic on GPU
+
+**Training Output:**
+- Best model saved to `checkpoints/best_pose_model.pth`
+- Includes confusion matrix and per-class accuracy
+- Optional ONNX export for deployment
+
+## Usage in Navigation
+
+### Integration with Detection Pipeline
+
+The pose classifier is used in the navigation system after animal detection:
+
+```python
+from navigation.policy.pose_classifier import ViewPointClassifier
+from PIL import Image
+
+# Initialize classifier
+classifier = ViewPointClassifier(
+    weight_path="model_weights/best_june_24_2025_IA_classifier_016.pth",
+    device="cpu",
+    threshold=0.5
+)
+
+# Process detected animal crops
+crops = [Image.open(path) for path in detection_crops]
+poses = classifier(crops)  # Returns list of pose strings
+
+# Use poses for navigation decisions
+for pose in poses:
+    if "front" in pose:
+        print("Animal is facing camera - approach with caution")
+    elif "back" in pose:
+        print("Animal is facing away - good for following")
+```
+
+### Multi-Label Pose System (Alternative)
+
+The `ViewPointClassifier` in `pose_classifier.py` uses a different approach:
+
+- **5 multi-label classes**: `up, front, back, right, left`
+- **EfficientNet-B4** backbone trained on zebra crops
+- **Input size**: 512×512 pixels
+- **Output**: Concatenated string (e.g., `"upfrontright"`)
+- **Threshold**: 0.5 (configurable)
+
+This allows detecting compound poses like "animal is facing front-right while looking up."
+
+## Performance Considerations
+
+### Inference Speed
+- **DINOv2-small**: ~15-20ms per image (CPU)
+- **DINOv2-base**: ~30-40ms per image (CPU)
+- **GPU acceleration**: 5-10x faster
+
+### Accuracy Targets
+- **Overall accuracy**: >85% on validation set
+- **Critical classes** (front/back): >90% accuracy
+- **Confusion**: Most errors occur between adjacent classes (e.g., front vs. front-left)
+
+### Deployment Notes
+- Model checkpoint: ~150MB (small), ~350MB (base)
+- ONNX export available for optimized inference
+- Batch processing recommended for multiple detections
+
+## Common Issues & Tips
+
+### Issue: Poor performance on occluded animals
+**Solution**: Train with more occluded examples or use confidence thresholding
+
+### Issue: Confusion between adjacent poses
+**Solution**: This is expected due to continuous nature of orientations; consider using pose groups (front-facing vs. side-facing vs. back-facing)
+
+### Issue: Inconsistent predictions across frames
+**Solution**: Apply temporal smoothing or majority voting across consecutive frames
+
+### Issue: Different performance on zebras vs. other species
+**Solution**: Retrain with balanced dataset across species, or train species-specific models
+
+## Dataset Statistics
+
+Current training data distribution (from folder structure):
+- Folders: `front`, `front-left`, `front-right`, `left`, `right`, `back-left`, `back-right`, `back`
+- Images per class: Variable (check with `train_pose_classifier.py --data_dir pose_labels`)
+- Species: Primarily zebras and giraffes
+- Source: Aerial drone footage from Mpala and OPC sessions
+
+## References
+
+- DINOv2 Paper: [https://arxiv.org/abs/2304.07193](https://arxiv.org/abs/2304.07193)
+- VARe-ID (ViewPoint Classifier): [https://github.com/ziesski/VARe-ID](https://github.com/ziesski/VARe-ID)
+- Individual identification of wildlife: [https://doi.org/10.1007/s10344-021-01549-4](Review on methods used for wildlife species and individual identification)
+- Training script: [train_pose_classifier.py](train_pose_classifier.py)
+- Navigation integration: [navigation/policy/pose_classifier.py](../navigation/policy/pose_classifier.py)
+
+## Quick Start
+
+1. **Prepare data**: Organize images in `pose_labels/` folders by class
+2. **Train model**: `python train_pose_classifier.py --data_dir ./pose_labels --epochs 30`
+3. **Evaluate**: Check confusion matrix and per-class accuracy in output
+4. **Export**: Use `--export_onnx` flag for optimized deployment
+5. **Integrate**: Load checkpoint and use for inference on detection crops

README.md

@@ -1,3 +1,353 @@
 ---
-license: mit
+# TODO: pick an OSI-compatible license tag (see note below) and add it as `license:` here.
+# TODO: if/when a HF dataset is published, add it as `datasets: <org>/<name>` (string, not list).
+language:
+- en
+library_name: pytorch
+tags:
+- biology
+- CV
+- images
+- animals
+- zebra
+- giraffe
+- pose-estimation
+- viewpoint-classification
+- dinov2
+- aerial-imagery
+- drone
+metrics:
+- accuracy
+model_description: An 8-class viewpoint/pose classifier for aerial drone imagery of wildlife (primarily zebras and giraffes). Uses a frozen DINOv2 vision-transformer backbone with a trainable MLP head to predict one of eight canonical orientations of the animal relative to the camera.
 ---
+
+<!--
+
+NOTE: Add more tags (your particular animal, type of model and use-case, etc.).
+
+As with your GitHub Project repo, it is important to choose an appropriate license for your model. Alongside the appropriate stakeholders (e.g., your PI, co-authors), select a license that is [Open Source Initiative](https://opensource.org/licenses) (OSI) compliant. You may also wish to consider adding a [RAIL license](https://www.licenses.ai/ai-licenses), which addresses responsible use.
+For more information on how to choose a license and why it matters, see [Choose A License](https://choosealicense.com) and [A Quick Guide to Software Licensing for the Scientist-Programmer](https://doi.org/10.1371/journal.pcbi.1002598) by A. Morin, et al.
+See the [Imageomics policy for licensing](https://imageomics.github.io/Imageomics-guide/wiki-guide/Digital-products-release-licensing-policy/) for more information.
+
+License tags (for the `yaml` above) can be found [here](https://hf.co/docs/hub/repositories-licenses).
+-->
+
+# Model Card for DINOv2 8-Class Animal Pose Classifier
+
+A lightweight viewpoint/pose classifier that predicts one of **8 canonical orientations** (front, front-left, front-right, left, right, back-left, back-right, back) for an animal crop extracted from aerial drone imagery. It pairs a **frozen DINOv2 vision-transformer backbone** with a small **trainable MLP head**, and is intended for use as a downstream module in a drone-based wildlife detection-and-navigation pipeline.
+
+## Model Details
+
+### Model Description
+
+This model takes a 224×224 RGB image crop of a single animal (typically produced by an upstream detector) and outputs a categorical prediction over 8 viewpoint classes arranged around the animal. The 8 classes form a discretization of the animal's heading relative to the camera, with adjacent classes separated by ~45°.
+
+The DINOv2 backbone is loaded via `torch.hub` from `facebookresearch/dinov2` and is kept frozen during training; only the MLP head is updated. This keeps the number of trainable parameters low (well under 1M for the `small` variant), reduces overfitting on small labeled pose datasets, and allows the same self-supervised representation to be reused for related downstream tasks.
+
+- **Developed by:** Imageomics Institute — Individual Identification of Zebras project (Claire Sun, et al.)
+- **Model type:** Image classifier (Vision Transformer feature extractor + MLP head)
+- **Language(s) (NLP):** N/A (vision model)
+- **License:** [More Information Needed — choose a license (see above notes)]
+- **Fine-tuned from model:** [facebookresearch/dinov2](https://github.com/facebookresearch/dinov2) (`dinov2_vits14`, `dinov2_vitb14`, or `dinov2_vitl14`)
+
+### Model Sources
+
+- **Repository:** [individual_id_zebras / Claire / pose_model](.)
+- **Training script:** [train_pose_classifier.py](train_pose_classifier.py)
+- **Inference wrapper:** [pose_classifier.py](pose_classifier.py)
+- **User guide:** [POSE_CLASSIFIER_GUIDE.md](POSE_CLASSIFIER_GUIDE.md)
+- **Paper:** [More Information Needed — optional]
+- **Demo:** [More Information Needed — encouraged]
+
+## Uses
+
+### Direct Use
+
+The model is intended to be applied to **tight, single-animal crops** (e.g., the output of a wildlife detector run on aerial drone frames). For each crop it returns the most likely of 8 viewpoint labels:
+
+```
+front, front-left, front-right, left, right, back-left, back-right, back
+```
+
+These labels are useful for:
+
+- Selecting frames in which an individual is best observed (e.g., side profiles for stripe-based re-identification).
+- Filtering training data for downstream identity models that are viewpoint-sensitive.
+- Behavioral analysis (e.g., orientation of herd members relative to the camera/drone).
+
+### Downstream Use
+
+This pose classifier is a component of a larger **drone navigation and individual-identification pipeline** for zebras and giraffes. Downstream uses include:
+
+- Conditioning a re-identification model on viewpoint.
+- Informing autonomous drone-positioning policies (e.g., maneuver to obtain a side-profile view).
+- Producing per-track viewpoint histograms used for sighting quality scoring.
+
+### Out-of-Scope Use
+
+- **Non-aerial / ground-level imagery.** The model is trained on top-down/oblique drone footage; predictions on eye-level photos are unlikely to be reliable.
+- **Species the model was not trained on.** Performance has only been characterized for zebras and giraffes. Application to unrelated species is out of scope without retraining.
+- **Continuous heading regression.** The model predicts 1-of-8 discrete classes, not a continuous angle. Adjacent classes (e.g., `front` vs `front-left`) are frequently confused and should not be treated as fully independent.
+- **Identity, species, or behavior inference.** The model does not predict the identity, species, or activity of the animal.
+
+## Bias, Risks, and Limitations
+
+- **Domain shift:** Training data is drawn primarily from aerial drone footage at two field sites (Mpala and OPC). Performance may degrade on imagery captured at other altitudes, lighting conditions, or camera angles.
+- **Class adjacency confusion:** Because viewpoint is fundamentally continuous, errors are concentrated between neighboring classes (e.g., `front` ↔ `front-left`). The 8-class discretization is a modeling choice, not a property of the underlying phenomenon.
+- **Species imbalance:** Most training samples are zebras; giraffe coverage is smaller and per-class performance has not been independently broken out.
+- **Occlusion sensitivity:** Heavily occluded or truncated crops (animals partially out of frame, overlapping individuals) are not well represented and tend to produce less reliable predictions.
+- **Tight-crop dependence:** The model expects detector-style crops centered on a single animal. Wide-scene images will not produce meaningful predictions.
+
+### Recommendations
+
+Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. In particular:
+
+- Treat adjacent-class confusion (e.g., `front`/`front-left`) as expected and consider collapsing to coarser bins (front/side/back) for decisions that don't need fine resolution.
+- Apply temporal smoothing or majority voting across consecutive frames when classifying tracked individuals.
+- Confidence-threshold or hold out predictions on visibly occluded crops.
+- Re-evaluate (or retrain) before deploying on a new site, species, or sensor.
+
+## How to Get Started with the Model
+
+The inference wrapper [`ViewPointClassifier`](pose_classifier.py) provides a one-line interface that takes a list of PIL crops and returns a list of pose labels.
+
+```python
+from PIL import Image
+from pose_classifier import ViewPointClassifier
+
+classifier = ViewPointClassifier(
+    weight_path="checkpoints/best_pose_model.pth",
+    model_size="small",          # must match the trained checkpoint
+    device="cpu",                # or "cuda"
+)
+
+crops = [Image.open(p).convert("RGB") for p in ["zebra1.jpg", "zebra2.jpg"]]
+poses = classifier(crops)
+# e.g. ['front-left', 'back']
+```
+
+The wrapper handles preprocessing (resize to 256, center-crop to 224, ImageNet normalization) and accepts PIL images, NumPy arrays, or torch tensors as input.
+
+To **train from scratch** on a new pose-labeled dataset:
+
+```bash
+python train_pose_classifier.py \
+    --data_dir ./pose_labels \
+    --model_size small \
+    --epochs 30 \
+    --batch_size 32 \
+    --lr 1e-3
+```
+
+See [POSE_CLASSIFIER_GUIDE.md](POSE_CLASSIFIER_GUIDE.md) for the full guide, including the visual reference diagram for each pose class.
+
+## Training Details
+
+### Training Data
+
+Pose-labeled crops of zebras and giraffes extracted from aerial drone footage at Mpala (Kenya) and OPC field sites. Data is organized either as a per-class folder hierarchy:
+
+```
+pose_labels/
+  front/  front-left/  front-right/  left/  right/  back-left/  back-right/  back/
+```
+
+or as a CSV with `image_path, pose` columns. Class counts are inherently imbalanced and are handled at the sampler level (see below).
+
+[More Information Needed — exact per-class sample counts, splits, and dataset card link]
+
+### Training Procedure
+
+#### Preprocessing
+
+Training-time transforms (applied per image):
+
+- Resize shorter side to 256
+- `RandomCrop(224)`
+- `ColorJitter(brightness=0.3, contrast=0.3, saturation=0.2)`
+- `RandomRotation(±15°)`
+- ToTensor + ImageNet normalization (`mean=[0.485, 0.456, 0.406]`, `std=[0.229, 0.224, 0.225]`)
+
+Validation-time transforms: `Resize(256) → CenterCrop(224) → ToTensor → Normalize`.
+
+**Symmetry-aware horizontal flip:** with p=0.5 the crop is horizontally flipped and the label is swapped according to the canonical symmetry of the 8-class scheme:
+
+```
+left  ↔ right
+front-left ↔ front-right
+back-left ↔ back-right
+front, back   unchanged
+```
+
+This effectively doubles training data without breaking label semantics.
+
+**Class balancing:** a `WeightedRandomSampler` with weights inversely proportional to per-class frequency ensures all 8 classes are sampled at equal rates during training.
+
+#### Training Hyperparameters
+
+- **Training regime:** fp16 mixed precision when running on CUDA (via `torch.cuda.amp`); fp32 on CPU.
+- **Optimizer:** AdamW, `lr=1e-3`, `weight_decay=0.01` (head parameters only — backbone is frozen).
+- **Loss:** `CrossEntropyLoss(label_smoothing=0.1)`.
+- **LR schedule:** `CosineAnnealingLR(T_max=epochs)`.
+- **Default epochs / batch size:** 30 / 32.
+- **Backbone:** frozen DINOv2 (`small` = ViT-S/14, 384-dim; `base` = ViT-B/14, 768-dim; `large` = ViT-L/14, 1024-dim).
+- **Head:** `LayerNorm → Linear(feat_dim, 256) → GELU → Dropout(0.3) → Linear(256, 128) → GELU → Dropout(0.3) → Linear(128, 8)`.
+
+Only the MLP head is trained — for the `small` variant this is well under 1M trainable parameters.
+
+#### Speeds, Sizes, Times
+
+- **Checkpoint size:** ~88 MB for the `small` variant (`best_pose_model.pth`), ~350 MB for `base`.
+- **Inference (CPU):** ~15–20 ms/image (`small`), ~30–40 ms/image (`base`).
+- **Inference (GPU):** roughly 5–10× faster than CPU.
+
+[More Information Needed — wall-clock training time, throughput per epoch]
+
+## Evaluation
+
+### Testing Data, Factors & Metrics
+
+#### Testing Data
+
+When training from a single `--data_dir`, the script performs an 80/20 random split into train/val. When `--train_csv` and `--val_csv` are supplied, those are used directly.
+
+[More Information Needed — held-out test set details, if any beyond the val split]
+
+#### Factors
+
+The natural disaggregations of interest are:
+
+- **Pose class** (8 categories) — adjacent-class confusion is the dominant error mode.
+- **Species** (zebra vs giraffe) — coverage and accuracy may differ.
+- **Site / session** (e.g., Mpala vs OPC sessions) — proxies for altitude, lighting, and habitat.
+
+[More Information Needed — disaggregated numbers]
+
+#### Metrics
+
+- **Top-1 accuracy** (overall and per-class).
+- **8×8 confusion matrix** (printed by [train_pose_classifier.py](train_pose_classifier.py) at the end of training).
+
+### Results
+
+Target performance reported in the user guide:
+
+- Overall validation accuracy: **>85%**
+- Critical front/back classes: **>90%**
+
+[More Information Needed — actual measured numbers for the released checkpoint, ideally as a confusion matrix figure]
+
+#### Summary
+
+The `small` DINOv2 backbone with the MLP head described above is the released configuration and offers a favorable accuracy/latency trade-off for the drone-navigation use case. The `base` and `large` variants are supported by the same training script for users with more compute and labeled data.
+
+## Model Examination
+
+[More Information Needed — saliency/feature-attribution analysis, if any]
+
+## Environmental Impact
+
+Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://doi.org/10.48550/arXiv.1910.09700).
+
+- **Hardware Type:** [More Information Needed — GPU model used for training]
+- **Hours used:** [More Information Needed]
+- **Cloud Provider:** Ohio Supercomputer Center (OSC)
+- **Compute Region:** Ohio, USA
+- **Carbon Emitted:** [More Information Needed]
+
+## Technical Specifications
+
+### Model Architecture and Objective
+
+```
+Input Image (224×224, RGB, ImageNet-normalized)
+    │
+    ▼
+DINOv2 ViT (frozen)
+    - small : ViT-S/14  → 384-d feature vector
+    - base  : ViT-B/14  → 768-d feature vector
+    - large : ViT-L/14  → 1024-d feature vector
+    │
+    ▼
+MLP head (trainable)
+    LayerNorm(feat_dim)
+    Linear(feat_dim → 256) + GELU + Dropout(0.3)
+    Linear(256 → 128)      + GELU + Dropout(0.3)
+    Linear(128 → 8)
+    │
+    ▼
+Logits over {front, front-left, front-right, left, right,
+             back-left, back-right, back}
+```
+
+Training objective: cross-entropy with label smoothing (0.1), optimized only over the MLP head parameters.
+
+### Compute Infrastructure
+
+#### Hardware
+
+- **Training:** a single CUDA-capable GPU is sufficient for the `small` variant; mixed precision is enabled automatically. Larger DINOv2 variants benefit from more GPU memory.
+- **Inference:** runs on CPU or a single GPU. CPU is viable for low-throughput on-board use; GPU is recommended for batched offline processing.
+
+#### Software
+
+- Python 3.x
+- PyTorch (with `torch.hub` access to `facebookresearch/dinov2`)
+- torchvision
+- pandas, numpy, Pillow, tqdm
+
+## Citation
+
+[More Information Needed]
+
+<!--
+If you use our model in your work, please cite the model and any associated paper.
+
+**Model**
+```
+@software{<ref_code>,
+  author = {<author1 and author2>},
+  doi = {<doi once generated>},
+  title = {DINOv2 8-Class Animal Pose Classifier},
+  version = {<version#>},
+  year = {<year>},
+  url = {https://huggingface.co/imageomics/<model_name>}
+}
+```
+-->
+
+Underlying backbone:
+
+```
+@article{oquab2023dinov2,
+  title   = {DINOv2: Learning Robust Visual Features without Supervision},
+  author  = {Oquab, Maxime and Darcet, Timoth{\'e}e and Moutakanni, Th{\'e}o and Vo, Huy V. and Szafraniec, Marc and Khalidov, Vasil and Fernandez, Pierre and Haziza, Daniel and Massa, Francisco and El-Nouby, Alaaeldin and others},
+  journal = {arXiv preprint arXiv:2304.07193},
+  year    = {2023},
+  url     = {https://arxiv.org/abs/2304.07193}
+}
+```
+
+## Acknowledgements
+
+This work was supported by the [Imageomics Institute](https://imageomics.org), which is funded by the US National Science Foundation's Harnessing the Data Revolution (HDR) program under [Award #2118240](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2118240) (Imageomics: A New Frontier of Biological Information Powered by Knowledge-Guided Machine Learning). Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.
+
+Compute was provided by the [Ohio Supercomputer Center](https://www.osc.edu/). The backbone model is DINOv2 by Meta AI Research.
+
+## Glossary
+
+- **Pose / viewpoint:** the orientation of the animal relative to the camera, discretized here into 8 bins of ~45° each.
+- **Frozen backbone:** the DINOv2 weights are fixed during training; gradients flow only through the MLP head.
+- **Symmetry-aware flip:** horizontal-flip augmentation paired with a label swap (`left↔right`, `front-left↔front-right`, `back-left↔back-right`) so that flipped images carry geometrically correct labels.
+
+## More Information
+
+See [POSE_CLASSIFIER_GUIDE.md](POSE_CLASSIFIER_GUIDE.md) for visual references of each pose class, training tips, and integration notes for the navigation pipeline.
+
+## Model Card Authors
+
+Jenna Kline 
+
+## Model Card Contact
+
+Elizabeth Campolongo, campolongo.4@osu.edu

checkpoints/best_pose_model.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2956a457eabb17260e7da687898042f2376aea178d2c22a13a16f1c12c48d21d
+size 88828281

pose_classifier.py

@@ -0,0 +1,134 @@
+# navigation_scripts/pose_classifier.py
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from torchvision import transforms as T
+from pathlib import Path
+import numpy as np
+from PIL import Image
+
+
+# Must match train_pose_classifier.py
+POSE_CLASSES = ['front', 'front-left', 'front-right', 'left', 'right', 'back-left', 'back-right', 'back']
+NUM_CLASSES = len(POSE_CLASSES)
+
+DINO_MODELS = {
+    'small': ('dinov2_vits14', 384),
+    'base': ('dinov2_vitb14', 768),
+    'large': ('dinov2_vitl14', 1024),
+}
+
+
+class _PoseClassifierModel(nn.Module):
+    """DINOv2 + MLP head for 8-class pose classification (mirrors train_pose_classifier.PoseClassifier)."""
+
+    def __init__(self, model_size='small', dropout=0.3):
+        super().__init__()
+        model_name, feat_dim = DINO_MODELS[model_size]
+
+        self.backbone = torch.hub.load('facebookresearch/dinov2', model_name)
+        for param in self.backbone.parameters():
+            param.requires_grad = False
+        self.backbone.eval()
+
+        self.head = nn.Sequential(
+            nn.LayerNorm(feat_dim),
+            nn.Linear(feat_dim, 256),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(256, 128),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(128, NUM_CLASSES),
+        )
+
+    def forward(self, x):
+        with torch.no_grad():
+            features = self.backbone(x)
+        return self.head(features)
+
+
+class ViewPointClassifier:
+    """
+    Predicts one of 8 canonical zebra viewpoints:
+        front, front-left, front-right, left, right, back-left, back-right, back
+
+    Uses a DINOv2-small backbone (frozen) with a trained MLP head.
+
+    __call__(crops) → list[str]
+        Each crop is a PIL.Image (RGB).  Returns the predicted pose label.
+    """
+    LABELS = POSE_CLASSES
+
+    def _to_pil(self, img):
+        """Accept PIL.Image | np.ndarray | torch.Tensor -> PIL.Image (RGB)."""
+        if isinstance(img, Image.Image):
+            return img.convert("RGB")
+
+        if isinstance(img, np.ndarray):
+            if img.ndim == 3 and img.shape[2] == 3:
+                img = img[..., ::-1]             # BGR → RGB
+            return Image.fromarray(img)
+
+        if torch.is_tensor(img):
+            return T.ToPILImage()(img.cpu())
+
+        raise TypeError(f"Unsupported crop type {type(img)}")
+
+    def __init__(
+        self,
+        weight_path="checkpoints/best_pose_model.pth",
+        model_size: str = "small",
+        device: str = "cpu",
+    ):
+        self.device = torch.device(device)
+
+        # Build the same architecture used in training
+        self.model = _PoseClassifierModel(model_size=model_size)
+
+        # Load checkpoint (saved by train_pose_classifier.py)
+        ckpt = torch.load(weight_path, map_location=self.device)
+        self.model.load_state_dict(ckpt['model_state_dict'])
+        self.model.eval().to(self.device)
+
+        # Match the validation transforms from training
+        self.tf = T.Compose(
+            [
+                T.Resize(256),
+                T.CenterCrop(224),
+                T.ToTensor(),
+                T.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]),
+            ]
+        )
+
+    @torch.inference_mode()
+    def __call__(self, crops):
+        """
+        Parameters
+        ----------
+        crops : list[PIL.Image]
+            One crop per detection.
+
+        Returns
+        -------
+        list[str]
+            Predicted pose label for each crop, e.g. 'front', 'back-left'.
+        """
+        if not crops:
+            return []
+        pil_crops = [self._to_pil(c) for c in crops]
+        batch = torch.stack([self.tf(c) for c in pil_crops]).to(self.device)
+        logits = self.model(batch)                      # shape [N, 8]
+        preds = torch.argmax(logits, dim=-1).cpu()      # single-label
+        return [self.LABELS[i] for i in preds]
+
+# ───────── quick sanity check ─────────
+if __name__ == "__main__":
+    from PIL import Image
+    import random
+
+    img_dir = Path("some/test/crops")   # directory of zebra chip .jpgs
+    samples = [Image.open(p) for p in random.sample(list(img_dir.glob("*.jpg")), 4)]
+
+    clf = ViewPointClassifier(device="cpu")
+    print(clf(samples))

train_pose_classifier.py

@@ -0,0 +1,420 @@
+#!/usr/bin/env python3
+"""
+8-Class Pose Classifier Training
+================================
+Train a classifier for animal pose relative to camera.
+
+Classes:
+  front, front-left, front-right, left, right, back-left, back-right, back
+
+Usage:
+  python train_pose_classifier.py --data_dir ./pose_labels --epochs 30
+  python train_pose_classifier.py --train_csv train.csv --val_csv val.csv --epochs 30
+"""
+
+import argparse
+import os
+from pathlib import Path
+import numpy as np
+from PIL import Image
+from tqdm import tqdm
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from torch.utils.data import Dataset, DataLoader, WeightedRandomSampler
+from torchvision import transforms
+import pandas as pd
+
+# ============================================================
+# Configuration
+# ============================================================
+
+POSE_CLASSES = ['front', 'front-left', 'front-right', 'left', 'right', 'back-left', 'back-right', 'back']
+CLASS_TO_IDX = {c: i for i, c in enumerate(POSE_CLASSES)}
+IDX_TO_CLASS = {i: c for c, i in CLASS_TO_IDX.items()}
+NUM_CLASSES = len(POSE_CLASSES)
+
+# Horizontal flip swaps these pairs
+FLIP_PAIRS = {
+    'front-left': 'front-right',
+    'front-right': 'front-left',
+    'left': 'right',
+    'right': 'left',
+    'back-left': 'back-right',
+    'back-right': 'back-left',
+    'front': 'front',
+    'back': 'back',
+}
+
+# DINOv2 model sizes
+DINO_MODELS = {
+    'small': ('dinov2_vits14', 384),
+    'base': ('dinov2_vitb14', 768),
+    'large': ('dinov2_vitl14', 1024),
+}
+
+
+# ============================================================
+# Dataset
+# ============================================================
+
+class PoseDataset(Dataset):
+    """Dataset that supports both folder structure and CSV"""
+    
+    def __init__(self, data_source, transform=None, augment_flip=True):
+        """
+        Args:
+            data_source: Either a directory path (folder structure) or CSV path
+            transform: Image transforms
+            augment_flip: Whether to apply horizontal flip with label swap
+        """
+        self.transform = transform
+        self.augment_flip = augment_flip
+        self.samples = []
+        
+        data_path = Path(data_source)
+        
+        if data_path.is_dir():
+            # Load from folder structure
+            for cls in POSE_CLASSES:
+                cls_dir = data_path / cls
+                if cls_dir.exists():
+                    for img_path in cls_dir.glob('*'):
+                        if img_path.suffix.lower() in ['.jpg', '.jpeg', '.png']:
+                            self.samples.append((str(img_path), cls))
+        else:
+            # Load from CSV
+            df = pd.read_csv(data_path)
+            img_col = 'image_path' if 'image_path' in df.columns else df.columns[0]
+            label_col = 'pose' if 'pose' in df.columns else df.columns[1]
+            
+            for _, row in df.iterrows():
+                if row[label_col] in POSE_CLASSES:
+                    self.samples.append((row[img_col], row[label_col]))
+        
+        print(f"Loaded {len(self.samples)} samples")
+        self._print_distribution()
+    
+    def _print_distribution(self):
+        from collections import Counter
+        counts = Counter(s[1] for s in self.samples)
+        print("Class distribution:")
+        for cls in POSE_CLASSES:
+            print(f"  {cls}: {counts.get(cls, 0)}")
+    
+    def __len__(self):
+        return len(self.samples)
+    
+    def __getitem__(self, idx):
+        img_path, label = self.samples[idx]
+        image = Image.open(img_path).convert('RGB')
+        
+        # Horizontal flip augmentation with label swap
+        do_flip = self.augment_flip and torch.rand(1) < 0.5
+        if do_flip:
+            image = transforms.functional.hflip(image)
+            label = FLIP_PAIRS[label]
+        
+        if self.transform:
+            image = self.transform(image)
+        
+        return image, CLASS_TO_IDX[label]
+    
+    def get_sample_weights(self):
+        """Weights for balanced sampling"""
+        from collections import Counter
+        counts = Counter(s[1] for s in self.samples)
+        weights = [1.0 / counts[s[1]] for s in self.samples]
+        return torch.DoubleTensor(weights)
+
+
+# ============================================================
+# Model
+# ============================================================
+
+class PoseClassifier(nn.Module):
+    """DINOv2 + MLP head for 8-class pose classification"""
+    
+    def __init__(self, model_size='small', dropout=0.3):
+        super().__init__()
+        
+        model_name, feat_dim = DINO_MODELS[model_size]
+        
+        # Load frozen DINOv2 backbone
+        self.backbone = torch.hub.load('facebookresearch/dinov2', model_name)
+        for param in self.backbone.parameters():
+            param.requires_grad = False
+        self.backbone.eval()
+        
+        # Trainable MLP head
+        self.head = nn.Sequential(
+            nn.LayerNorm(feat_dim),
+            nn.Linear(feat_dim, 256),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(256, 128),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(128, NUM_CLASSES)
+        )
+    
+    def forward(self, x):
+        with torch.no_grad():
+            features = self.backbone(x)
+        return self.head(features)
+    
+    def predict_proba(self, x):
+        logits = self.forward(x)
+        return F.softmax(logits, dim=-1)
+
+
+# ============================================================
+# Training
+# ============================================================
+
+def get_transforms(train=True):
+    normalize = transforms.Normalize(
+        mean=[0.485, 0.456, 0.406],
+        std=[0.229, 0.224, 0.225]
+    )
+    
+    if train:
+        return transforms.Compose([
+            transforms.Resize(256),
+            transforms.RandomCrop(224),
+            transforms.ColorJitter(brightness=0.3, contrast=0.3, saturation=0.2),
+            transforms.RandomRotation(15),
+            transforms.ToTensor(),
+            normalize,
+        ])
+    else:
+        return transforms.Compose([
+            transforms.Resize(256),
+            transforms.CenterCrop(224),
+            transforms.ToTensor(),
+            normalize,
+        ])
+
+
+def train_epoch(model, dataloader, optimizer, criterion, device, scaler=None):
+    model.train()
+    model.backbone.eval()  # Keep backbone frozen
+    
+    total_loss = 0
+    correct = 0
+    total = 0
+    
+    pbar = tqdm(dataloader, desc='Training')
+    for images, labels in pbar:
+        images, labels = images.to(device), labels.to(device)
+        
+        optimizer.zero_grad()
+        
+        if scaler:
+            with torch.cuda.amp.autocast():
+                outputs = model(images)
+                loss = criterion(outputs, labels)
+            scaler.scale(loss).backward()
+            scaler.step(optimizer)
+            scaler.update()
+        else:
+            outputs = model(images)
+            loss = criterion(outputs, labels)
+            loss.backward()
+            optimizer.step()
+        
+        total_loss += loss.item()
+        _, predicted = outputs.max(1)
+        total += labels.size(0)
+        correct += predicted.eq(labels).sum().item()
+        
+        pbar.set_postfix({'loss': f'{loss.item():.4f}', 'acc': f'{100*correct/total:.1f}%'})
+    
+    return total_loss / len(dataloader), correct / total
+
+
+@torch.no_grad()
+def evaluate(model, dataloader, criterion, device):
+    model.eval()
+    
+    total_loss = 0
+    correct = 0
+    total = 0
+    all_preds, all_labels = [], []
+    
+    for images, labels in tqdm(dataloader, desc='Evaluating'):
+        images, labels = images.to(device), labels.to(device)
+        
+        outputs = model(images)
+        loss = criterion(outputs, labels)
+        
+        total_loss += loss.item()
+        _, predicted = outputs.max(1)
+        total += labels.size(0)
+        correct += predicted.eq(labels).sum().item()
+        
+        all_preds.extend(predicted.cpu().numpy())
+        all_labels.extend(labels.cpu().numpy())
+    
+    return total_loss / len(dataloader), correct / total, all_preds, all_labels
+
+
+def print_confusion_matrix(preds, labels):
+    """Print confusion matrix"""
+    from collections import defaultdict
+    
+    matrix = defaultdict(lambda: defaultdict(int))
+    for p, l in zip(preds, labels):
+        matrix[IDX_TO_CLASS[l]][IDX_TO_CLASS[p]] += 1
+    
+    print("\nConfusion Matrix (rows=true, cols=pred):")
+    
+    # Header
+    header = f"{'':>12}" + "".join(f"{c[:6]:>8}" for c in POSE_CLASSES)
+    print(header)
+    
+    for true_class in POSE_CLASSES:
+        row = f"{true_class:>12}"
+        for pred_class in POSE_CLASSES:
+            count = matrix[true_class][pred_class]
+            row += f"{count:>8}"
+        print(row)
+    
+    # Per-class accuracy
+    print("\nPer-class accuracy:")
+    for cls in POSE_CLASSES:
+        correct = matrix[cls][cls]
+        total = sum(matrix[cls].values())
+        acc = correct / total * 100 if total > 0 else 0
+        print(f"  {cls:>12}: {acc:5.1f}% ({correct}/{total})")
+
+
+def export_onnx(model, output_path, device='cpu'):
+    """Export to ONNX"""
+    model.eval()
+    model.to(device)
+    
+    dummy = torch.randn(1, 3, 224, 224).to(device)
+    
+    torch.onnx.export(
+        model, dummy, output_path,
+        export_params=True,
+        opset_version=14,
+        input_names=['image'],
+        output_names=['logits'],
+        dynamic_axes={'image': {0: 'batch'}, 'logits': {0: 'batch'}}
+    )
+    print(f"Exported to {output_path}")
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--data_dir', type=str, help='Directory with class folders')
+    parser.add_argument('--train_csv', type=str, help='Training CSV')
+    parser.add_argument('--val_csv', type=str, help='Validation CSV')
+    parser.add_argument('--model_size', type=str, default='small', choices=['small', 'base', 'large'])
+    parser.add_argument('--epochs', type=int, default=30)
+    parser.add_argument('--batch_size', type=int, default=32)
+    parser.add_argument('--lr', type=float, default=1e-3)
+    parser.add_argument('--output_dir', type=str, default='./checkpoints')
+    parser.add_argument('--export_onnx', action='store_true')
+    args = parser.parse_args()
+    
+    device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
+    print(f"Device: {device}")
+    
+    os.makedirs(args.output_dir, exist_ok=True)
+    
+    # Load data
+    train_transform = get_transforms(train=True)
+    val_transform = get_transforms(train=False)
+    
+    if args.train_csv:
+        train_dataset = PoseDataset(args.train_csv, train_transform, augment_flip=True)
+        val_dataset = PoseDataset(args.val_csv, val_transform, augment_flip=False) if args.val_csv else None
+    elif args.data_dir:
+        full_dataset = PoseDataset(args.data_dir, train_transform, augment_flip=True)
+        # Split 80/20
+        n_val = int(0.2 * len(full_dataset))
+        n_train = len(full_dataset) - n_val
+        train_dataset, val_dataset = torch.utils.data.random_split(full_dataset, [n_train, n_val])
+        # Wrap val with no augmentation
+        val_dataset.dataset.augment_flip = False
+        val_dataset.dataset.transform = val_transform
+    else:
+        print("Provide --data_dir or --train_csv")
+        return
+    
+    # Weighted sampler for class balance
+    if hasattr(train_dataset, 'get_sample_weights'):
+        weights = train_dataset.get_sample_weights()
+        sampler = WeightedRandomSampler(weights, len(weights))
+        train_loader = DataLoader(train_dataset, batch_size=args.batch_size, sampler=sampler, num_workers=4)
+    else:
+        train_loader = DataLoader(train_dataset, batch_size=args.batch_size, shuffle=True, num_workers=4)
+    
+    val_loader = DataLoader(val_dataset, batch_size=args.batch_size, shuffle=False, num_workers=4) if val_dataset else None
+    
+    # Model
+    print(f"\nLoading DINOv2-{args.model_size}...")
+    model = PoseClassifier(model_size=args.model_size).to(device)
+    
+    trainable = sum(p.numel() for p in model.head.parameters())
+    print(f"Trainable parameters: {trainable:,}")
+    
+    # Training
+    criterion = nn.CrossEntropyLoss(label_smoothing=0.1)
+    optimizer = torch.optim.AdamW(model.head.parameters(), lr=args.lr, weight_decay=0.01)
+    scheduler = torch.optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=args.epochs)
+    scaler = torch.cuda.amp.GradScaler() if device.type == 'cuda' else None
+    
+    best_acc = 0
+    
+    for epoch in range(args.epochs):
+        print(f"\nEpoch {epoch+1}/{args.epochs}")
+        
+        train_loss, train_acc = train_epoch(model, train_loader, optimizer, criterion, device, scaler)
+        
+        if val_loader:
+            val_loss, val_acc, preds, labels = evaluate(model, val_loader, criterion, device)
+            print(f"Train Loss: {train_loss:.4f}, Acc: {train_acc*100:.1f}%")
+            print(f"Val Loss: {val_loss:.4f}, Acc: {val_acc*100:.1f}%")
+            
+            if val_acc > best_acc:
+                best_acc = val_acc
+                torch.save({
+                    'epoch': epoch,
+                    'model_state_dict': model.state_dict(),
+                    'head_state_dict': model.head.state_dict(),
+                    'val_acc': val_acc,
+                    'classes': POSE_CLASSES,
+                }, f'{args.output_dir}/best_pose_model.pth')
+                print(f"  → Saved (acc: {val_acc*100:.1f}%)")
+        else:
+            print(f"Train Loss: {train_loss:.4f}, Acc: {train_acc*100:.1f}%")
+        
+        scheduler.step()
+    
+    # Final evaluation
+    if val_loader:
+        print("\n" + "="*60)
+        print("Final Evaluation")
+        print("="*60)
+        
+        ckpt = torch.load(f'{args.output_dir}/best_pose_model.pth')
+        model.load_state_dict(ckpt['model_state_dict'])
+        
+        _, acc, preds, labels = evaluate(model, val_loader, criterion, device)
+        print(f"Best Accuracy: {acc*100:.1f}%")
+        print_confusion_matrix(preds, labels)
+    
+    # Export
+    if args.export_onnx:
+        export_onnx(model, f'{args.output_dir}/pose_classifier.onnx')
+    
+    print("\nDone!")
+
+
+if __name__ == '__main__':
+    main()