# VGG
VGG is a convolutional image classifier built from uniform stacks of small 3x3 convolutions instead of larger filters. LibreYOLO ships the 16- and 19-layer sizes, plain and with batch normalization, for image classification.
Tasks: Classification. Install: pip install libreyolo.
Verified against LibreYOLO v1.6.0.

## Install

VGG needs no optional extra. Everything it imports is in the base install.

```bash
pip install libreyolo
```

## Predict

Weights download from Hugging Face on first use and are cached locally.

**Python**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreVGG16-cls.pt")
result = model(SAMPLE_IMAGE, save=True)

probs = result.probs
print(probs.top1, probs.top1conf)
print(probs.top5, probs.top5conf)
```

**CLI**

```bash
libreyolo predict model=LibreVGG16-cls.pt source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg save=True
```

A classifier returns `result.probs` instead of `result.boxes`: `top1`
and `top5` give class indices, `top1conf` and `top5conf` give their
confidences. Prediction runs at a fixed 224px input and raises if you pass a
different `imgsz`. See [prediction](/docs/predict) for sources, streaming and
result handling.

## Variants

Four sizes: 16 and 19 convolutional layers, each with a plain and a
batch-normalized variant. The shipped weights are torchvision's later
from-scratch ImageNet training, not conversions of the Oxford group's original
2014 Caffe release. LibreYOLO ships this family inference-only: prediction,
ImageNet-style top-1/top-5 validation and export are supported, and
fine-tuning is not implemented.

## Validate

`val()` runs against an ImageFolder-style split (a directory with `train/` and
`val/` subfolders, one folder per class) and returns top-1 and top-5 accuracy.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreVGG16-cls.pt")

# data is a directory root with train/ and val/ class-folder splits
# (ImageFolder layout), not a dataset YAML.
metrics = model.val(data="imagenet-1k/")

print(metrics["metrics/accuracy_top1"])
print(metrics["metrics/accuracy_top5"])
```

**CLI**

```bash
libreyolo val model=LibreVGG16-cls.pt data=imagenet-1k/
```

Validation and INT8 calibration use the family evaluation transform. Export metadata records `norm_mean`, `norm_std` and `resize_mode`; older artifacts fall back to family values. Calibration preprocessors return the required CHW array and ratio.

## Export

| Task | ONNX | TorchScript | ExecuTorch | TensorRT | OpenVINO | Paddle | MNN | RKNN | ncnn | TFLite | CoreML | Core AI |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Classification | yes | yes | yes | yes | yes |  |  |  | yes |  |  |  |

A "yes" means the export is supported. An empty cell means the exporter refuses that combination.

An exported artifact loads back through `LibreYOLO()` on its file suffix, so a
`.onnx` or `.engine` file behaves like a checkpoint and returns the same
`Results`. [Export](/docs/export) lists the arguments every format accepts and
the extras a few of them add.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreVGG16-cls.pt")
model.export(format="onnx")
model.export(format="tensorrt", half=True)
```

**CLI**

```bash
libreyolo export model=LibreVGG16-cls.pt format=onnx
libreyolo export model=LibreVGG16-cls.pt format=tensorrt half=True
```

**Use the exported file**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

# The factory routes on the file suffix, so an exported artifact loads
# like any checkpoint and returns the same Results object.
model = LibreYOLO("LibreVGG16-cls.onnx")
result = model(SAMPLE_IMAGE)

print(result.probs.top1)
```

## Checkpoints

Every published weight file for this family.

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibreVGG16-cls.pt` | 224 | Classification | bsd-3-clause |
| `LibreVGG19bn-cls.pt` | 224 | Classification | bsd-3-clause |
| `LibreVGG19-cls.pt` | 224 | Classification | bsd-3-clause |
| `LibreVGG16bn-cls.pt` | 224 | Classification | bsd-3-clause |

## Licensing

Check the license on the Hugging Face repository of the specific weights you download. That repository is authoritative and licenses are not always uniform across a family. This is a description of the licenses involved, not legal advice.

- Original work: VGG, Visual Geometry Group, University of Oxford
- Upstream license: BSD-3-Clause
- Upstream source: https://github.com/pytorch/vision
- LibreYOLO code: BSD-3-Clause
- Weights: BSD-3-Clause, republished at https://huggingface.co/LibreYOLO
- Interpretation: BSD-3-Clause is a permissive license, so these weights can be used in commercial and closed-source products. It asks you to keep the copyright notice, the list of conditions and the disclaimer with any copy you redistribute, and it forbids using the contributors' names to endorse a derived product without permission; it carries no explicit patent grant. LibreYOLO's code and the four shipped checkpoints (16, 19, 16-BN, 19-BN) are both derived from torchvision, not from the Oxford group's original 2014 Caffe release, which is a separate model under Creative Commons Attribution and is not what LibreYOLO redistributes. Torchvision itself notes that BSD-3-Clause redistribution of a pretrained checkpoint is an implied basis rather than a grant written for that specific checkpoint, and that pretrained-model terms can depend on the data a model was trained on; LibreYOLO repeats that caveat on each hosted weights repository.


## VGG architecture

- VGG-16: [SVG](/diagrams/models/vgg/16-classify.svg), [interactive diagram](/diagrams/models/vgg/16-classify.html)
- VGG-19: [SVG](/diagrams/models/vgg/19-classify.svg), [interactive diagram](/diagrams/models/vgg/19-classify.html)
- VGG-16bn: [SVG](/diagrams/models/vgg/16bn-classify.svg), [interactive diagram](/diagrams/models/vgg/16bn-classify.html)
- VGG-19bn: [SVG](/diagrams/models/vgg/19bn-classify.svg), [interactive diagram](/diagrams/models/vgg/19bn-classify.html)
- VGG family: [SVG](/diagrams/models/vgg/family-plain.svg), [interactive diagram](/diagrams/models/vgg/family-plain.html)
- VGG family with BatchNorm: [SVG](/diagrams/models/vgg/family-bn.svg), [interactive diagram](/diagrams/models/vgg/family-bn.html)