aircraft-clf

Fine-grained aircraft classification using transfer learning on the FGVC Aircraft 2013b dataset.

---

Dataset

FGVC Aircraft 2013b — 10,000 images of aircraft across 100 variants, grouped into 70 families and 30 manufacturers.

Target	Classes	Example
manufacturer	30	Boeing, Airbus, Cessna
family	70	Boeing 737, Airbus A320
variant	100	Boeing 737-800, Airbus A320-200

The dataset is downloaded automatically on first training run (~500 MB).

---

Approach

Five models trained under the same interface:

Key	Architecture	Strategy	Input size
tf_imagenet	Xception	Transfer learning — ImageNet backbone, frozen, custom head	224 × 224
tf_efficientnet	EfficientNetV2-B0	Transfer learning — ImageNet backbone, frozen, custom head	224 × 224
tf_resnet	ResNet50V2	Transfer learning — ImageNet backbone, frozen, custom head	224 × 224
tf_cnn	Custom 4-layer CNN	Trained from scratch	96 × 96
svm_hog	SVM on HOG features	Classical ML baseline	224 × 224

Transfer learning models use ImageNet-pretrained backbones as frozen feature extractors with a trainable classification head (GlobalAveragePooling → Dropout → Dense). Partial fine-tuning is supported via fine_tune_at.

tf_cnn uses a smaller input (96 × 96) so that its intermediate feature maps fit in GPU memory — 224 × 224 would produce a ~1.78 GiB activation tensor that exceeds cuDNN's autotuning budget on typical consumer GPUs. 96 × 96 is sufficient for a from-scratch CNN. To train at a larger resolution, change preferred_image_size in tf_cnn.py and use --device cpu.

---

GPU / TPU

GPU is detected and configured automatically. All TensorFlow models enable memory growth on startup so they don't claim the full VRAM.

Mixed precision (FP16 compute, FP32 accumulation) is supported on the three transfer learning models (tf_imagenet, tf_efficientnet, tf_resnet) and roughly halves memory usage on RTX / A100 GPUs:

from aircraft_clf.models.tf_imagenet import TFImaNetClassifier

model = TFImaNetClassifier(policy="mixed_float16")
model.build(input_shape=(224, 224, 3), num_classes=30)

Multi-GPU / TPU — wrap training inside a tf.distribute strategy before calling model.build():

import tensorflow as tf

strategy = tf.distribute.MirroredStrategy()          # multi-GPU
# strategy = tf.distribute.TPUStrategy(tpu)          # TPU (Google Cloud / Colab)

with strategy.scope():
    model = TFImaNetClassifier()
    model.build(input_shape=(224, 224, 3), num_classes=30)

All Keras model construction and compilation happens inside build(), which makes it a clean drop-in for any tf.distribute strategy.

---

Setup

Requires uv.

git clone https://github.com/Djima/aircraft-clf
cd aircraft-clf
uv sync

---

Usage

Train

# Train Xception on manufacturer classification, 15 epochs (CPU, default)
uv run aircraft-train --models tf_imagenet --target manufacturer --epochs 15 --device cpu

# Same run on GPU
uv run aircraft-train --models tf_imagenet --target manufacturer --epochs 15 --device gpu

# GPU with reduced batch size for low VRAM (e.g. < 4 GB)
uv run aircraft-train --models tf_imagenet --target manufacturer --epochs 15 --device gpu --batch-size 8

# Train all models
uv run aircraft-train --models all --target manufacturer

# List available models
uv run aircraft-train --list

Quick smoke-test (1 epoch per model)

CPU — all models:

uv run aircraft-train --models svm_hog       --target manufacturer --epochs 1 --device cpu
uv run aircraft-train --models tf_cnn        --target manufacturer --epochs 1 --device cpu
uv run aircraft-train --models tf_efficientnet --target manufacturer --epochs 1 --device cpu
uv run aircraft-train --models tf_resnet     --target manufacturer --epochs 1 --device cpu
uv run aircraft-train --models tf_imagenet   --target manufacturer --epochs 1 --device cpu

GPU — transfer learning models (tf_cnn and svm_hog stay on CPU):

uv run aircraft-train --models tf_efficientnet --target manufacturer --epochs 1 --device gpu
uv run aircraft-train --models tf_resnet     --target manufacturer --epochs 1 --device gpu
uv run aircraft-train --models tf_imagenet   --target manufacturer --epochs 1 --device gpu
uv run aircraft-train --models tf_cnn        --target manufacturer --epochs 1 --device cpu
uv run aircraft-train --models svm_hog       --target manufacturer --epochs 1

Override image size or any config value via environment variables (transfer learning models only — tf_cnn uses its own fixed preferred_image_size):

AIRCRAFT_IMAGE_WIDTH=299 AIRCRAFT_IMAGE_HEIGHT=299 uv run aircraft-train --models tf_imagenet

Predict

# Single image, top-5 predictions
uv run aircraft-predict path/to/plane.jpg

# Batch inference with a different model and target
uv run aircraft-predict img1.jpg img2.jpg --model tf_efficientnet --target family --top-k 3

Gradio UI

uv run aircraft-gradio

Upload an aircraft image, pick a model and target, and get ranked predictions with confidence scores.

---

Project structure

aircraft_clf/
├── cli/
│   ├── train.py           # aircraft-train entry point
│   └── predict.py         # aircraft-predict entry point
├── data/
│   ├── download.py        # dataset download & extraction
│   └── preprocessing.py   # image loading, resizing, label encoding
├── models/
│   ├── base.py            # BaseClassifier ABC
│   ├── registry.py        # model registry
│   ├── predictor.py       # predict_topk
│   ├── svm_hog.py
│   ├── tf_cnn.py
│   ├── tf_imagenet.py     # Xception
│   ├── tf_efficientnet.py
│   └── tf_resnet.py
├── config.py              # pydantic-settings config (YAML + env vars)
├── config.yaml
└── gradio_app.py          # Gradio web UI

---

Reference

S. Maji, J. Kannala, E. Rahtu, M. Blaschko, A. Vedaldi. Fine-Grained Visual Classification of Aircraft. arXiv, 2013.