diff --git a/README.md b/README.md index 74046957..11ac1323 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,8 @@ glomap mapper --database_path DATABASE_PATH --output_path OUTPUT_PATH --image_pa ``` For more details on the command line interface, one can type `glomap -h` or `glomap mapper -h` for help. +We also provide a guide on improving the obtained reconstruction, which can be found [here](docs/getting_started.md) + Note: - GLOMAP depends on two external libraries - [COLMAP](https://github.com/colmap/colmap) and [PoseLib](https://github.com/PoseLib/PoseLib). With the default setting, the library is built automatically by GLOMAP via `FetchContent`. @@ -80,6 +82,22 @@ glomap mapper \ --output_path ./output/south-building/sparse ``` +### Visualize and use the results + +The results are written out in the COLMAP sparse reconstruction format. Please +refer to [COLMAP](https://colmap.github.io/format.html#sparse-reconstruction) +for more details. + +The reconstruction can be visualized using the COLMAP GUI, for example: +```shell +colmap gui --import_path ./output/south-building/sparse/0 +``` +Alternatives like [rerun.io](https://rerun.io/examples/3d-reconstruction/glomap) +also enable visualization of COLMAP and GLOMAP outputs. + +If you want to inspect the reconstruction programmatically, you can use +`pycolmap` in Python or link against COLMAP's C++ library interface. + ### Notes - For larger scale datasets, it is recommended to use `sequential_matcher` or diff --git a/docs/getting_started.md b/docs/getting_started.md index 653b4364..6ae06514 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -1,20 +1,46 @@ # Getting started -### Installation and End-to-End Examples -Please refer to the main `README.md` -### Recommended practice +## Installation and end-to-end examples + +Please refer to the main `README.md`. + +## Recommended settings + The default parameters do not always gaurantee satisfying reconstructions. -Regarding this, there are several things which can generally help +Regarding this, there are several things which can generally help. + +### Share camera parameters + +If images are known to be taken with the same physical camera under identical +camera settings, or images are well organized and known to be taken by several +cameras, it is higly recommended to share the camera intrinsics as appropriate. +To achieve this, one can set `--ImageReader.single_camera_per_folder` or +`--ImageReader.single_camera_per_image` in `colmap feature_extractor`. -#### Share camera parameters as much as possible -If images are known to be taken with the same camera, or images are well organized and known to be taken by several cameras, it is higly recommended to share the camera intrinsics -To achieve this, one can set `--ImageReader.single_camera_per_folder` or `--ImageReader.single_camera_per_image` in `colmap feature_extractor` to be 1. +### Handle high-resolution or blurry images -#### Allow larger epipolar error -If images are of high resolution, or are blurry, it is worth trying to increase the allowed epipolar error by modifying `--RelPoseEstimation.max_epipolar_error`. For example, make it 4, or 10. +If images have high resolution or are blurry, it is worth trying to increase the +allowed epipolar error by modifying `--RelPoseEstimation.max_epipolar_error`. +For example, increase it to 4 or 10. + +### Speedup reconstruction process #### Cap the number of tracks -If the number of images and points are large, the run-time of global bundle adjustment can be long. In this case, to further speed up the overall reconstruction process, the total number of points can be capped, by changing `--TrackEstablishment.max_num_tracks`. Typically, one image should not need more than 1000 tracks to achieve good performance, so this number can be adjusted to $1000 \times n$. -Afterwards, if a full point cloud is desired (for example, to initialize a Gaussian Splatting), points can be triangulated directly by calling `colmap point_triangulator`. -Note, if the `--skip_retriangulation` is not set true when calling `glomap mapper`, retriangulation should already been performed. +If the number of images and points are large, the run-time of global bundle +adjustment can be long. In this case, to further speed up the overall +reconstruction process, the total number of points can be capped, by changing +`--TrackEstablishment.max_num_tracks`. Typically, one image should not need more +than 1000 tracks to achieve good performance, so this number can be adjusted to +$1000 \times n$. Afterwards, if a full point cloud is desired (for example, to +initialize a Gaussian Splatting), points can be triangulated directly by calling +`colmap point_triangulator`. + +Note, if the `--skip_retriangulation` is not set when calling `glomap mapper`, +retriangulation should already been performed. + +#### Limit optimization iterations + +The number of global positioning and bundle adjustment iterations can be limited +using the `--GlobalPositioning.max_num_iterations` and +`--BundleAdjustment.max_num_iterations` options.