Upload 3 files (#1)

- Upload 3 files (e392384e5bc4761815dd34073a32fd1293dfe579)

README.md

@@ -1,4 +1,6 @@
 ---
+license: apache-2.0
+pipeline_tag: video-classification
 tags:
 - video-classification
 - action-recognition
@@ -9,178 +11,229 @@ tags:
 - pytorch
 - computer-vision
 - spatiotemporal
-- 3dcnn
-library_name: pytorch
+- 3d-cnn
+- torchvision
+- human-action-classification
 datasets:
 - hmdb51
 - ucf101
 metrics:
 - accuracy
-- f1
 - precision
-pipeline_tag: video-classification
+- recall
+- f1
+model-index:
+- name: mc3-18-hmdb51-ucf-transfer
+  results:
+  - task:
+      type: video-classification
+      name: Action Recognition
+    dataset:
+      name: HMDB51
+      type: hmdb51
+      split: test
+    metrics:
+    - type: accuracy
+      value: 55.46
+      name: Top-1 Accuracy
+    - type: precision
+      value: 53.89
+      name: Macro Precision
+    - type: recall
+      value: 55.44
+      name: Macro Recall
+    - type: f1
+      value: 53.66
+      name: Macro F1
+language:
+- en
 ---
 
-# MC3-18 HMDB51 (UCF-101 Init)
-
-## Model Description
+[![🐙 GitHub](https://img.shields.io/badge/GitHub-Repository-181717?logo=github&logoColor=white&style=for-the-badge)](https://github.com/dronefreak/human-action-classification)
+[![📄 Paper: MC3](https://img.shields.io/badge/Paper-MC3-2EA44F?logo=arxiv&logoColor=white&style=for-the-badge)](https://arxiv.org/abs/1711.11248)
+[![💽 Dataset: HMDB51](https://img.shields.io/badge/Dataset-HMDB51-34aa44?logo=database&logoColor=white&style=for-the-badge)](https://serre-lab.clps.brown.edu/resource/hmdb-a-large-human-motion-database/)
 
-MC3-18 (Mixed Convolution 3D) finetuned on HMDB51 split 1 for human action recognition. This model was initialized with weights from an MC3-18 model pretrained on UCF-101 (87% accuracy) rather than Kinetics-400.
+# MC3-18 HMDB51 (UCF-101 Init)
 
-**Validation Accuracy: 55.46%**
+MC3-18 (Mixed Convolution 3D) fine-tuned on HMDB51 split 1, initialized from this project's own [MC3-18/UCF-101 model](https://huggingface.co/dronefreak/mc3-18-ucf101) (87.05% accuracy) instead of Kinetics-400 -- trained as part of the video pipeline in [human-action-classification](https://github.com/dronefreak/human-action-classification), to test whether a domain-closer pretraining source (another trimmed, YouTube-sourced action dataset) transfers better than a larger but more generic one. A sibling model initialized from Kinetics-400 is also available; see Related Resources below.
 
-This model demonstrates transfer learning from UCF-101 to HMDB51. Despite similar validation accuracy to Kinetics initialization (56.34%), this approach shows better generalization with a smaller train-validation gap.
+<br>
 
-## Model Details
+<!-- ROW 1: Identity & Tech Stack -->
+<div style="display: flex; justify-content: center; align-items: center; gap: 8px; margin-bottom: 8px; flex-wrap: wrap;">
+  <img src="https://img.shields.io/badge/Task-Video_Classification-blue?style=flat-square" alt="Task">
+  <img src="https://img.shields.io/badge/Architecture-MC3--18-0aa1a7?style=flat-square" alt="Architecture">
+  <img src="https://img.shields.io/badge/Pretrained_On-UCF--101-purple?style=flat-square" alt="Pretrained on UCF-101">
+</div>
 
-- **Architecture:** MC3-18 (11.7M parameters)
-- **Initialization:** UCF-101 pretrained weights (87% accuracy on UCF-101)
-- **Dataset:** HMDB51 split 1
-  - Train: 3,570 videos across 51 action classes
-  - Validation: 1,530 videos
-- **Input:** RGB video clips (16 frames, 112x112 spatial resolution)
-- **Output:** 51-class action predictions
+<!-- ROW 2: Performance Metrics -->
+<div style="display: flex; justify-content: center; align-items: center; gap: 8px; margin-bottom: 8px; flex-wrap: wrap;">
+  <img src="https://img.shields.io/badge/Accuracy-55.46%25-yellow?style=flat-square" alt="Accuracy">
+  <img src="https://img.shields.io/badge/F1-53.66%25-orange?style=flat-square" alt="F1 Score">
+  <img src="https://img.shields.io/badge/Params-11.5M-lightgrey?style=flat-square" alt="Params">
+</div>
 
-## Training Configuration
-```yaml
-Frames: 16
-Frame Interval: 2
-Spatial Size: 112x112
-Batch Size: 16
-Epochs: 100
-Learning Rate: 0.0003
-Weight Decay: 2e-3
-Optimizer: SGD (momentum=0.9)
-```
+<!-- ROW 3: Metadata -->
+<div style="display: flex; justify-content: center; align-items: center; gap: 8px; margin-bottom: 24px; flex-wrap: wrap;">
+  <img src="https://img.shields.io/badge/License-Apache--2.0-lightgrey?style=flat-square" alt="License">
+  <a href="https://github.com/dronefreak/human-action-classification"><img src="https://img.shields.io/badge/Source-human--action--classification-black?style=flat-square" alt="Source"></a>
+</div>
 
-**Augmentation:**
-- MixUp (alpha=0.4)
-- CutMix (alpha=0.8)
-- Label Smoothing (0.1)
-- Random horizontal flip
-- Color jitter
-- Random grayscale
+---
 
 ## Performance
 
-| Metric | Value |
-|--------|-------|
-| Validation Accuracy | 55.46% |
-| Training Accuracy | 68.59% |
-| Train-Val Gap | 13% |
-| Val F1 Score | 0.5359 |
-| Val Precision | 0.5379 |
-
-## Why UCF-101 Transfer?
+| Metric              | Value      |
+| ------------------- | ---------- |
+| Accuracy (Top-1)     | 55.46%     |
+| Precision (macro)   | 53.89%     |
+| Recall (macro)      | 55.44%     |
+| F1 Score (macro)    | 53.66%     |
+| Parameters          | 11.5M      |
+| Best epoch          | 49 / 100   |
 
-UCF-101 and HMDB51 share similar characteristics:
-- Both are human action recognition datasets
-- Similar video sources (YouTube, movies)
-- Overlapping action categories (basketball, biking, diving, etc.)
-- Similar temporal and spatial scales
+Within 1 point of the Kinetics-400-initialized sibling model (56.34% accuracy) despite UCF-101 being a ~30x smaller pretraining corpus -- see Kinetics-400 vs. UCF-101 Initialization below.
 
-This makes UCF-101 a more natural pretraining source than Kinetics-400 for HMDB51 transfer.
-
-## Better Generalization
+---
 
-Compared to Kinetics-400 initialization:
+## Evaluation Protocol
 
-| Initialization | Val Acc | Train Acc | Gap |
-|---------------|---------|-----------|-----|
-| Kinetics-400 | 56.34% | ~75% | 19% |
-| UCF-101 (this) | 55.46% | 68.59% | 13% |
+Metrics above come from `VideoTrainer.validate()` in `hac.video.training.train`, run on HMDB51 split 1's test set (1,530 videos, 51 classes), at the checkpoint's best-performing epoch. Each clip: 16 frames sampled at stride 2 (i.e. spanning up to 32 source frames), resized preserving aspect ratio to roughly 128x171, center-cropped to 112x112, normalized with Kinetics-400 statistics -- a single center clip per video, no test-time augmentation or multi-crop averaging.
 
-The UCF-101 initialization achieves:
-- Similar validation accuracy (only 0.88% lower)
-- Much better generalization (6% smaller train-val gap)
-- Lower training accuracy (less memorization)
+---
 
-This suggests UCF-101 features are better regularized for HMDB51, even though Kinetics-400 is a larger pretraining dataset.
+## Usage
 
-## Frame Tiling Issue
+### Install Dependencies
 
-**Important caveat:** The UCF-101 checkpoint was trained with `num_frames=16, frame_interval=2` (requiring 32 consecutive frames). However, many HMDB51 videos are shorter than 32 frames.
+Not yet published on PyPI -- install from source:
 
-For short videos, the data loader tiles/repeats frames to reach 16 frames. This may hurt performance on those samples but was necessary to match the UCF-101 pretraining configuration.
+```bash
+git clone https://github.com/dronefreak/human-action-classification
+cd human-action-classification
+pip install -e .
+```
 
-The Kinetics-initialized model uses `num_frames=8, frame_interval=1` to avoid this issue, which may explain its slightly higher validation accuracy despite worse generalization.
+### Load the Model from Hugging Face
 
-## Usage
 ```python
+import json
 import torch
-from torchvision.models.video import mc3_18
-from torchvision import transforms
-import cv2
-
-# Load model
-model = mc3_18(weights=None)
-model.fc = torch.nn.Linear(model.fc.in_features, 51)
-checkpoint = torch.load('best.pth')
-model.load_state_dict(checkpoint['model_state_dict'])
+from huggingface_hub import hf_hub_download
+from hac.video.models.classifier import Video3DCNN
+
+config_path = hf_hub_download(repo_id="dronefreak/mc3-18-hmdb51-ucf-transfer", filename="config.json")
+weights_path = hf_hub_download(
+    repo_id="dronefreak/mc3-18-hmdb51-ucf-transfer",
+    filename="mc3-18-hmdb51-ucf-transfer.pth",
+)
+
+with open(config_path) as f:
+    config = json.load(f)
+
+model = Video3DCNN(
+    num_classes=config["num_classes"],  # 51
+    model_name=config["model_type"],
+    pretrained=False,
+)
+
+checkpoint = torch.load(weights_path, map_location="cpu", weights_only=False)
+model.load_state_dict(checkpoint["model_state_dict"])
 model.eval()
+```
 
-# Preprocessing
-transform = transforms.Compose([
-    transforms.ToPILImage(),
-    transforms.Resize((128, 171)),
-    transforms.CenterCrop(112),
-    transforms.ToTensor(),
-    transforms.Normalize(mean=[0.43216, 0.394666, 0.37645], 
-                        std=[0.22803, 0.22145, 0.216989])
-])
-
-# Load 16 frames from video (sample every 2nd frame)
-frames = []  # Load your frames here
-frames = [transform(frame) for frame in frames]
-video_tensor = torch.stack(frames).permute(1, 0, 2, 3).unsqueeze(0)  # (1, 3, 16, 112, 112)
-
-# Inference
-with torch.no_grad():
-    output = model(video_tensor)
-    pred = output.argmax(dim=1)
+### Run Inference on a Video
+
+The repo's `VideoPredictor` wraps frame sampling, transforms, and the forward pass end-to-end (pass `num_frames=16` to match this model's training configuration):
+
+```python
+from hac.video.inference.predictor import VideoPredictor
+
+predictor = VideoPredictor(model_path=weights_path, num_frames=16, device="cpu")
+result = predictor.predict_video("path/to/video.mp4", top_k=5)
+
+print(result["top_class"], result["top_confidence"])
 ```
 
-## Alternative Approach
+Note: `VideoPredictor`'s built-in class list defaults to UCF-101's 101 classes -- for HMDB51 you'll want to pass/override the 51 class names listed below rather than relying on the predictor's default.
+
+---
+
+## Training Configuration
+
+| Setting               | Value                                                                     | Source                       |
+| ---------------------- | -------------------------------------------------------------------------- | ----------------------------- |
+| Dataset                | HMDB51 split 1 (3,570 train / 1,530 test videos, 51 classes)              | HMDB51 split files            |
+| Architecture           | MC3-18 (`torchvision.models.video.mc3_18`)                                | checkpoint config             |
+| Pretrained init        | This project's [MC3-18/UCF-101 model](https://huggingface.co/dronefreak/mc3-18-ucf101) | checkpoint config + repo history |
+| Optimizer              | SGD (momentum=0.9, nesterov=False)                                        | checkpoint optimizer state    |
+| Initial learning rate  | 0.0003                                                                     | checkpoint optimizer state    |
+| Weight decay           | 0.002                                                                      | checkpoint optimizer state    |
+| LR schedule            | StepLR (step_size=20, gamma=0.1)                                          | checkpoint scheduler state    |
+| Epochs trained         | 100 (best at epoch 49)                                                     | checkpoint + training history |
+| Frames per clip        | 16, frame_interval=2                                                       | training script default       |
+| Spatial resolution     | 112x112 (aspect-preserving resize + random crop)                          | training script default       |
+| Batch size             | not recorded in checkpoint                                                 | --                             |
+| Augmentation           | MixUp (alpha=0.4), CutMix (alpha=0.8), label smoothing (0.1), RandomHorizontalFlip, ColorJitter, RandomGrayscale | training script default (unconfirmed exact values for this run) |
+
+Rows marked "checkpoint ..." are read directly out of the optimizer/scheduler state and config dict stored inside `mc3-18-hmdb51-ucf-transfer.pth`. Rows marked "training script default" reflect `hac.video.training.train`'s CLI defaults/flags at the time of training but weren't independently re-derived from the checkpoint for this exact run -- no separate run-config file was saved alongside it.
 
-We also provide a model initialized from Kinetics-400 instead of UCF-101. That model achieves 56.34% validation accuracy but with worse generalization (19% train-val gap).
+---
 
-See: `mc3-18-hmdb51-kinetics`
+## Kinetics-400 vs. UCF-101 Initialization
 
-**UCF-101 vs Kinetics initialization:**
-- UCF-101 (this): Better generalization (13% gap), requires 16 frames, closer domain to HMDB51
-- Kinetics: Slightly higher accuracy (56.34%), optimized for short clips (8 frames), larger pretraining dataset
+This project also ships an MC3-18/HMDB51 model initialized from Kinetics-400 instead of UCF-101 -- see [mc3-18-hmdb51-kinetics](https://huggingface.co/dronefreak/mc3-18-hmdb51-kinetics) (56.34% accuracy).
 
-## Limitations
+| Initialization | Accuracy | Notes |
+| --------------- | -------- | ----- |
+| UCF-101 (this model) | 55.46% | ~30x smaller pretraining corpus than Kinetics-400; domain-closer to HMDB51 (similar YouTube/movie sources, overlapping action categories); 16-frame clips |
+| [Kinetics-400](https://huggingface.co/dronefreak/mc3-18-hmdb51-kinetics) | 56.34% | Larger, more diverse pretraining corpus; 8-frame clips (avoids tiling on HMDB51's shorter videos) |
 
-- Requires 16-frame inputs (causes frame tiling on short HMDB51 videos)
-- Still overfits despite better generalization (13% train-val gap)
-- Single model without ensemble
-- No test-time augmentation
-- Trained on HMDB51 split 1 only
+The two reach nearly identical validation accuracy despite very different pretraining sources -- consistent with the idea that domain similarity can partly substitute for pretraining-set size, though a single run per initialization isn't enough to call that conclusive. The original training run's console logs reportedly showed a smaller train/validation gap for this UCF-101-initialized model than for the Kinetics-initialized one; that figure isn't stored in the checkpoint itself, so it isn't independently re-verified in this card.
 
-## Transfer Learning Insight
+**Frame tiling caveat:** this model uses 16-frame clips at stride 2 to match its UCF-101 pretraining configuration, but many HMDB51 videos are shorter than the resulting 32-frame span -- short clips get frame-repeated ("tiled") to reach 16 sampled frames, which may hurt performance on those specific samples. The Kinetics-initialized sibling avoids this by using 8-frame, stride-1 clips instead.
 
-This model demonstrates that:
-1. **Pretraining dataset size is not everything** - UCF-101 (13K videos) transfers better than Kinetics-400 (400K videos) when domain similarity matters
-2. **Domain alignment matters** - UCF-101 and HMDB51 share similar action types and video characteristics
-3. **Config matching matters** - Matching pretraining config (16 frames) can conflict with target dataset characteristics (short videos)
+---
 
 ## HMDB51 Classes
 
-The model predicts 51 action classes including: brush_hair, cartwheel, catch, chew, clap, climb, climb_stairs, dive, draw_sword, dribble, drink, eat, fall_floor, fencing, flic_flac, golf, handstand, hit, hug, jump, kick, kick_ball, kiss, laugh, pick, pour, pullup, punch, push, pushup, ride_bike, ride_horse, run, shake_hands, shoot_ball, shoot_bow, shoot_gun, sit, situp, smile, smoke, somersault, stand, swing_baseball, sword, sword_exercise, talk, throw, turn, walk, wave.
+The model predicts 51 action classes: brush_hair, cartwheel, catch, chew, clap, climb, climb_stairs, dive, draw_sword, dribble, drink, eat, fall_floor, fencing, flic_flac, golf, handstand, hit, hug, jump, kick, kick_ball, kiss, laugh, pick, pour, pullup, punch, push, pushup, ride_bike, ride_horse, run, shake_hands, shoot_ball, shoot_bow, shoot_gun, sit, situp, smile, smoke, somersault, stand, swing_baseball, sword, sword_exercise, talk, throw, turn, walk, wave.
+
+---
+
+## Known Limitations
+
+- Frame tiling on short HMDB51 clips (see caveat above) may depress accuracy on a subset of test videos.
+- Single model, no ensembling; no test-time augmentation (multi-crop, multi-clip temporal sampling).
+- Trained and evaluated on HMDB51 split 1 only -- performance on splits 2/3 is unverified.
+- Depends on this project's own MC3-18/UCF-101 checkpoint as its pretraining source rather than a widely-used public pretrained model, making external reproduction harder without first training that upstream model.
 
-## Training Details
+---
+
+## Repository Contents
+
+```text
+mc3-18-hmdb51-ucf-transfer.pth
+config.json
+README.md
+```
+
+`config.json` doubles as the Hub's download-count query file: since this repo has no `library_name` integration the Hub recognizes, it falls back to counting requests against `config.json` (per [Hugging Face's download-stats docs](https://huggingface.co/docs/hub/models-download-stats)) -- the loading snippet above fetches it as part of normal usage, so downloads register.
+
+---
 
-- Framework: PyTorch
-- Hardware: Single GPU (CUDA)
-- Training Time: ~1.5 hours (100 epochs)
-- Convergence: Best model saved around epoch 90-100
+## Related Resources
+
+- [mc3-18-hmdb51-kinetics](https://huggingface.co/dronefreak/mc3-18-hmdb51-kinetics) -- sibling model, same architecture/dataset, initialized from Kinetics-400 instead of UCF-101
+- [mc3-18-ucf101](https://huggingface.co/dronefreak/mc3-18-ucf101) -- the UCF-101 model this model was transferred from
+- [human-action-classification](https://github.com/dronefreak/human-action-classification) -- the training/inference framework used to produce this checkpoint
+
+---
 
 ## Citation
 
-If you use this model, please cite:
+If you use this model, please consider citing the HMDB51 and UCF-101 datasets, the MC3 architecture, and the training framework:
 
-HMDB51 dataset:
 ```bibtex
 @inproceedings{kuehne2011hmdb,
   title={HMDB: a large video database for human motion recognition},
@@ -192,30 +245,48 @@ HMDB51 dataset:
 }
 ```
 
-UCF-101 dataset:
 ```bibtex
 @article{soomro2012ucf101,
-  title={UCF101: A dataset of 101 human actions classes from videos in the wild},
+  title={UCF101: A Dataset of 101 Human Actions Classes From Videos in the Wild},
   author={Soomro, Khurram and Zamir, Amir Roshan and Shah, Mubarak},
   journal={arXiv preprint arXiv:1212.0402},
   year={2012}
 }
 ```
 
-MC3 architecture:
 ```bibtex
 @inproceedings{tran2018closer,
-  title={A closer look at spatiotemporal convolutions for action recognition},
+  title={A Closer Look at Spatiotemporal Convolutions for Action Recognition},
   author={Tran, Du and Wang, Heng and Torresani, Lorenzo and Ray, Jamie and LeCun, Yann and Paluri, Manohar},
-  booktitle={Proceedings of the IEEE conference on Computer Vision and Pattern Recognition},
-  pages={6450--6459},
+  booktitle={Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition (CVPR)},
   year={2018}
 }
 ```
 
+```bibtex
+@misc{saksena2025mc3hmdbucf,
+  author = {Saumya Saksena},
+  title = {{MC3-18 HMDB51 (UCF-101 Init)}},
+  year = {2025},
+  publisher = {Hugging Face},
+  howpublished = {\url{https://huggingface.co/dronefreak/mc3-18-hmdb51-ucf-transfer}},
+  note = {Trained with the human-action-classification framework, Top-1 Accuracy: 55.46\%}
+}
+```
+
+```bibtex
+@software{saksena2026hac,
+  author       = {Saumya Saksena},
+  title        = {{Human Action Classification: Pose-based and Video-based Models}},
+  year         = 2026,
+  publisher    = {GitHub},
+  journal      = {GitHub repository},
+  howpublished = {\url{https://github.com/dronefreak/human-action-classification}}
+}
+```
+
+---
+
 ## License
 
-Model weights: [Apache]
-Code: [Apache]
-HMDB51 Dataset: [Original dataset license]
-UCF-101 Dataset: [Original dataset license]
+Apache-2.0

config.json

@@ -0,0 +1,37 @@
+{
+  "model_type": "mc3_18",
+  "architecture": "torchvision.models.video.mc3_18",
+  "num_classes": 51,
+  "pretrained": true,
+  "pretrained_dataset": "UCF-101 (dronefreak/mc3-18-ucf101, 87.05% accuracy)",
+  "task": "video-classification",
+  "dataset": "HMDB51",
+  "dataset_split": "split1",
+  "input": {
+    "num_frames": 16,
+    "frame_interval": 2,
+    "spatial_size": 112,
+    "normalize_mean": [0.43216, 0.394666, 0.37645],
+    "normalize_std": [0.22803, 0.22145, 0.216989]
+  },
+  "training": {
+    "optimizer": "SGD",
+    "momentum": 0.9,
+    "nesterov": false,
+    "initial_lr": 0.0003,
+    "weight_decay": 0.002,
+    "lr_scheduler": "StepLR",
+    "lr_step_size": 20,
+    "lr_gamma": 0.1,
+    "epochs": 100,
+    "best_epoch": 49
+  },
+  "metrics": {
+    "accuracy": 0.5546,
+    "precision_macro": 0.5389,
+    "recall_macro": 0.5544,
+    "f1_macro": 0.5366
+  },
+  "framework": "human-action-classification",
+  "framework_url": "https://github.com/dronefreak/human-action-classification"
+}

mc3-18-hmdb51-ucf-transfer.pth

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:167bacb711baad52446ac95f14ca3a6f04ef881d8eebc6c61e2d1befca37b179
-size 92223701
+oid sha256:df97c7057e22e77bc6da580ff622ea1a2cec554d935bdd1ef7531fe7a1fa1d13
+size 92223893