{"id":13436113,"url":"https://github.com/lewisjiang/contour-context","last_synced_at":"2025-03-18T12:31:15.117Z","repository":{"id":82196294,"uuid":"488472298","full_name":"lewisjiang/contour-context","owner":"lewisjiang","description":"[ICRA'23] Official code repo for \"Contour Context: Abstract Structural Distribution for 3D LiDAR Loop Detection and Metric Pose Estimation\"","archived":false,"fork":false,"pushed_at":"2024-03-06T06:40:44.000Z","size":790,"stargazers_count":178,"open_issues_count":6,"forks_count":25,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-27T19:02:51.406Z","etag":null,"topics":["lidar-localization","loop-closure"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lewisjiang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-04T06:10:38.000Z","updated_at":"2024-10-22T07:17:22.000Z","dependencies_parsed_at":"2024-10-27T18:15:04.108Z","dependency_job_id":"38f8bd48-ecc8-4acc-9505-0e7eda362bbf","html_url":"https://github.com/lewisjiang/contour-context","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lewisjiang%2Fcontour-context","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lewisjiang%2Fcontour-context/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lewisjiang%2Fcontour-context/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lewisjiang%2Fcontour-context/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lewisjiang","download_url":"https://codeload.github.com/lewisjiang/contour-context/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244222292,"owners_count":20418486,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lidar-localization","loop-closure"],"created_at":"2024-07-31T03:00:44.224Z","updated_at":"2025-03-18T12:31:15.112Z","avatar_url":"https://github.com/lewisjiang.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# contour-context\n\n## Introduction\nThis is the official code repository of \"**Contour Context: Abstract Structural Distribution for 3D LiDAR Loop Detection and Metric Pose Estimation**\", which is accepted by ICRA'23.\n\n**Contour Context** is a simple, effective, and efficient 3D LiDAR topological loop closure detector with accurate 3-DoF metric pose estimation, targeting the urban autonomous driving scenario. Our key insight is that the scene expressed in BEV can be modeled as a probability distribution of salient structures. A two-step discrete constellation consensus verification and GMM L2 optimization with continuous densities is used to calculate similarity between two scans, after preselecting loop candidates using an efficient retrieval key. Our method is competitive compared with many recent works on different datasets.\n\n**Authors:** Binqian Jiang and Shaojie Shen from the [HKUST Aerial Robotics Group](https://uav.hkust.edu.hk/).\n\n[preprint](https://arxiv.org/abs/2302.06149), [video](https://www.youtube.com/watch?v=BnwpP-CfI7g), [code](https://github.com/lewisjiang/contour-context)\n\n\n\nIf you find this work useful, please consider citing our paper:\n\n```\n@inproceedings{jiang2023contour,\naddress     = {London, United Kingdom},\ntitle       = {Contour Context: Abstract Structural Distribution for 3D LiDAR Loop Detection and Metric Pose Estimation},\nISBN        = {9798350323658},\nDOI         = {10.1109/ICRA48891.2023.10160337},\nbooktitle   = {2023 IEEE International Conference on Robotics and Automation (ICRA)},\nauthor      = {Jiang, Binqian and Shen, Shaojie},\nyear        = {2023},\npages       = {8386–8392}\n}\n\n```\n\n\n\n## Usage\n\nWe've tested on Ubuntu 20.04 with ROS 1. The `cont2contops` library, which contains all the required functions of *Contour Context*, is totally ROS-free.\n\n### Dependencies\n1. [Eigen 3](https://eigen.tuxfamily.org/index.php?title=Main_Page)\n2. [Ceres 2](https://github.com/ceres-solver/ceres-solver)\n3. [OpenCV 4](https://github.com/opencv/opencv)\n4. [pcl](https://github.com/PointCloudLibrary/pcl)\n5. [glog](https://github.com/google/glog)\n\nOur project also relies on [nanoflann](https://github.com/jlblancoc/nanoflann). Note that their code has already been included in the `./thirdparty` folder after some modifications.\n\n### On KITTI Odometry dataset\n[Official site](https://www.cvlibs.net/datasets/kitti/eval_odometry.php). Note that we use GT poses from [Semantic KITTI](http://www.semantic-kitti.org/dataset.html).\n\n#### Procedure\n\n1. Download and unzip the dataset. Put the poses files in place as Semantic KITTI.\n2. Download and compile code:\n   1. `cd /path/to/catkin_ws/src `\n   2. `git clone https://github.com/lewisjiang/contour-context.git`\n   3. `cd .. \u0026\u0026 catkin build cont2 \u0026\u0026 source devel/setup.bash`\n3. (Once for a sequence) In `./scripts/gen_batch_bin_configs.py`, \n   1. Uncomment a sequence and modify the path parameters in `== KITTI Odometry ==` section (`== Mulran Odometry ==` for MulRan) following the commented examples.\n   2. Uncomment `gen_kitti(dir_lid_bin, fp_pose, fp_times, fp_calib, sav_1, sav_2)`  (`gen_mulran(...)` for MulRan) and run the script.\n4. In  `./config/batch_bin_test_config.yaml`, \n   1. Set the `fpath_sens_gt_pose` and `fpath_lidar_bins` parameters as `sav_1` and `sav_2` respectively. \n   2. Set  the `fpath_outcome_sav` in the file as you like.\n   3. (For MulRan) Modify the settings `ta_h_bar`, `lv_grads_`  in as instructed in the config file.\n5. `rosrun cont2 cont2_batch_bin_test`\n6. Terminate the program and you will find the runtime log in `./log` and topological loop detection and mpe results in `./results/outcome_txt`.\n7. Modify the file paths for gt sensor poses and outcome in `./scripts/pr_mpe.py` before running the script to get pr curve, max f1 score and metric pose estimation of a given sequence. \n   1. (For MulRan) Finish the additional steps first.\n\n\n\n### On MulRan dataset\n\n[Official site](https://sites.google.com/view/mulran-pr/dataset)\n\n#### Procedure\n\nSimilar to above.\n\n#### Additional steps \n\nOur system uses time gap to exclude past poses from the query candidates, so it may be problematic since the vehicle always stops at red lights in MulRan. Therefore we reindex the frames in MulRan to skip stationary times. To do this, \n\n1. Finish the above 1-6.\n2. In `./include/cont2/evaluator.h` ,\n   1. Uncomment `// save gt pose and bin path ` section  and recompile.\n   2. `rosrun cont2 cont2_batch_bin_test` once to generate new `ts-sens_pose-` (for config `fpath_sens_gt_pose`) and `ts-lidar_bins`  (for config `fpath_lidar_bins`) files.\n   3. Save the two new files and use them in the configuration yaml.\n   4. Comment `// save gt pose and bin path ` section and recompile.\n\n3. Run normally.\n\n### Visualization\n\n#### Loop connections\n\nMake sure the `PUB_ROS_MSG` flag is set to `1` in the cmakelists file.\n\n```bash\ncd /path/to/catkin_ws\nrviz -d ./src/contour-context/config/dummy_lc.rviz \u0026 rosrun cont2 cont2_batch_bin_test\n```\n\nSample image (KITTI08 at max f1 score):\n\n![](./img/k08_1.mp4.png)\n\n\n\n#### Raw contours\n\nSet `SAVE_MID_FILE` to `1`  in the cmakelists to save raw contours as images on the go.\n\nSample raw contours (KITTI 08, #0237 and #1648):\n\n![](./img/pair_000237-001648.png)\n\n#### Ellipses of contours\n\nIn `./scripts/plot_contours.py`, ...\n\nSample CAs from a pair of loop closure scans (transform applied, KITTI 08, #0237 and #1648):\n\n![](./img/ellipse_t0237-t1648-tf_ed.svg)\n\n## Misc\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flewisjiang%2Fcontour-context","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flewisjiang%2Fcontour-context","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flewisjiang%2Fcontour-context/lists"}