---
license: cc-by-nc-4.0
library_name: pytorch
pipeline_tag: image-classification
tags:
  - image-classification
  - convnext
  - vehicles
  - cars
  - stanford-cars
  - fine-grained-classification
  - pytorch
  - transfer-learning
datasets:
  - naufalso/stanford_cars
metrics:
  - accuracy
  - 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}")
```

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).

## Intended use

**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.

**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 data

- **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`.

## Training procedure

Fine-tuned end-to-end from ImageNet-pretrained weights with mixed-precision (AMP) on a CUDA GPU.

### 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 |

### Data augmentation (training)

`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.

The checkpoint corresponds to the epoch with the lowest validation loss.

## Evaluation results

Evaluated on the Stanford Cars test split (8,000 images, 195 classes).

| 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

| 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 |

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.

## Limitations and bias

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

- 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

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.