README.md

metadata

license: cc-by-nd-4.0
language:
  - en
base_model:
  - lakeAGI/PersonViTReID

PersonViT — Re‑ID Ablation on PRW

This repository contains an evaluation and fine‑tuning pipeline for PersonViT (TransReID backbone) on the PRW (Person Re‑Identification in the Wild) dataset.

The notebook is designed for Kaggle and includes:

• pretrained checkpoint evaluation
• a structured multi‑phase ablation study (strategy -> loss -> ViT‑Small)
• automatic on‑disk checkpointing of results after every run to survive disconnects

---

What the notebook does

The notebook runs an ablation study in three phases:

1. Pretrained evaluation (ViT‑Base)
   Evaluates multiple pretrained PersonViT ViT‑Base checkpoints on PRW and selects the best baseline (highest mAP).

2. Phase 1 — Strategy comparison (loss fixed = ArcFace)
   Compares three fine‑tuning strategies:

   • full: unfreeze everything, very small LR
   • partial: freeze backbone, train head only
   • freeze: freeze backbone and reset head, retrain head

3. Phase 2 — Loss comparison (strategy fixed = best Phase 1)
   With the best strategy fixed (full), compares metric learning losses:

   • Triplet (with hard mining)
   • ArcFace (reuses the Phase 1 ArcFace run for the winning strategy)
   • Angular (configured to avoid “loss = 0” issues from overly restrictive mining)

4. Phase 3 — ViT‑Small (best strategy + best loss)
   Fine‑tunes ViT‑Small using the best strategy+loss from Phase 1/2, then adds it to the final comparison.

Finally, it generates comparison plots and exports a summary CSV.

---

Requirements

Hardware

• Single GPU recommended (tested design target: 1× NVIDIA T4 16GB)

Software

• Python 3.x
• PyTorch 2.x
• Kaggle notebook environment (or equivalent)

Python packages (installed by the notebook)

• albumentations
• opencv-python-headless
• scipy
• torchmetrics
• timm
• einops
• yacs
• pytorch-metric-learning
• thop

---

Dataset and checkpoints

PRW dataset

Configure the PRW root directory in the notebook Config:

• cfg.dataset_root = '/kaggle/input/datasets/edoardomerli/prw-person-re-identification-in-the-wild'

The notebook expects the standard PRW structure (frames, annotations, query_box, split mats, etc.).

Pretrained checkpoints

The notebook evaluates multiple pretrained ViT‑Base checkpoints and uses the best one for fine‑tuning.
It also contains a Phase 3 configuration for ViT‑Small (Market‑1501 pretrained).

Make sure the checkpoint paths in Config match your Kaggle inputs.

---

How to run (recommended order)

1. Install & Imports
2. Config
3. Datasets & DataLoaders (this step takes time because PRW annotations are parsed)
4. (Optional) Resume: run load_results() to restore RESULTS from disk
5. Run the experiment blocks in order:
   • Pretrained evaluation
   • Phase 1 runs + Phase 1 plots (selects best strategy)
   • Phase 2 runs + Phase 2 plots (selects best loss)
   • Phase 3 (ViT‑Small)
   • Final comparison + CSV export

The fine‑tuning helper automatically skips runs already present in the saved results, so you can safely re-run cells after a disconnect.

---

Output files

Progressive results checkpoint (anti-disconnect)

Saved every time RESULTS is updated:

• evaluation_results/all_results.json

Final summary table

Saved at the end:

• evaluation_results/all_results.csv

Plots

Saved into:

• evaluation_results/plots/

Typical outputs include:

• bar chart (mAP & Rank‑1)
• heatmap (mAP across strategy × loss when applicable)
• radar chart with 4 metrics: mAP, Rank‑1, Rank‑5, Rank‑10
• per-run training curves:
  • /kaggle/working/personvit_finetuning/curves_<run_key>.png

Fine‑tuning checkpoints

Best checkpoint per run:

• /kaggle/working/personvit_finetuning/best_<run_key>.pth

---

Key concepts and run keys

Fine‑tuning strategies

• full: unfreeze all parameters (low LR, avoids catastrophic forgetting)
• partial: freeze backbone, train only head
• freeze: freeze backbone, reset head modules, retrain head from scratch

Losses

• triplet: TripletMarginLoss + hard mining
• arcface: ArcFace loss (with its own internal parameters)
• angular: Angular loss (configured to avoid empty mining → loss=0)

Run key naming

• Phase 1:
  • full_arcface, partial_arcface, freeze_arcface
• Phase 2 (for best strategy S):
  • S_triplet, S_arcface (reused), S_angular
• Phase 3:
  • vit_small_<best_strategy>_<best_loss>

---

What is saved in RESULTS

RESULTS[run_key] stores:

• Metrics: mAP, rank1, rank5, rank10, num_valid_queries
• Profiling: total_params, flops_giga, inference_ms, throughput
• Fine‑tuning only:
  • history (training curves data)
  • trainable_params (number of trainable parameters) to quantify how much of the model was actually fine‑tuned
• Metadata: strategy, loss, plus display_name for pretrained baselines

---

AMP / Mixed precision note

The notebook uses native PyTorch AMP to speed up training and reduce VRAM usage on T4-class GPUs. If you update PyTorch and see deprecation warnings, switch to the newer API:

• torch.amp.GradScaler('cuda', ...)
• torch.amp.autocast(device_type='cuda', ...)

If you disable AMP (cfg.use_amp = False), training will run in FP32 (more stable, slower, higher VRAM usage).

---

Credits

• PersonViT codebase and pretrained weights belong to their respective authors.
• This repository provides an ablation and fine‑tuning workflow tailored for PRW on a single GPU with robust persistence.