Add megaloc README with benchmarks and usage

megaloc/README.md

@@ -0,0 +1,148 @@
+# 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}
+}
+```