Update README.md

README.md

@@ -4,291 +4,210 @@ library_name: pytorch
 pipeline_tag: image-classification
 tags:
   - image-classification
-  - pytorch
   - convnext
   - vehicles
   - cars
   - stanford-cars
   - fine-grained-classification
+  - pytorch
+  - transfer-learning
 datasets:
   - naufalso/stanford_cars
 metrics:
   - accuracy
----
-
-# TwinCar: Deep Learning for Automotive Classification
-
-TwinCar is a deep learning project focused on vehicle classification and automotive attribute prediction. It explores and compares multiple state-of-the-art convolutional neural networks (CNNs) and Vision Transformer architectures using transfer learning techniques on public automotive datasets.
-
-The project evaluates model performance across different datasets and training strategies, including fine-tuning and feature extraction, while providing a reproducible workflow for data preparation, training, evaluation, and inference.
-
-## Features
-
-* Comparison of multiple deep learning architectures:
-
-  * EfficientNet-B0
-  * ConvNeXt-Tiny
-  * Vision Transformer (ViT-B/16)
-  * Swin Transformer (Swin-T)
-  * DeiT
-* Support for multiple automotive datasets:
-
-  * Stanford Cars
-  * CompCars
-* Transfer learning experiments with both fine-tuning and frozen-backbone approaches
-* Comprehensive evaluation metrics and visualizations
-* Batch inference demonstrations
-* Structured and reproducible notebook-based workflow
-
----
-
-## Project Structure
-
-```text
-TwinCar/
-├── notebooks/
-│   ├── 01_data_exploration.ipynb
-│   ├── 02_data_preparation.ipynb
-│   │
-│   ├── EfficientNet Experiments
-│   ├── 03a_efficientnet_b0_v1.ipynb
-│   ├── 03a_efficientnet_b0_v1_evaluation.ipynb
-│   ├── 03b_efficientnet_b0_v2.ipynb
-│   ├── 03b_efficientnet_b0_v2_evaluation.ipynb
-│   │
-│   ├── ConvNeXt Experiments
-│   ├── 04_convnext.ipynb
-│   ├── 04_convnext_tiny_evaluation.ipynb
-│   │
-│   ├── Stanford Cars Models
-│   ├── ConvNeXt_Tiny - Stanford Cars.ipynb
-│   ├── ConvNeXt_Tiny with freezing - Stanford Cars.ipynb
-│   ├── ConvNeXt_Tiny with freezing v2 - Stanford Cars.ipynb
-│   ├── EfficientNet_B0 - Stanford Cars.ipynb
-│   ├── Swin_T - Stanford Cars.ipynb
-│   ├── ViT_B_16_StanfordCars_model.ipynb
-│   ├── deit_tiny_patch16_224 - Stanford Cars.ipynb
-│   │
-│   ├── CompCars Models
-│   ├── 06_compcars_efficientnet_b0_make_model_year.ipynb
-│   ├── EfficientNet_B0 - Comp Cars.ipynb
-│   ├── ConvNeXt_Tiny - Comp Cars.ipynb
-│   ├── CompCars_ViT_model.ipynb
-│   │
-│   ├── 05_batch_prediction_demo.ipynb
-│   └── ml-final-project.ipynb
-│
-├── models/
-├── reports/
-├── scripts/
-├── requirements.txt
-└── README.md
-```
-
----
-
-## Datasets
-
-### Stanford Cars
-
-A fine-grained vehicle classification dataset containing approximately 16,000 images across 196 vehicle categories. It is widely used for benchmarking car recognition models.
-
-### CompCars
-
-A large-scale automotive dataset containing over 30,000 images with detailed annotations, including vehicle make, model, and year. It is suitable for both classification and attribute prediction tasks.
-
----
-
-## Model Architectures
-
-### CNN-Based Models
-
-#### EfficientNet-B0
-
-EfficientNet uses compound scaling to balance network depth, width, and resolution. Multiple versions are included to evaluate the impact of training and optimization strategies.
-
-#### ConvNeXt-Tiny
-
-A modern CNN architecture inspired by Vision Transformers while retaining the efficiency and simplicity of convolutional networks. Experiments include both fully trainable and partially frozen variants.
-
-### Transformer-Based Models
-
-#### Vision Transformer (ViT-B/16)
-
-A pure transformer architecture that processes images as sequences of patches for image classification.
-
-#### Swin Transformer (Swin-T)
-
-A hierarchical transformer architecture that uses shifted-window attention for efficient feature extraction.
-
-#### DeiT
-
-A data-efficient transformer model designed to achieve strong performance with reduced training requirements.
-
----
-
-## Installation
-
-### Prerequisites
-
-* Python 3.8+
-* CUDA-capable GPU (recommended)
-* Jupyter Notebook
-
-### Clone the Repository
-
-```bash
-git clone https://github.com/dragicakostoska/TwinCar.git
-cd TwinCar
-```
-
-### Install Dependencies
-
-```bash
-pip install -r requirements.txt
+  - f1
+  - precision
+  - recall
+model-index:
+  - name: twincars_convnext
+    results:
+      - task:
+          type: image-classification
+          name: Image Classification
+        dataset:
+          name: Stanford Cars
+          type: naufalso/stanford_cars
+        metrics:
+          - type: accuracy
+            value: 0.8708
+            name: Top-1 Accuracy
+          - type: accuracy
+            value: 0.9681
+            name: Top-5 Accuracy
+          - type: f1
+            value: 0.8705
+            name: Weighted F1
+          - type: precision
+            value: 0.8765
+            name: Macro Precision
+          - type: recall
+            value: 0.8696
+            name: Macro Recall
+---
+
+# TwinCar — ConvNeXt-Tiny (Stanford Cars)
+
+A fine-grained vehicle make/model classifier built on **ConvNeXt-Tiny**, fully fine-tuned on the **Stanford Cars** dataset (195 classes). This is the best-performing model from the [TwinCar](https://github.com/dragicakostoska/TwinCar) project, which compares several CNN and Vision Transformer architectures for automotive classification.
+
+Given an image of a car, the model predicts the vehicle's make, model, and year as a single fine-grained class (e.g. `BMW_X5_SUV_2007`).
+
+## Model details
+
+| | |
+|---|---|
+| **Architecture** | ConvNeXt-Tiny (`torchvision.models.convnext_tiny`) |
+| **Initialization** | ImageNet-1k pretrained weights (`ConvNeXt_Tiny_Weights.IMAGENET1K_V1`) |
+| **Fine-tuning** | Full network (single-phase, no frozen layers) |
+| **Classes** | 195 fine-grained make/model/year categories |
+| **Input size** | 224 × 224 RGB |
+| **Framework** | PyTorch |
+| **Weights file** | `best_model.pt` (raw `state_dict`, ~112 MB) |
+
+The classifier head is the standard ConvNeXt-Tiny head with the final `Linear` layer replaced by a `Linear(in_features, 195)`. Only the final layer is reshaped; LayerNorm and Flatten are kept as in the original head.
+
+## Files in this repository
+
+| File | Description |
+|---|---|
+| `best_model.pt` | Model weights, saved as a plain `state_dict` |
+| `idx_to_class.json` | Maps class index → label string (e.g. `42 → "BMW_X5_SUV_2007"`) |
+| `train_config.json` | Training hyperparameters and preprocessing constants |
+| `README.md` | This model card |
+
+> **Note on the weights format.** `best_model.pt` is a raw `state_dict` saved with `torch.save(model.state_dict(), ...)`, not a wrapped checkpoint. Load it directly with `model.load_state_dict(...)` as shown below.
+
+## How to use
+
+```python
+import json
+import torch
+import torch.nn as nn
+from PIL import Image
+from torchvision import models, transforms
+from huggingface_hub import hf_hub_download
+
+REPO_ID = "cherky15/twincars_convnext"
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+# 1. Download files from the Hub
+weights_path = hf_hub_download(REPO_ID, "best_model.pt")
+labels_path  = hf_hub_download(REPO_ID, "idx_to_class.json")
+config_path  = hf_hub_download(REPO_ID, "train_config.json")
+
+with open(labels_path) as f:
+    idx_to_class = {int(k): v for k, v in json.load(f).items()}
+with open(config_path) as f:
+    config = json.load(f)
+
+num_classes = len(idx_to_class)  # 195
+
+# 2. Rebuild the architecture and load the weights
+model = models.convnext_tiny(weights=None)
+in_features = model.classifier[2].in_features
+model.classifier[2] = nn.Linear(in_features, num_classes)
+
+state_dict = torch.load(weights_path, map_location=device)
+model.load_state_dict(state_dict)
+model.to(device).eval()
+
+# 3. Preprocess (must match validation/test transforms used in training)
+transform = transforms.Compose([
+    transforms.Resize(256),
+    transforms.CenterCrop(config["img_size"]),          # 224
+    transforms.ToTensor(),
+    transforms.Normalize(mean=config["imagenet_mean"],  # ImageNet stats
+                         std=config["imagenet_std"]),
+])
+
+# 4. Predict
+image = Image.open("car.jpg").convert("RGB")
+x = transform(image).unsqueeze(0).to(device)
+
+with torch.no_grad():
+    probs = torch.softmax(model(x), dim=1)
+    top5_prob, top5_idx = probs.topk(5, dim=1)
+
+for prob, idx in zip(top5_prob[0], top5_idx[0]):
+    label = idx_to_class[int(idx)].replace("_", " ")
+    print(f"{label:40s} {prob.item():.3f}")
 ```
 
----
-
-## Dependencies
-
-Core libraries used throughout the project include:
-
-* PyTorch and TorchVision
-* NumPy and Pandas
-* Pillow
-* Hugging Face Datasets
-* Scikit-learn
-* Matplotlib
-* tqdm
-* Jupyter Notebook and IPython Kernel
-
----
-
-## Workflow
-
-### 1. Data Exploration
-
-`01_data_exploration.ipynb`
-
-* Explore dataset characteristics
-* Visualize class distributions
-* Inspect image samples and dataset statistics
-
-### 2. Data Preparation
-
-`02_data_preparation.ipynb`
-
-* Apply preprocessing and augmentation techniques
-* Create training, validation, and test splits
-* Build dataset loaders and transformations
-
-### 3. Model Training
-
-* Select the desired architecture notebook
-* Configure hyperparameters
-* Train using transfer learning or fine-tuning
-* Monitor performance throughout training
-
-### 4. Evaluation
-
-* Analyze classification metrics
-* Generate confusion matrices
-* Visualize training and validation curves
-* Compare model performance across architectures
+For batch inference over a folder of images (with make/model/year parsing and CSV export), see `batch_predict.py` in the [TwinCar repository](https://github.com/dragicakostoska/TwinCar).
 
-### 5. Inference
+## Intended use
 
-`05_batch_prediction_demo.ipynb`
+**Intended:** fine-grained recognition of car make/model/year on clean, well-framed images similar in distribution to Stanford Cars (single centered vehicle, mostly clear backgrounds), and as a research/educational baseline for comparing architectures on fine-grained classification.
 
-* Load trained models
-* Run predictions on image batches
-* Visualize outputs and confidence scores
+**Out of scope:** the model only knows the 195 Stanford Cars categories. It cannot recognize makes/models outside this set, and will still return a confident class for non-car images or unseen vehicles. It is not validated for safety-critical or surveillance use.
 
----
-
-## Training Strategies
-
-The project investigates two common transfer learning approaches:
+## Training data
 
-### Fine-Tuning
+- **Dataset:** [Stanford Cars](https://huggingface.co/datasets/naufalso/stanford_cars) (`naufalso/stanford_cars`)
+- **Classes:** 195 fine-grained make/model/year categories
+- **Test split:** 8,000 images
+- Class imbalance was handled during training with a `WeightedRandomSampler`.
 
-All network layers are trained starting from pretrained weights, allowing the model to adapt fully to the target dataset.
+## Training procedure
 
-### Feature Extraction
+Fine-tuned end-to-end from ImageNet-pretrained weights with mixed-precision (AMP) on a CUDA GPU.
 
-Earlier layers are frozen while only the classification head is trained. This reduces training time and helps preserve pretrained feature representations.
+### Hyperparameters
 
----
+| Hyperparameter | Value |
+|---|---|
+| Optimizer | AdamW |
+| Learning rate | 3e-4 |
+| Weight decay | 1e-4 |
+| Loss | CrossEntropy with label smoothing = 0.1 |
+| LR scheduler | ReduceLROnPlateau (mode=min, factor=0.5, patience=2) |
+| Batch size | 32 |
+| Max epochs | 30 |
+| Early stopping | patience = 5 (on validation loss) |
+| Image size | 224 × 224 |
+| Seed | 42 |
 
-## Evaluation Metrics
+### Data augmentation (training)
 
-Each evaluation notebook provides:
+`RandomResizedCrop(224, scale=(0.8, 1.0))`, `RandomHorizontalFlip(p=0.5)`, `RandomRotation(10)`, `ColorJitter(brightness=0.2, contrast=0.2, saturation=0.1, hue=0.02)`, then `ToTensor` and ImageNet normalization. Validation/test images use `Resize(256)` → `CenterCrop(224)` → normalize.
 
-* Top-1 and Top-5 Accuracy
-* Precision, Recall, and F1 Score
-* Per-class performance analysis
-* Confusion matrices
-* Training and validation loss curves
-* Inference speed comparisons
-* Prediction visualizations
+The checkpoint corresponds to the epoch with the lowest validation loss.
 
----
+## Evaluation results
 
-## Key Observations
+Evaluated on the Stanford Cars test split (8,000 images, 195 classes).
 
-* EfficientNet-B0 v2 improves upon the baseline v1 configuration.
-* ConvNeXt-Tiny achieves strong performance while maintaining computational efficiency.
-* Transformer-based architectures provide competitive results and different representational advantages compared to CNNs.
-* Transfer learning significantly reduces training requirements while maintaining strong classification accuracy.
+| Metric | Value |
+|---|---:|
+| Test loss | 0.6942 |
+| **Top-1 accuracy** | **87.08%** |
+| Top-5 accuracy | 96.81% |
+| Macro Precision | 0.8765 |
+| Macro Recall | 0.8696 |
+| Macro F1 | 0.8697 |
+| Weighted F1 | 0.8705 |
+| Make accuracy | 93.03% |
+| Make + Model accuracy | 87.58% |
 
----
+### Comparison with other TwinCar models
 
-## Customization
+| Model | Top-1 | Top-5 | Weighted F1 | Make + Model Acc | Size |
+|---|---:|---:|---:|---:|---:|
+| EfficientNet-B0 v1 | 83.08% | 95.20% | 0.8308 | 83.45% | 17.33 MB |
+| EfficientNet-B0 v2 | 81.64% | 94.50% | 0.8184 | 82.19% | 17.33 MB |
+| **ConvNeXt-Tiny (this model)** | **87.08%** | **96.81%** | **0.8705** | **87.58%** | 111.95 MB |
 
-The project can be extended in several ways:
+ConvNeXt-Tiny is the strongest model for the core TwinCar goal — distinguishing visually similar makes/models (e.g. Audi S4 vs S5, BMW 3 Series vs M3) — thanks to a stronger backbone, at the cost of a larger model size. EfficientNet-B0 v1 remains a useful lightweight baseline (~6× smaller) when deployment size matters.
 
-* Integrate additional automotive datasets
-* Add new model architectures
-* Experiment with alternative hyperparameters
-* Explore multi-task learning objectives
-* Implement custom data augmentation pipelines
+## Limitations and bias
 
----
-
-## Future Work
-
-* Convert notebook workflows into modular Python packages
-* Implement model ensembling techniques
-* Add advanced augmentation methods such as MixUp and RandAugment
-* Explore knowledge distillation strategies
-* Optimize deployment using ONNX or TensorRT
-* Develop an inference API
-* Create a unified benchmark report across all experiments
-
----
+Results are measured on the Stanford Cars test split. Real-world images — e.g. from drones or ground robots, with varied angles, shadows, reflections, occlusion, or cluttered parking-lot backgrounds — will likely degrade accuracy. The reported numbers are benchmark performance on a curated dataset, **not** guaranteed production performance. The label space and any demographic/geographic biases are inherited from Stanford Cars (predominantly US-market vehicles up to ~2012).
 
 ## References
 
-* EfficientNet — *Scaling Convolutional Neural Networks Efficiently*
-* ConvNeXt — *A ConvNet for the 2020s*
-* Vision Transformer — *An Image is Worth 16×16 Words*
-* Swin Transformer — *Hierarchical Vision Transformer Using Shifted Windows*
-* DeiT — *Data-efficient Image Transformers*
-
----
-
-## Contributing
-
-Contributions, suggestions, and bug reports are welcome. Feel free to open an issue or submit a pull request.
-
----
+- ConvNeXt — *A ConvNet for the 2020s* (Liu et al., 2022)
+- Stanford Cars — *3D Object Representations for Fine-Grained Categorization* (Krause et al., 2013)
+- Project repository — [github.com/dragicakostoska/TwinCar](https://github.com/dragicakostoska/TwinCar)
 
 ## License
 
-This project is provided for educational and research purposes.
-
-
----
-
-**Last Updated:** June 2026
+Released under **CC BY-NC 4.0** for educational and research purposes. Note that use is also subject to the terms of the Stanford Cars dataset and the ImageNet-pretrained base weights.