CosPlace: Group-Based Training for Visual Geo-localization and Its 1 TB Dataset Problem

The Retrieval Problem CosPlace Reframes as Classification

Visual geo-localization asks a system to determine where a photograph was taken by matching it against a database of geo-tagged reference images. The conventional formulation treats this as a ranking problem: train an embedding so that a query image lands closer to its true location than to any other. CosPlace takes a different route. Instead of optimizing pairwise distances, it partitions the training data into disjoint geographic clusters called CosPlace Groups and trains the network to predict which group a given image belongs to. Each group becomes a class label.

The intended users are researchers and engineers building image-retrieval systems who care about descriptor size. The README describes the method as reaching state-of-the-art results with compact descriptors, and the trained model table spans descriptor dimensions from 32 to 2048 across ResNet-18, ResNet-50, and ResNet-101 backbones. A 32-dimensional descriptor is small enough to make large-scale nearest-neighbour search tractable, which is the practical constraint the paper addresses. If your deployment budget for per-image storage or index memory is measured in tens of bytes rather than thousands, the descriptor dimension column in that table is the number that matters.

How CosPlace Groups Turn Geography into Class Labels

The mechanism is visible in the training entry point. Running train.py against the SF-XL raw training database triggers an automatic split of the dataset into CosPlace Groups, and the resulting object is cached in a folder named cache. The README's own visualization shows how these groups are formed over a map. The practical consequence is that the first training run pays a preprocessing cost that later runs skip, because the group assignment is persisted to disk rather than recomputed.

This design converts a metric-learning objective into a standard classification objective. The network outputs a distribution over groups, and the loss is computed against the group index rather than against a distance margin. The advantage claimed by the paper is scalability: classification over a fixed set of classes does not require mining hard negative pairs from a database that grows with the training set, which is what makes pairwise-ranking methods expensive at SF-XL scale. The trade-off is that the group partition is a fixed artifact. Its granularity determines what the model can discriminate. A group that is too coarse will teach the network to confuse distinct nearby locations; a group that is too fine produces classes with very few examples. The paper's contribution is largely about how to choose that partition, and the README does not expose a knob for adjusting it beyond the automatic split.

Getting a Trained Model Without Cloning the Repository

The fastest path into CosPlace is PyTorch Hub, and the README gives the exact call:

import torch model = torch.hub.load("gmberton/cosplace", "get_trained_model", backbone="ResNet50", fc_output_dim=2048)

This is the part of the project with the lowest adoption cost. You do not need the dataset, you do not need to run train.py, and you do not need the repository on disk. The two arguments that matter are backbone and fc_output_dim, and they must correspond to a checkpoint that actually exists. The README's model table shows that ResNet-18 has no published checkpoint at 1024 or 2048 dimensions, while ResNet-50 and ResNet-101 cover the full range from 32 to 2048. Requesting a combination that was never released is the most likely way to get a failure here.

If you prefer to manage weights yourself, the table links to Google Drive downloads for each backbone and dimensionality pair. Training from scratch is a different proposition. The README's example command is:

python3 train.py --train_set_folder path/to/sf_xl/raw/train/database --val_set_folder path/to/sf_xl/processed/val --test_set_folder path/to/sf_xl/processed/test

Defaults are ResNet-18 with 512-dimensional descriptors, which the README states fits in less than 4 GB of VRAM. Two flags change that: --backbone ResNet50 and --fc_output_dim 128. A third, --use_amp16, enables automatic mixed precision for faster training, with the explicit caveat that none of the paper's results or statistics used AMP. If you are trying to reproduce a published number, that caveat matters.

The SF-XL Dataset Is the Real Barrier to Entry

The README states that SF-XL is about 1 TB. Training uses only a subset, which is 360 GB. There is also a 5 GB small version, and the README is direct about its purpose: it will lead to lower results and should be used only for debugging or exploration. The dataset is not on a package index or a public HTTP endpoint. It is behind a Google Form linked from the README, which means access depends on filling in that form and receiving a download path.

That single fact determines who can realistically use CosPlace for training. If you have a workstation with a large NVMe array and the bandwidth to pull 360 GB, the pipeline is straightforward. If you are on Colab, the README acknowledges the constraint by pointing you at the 5 GB version, which is explicitly not for producing competitive results. There is no middle path documented between 360 GB and 5 GB.

The evaluation side is far cheaper. eval.py takes a backbone, a descriptor dimension, and a checkpoint path:

python3 eval.py --backbone ResNet50 --fc_output_dim 128 --resume_model path/to/best_model.pth

For inspecting behaviour, --num_preds_to_save writes prediction images under ./logs/<exp_name>/*/preds, and --save_only_wrong_preds restricts output to queries where the top prediction is wrong. The README notes that saving predictions for every query can take a long time, which is why the wrong-predictions-only flag exists. If you are debugging a deployment, that flag is the one to reach for first, because the failure cases are the informative ones.

Where CosPlace Is the Wrong Tool

The README contains an unusually candid note: CosPlace is quite old, and it directs readers looking for state-of-the-art visual place recognition to a separate project, MegaLoc. That sentence alone should shape your decision. If your goal is the best possible retrieval accuracy on a current benchmark, this repository is not the endpoint the author recommends, and the trained models here are dated to a 2022 paper with a v1.0 release in January 2023.

A second limitation is structural. The method depends on a geographic partition of the training set, and the repository's automatic split is tied to SF-XL's layout. There is no documented path for applying the same group-formation logic to a different city or a different dataset with the same guarantees. If your target domain is not San Francisco, you are relying on the learned descriptor to transfer, which is exactly what the paper's cross-dataset evaluation (training on SF-XL, testing on Pitts250k) is designed to measure. The README's comparison image makes clear that CosPlace is trained on SF-XL while the other methods shown are trained on Pitts30k, so read any accuracy comparison with that asymmetry in mind.

Third, the descriptor dimension is baked into the checkpoint. A model trained with --fc_output_dim 128 cannot be evaluated as if it were a 512-dimensional model. Mismatches between the training flag and the evaluation flag are a silent source of wrong numbers rather than a clean error, so the pairing has to be tracked manually.

CosPlace Against Pairwise-Ranking VPR Methods

The clearest alternative in the visual place recognition literature is the pairwise-ranking family, where a network is trained with a contrastive or triplet-style objective that pulls matching image pairs together and pushes non-matching pairs apart. NetVLAD is the canonical example of this approach. The difference in mechanism is not cosmetic. A ranking objective requires sampling informative pairs, and as the reference database grows, the fraction of pairs that are informative shrinks, which is why hard-negative mining becomes a substantial engineering problem at scale.

CosPlace removes that sampling step entirely by reducing training to classification over groups. There is no margin to tune and no miner to configure. The cost is that the geographic partition is fixed before training begins, and the model can only learn to separate the classes it was given. A ranking method, in principle, can learn fine-grained distinctions that the class structure never encoded.

Within this repository's own documentation, the most relevant comparison is against the author's later work. MegaLoc is presented as the current state-of-the-art option for visual place recognition, and the README frames CosPlace as a historical point rather than a live competitor. That is a more useful signal than any benchmark table, because it comes from the person who wrote both.

Licence, Maintenance, and What a Fork Actually Costs

CosPlace is MIT licensed, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are retained. The trained model weights are distributed through Google Drive links and PyTorch Hub rather than through a package registry, so there is no versioned artefact you can pin in a requirements file. If you build on a specific checkpoint, archive the .pth file yourself; the Drive links are outside the repository's control and outside its version history.

The repository is not archived, and the most recent push recorded is 2026-03-15, which indicates the code is still being touched even though the method itself dates to 2022. The only listed release is v1.0 from January 2023, titled around releasing trained models for torch.hub. There is no changelog, no deprecation policy, and no stated support window. Upgrading means checking whether the torch.hub entry point still resolves and whether the checkpoint you depend on is still reachable.

The practical maintenance question is whether you are consuming the models or the training code. Consuming the models through torch.hub is close to zero maintenance: one function call, two arguments, and a dependency on PyTorch itself. Consuming the training code means owning the SF-XL download, the cache directory that holds the group split, and the VRAM budget for whichever backbone you choose. Those are three separate operational commitments, and only the first one is cheap.

Editorial conclusion

Adopt CosPlace if you need a compact global descriptor for image retrieval and want to load a pretrained model directly through torch.hub without cloning the repository. Do not adopt it if you need to train from scratch without obtaining the SF-XL dataset, or if you require modern state-of-the-art accuracy, since the README states the method is quite old and points to MegaLoc. Before committing, verify the specific backbone and descriptor dimension you plan to deploy against the download table, and confirm that the --fc_output_dim value you pass to eval.py matches the checkpoint you are loading.

Official sources

1. gmberton/CosPlace on GitHub
2. Issues
3. License: MIT
4. README
5. Releases