# SSD
SSD (Single Shot MultiBox Detector) predicts every box and class score from a dense grid of default boxes in one forward pass, with no separate region-proposal stage. LibreYOLO ships the VGG16-backed SSD300 checkpoint as an inference-only detector.
Tasks: Detection. Install: pip install libreyolo.
Verified against LibreYOLO v1.5.0.

## Install

SSD 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("LibreSSD300.pt")
result = model(SAMPLE_IMAGE, save=True)

for box in result.boxes:
    print(box.cls, box.conf, box.xyxy)
```

**CLI**

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

The returned `Results` object is the one every family returns, so swapping in a
different detector is a one line change. SSD decodes its default-box grid with
per-class scores and then runs non-maximum suppression, so `conf`, `iou` and
`max_det` all have a real effect here, unlike the query-based detectors in this
library. See [prediction](/docs/predict) for sources, streaming and result
handling.

## Variants

SSD ships one checkpoint: the VGG16-backed SSD300 network at its fixed native
canvas. There is no size or scale choice in this family; predict, validate and
export all use that one graph.

The weight file is `LibreSSD300.pt`, the family prefix followed by its only size
key, `"300"`. The class behind it is `LibreSSD`, so a direct construction is
`LibreSSD(size="300")` rather than a class named after the file.

## Validate

`val()` returns a dictionary of `metrics/` keys covering precision, recall,
mAP 50 and mAP 50-95, measured against any dataset in the format you trained on.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreSSD300.pt")
metrics = model.val(data="my-dataset.yaml")

print(metrics["metrics/mAP50-95"])
print(metrics["metrics/mAP50"])
```

**CLI**

```bash
libreyolo val model=LibreSSD300.pt data=my-dataset.yaml
```

## Export

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

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

SSD exports to ONNX only; every other format is currently blocked for this
family. Export always uses the checkpoint's native canvas, and the graph
exposes SSD's raw packed head rather than a fused non-maximum-suppression
output, so `nms=True` is not accepted at export time. LibreYOLO's own backends
run the decode and suppression step after loading the graph back.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreSSD300.pt")

# imgsz is left out here on purpose: SSD300 traces at its checkpoint's
# native canvas, and any other value raises before export starts.
model.export(format="onnx")
```

**CLI**

```bash
libreyolo export model=LibreSSD300.pt format=onnx
```

**Use the exported file**

```python
from libreyolo import LibreYOLO

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

print(result.boxes.xyxy)
```

## Checkpoints

Every published weight file for this family.

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibreSSD300.pt` | 300 | Detection | 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: SSD, UNC Chapel Hill, Zoox, Google and University of Michigan
- 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 its copyright notice and disclaimer with any copy you redistribute, and it places no obligation on your own application code. The official SSD300 COCO checkpoint carries no separate, checkpoint-specific license: LibreYOLO's mirror applies BSD-3-Clause on an explicitly disclosed implied basis, the same basis torchvision states for its own pretrained SSD300 weights. The VGG16 backbone the graph is built on traces back to Oxford's fully convolutional reduced VGGNet, released under CC BY 4.0 by Karen Simonyan and Andrew Zisserman.

LibreYOLO's SSD300 code is not ported from the paper authors' own Caffe
release; it derives from torchvision's BSD-3-Clause SSD300 implementation, and
that is the repository linked above as the upstream source. The backbone's
VGG16 weights trace further back to Oxford's fully convolutional reduced
VGGNet, released under CC BY 4.0 by Karen Simonyan and Andrew Zisserman.

## Citation

```bibtex
@inproceedings{liu2016ssd,
  title = {{SSD}: Single Shot MultiBox Detector},
  author = {Liu, Wei and Anguelov, Dragomir and Erhan, Dumitru and Szegedy, Christian and Reed, Scott and Fu, Cheng-Yang and Berg, Alexander C.},
  booktitle = {ECCV},
  year = {2016}
}
```

Copied from https://github.com/weiliu89/caffe/tree/ssd#citing-ssd


## SSD300 architecture

- SSD300 VGG16: [SVG](/diagrams/models/ssd/300.svg), [interactive diagram](/diagrams/models/ssd/300.html)