DOCSEARCHbyAlgolia
Submit Docs

CosPlace Documentation

repository·main·Indexed 19 days ago

https://github.com/gmberton/cosplace

A PyTorch implementation of CosPlace, a scalable visual geo-localization method for large-scale applications. It includes tools for training models using the SF-XL dataset via train.py, evaluating models with eval.py, and loading pre-trained models through PyTorch Hub.

Tokens
1K
Snippets
3
Records
4
Agent score
14%

What's inside CosPlace

  1. Visualize CosPlace predictions

    main

    When running eval.py, you can visualize how the model performs by saving prediction images.

    1. Pass --num_preds_to_save <N> to save a specific number of prediction images.
    2. Pass --exp_name <name> to define an experiment name.
    3. The resulting images will be generated under the directory: ./logs/<exp_name>/*/preds.

    To focus on failure cases, use the --save_only_wrong_preds flag, which only saves images where the top prediction was incorrect.

  2. Test a trained CosPlace model

    main

    Use eval.py to evaluate a trained model. You must specify the backbone, the descriptor dimensionality, and the path to the trained model weights.

    Key Options:

    • --backbone: The architecture used during training.
    • --fc_output_dim: The dimensionality of the descriptors.
    • --resume_model: Path to the .pth model file.
    • --num_preds_to_save: Number of predictions to visualize.
    • --exp_name: Name for the experiment (used for output paths).
    • --save_only_wrong_preds: If set, only saves predictions where the first prediction was incorrect (useful for analyzing failure cases).
    # Basic evaluation
python3 eval.py --backbone ResNet50 --fc_output_dim 128 --resume_model path/to/best_model.pth

# Evaluation with prediction visualization
python3 eval.py --backbone ResNet50 --fc_output_dim 512 --resume_model path/to/best_model.pth --num_preds_to_save=3 --exp_name=cosplace_on_stlucia

# Evaluation saving only incorrect predictions
python3 eval.py --backbone ResNet50 --fc_output_dim 512 --resume_model path/to/best_model.pth --save_only_wrong_preds

  3. Train CosPlace models

    main

    To train a CosPlace model, use the train.py script. You must provide paths to the SF-XL dataset folders. The script automatically handles splitting the dataset into CosPlace Groups and caches the result in a cache folder.

    By default, the script uses a ResNet-18 backbone with 512-dimensional descriptors, which requires less than 4GB of VRAM.

    Key Options:

    • --backbone: Specify the architecture (e.g., ResNet50).
    • --fc_output_dim: Set the dimensionality of the output descriptors.
    • --use_amp16: Enable Automatic Mixed Precision (AMP) to speed up training (note: the original paper results did not use AMP).

    Run python3 train.py -h to view all available hyperparameters.

    # Basic training with SF-XL dataset
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

# Training with a custom backbone and descriptor dimension
python3 train.py --backbone ResNet50 --fc_output_dim 128

# Training with Automatic Mixed Precision (AMP)
python3 train.py --use_amp16

  4. Load trained CosPlace models via PyTorch Hub

    main

    You can use pre-trained CosPlace models in your own projects without cloning the repository by using torch.hub.load. This allows you to pull models directly from the gmberton/cosplace repository.

    import torch

# Load a trained ResNet50 model with 2048-dimensional descriptors
model = torch.hub.load("gmberton/cosplace", "get_trained_model", backbone="ResNet50", fc_output_dim=2048)