Thanks for considering a contribution. Keep PRs focused and small.
CMake presets (defined in CMakePresets.json) configure the standard workflow:
cmake --preset debug # or: release, asan, ubsan
cmake --build --preset debug
ctest --preset debugdebug/release: standard configurations. Both enableDINOV2_FATAL_WARNINGSby default, so warnings are errors.asan/ubsan: AddressSanitizer and UndefinedBehaviorSanitizer builds for debugging memory and UB issues.
Build directories are build-<preset>/.
Unit tests use doctest. Run the suite with:
cmake --build --preset debug && ctest --preset debugRun the same suite under the asan and ubsan presets before submitting anything that touches memory handling or the compute path.
scripts/parity_check.py compares dinov2-cli embeddings and top-1 classification against the HuggingFace PyTorch reference and reports cosine similarity per image:
.venv/bin/python scripts/parity_check.py --gguf models/model.ggufIt needs the .venv deps (torch, transformers, pillow) and a downloaded GGUF.
Default gates are cls/pooled cosine >= 0.999 and patch flat + per-token-mean cosine >= 0.99; the per-token minimum is reported as informational because f16 inference diverges from the f32 reference on a small token tail. Pass --patches-token-min-threshold <float> for a strict per-token check.
CI enforces clang-format-18. Before committing:
clang-format-18 -i <changed files>Format violations fail the lint job.
DINOV2_FATAL_WARNINGS=ON (the preset default) promotes warnings to errors. Keep the build clean under this option; do not disable it to mask warnings.
- One logical change per PR. Keep refactors separate from features.
- Ensure the full test suite passes under
debug,asanandubsan. - Update docs (
README.md,docs/) if you change behavior or interfaces. - Follow conventional commit format (e.g.
feat:,fix:,docs:,ci:).
The README's ready-to-download GGUFs live at dinov2-cpp-core/<variant>-gguf on Hugging Face. To convert a variant yourself from the upstream PyTorch checkpoints:
| Model | Source checkpoint (PyTorch) | Recommendation |
|---|---|---|
| small (no registers) | facebook/dinov2-small-imagenet1k-1-layer | Baseline reproduction or task comparison |
| base (no registers) | facebook/dinov2-base-imagenet1k-1-layer | Baseline reproduction or task comparison |
| large (no registers) | facebook/dinov2-large-imagenet1k-1-layer | Baseline reproduction or task comparison |
| giant (no registers) | facebook/dinov2-giant-imagenet1k-1-layer | Baseline reproduction or task comparison |
| small (registers) | facebook/dinov2-with-registers-small-imagenet1k-1-layer | Recommended for patch/dense features |
| base (registers) | facebook/dinov2-with-registers-base-imagenet1k-1-layer | Recommended for patch/dense features |
| large (registers) | facebook/dinov2-with-registers-large-imagenet1k-1-layer | Recommended for patch/dense features |
| giant (registers) | facebook/dinov2-with-registers-giant-imagenet1k-1-layer | Recommended for patch/dense features |
The converter also accepts the backbone-only names facebook/dinov2-{small,base,large,giant} and facebook/dinov2-with-registers-{small,base,large,giant}. These produce feature-only GGUFs and do not invent ImageNet classifier heads or labels.
For the bounded rationale, see Vision Transformers Need Registers and the official DINOv2 results. Register-token checkpoints are recommended for patch and dense feature workflows, while no-register checkpoints remain useful for exact baseline reproduction and task-specific comparisons.
python ./scripts/dinov2-to-gguf.py --model_name facebook/dinov2-small-imagenet1k-1-layerSee docs/hf-publishing.md for how CI publishes the mirrors (HF_TOKEN setup included).
git clone --recurse-submodules https://github.com/espetro/dinov2.cpp.git
cd dinov2.cpp
cmake --preset release && cmake --build --preset releasePer-device optimizations (AMD hosts, OpenMP), sanitizer presets and benchmark instructions: docs/build.md.
CHANGELOG.md is auto-generated by git-cliff from
the git history at every v* tag push (see
.github/workflows/changelog.yml and
cliff.toml). This project uses
conventional commits:
feat(<scope>): <subject>
fix(<scope>): <subject>
refactor: <subject>
bench: <subject>
ci: <subject>
docs: <subject>
chore: <subject>
test: <subject>
Rules:
- Subject lines stay plain. No em-dashes. They print directly into the
changelog under
### Changed/### Added/### Fixed. AI-style flourish prose causes clutter in the finalCHANGELOG.md. - One logical change per commit. Each commit maps to one bullet in
the next release's
[Unreleased]section; multi-concern commits read as a wall of text. - Scope is encouraged, not required. The scope in parens surfaces
as
*(scope)*before the subject, which makes dense releases skimmable. Use the area affected:quantize,cli,bench,plan,release,dinov2, etc. chore(deps):andchore(release):are auto-skipped by cliff.toml. Use those prefixes for bumps that don't need changelog coverage.- Breaking changes: add an exclamation after the typeword
(
feat!:/refactor!:) or includeBREAKING CHANGE:in the body footer.git-cliffreads the!flag and prefixes the bullet with[**breaking**]in the changelog. - Local regen:
git-cliff --config cliff.toml --unreleased --tag vNEXT --next-tag vNEXTprints the next release section. Useful when drafting release notes for a tag in flight.
Hand-editing CHANGELOG.md: edit only the lines above
<!-- git-cliff: end of header -->. Everything below that marker is
regenerated on every v* push and any manual entry there is overwritten.
The footer's release-comparison link table is also a manual section,
marked by <!-- git-cliff: end of body -->; add a new row when a new tag
ships.