Upload Re-ID model checkpoints and model card

README.md

@@ -1,3 +1,166 @@
----
-license: mit
----
+---
+license: mit
+library_name: pytorch
+tags:
+  - person-reidentification
+  - person-reid
+  - computer-vision
+  - pytorch
+  - resnet
+  - bnneck
+  - triplet-loss
+  - multi-camera-tracking
+datasets:
+  - Market-1501
+metrics:
+  - mAP
+  - Rank-1
+---
+
+# MCTrack Re-ID Model
+
+Person re-identification model trained on Market-1501 as part of the
+**MSML 640 (Computer Vision) Final Project** at the University of Maryland.
+This model is the appearance backbone used in our multi-camera object tracking
+system.
+
+## Model Variants
+
+This repo contains two checkpoints:
+
+- **best_60ep.pth** (primary) - trained for 60 epochs.
+  Used as the deployed Re-ID model in our final cross-camera demos due to
+  qualitatively cleaner cluster outputs.
+- **best_120ep.pth** (ablation) - same recipe, trained for 120 epochs.
+  Slightly higher Re-ID accuracy but only marginal improvement on downstream
+  tasks (see "Performance" below).
+
+Both checkpoints contain only the model state_dict. No optimizer or scheduler
+state.
+
+## Architecture
+
+- **Backbone:** ResNet-50 (ImageNet-initialized; final stride changed from
+  2 to 1 to retain higher-resolution features)
+- **Pooling:** Global average pooling
+- **Neck:** BNNeck (Batch Normalization neck) - separates triplet-loss
+  features from classification features
+- **Embedding dimension:** 256
+- **Total parameters:** ~25M
+
+## Training Recipe
+
+| Setting          | Value                                                            |
+| ---------------- | ---------------------------------------------------------------- |
+| Dataset          | Market-1501 (12,936 train images, 751 train IDs)                 |
+| Identity sampler | P=16 IDs x K=4 instances per batch                               |
+| Batch size       | 64                                                               |
+| Optimizer        | Adam, lr=3.5e-4, weight_decay=5e-4                               |
+| LR schedule      | Linear warmup (10 epochs), step decay (x0.1 at epochs 40 and 70) |
+| Loss             | Combined CE (label smoothing 0.1) + triplet (soft margin)        |
+| Image size       | 256x128                                                          |
+| Augmentation     | Random horizontal flip, random erasing                           |
+
+## Performance
+
+### Standalone Re-ID (Market-1501)
+
+| Variant   | mAP   | Rank-1 | Rank-5 | Rank-10 |
+| --------- | ----- | ------ | ------ | ------- |
+| 60-epoch  | 73.73 | 89.32  | 96.04  | 97.74   |
+| 120-epoch | 75.15 | 90.66  | 96.79  | 98.04   |
+
+### Downstream - Single-camera tracking (MOT17, with DeepSORT)
+
+| Variant   | HOTA | MOTA | IDF1 | IDSW |
+| --------- | ---- | ---- | ---- | ---- |
+| 60-epoch  | 41.1 | 36.5 | 48.6 | 260  |
+| 120-epoch | 41.0 | 36.6 | 48.8 | 246  |
+
+### Downstream - Cross-camera tracking (Wildtrack, with ground-plane filter)
+
+| Variant   | IDF1  | IDP   | IDR   |
+| --------- | ----- | ----- | ----- |
+| 60-epoch  | 16.99 | 23.80 | 13.21 |
+| 120-epoch | 18.72 | 26.41 | 14.50 |
+
+## Usage
+
+Download and load with `huggingface_hub`:
+
+```python
+from huggingface_hub import hf_hub_download
+import torch
+
+ckpt_path = hf_hub_download(
+    repo_id="blank4hd/mctrack-reid",
+    filename="best_60ep.pth",
+)
+
+state = torch.load(ckpt_path, map_location="cpu", weights_only=False)
+model_state = state["state_dict"]
+```
+
+To use this with the model architecture, you need the `ReIDModel` class from
+the project repository. A minimal standalone loader (`load_reid.py`) is
+provided alongside this model card with the architecture definition inlined,
+so the model can be used without cloning the full project.
+
+## Intended Use
+
+This model produces 256-dimensional appearance embeddings for cropped person
+images. Two crops of the same person are expected to produce embeddings with
+high cosine similarity; crops of different people produce embeddings with low
+similarity.
+
+**Suitable for:**
+
+- Person re-identification in research / academic settings
+- Appearance feature extraction in tracking pipelines (e.g., DeepSORT)
+- Educational demonstration of metric learning
+
+**Not suitable for:**
+
+- Surveillance applications without explicit consent
+- Identification of individuals across populations (high false-positive rate
+  in cross-domain settings)
+- Any use where reliability is safety-critical
+
+## Limitations
+
+- **Domain gap.** Trained on Market-1501 (Tsinghua University campus, ~5
+  surveillance cameras). Performance degrades on outdoor pedestrian-square
+  scenes (e.g., Wildtrack), where IDF1 drops to ~17-19% in cross-camera
+  matching.
+- **Person crops only.** Expects the input to be a tightly-cropped person
+  image. Whole scenes or non-person inputs produce meaningless embeddings.
+- **Resolution sensitive.** Trained at 256x128. Significantly different input
+  resolutions will degrade quality.
+- **No fairness audit.** Not evaluated for performance disparities across
+  demographic groups.
+
+## Training Details (compute and time)
+
+- **Hardware:** Apple M4 Pro (MPS backend)
+- **Per-epoch time:** ~46 seconds
+- **Total training time:** 60-epoch ~46 min; 120-epoch ~92 min
+- **Memory usage:** ~3 GB unified memory at batch size 64
+
+## Citation
+
+This work was completed for the MSML 640 final project, Spring 2026.
+
+```
+Group 9 - MSML 640 Final Project
+Multi-Camera Object Tracking with Person Re-Identification
+```
+
+## Acknowledgments
+
+- Architecture inspired by Luo et al. ("Bag of Tricks and a Strong Baseline
+  for Deep Person Re-Identification", CVPR Workshop 2019)
+- BNNeck design from the same paper
+- Triplet loss formulation from Hermans et al. ("In Defense of the Triplet
+  Loss for Person Re-Identification", arXiv 2017)
+- Market-1501 dataset from Zheng et al. ("Scalable Person Re-Identification:
+  A Benchmark", ICCV 2015)

best_120ep.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:007fbe03dd4cb3c2b8b44d9b33a35f73b28b460a17c397018705c71113a3ac23
+size 102632278

best_60ep.pth

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

load_reid.py

@@ -0,0 +1,114 @@
+from pathlib import Path
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from PIL import Image
+from torchvision import models, transforms
+
+
+class ReIDModel(nn.Module):
+    """Minimal Re-ID model matching the trained checkpoint architecture.
+
+    ResNet-50 backbone (final stride 1) -> global average pooling -> BNNeck.
+    Returns 256-dim L2-normalized embeddings during inference.
+    """
+
+    def __init__(self, num_classes: int = 751, embedding_dim: int = 256):
+        super().__init__()
+        backbone = models.resnet50(weights=None)
+        backbone.layer4[0].conv2.stride = (1, 1)
+        backbone.layer4[0].downsample[0].stride = (1, 1)
+        self.backbone = nn.Sequential(*list(backbone.children())[:-2])
+
+        self.global_pool = nn.AdaptiveAvgPool2d(1)
+        self.feature_dim = 2048
+        self.bnneck = nn.BatchNorm1d(self.feature_dim)
+        self.bnneck.bias.requires_grad_(False)
+        nn.init.constant_(self.bnneck.weight, 1.0)
+        nn.init.constant_(self.bnneck.bias, 0.0)
+
+        self.embedding_layer = nn.Linear(self.feature_dim, embedding_dim, bias=False)
+        nn.init.kaiming_normal_(self.embedding_layer.weight, mode="fan_out")
+
+        self.num_classes = num_classes
+        if num_classes > 0:
+            self.classifier = nn.Linear(self.feature_dim, num_classes, bias=False)
+            nn.init.normal_(self.classifier.weight, std=0.001)
+        else:
+            self.classifier = None
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """Return an L2-normalized embedding of shape (N, embedding_dim)."""
+        feat_map = self.backbone(x)
+        pooled = self.global_pool(feat_map).flatten(1)
+        bn_features = self.bnneck(pooled)
+        embedding = self.embedding_layer(bn_features)
+        embedding = F.normalize(embedding, p=2, dim=1)
+        return embedding
+
+
+def load_model(checkpoint_path: str | Path, device: str = "cpu") -> ReIDModel:
+    """Load the trained Re-ID model from a stripped checkpoint."""
+    model = ReIDModel(num_classes=751, embedding_dim=256)
+    state = torch.load(str(checkpoint_path), map_location=device, weights_only=False)
+    sd = state["state_dict"] if "state_dict" in state else state
+    missing_keys, unexpected_keys = model.load_state_dict(sd, strict=False)
+    if missing_keys:
+        print(f"Warning: missing keys: {len(missing_keys)} keys")
+    if unexpected_keys:
+        print(f"Warning: unexpected keys: {len(unexpected_keys)} keys")
+    model.eval()
+    model.to(device)
+    return model
+
+
+_PREPROCESS = transforms.Compose(
+    [
+        transforms.Resize((256, 128)),
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
+    ]
+)
+
+
+def preprocess_image(image: Image.Image) -> torch.Tensor:
+    """Preprocess a PIL image to model input format."""
+    if image.mode != "RGB":
+        image = image.convert("RGB")
+    return _PREPROCESS(image).unsqueeze(0)
+
+
+def cosine_similarity(emb_a: torch.Tensor, emb_b: torch.Tensor) -> float:
+    """Cosine similarity between two L2-normalized embeddings, in [-1, 1]."""
+    return float(F.cosine_similarity(emb_a, emb_b).item())
+
+
+if __name__ == "__main__":
+    import sys
+
+    from huggingface_hub import hf_hub_download
+
+    print("Downloading model from Hugging Face...")
+    ckpt = hf_hub_download(repo_id="blank4hd/mctrack-reid", filename="best_60ep.pth")
+    model = load_model(ckpt)
+    print(f"Model loaded. Embedding dim: 256, parameter count: {sum(p.numel() for p in model.parameters()) / 1e6:.1f}M")
+
+    if len(sys.argv) >= 3:
+        img_a = Image.open(sys.argv[1])
+        img_b = Image.open(sys.argv[2])
+        x_a = preprocess_image(img_a)
+        x_b = preprocess_image(img_b)
+        with torch.no_grad():
+            emb_a = model(x_a)
+            emb_b = model(x_b)
+        sim = cosine_similarity(emb_a, emb_b)
+        print(f"Cosine similarity: {sim:.4f}")
+        if sim > 0.7:
+            print("Likely SAME person")
+        elif sim > 0.4:
+            print("Possibly same person (uncertain)")
+        else:
+            print("Likely DIFFERENT people")
+    else:
+        print("Usage: python load_reid.py <image_a.jpg> <image_b.jpg>")