Skip to content

Latest commit

 

History

History

pipeline

README.adoc

kapture-localization / pipeline

Here we provide usage examples of different pipeline scripts. For a more detailed explanation, please refer to doc/tutorial.

Before executing the following commands, please make sure:

  • You have local and global features saved in the recommended dataset structure. Refer to the section prepare data of doc/tutorial page.

  • Windows users should take care of extra installation steps. Refer to doc/installation.

  • if the COLMAP executable is not available from PATH, the parameter -colmap needs to be set.

  • if your operating system cannot infer the python binary from the shebang or the file extension (default behaviour), you can explicitely give the python binary path with the -python parameter or let python find it from sys.executable with --auto-python-binary.

kapture_pipeline_mapping.py

This script computes:

  • the image pairs from global features,

  • the corresponding keypoint matches,

  • the geometric verification of the matches, and finally

  • the COLMAP map (which is later used for localization).

kapture_pipeline_mapping.py
    -i my_dataset/mapping \
    -kpt my_dataset/local_features/r2d2_WASF-N8_20k/keypoints \
    -desc my_dataset/local_features/r2d2_WASF-N8_20k/descriptors \
    -gfeat my_dataset/global_features/AP-GeM-LM18/global_features \
    -matches my_dataset/local_features/r2d2_WASF-N8_20k/NN_no_gv/matches \
    -matches-gv my_dataset/local_features/r2d2_WASF-N8_20k/NN_colmap_gv/matches \
    --colmap-map my_dataset/colmap-sfm/r2d2_WASF-N8_20k/AP-GeM-LM18_top20 # lfeat_type / map_pairs \
    --topk 20

kapture_pipeline_localize.py

This script computes:

  • the image pairs (query-map) from global features,

  • the corresponding keypoint matches,

  • the geometric verification of the matches, and finally

  • localization of images against an existing COLMAP map.

config=0 : []
config=1 : ['--Mapper.ba_refine_focal_length', '0',
            '--Mapper.ba_refine_principal_point', '0',
            '--Mapper.ba_refine_extra_params', '0']
config=2 : ['--Mapper.ba_refine_focal_length', '0',
            '--Mapper.ba_refine_principal_point', '0',
            '--Mapper.ba_refine_extra_params', '0',
            '--Mapper.min_num_matches', '4',
            '--Mapper.init_min_num_inliers', '4',
            '--Mapper.abs_pose_min_num_inliers', '4',
            '--Mapper.abs_pose_min_inlier_ratio', '0.05',
            '--Mapper.ba_local_max_num_iterations', '50',
            '--Mapper.abs_pose_max_error', '20',
            '--Mapper.filter_max_reproj_error', '12'],
config=3 : ['--Mapper.ba_refine_focal_length', '1',
            '--Mapper.ba_refine_principal_point', '0',
            '--Mapper.ba_refine_extra_params', '0',
            '--Mapper.min_num_matches', '4',
            '--Mapper.init_min_num_inliers', '4',
            '--Mapper.abs_pose_min_num_inliers', '4',
            '--Mapper.abs_pose_min_inlier_ratio', '0.05',
            '--Mapper.ba_local_max_num_iterations', '50',
            '--Mapper.abs_pose_max_error', '20',
            '--Mapper.filter_max_reproj_error', '12']
kapture_pipeline_localize.py
    -i my_dataset/mapping \
    --query my_dataset/query \
    --merge-path my_dataset/map_plus_query # optional, providing it will avoid recomputing it \
    -kpt my_dataset/local_features/r2d2_WASF-N8_20k/keypoints \
    -desc my_dataset/local_features/r2d2_WASF-N8_20k/descriptors \
    -gfeat my_dataset/global_features/AP-GeM-LM18/global_features \
    -matches my_dataset/local_features/r2d2_WASF-N8_20k/NN_no_gv/matches \
    -matches-gv my_dataset/local_features/r2d2_WASF-N8_20k/NN_colmap_gv/matches \
    --colmap-map my_dataset/colmap-sfm/r2d2_WASF-N8_20k/AP-GeM-LM18_top20 # lfeat_type / map_pairs \
    -o my_dataset/colmap-localization/r2d2_WASF-N8_20k/AP-GeM-LM18_top20/AP-GeM-LM18_top20/ # lfeat_type / map_pairs / query_pairs / \
    --topk 20 \
    --config 2
# For RobotCar or RobotCar_v2 --benchmark-style RobotCar_Seasons needs to be added.
# For Gangnam_Station --benchmark-style Gangnam_Station
# For Hyundai_Department_Store --benchmark-style Hyundai_Department_Store
# For RIO10 --benchmark-style RIO10
# For ETH-Microsoft --benchmark-style ETH_Microsoft

kapture_pipeline_image_retrieval_benchmark.py

This can be used to evaluate image retrieval for visual localization. Please refer to doc/tutorial for more details.

This script executes two more steps compared to localize.py :

  • pose approximation (EWB, BDI, CSI), and

  • local SFM.

More details about these two methods can be found in our 3DV paper.

kapture_pipeline_image_retrieval_benchmark.py
    -i my_dataset/mapping \
    --query my_dataset/query \
    --merge-path my_dataset/map_plus_query  # optional, providing it will avoid recomputing it \
    -kpt my_dataset/local_features/r2d2_WASF-N8_20k/keypoints \
    -desc my_dataset/local_features/r2d2_WASF-N8_20k/descriptors \
    -gfeat my_dataset/global_features/AP-GeM-LM18/global_features \
    -matches my_dataset/local_features/r2d2_WASF-N8_20k/NN_no_gv/matches \
    -matches-gv my_dataset/local_features/r2d2_WASF-N8_20k/NN_colmap_gv/matches \
    --colmap-map my_dataset/colmap-sfm/r2d2_WASF-N8_20k/AP-GeM-LM18_top20 # lfeat_type / map_pairs \
    -o my_dataset/ir-benchmark/r2d2_WASF-N8_20k/AP-GeM-LM18_top20/AP-GeM-LM18_top20/ # lfeat_type / map_pairs / query_pairs \
    --topk 20 \
    --config 2

# For RobotCar or RobotCar_v2 --benchmark-style RobotCar_Seasons needs to be added.
# For Gangnam_Station --benchmark-style Gangnam_Station
# For Hyundai_Department_Store --benchmark-style Hyundai_Department_Store
# For RIO10 --benchmark-style RIO10
# For ETH-Microsoft --benchmark-style ETH_Microsoft