# ZipDepth
ZipDepth is a compact reparameterizable CNN distilled from Depth Anything V2 Large that predicts a dense relative inverse-depth map. LibreYOLO supports it for the depth task: predict and zero-shot validation, with no training path.
Tasks: Depth. Install: pip install libreyolo.
Verified against LibreYOLO v1.5.0.

## Install

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

depth = result.depth_map
print(depth.min, depth.max, depth.mean)
```

**CLI**

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

**NPU/edge checkpoint**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

# Same encoder, an unfold-free upsampling head for compilers that lack
# gather/unfold support. Output is visually equivalent to the b checkpoint.
model = LibreYOLO("LibreZipDepthbnpu-depth.pt")
result = model(SAMPLE_IMAGE, save=True)
```

`result.depth_map` carries a dense relative inverse-depth map: higher
values mean closer to the camera, and the values have no metric unit or
cross-image scale. `save=True` writes a colormapped visualization of that map
to disk; `Results.plot()` renders the depth map as a PIL image, and `pil=False`
returns the array instead. See [prediction](/docs/predict) for sources,
streaming and result handling.

## Variants

Two checkpoints, both the same encoder capacity, differing only in the trained
upsampling head. `b` uses convex upsampling and runs on GPU or CPU. `bnpu`
swaps in an unfold-free decoder for NPU and edge compilers that lack
gather/unfold support; its output is documented as visually equivalent to `b`.
Pick `bnpu` when the export target is a constrained runtime, `b` otherwise.

Both checkpoints were distilled from Depth Anything V2 Large pseudo-labels, so
this family is the compact, edge-oriented tier of LibreYOLO's depth task,
alongside the larger Depth Anything V2 encoders.

Training is not offered for this family. `LibreZipDepth.train()` raises
`NotImplementedError` unconditionally: the upstream recipe distills pseudo-labels
over a large image set that is not reproducible as a LibreYOLO training run.
Train upstream at [fabiotosi92/ZipDepth](https://github.com/fabiotosi92/ZipDepth)
and convert the result with `weights/convert_zipdepth_weights.py`.

## Validate

`val()` runs the shared depth validator: it aligns each prediction to its
ground truth with a per-image least-squares scale and shift, then reports the
standard zero-shot relative-depth metrics, AbsRel, RMSE and the three delta
thresholds.

**Python**

```python
from libreyolo import LibreYOLO

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

print(metrics["metrics/abs_rel"])
print(metrics["metrics/rmse"])
print(metrics["metrics/delta1"])
```

**CLI**

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

## Export

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

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

Export follows a fixed-resolution dense contract: the source image is
stretch-resized to the exported canvas, and the returned depth map is resized
back to the original canvas afterward. An exported artifact loads back through
`LibreYOLO()` on its file suffix, so a `.onnx` or `.ncnn` file behaves like a
checkpoint and returns the same `Results`, with `depth_map` in place of boxes.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreZipDepthb-depth.pt")
model.export(format="onnx")
model.export(format="ncnn")
```

**CLI**

```bash
libreyolo export model=LibreZipDepthb-depth.pt format=onnx
libreyolo export model=LibreZipDepthbnpu-depth.pt format=ncnn
```

**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("LibreZipDepthb-depth.onnx")
result = model(SAMPLE_IMAGE)

print(result.depth_map.data.shape)
```

## Checkpoints

Every published weight file for this family.

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibreZipDepthb-depth.pt` |  | Depth | mit |
| `LibreZipDepthbnpu-depth.pt` |  | Depth | mit |

## 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: ZipDepth, University of Bologna
- Upstream license: MIT
- Upstream source: https://github.com/fabiotosi92/ZipDepth
- LibreYOLO code: MIT
- Weights: MIT, republished at https://huggingface.co/LibreYOLO
- Interpretation: MIT is a permissive license, so both checkpoints can be used in commercial and closed-source products with no redistribution restriction beyond keeping the license notice. It places no obligation on your own application code. The weights were trained by distilling pseudo-labels from Depth Anything V2 Large, whose Large checkpoint is itself CC-BY-NC-4.0; the ZipDepth authors publish the distilled student under MIT regardless, and LibreYOLO republishes that same MIT-licensed student.

## Citation

```bibtex
@inproceedings{tosi2026zipdepth,
  title     = {ZipDepth: Bringing Lightweight Zero-Shot Monocular Depth Anywhere, on Any Device},
  author    = {Tosi, Fabio and Bartolomei, Luca and Poggi, Matteo and Mattoccia, Stefano},
  booktitle = {European Conference on Computer Vision (ECCV)},
  year      = {2026}
}
```

Copied from https://github.com/fabiotosi92/ZipDepth#-citation


## ZipDepth architecture

- b: [SVG](/diagrams/models/zipdepth/b-depth.svg), [interactive diagram](/diagrams/models/zipdepth/b-depth.html)
- bnpu: [SVG](/diagrams/models/zipdepth/bnpu-depth.svg), [interactive diagram](/diagrams/models/zipdepth/bnpu-depth.html)
- Shared base withbothhead alternatives: [SVG](/diagrams/models/zipdepth/family.svg), [interactive diagram](/diagrams/models/zipdepth/family.html)