Delete megaloc/README.md with huggingface_hub

megaloc/README.md

@@ -1,148 +0,0 @@
-# MegaLoc Quantized Models
-
-Quantized ONNX and CoreML models for [MegaLoc](https://arxiv.org/abs/2502.17237) — a state-of-the-art visual place recognition model based on DINOv2 ViT-B/14.
-
-All benchmarks below were run on a MacBook Pro with Apple Silicon (M-series), 518×518 input, single-threaded CPU for ONNX Runtime, GPU for CoreML.
-
-## Available Models
-
-| File | Format | Size | Ratio | CosSim | Latency | FPS | Notes |
-|------|--------|------|-------|--------|---------|-----|-------|
-| `megaloc.onnx` | ONNX FP32 | 873 MB | 1.0× | 1.000000 | 387 ms | 2.6 | Baseline, float32 reference |
-| `megaloc_fp16.onnx` | ONNX FP16 | 437 MB | 2.0× | 0.999988 | 394 ms | 2.5 | Near-lossless, recommended for ONNX |
-| `megaloc_int8.onnx` | ONNX INT8 | 223 MB | 3.9× | 0.996453 | 475 ms | 2.1 | Weight-only quantization, Recall@1 still 100% |
-| `megaloc_coreml_fp32.mlpackage` | CoreML FP32 | 873 MB | 1.0× | 1.000000 | 78 ms | 12.8 | CoreML baseline, 5× faster than ONNX |
-| `megaloc_coreml_int8.mlpackage` | CoreML INT8 | 219 MB | 4.0× | 0.998315 | 78 ms | 12.9 | **Recommended** — best size/speed/accuracy trade-off |
-
-## Benchmark Summary
-
-```
-Model                      Size       Ratio   CosSim      Latency   FPS
-─────────────────────────────────────────────────────────────────────────
-ONNX FP32                 872.9 MB    1.0×    1.000000    387 ms    2.6
-ONNX FP16                 436.8 MB    2.0×    0.999988    394 ms    2.5
-ONNX INT8                 222.5 MB    3.9×    0.996453    475 ms    2.1
-CoreML FP32               872.8 MB    1.0×    1.000000     78 ms   12.8
-CoreML INT8               218.8 MB    4.0×    0.998315     78 ms   12.9
-```
-
-### Retrieval Accuracy
-
-| Model | Recall@1 | Recall@3 | Recall@5 | Kendall Tau |
-|-------|----------|----------|----------|-------------|
-| ONNX FP16 | 100% | 100% | 100% | 0.94 |
-| ONNX INT8 | 100% | 100% | 100% | 0.58 |
-
-Despite a drop in descriptor-level cosine similarity, INT8 models preserve top-K retrieval perfectly. The full ranking order (Kendall Tau) shows some reshuffling, but the most relevant results remain correct.
-
-### Why CoreML is faster than ONNX Runtime?
-
-- ONNX Runtime uses CPU execution by default on macOS, while **CoreML leverages Apple Silicon GPU** via Metal Performance Shaders
-- ONNX INT8 is slower (475 ms vs 387 ms) because the weight-only quantization inserts `DequantizeLinear` nodes — each MatMul first converts INT8 back to float32, adding overhead without the speed benefit of integer math
-- CoreML INT8 runs at the same speed as FP32 (78 ms) because the GPU's integer compute units are used natively
-
-### On sub-8-bit quantization
-
-We experimented with 4-bit and 1-bit quantization (ONNX INT4, CoreML 4-bit/2-bit K-Means palettization). **All failed** with cosine similarity ≈ 0. The DINOv2 ViT backbone has 12 transformer blocks + aggregator (~200 weight tensors). Quantization error from only 16 levels accumulates catastrophically across 48+ MatMul layers. This is a known limitation — ViT architectures below 8-bit require **quantization-aware training (QAT)** to preserve accuracy.
-
-## Usage
-
-### ONNX Inference
-
-```bash
-pip install onnxruntime pillow numpy
-
-python3 -c "
-import onnxruntime as ort, numpy as np
-from PIL import Image
-
-# Choose from the table above
-session = ort.InferenceSession('megaloc_fp16.onnx', providers=['CPUExecutionProvider'])
-
-# Preprocess: resize to 518×518, normalize to [0, 1]
-img = Image.open('image.jpg').convert('RGB').resize((518, 518), Image.LANCZOS)
-data = np.array(img).astype(np.float32) / 255.0
-data = np.expand_dims(data.transpose(2, 0, 1), axis=0)  # [1, 3, 518, 518]
-
-# Inference → L2-normalized descriptor [1, 8448]
-descriptor = session.run(None, {'images': data})[0]
-
-# Compare two images via cosine similarity
-cos_sim = np.dot(desc1, desc2.T)  # both already L2-normalized
-"
-```
-
-### CoreML Inference (macOS only)
-
-```bash
-pip install coremltools pillow numpy
-
-python3 -c "
-import coremltools as ct, numpy as np
-from PIL import Image
-
-model = ct.models.MLModel('megaloc_coreml_int8.mlpackage')
-
-# Preprocess
-img = Image.open('image.jpg').convert('RGB').resize((518, 518), Image.LANCZOS)
-data = np.array(img).astype(np.float32) / 255.0
-data = np.expand_dims(data.transpose(2, 0, 1), axis=0)
-
-# Inference
-descriptor = list(model.predict({'images': data}).values())[0]  # [1, 8448]
-"
-```
-
-### Torch Hub (original float32)
-
-```python
-import torch
-model = torch.hub.load("gmberton/MegaLoc", "get_trained_model")
-model.eval()
-with torch.no_grad():
-    descriptor = model(image_tensor)  # [B, 3, 518, 518] → [B, 8448]
-```
-
-## Quantization Details
-
-### ONNX Models
-
-- **FP16**: Converted via `onnxconverter_common.float16.convert_float_to_float16()` with `keep_io_types=True` (input/output remain float32).
-- **INT8**: Per-channel symmetric weight quantization. Each weight tensor is independently quantized: `q = clamp(round(W / scale), -128, 127)` with `scale = max(|W|) / 127` per output channel. Weights stored as INT8 with `DequantizeLinear` nodes inserted in the graph.
-
-### CoreML Models
-
-- **FP32/INT8**: Converted from PyTorch via `torch.export` + `coremltools.convert()` at macOS 15 deployment target.
-- **INT8**: Applied `linear_quantize_weights()` with symmetric per-channel INT8 linear quantization. No calibration data needed for weight-only quantization.
-- CoreML handles integer compute scheduling automatically — INT8 weights are dequantized on-the-fly inside GPU compute units with no extra latency.
-
-## Reproducing
-
-```bash
-# Clone and install dependencies
-git clone https://github.com/gmberton/MegaLoc
-cd MegaLoc
-pip install uv && uv sync
-
-# ONNX INT8 quantization
-uv run python quantize_megaloc.py --method 8bit --input megaloc.onnx
-
-# PyTorch → CoreML conversion + compression
-uv run python convert_coreml.py
-
-# Benchmark accuracy & speed (requires calibration images)
-uv run python benchmark_quantized.py --data-dir /path/to/images --runs 30
-```
-
-## Reference
-
-```bibtex
-@inproceedings{Berton_2025_MegaLoc,
-    author    = {Berton, Gabriele and Masone, Carlo},
-    title     = {MegaLoc: One Retrieval to Place Them All},
-    booktitle = {IEEE/CVF Conference on Computer Vision and Pattern Recognition Workshops},
-    month     = {June},
-    year      = {2025},
-    pages     = {2886--2892}
-}
-```