From c151b98cbe84efb5e43d2cdc506ca88c0029cb6b Mon Sep 17 00:00:00 2001 From: Jungha Cho Date: Thu, 11 Jan 2024 15:51:26 +0900 Subject: [PATCH 01/10] Installation issues resolved --- README.md | 10 +- Windows.md | 97 +++++++++++++++++++ .../src/create_charuco_boards.cpp | 4 +- calib.ps1 | 6 ++ 4 files changed, 107 insertions(+), 10 deletions(-) create mode 100644 Windows.md create mode 100644 calib.ps1 diff --git a/README.md b/README.md index c9a42522..690927c7 100755 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ Toolbox described in the paper ["MC-Calib: A generic and robust calibration tool Requirements: Ceres, Boost, OpenCV 4.5.x, c++17 +For Windows users, follow [this installation guide](/Windows.md) + There are several ways to get the environment ready. Choose any of them: 1. The easiest way to get the environment is to pull it from the Docker Hub: @@ -25,16 +27,8 @@ There are several ways to get the environment ready. Choose any of them: - Run pulled image: ```bash - xhost +si:localuser:root docker run \ - --runtime=nvidia \ -ti --rm \ - --network host \ - --gpus all \ - --env="DISPLAY" \ - --env="QT_X11_NO_MITSHM=1" \ - --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \ - --volume="$HOME/.Xauthority:/home/.Xauthority:rw" \ --volume="${PWD}:/home/MC-Calib" \ --volume="PATH_TO_DATA:/home/MC-Calib/data" \ bailool/mc-calib-prod diff --git a/Windows.md b/Windows.md new file mode 100644 index 00000000..48e7c6f3 --- /dev/null +++ b/Windows.md @@ -0,0 +1,97 @@ +# MC-Calib Installation for Windows Users +**By Jungha Cho** +*Jan 9, 2024* + +This documentation is meant to guide the installation of the MC-Calib toolbox, especially for Windows OS users. Therefore, it is recommended to the readers to first read through the original MC-Calib toolbox github README before going through any of the steps recorded in this documentation. Furthermore, this documentation is meant to guide users who are not familiar to C++ application installation through a step-by-step guideline. + +## Setting up development environment in Visual Studio Code: +- Install Docker extension +- Install Powershell extension + +*Note: user may also use powershell/CMD app directly* + +## Installation Steps: + +1. **Install Docker Desktop for Windows** + Windows 10 or above will be supported by WSL2 backend while any Windows below 10 should be using Hyper-V backend. If you are using Windows 8 or below, you should additionally turn on the Hyper-V and Containers Windows features. You can follow [Docker instructions](https://docs.docker.com/desktop/install/windows-install/) for this step. + + +2. **Download the MC-Calib repository from GitHub** + The repository can then be placed in a separate folder/directory that the user will later mount on docker to set as /home for the docker container run. Copy the absolute address of this Windows directory where the repository is located because it will be our `$(PWD)`. + +3. **Pulling Docker Image** + Using Windows Powershell or CMD, we pull the docker images using the commands given in the README. + + First, we move to the directory where our downloaded repository is located. + The command for this is: + `Cd (copied absolute path)` + + Then pull the docker image using either one of the commands given below. + +```bash +docker pull bailool/mc-calib-prod # production environment +docker pull bailool/mc-calib-dev # development environment +``` + +4. **Running Pulled Image using Docker** +In order to avoid running the image manually every time, we can create a `*.ps1` file containing the necessary docker run commands (or enter the commands manually in Windows Powershell or CMD). Below are the commands necessary. + + +```bash +Docker run ` + -ti --rm ` + --volume=”$(PWD):/home/MC-Calib” ` + --volume=”PATH_TO_DATA:/home/MC-Calib/data” ` + bailool/mc-calib-prod +``` + +### User Personalization + +- `--volume=”$(PWD):/home/MC-Calib”` : +Mounts a volume from the host machine to the docker container. `$(PWD)` refers to the current directory on the host machine (that the user is located in his/her powershell/cmd). Any data or files within that directory on the host machine will then be able to be accessed/mapped to `/home/MC-Calib` inside the Docker container. It is hence recommended that `*.ps1` file containing the command lines above is located in the exact Windows directory that the user intends to make as /home to docker container. + +- `--volume=”PATH_TO_DATA:/home/MC-Calib/data”` : +Another volume mapping. This line maps the necessary data in our Windows directory to the Docker directory specified above. It is recommended that the docker directory address is not changed. + +However, it is important to set the appropriate `PATH_TO_DATA` to a correct directory that actually contains the images data that the user intends to calibrate with. While the location of the images are completely given as user’s freedom, the images are required to be contained in a certain prefixed directory within the chosen location. Depending on how many cameras we have, we separate each camera’s images into different subdirectories named `Cam_001`, `Cam_002`, and so forth. The prefix (`Cam_`) is essential. + +For example, if we choose to save our images in `D:\project\calibration\test\images` for 2 cameras, we create two subdirectories as follows: + +```bash +D:\project\calibration\test\images\Cam_001 +D:\project\calibration\test\images\Cam_002 +``` +After personalization, user can run the *.ps1 file in the Powershell/CMD/etc. + +```bash +.\calib.ps1 +``` + +## Compiling the MC-Calib repository + +Once we are in the docker container successfully, we are ready to compile the MC-Calib repository. We will utilize CMake to link our files together and make a compile-ready object file for us. + +First, head to `/home/MC-Calib` directory, where the user should already have placed the downloaded github repository of our toolbox. + +As it is a convention in compiling and building applications using CMake, we create the build directory and start compiling in it. + +```bash +mkdir build +cd build +cmake -DCMAKE_BUILD_TYPE=Release .. +make -j10 +``` + +If we need to recompile after some revisions, we can repeat `make -j10` in the build directory again. + +## Testing charuco board generation + +In `/home/MC-Calib/build` directory, using the command below should generate and save 7 charuco boards. + +```bash +./apps/create_charuco_boards/generate_charuco ../configs/Real_images/calib_param_Seq01_Non-overlapping.yml +``` + +The generated charuco boards can be found in the Windows directory `\build\apps\create_charuco`. + +Once you can confirm that charuco boards are generated and saved successfully, installation is finished. diff --git a/apps/create_charuco_boards/src/create_charuco_boards.cpp b/apps/create_charuco_boards/src/create_charuco_boards.cpp index c35b7efc..85c5905d 100644 --- a/apps/create_charuco_boards/src/create_charuco_boards.cpp +++ b/apps/create_charuco_boards/src/create_charuco_boards.cpp @@ -83,8 +83,8 @@ int main(int argc, char *argv[]) { cv::Size(resolution_x_per_board[i], resolution_y_per_board[i]), boardImage, 10, 1); // Display marker - cv::imshow("My Charuco", boardImage); - cv::waitKey(1); + // cv::imshow("My Charuco", boardImage); + // cv::waitKey(1); // Save the marker std::ostringstream ss; ss << std::setw(3) << std::setfill('0') << i; diff --git a/calib.ps1 b/calib.ps1 new file mode 100644 index 00000000..aeff5d04 --- /dev/null +++ b/calib.ps1 @@ -0,0 +1,6 @@ +docker run ` + -ti --rm ` + --volume="$(PWD):/home/MC-Calib" ` + --volume="D:\2023_Fall\EVENT\mc_calib\data\dataset:/home/MC-Calib/data" ` + bailool/mc-calib-prod + From 8941992b800d27cc44fae48c6013d16d70dfdce6 Mon Sep 17 00:00:00 2001 From: Jungha Cho Date: Thu, 11 Jan 2024 16:29:00 +0900 Subject: [PATCH 02/10] contributing.rst fixed pt1 --- docs/contributing.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 226ca037..c4a71da2 100755 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -27,14 +27,15 @@ To create a pull request: docker run -it --rm --workdir /src -v $(pwd):/src clang-format-lint --clang-format-executable /clang-format/clang-format11 -r --inplace True --exclude '.git ./libs' . -5. Make sure new changes pass the tests. The end-to-end tests rely on `Synthetic Data `_. +5. Make sure new changes pass the tests. The end-to-end tests rely on `Synthetic Data `_. Extract that and place (or symlink) Blender_Images folder under MC-Calib/data/. .. code-block:: bash - + mkdir build cd build cmake -DCMAKE_BUILD_TYPE=Debug .. + make -j10 ./tests/boost_tests_run 6. Run static analysis tools and fix introduced dangerous code constructs: From 01560118d0975299bc8d91562baa3969475d8b54 Mon Sep 17 00:00:00 2001 From: Jungha Cho Date: Mon, 15 Jan 2024 15:43:04 +0900 Subject: [PATCH 03/10] ASan and Valgrind both available --- CMakeLists.txt | 7 +++++++ calib.ps1 => calib_dev.ps1 | 2 +- calib_prod.ps1 | 5 +++++ 3 files changed, 13 insertions(+), 1 deletion(-) rename calib.ps1 => calib_dev.ps1 (84%) create mode 100644 calib_prod.ps1 diff --git a/CMakeLists.txt b/CMakeLists.txt index 69e02990..398d4cec 100755 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -3,6 +3,13 @@ project(MC-Calib VERSION 1.2.0 DESCRIPTION "MC-Calib: A generic and robust calib add_definitions(-std=c++17) set(CMAKE_CXX_FLAGS "-std=c++17") # required for Ceres https://github.com/colmap/colmap/issues/905#issuecomment-731138700 + +option(USE_SANITIZERS "Enable AddressSanitizer and LeakSanitizer" OFF) + +if(USE_SANITIZERS) + set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsanitize=address,leak") +endif() + set(CMAKE_CONFIGURATION_TYPES ${CMAKE_BUILD_TYPE} CACHE STRING "" FORCE) find_package(OpenCV REQUIRED) diff --git a/calib.ps1 b/calib_dev.ps1 similarity index 84% rename from calib.ps1 rename to calib_dev.ps1 index aeff5d04..b17e8106 100644 --- a/calib.ps1 +++ b/calib_dev.ps1 @@ -2,5 +2,5 @@ docker run ` -ti --rm ` --volume="$(PWD):/home/MC-Calib" ` --volume="D:\2023_Fall\EVENT\mc_calib\data\dataset:/home/MC-Calib/data" ` - bailool/mc-calib-prod + bailool/mc-calib-dev diff --git a/calib_prod.ps1 b/calib_prod.ps1 new file mode 100644 index 00000000..4000da87 --- /dev/null +++ b/calib_prod.ps1 @@ -0,0 +1,5 @@ +docker run ` + -ti --rm ` + --volume="$(PWD):/home/MC-Calib" ` + --volume="D:\2023_Fall\EVENT\mc_calib\data\dataset:/home/MC-Calib/data" ` + bailool/mc-calib-prod \ No newline at end of file From a6e9c2a65b644003de5ab518b3bb74df043b872d Mon Sep 17 00:00:00 2001 From: Jungha Cho Date: Mon, 15 Jan 2024 21:31:32 +0900 Subject: [PATCH 04/10] contributing.rst for Linux & Windows --- docs/contributing.rst | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index c4a71da2..cadad1e2 100755 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -23,18 +23,27 @@ To create a pull request: 4. Apply clang-format-lint to new changes: +for Linux/Unix: + .. code-block:: bash docker run -it --rm --workdir /src -v $(pwd):/src clang-format-lint --clang-format-executable /clang-format/clang-format11 -r --inplace True --exclude '.git ./libs' . -5. Make sure new changes pass the tests. The end-to-end tests rely on `Synthetic Data `_. +for Windows: + +.. code-block:: bash + + docker run -it --rm --workdir /src -v ${pwd}:/src clang-format-lint --clang-format-executable /clang-format/clang-format11 -r --inplace True --exclude '.git ./libs' . + + +5. Make sure new changes pass the tests. Make sure to use 'bailool/mc-calib-prod' as our docker image when running docker with commands using ps1/sh.The end-to-end tests rely on `Synthetic Data `_. Extract that and place (or symlink) Blender_Images folder under MC-Calib/data/. .. code-block:: bash mkdir build cd build - cmake -DCMAKE_BUILD_TYPE=Debug .. + cmake -DCMAKE_BUILD_TYPE=Debug -DUSE_SANITIZERS=ON .. make -j10 ./tests/boost_tests_run @@ -44,7 +53,7 @@ Extract that and place (or symlink) Blender_Images folder under MC-Calib/data/. cd build apt install cppcheck - cppcheck ../src + cppcheck ../McCalib/src # known errors: logger.h:19:1: error: There is an unknown macro here somewhere. Configuration is required. If BOOST_LOG_GLOBAL_LOGGER is a macro then please configure it. [unknownMacro] BOOST_LOG_GLOBAL_LOGGER(logger, boost::log::sources::severity_logger_mt) @@ -54,9 +63,13 @@ Extract that and place (or symlink) Blender_Images folder under MC-Calib/data/. cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_BUILD_TYPE=Debug .. run-clang-tidy +7. Perform ASanitizer test in the build directory. In order to run the test properly, the synthetic image data or the blender image data must be downloaded and placed in the data folder. The synthetic image data can be downloaded from `Synthetic Data `_. The blender image data can be downloaded from `Blender Data `_. Extract the data and place (or symlink) Blender_Images folder under MC-Calib/data/. + +.. code-block:: bash + ./apps/calibrate/calibrate ../tests/configs_for_end2end_tests/calib_param_synth_Scenario1.yml -7. Perform valgrind test and fix introduced memory leaks: +8. Perform valgrind test and fix introduced memory leaks: .. code-block:: bash @@ -73,7 +86,7 @@ Extract that and place (or symlink) Blender_Images folder under MC-Calib/data/. --suppressions=../tests/valgrind_suppress/opencv_valgrind.supp \ --suppressions=../tests/valgrind_suppress/opencv_valgrind_3rdparty.supp \ --suppressions=../tests/valgrind_suppress/boost_valgrind.supp \ - ./calibrate ../tests/configs_for_end2end_tests/calib_param_synth_Scenario1.yml + ./apps/calibrate/calibrate ../tests/configs_for_end2end_tests/calib_param_synth_Scenario1.yml # current state of this repository: ==6274== LEAK SUMMARY: @@ -83,7 +96,7 @@ Extract that and place (or symlink) Blender_Images folder under MC-Calib/data/. ==6274== still reachable: 0 bytes in 0 blocks ==6274== suppressed: 420,593 bytes in 3,714 blocks -8. Create pull request. +9. Create pull request. Naming convention: From b83ae16f3006490bbc4ba5fa659761f4883ac827 Mon Sep 17 00:00:00 2001 From: Jungha Cho Date: Mon, 15 Jan 2024 23:37:57 +0900 Subject: [PATCH 05/10] contributing.rst edited --- docs/contributing.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index cadad1e2..c049a84e 100755 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -63,7 +63,8 @@ Extract that and place (or symlink) Blender_Images folder under MC-Calib/data/. cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_BUILD_TYPE=Debug .. run-clang-tidy -7. Perform ASanitizer test in the build directory. In order to run the test properly, the synthetic image data or the blender image data must be downloaded and placed in the data folder. The synthetic image data can be downloaded from `Synthetic Data `_. The blender image data can be downloaded from `Blender Data `_. Extract the data and place (or symlink) Blender_Images folder under MC-Calib/data/. +7. Perform ASanitizer test in the build directory. In order to run the test properly, the synthetic image data or the blender image data must be downloaded and placed in the data folder. +The synthetic image data can be downloaded from `Synthetic Data `_. .. code-block:: bash @@ -71,6 +72,8 @@ Extract that and place (or symlink) Blender_Images folder under MC-Calib/data/. 8. Perform valgrind test and fix introduced memory leaks: +In order to use Valgrind, ASanitizer must first be disabled. This can be done by recompiling the /home/MC-Calib/build + .. code-block:: bash apt update From a675de28b79210a534add3fc37a537632fab64d7 Mon Sep 17 00:00:00 2001 From: Jungha Cho Date: Tue, 16 Jan 2024 00:35:27 +0900 Subject: [PATCH 06/10] finalizing contributing.rst --- docs/contributing.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index c049a84e..3fb4bab9 100755 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -72,7 +72,15 @@ The synthetic image data can be downloaded from `Synthetic Data Date: Tue, 16 Jan 2024 16:15:16 +0900 Subject: [PATCH 07/10] small revision to clarify text --- docs/contributing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 3fb4bab9..4947552a 100755 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -36,7 +36,7 @@ for Windows: docker run -it --rm --workdir /src -v ${pwd}:/src clang-format-lint --clang-format-executable /clang-format/clang-format11 -r --inplace True --exclude '.git ./libs' . -5. Make sure new changes pass the tests. Make sure to use 'bailool/mc-calib-prod' as our docker image when running docker with commands using ps1/sh.The end-to-end tests rely on `Synthetic Data `_. +5. Now we have to make sure our new changes pass the tests. In order to test them, we must first open docker image 'bailool/mc-calib-prod'. Make sure to change the starter command in your *.sh/*.ps1 file accordingly. The end-to-end tests rely on `Synthetic Data `_. Extract that and place (or symlink) Blender_Images folder under MC-Calib/data/. .. code-block:: bash @@ -64,7 +64,7 @@ Extract that and place (or symlink) Blender_Images folder under MC-Calib/data/. run-clang-tidy 7. Perform ASanitizer test in the build directory. In order to run the test properly, the synthetic image data or the blender image data must be downloaded and placed in the data folder. -The synthetic image data can be downloaded from `Synthetic Data `_. +Refer back to Step 5 for more information. By running calibrate, we will be able to see if the ASanitizer finds any errors or leaks on the way. .. code-block:: bash @@ -72,7 +72,7 @@ The synthetic image data can be downloaded from `Synthetic Data Date: Tue, 16 Jan 2024 16:18:35 +0900 Subject: [PATCH 08/10] finalizing for PR --- calib_dev.ps1 | 6 ------ calib_prod.ps1 | 5 ----- 2 files changed, 11 deletions(-) delete mode 100644 calib_dev.ps1 delete mode 100644 calib_prod.ps1 diff --git a/calib_dev.ps1 b/calib_dev.ps1 deleted file mode 100644 index b17e8106..00000000 --- a/calib_dev.ps1 +++ /dev/null @@ -1,6 +0,0 @@ -docker run ` - -ti --rm ` - --volume="$(PWD):/home/MC-Calib" ` - --volume="D:\2023_Fall\EVENT\mc_calib\data\dataset:/home/MC-Calib/data" ` - bailool/mc-calib-dev - diff --git a/calib_prod.ps1 b/calib_prod.ps1 deleted file mode 100644 index 4000da87..00000000 --- a/calib_prod.ps1 +++ /dev/null @@ -1,5 +0,0 @@ -docker run ` - -ti --rm ` - --volume="$(PWD):/home/MC-Calib" ` - --volume="D:\2023_Fall\EVENT\mc_calib\data\dataset:/home/MC-Calib/data" ` - bailool/mc-calib-prod \ No newline at end of file From eb05d1b68a3583c840adcdba4b6bd9b4a603415a Mon Sep 17 00:00:00 2001 From: Jungha Cho Date: Wed, 17 Jan 2024 11:14:34 +0900 Subject: [PATCH 09/10] minor revisions based on review comments --- Windows.md => docs/Windows.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) rename Windows.md => docs/Windows.md (82%) diff --git a/Windows.md b/docs/Windows.md similarity index 82% rename from Windows.md rename to docs/Windows.md index 48e7c6f3..c74df601 100644 --- a/Windows.md +++ b/docs/Windows.md @@ -1,8 +1,7 @@ # MC-Calib Installation for Windows Users -**By Jungha Cho** -*Jan 9, 2024* +**By @Harvendois** -This documentation is meant to guide the installation of the MC-Calib toolbox, especially for Windows OS users. Therefore, it is recommended to the readers to first read through the original MC-Calib toolbox github README before going through any of the steps recorded in this documentation. Furthermore, this documentation is meant to guide users who are not familiar to C++ application installation through a step-by-step guideline. +This documentation is meant to guide the installation of the MC-Calib toolbox, specifically for Windows OS users. Therefore, it is recommended to the readers to first read through the original MC-Calib toolbox github README before going through any of the steps recorded in this documentation. Furthermore, this documentation is meant to guide users who are not familiar to C++ application installation through a step-by-step guideline. ## Setting up development environment in Visual Studio Code: - Install Docker extension @@ -17,14 +16,14 @@ This documentation is meant to guide the installation of the MC-Calib toolbox, e 2. **Download the MC-Calib repository from GitHub** - The repository can then be placed in a separate folder/directory that the user will later mount on docker to set as /home for the docker container run. Copy the absolute address of this Windows directory where the repository is located because it will be our `$(PWD)`. + The repository can then be placed in a separate folder/directory that the user will later mount in docker to set as '/home' for the docker container run. Copy the absolute address of this Windows directory where the repository is located because it will be our `$(PWD)`. 3. **Pulling Docker Image** Using Windows Powershell or CMD, we pull the docker images using the commands given in the README. First, we move to the directory where our downloaded repository is located. The command for this is: - `Cd (copied absolute path)` + `cd (copied absolute path)` Then pull the docker image using either one of the commands given below. @@ -61,7 +60,7 @@ For example, if we choose to save our images in `D:\project\calibration\test\ima D:\project\calibration\test\images\Cam_001 D:\project\calibration\test\images\Cam_002 ``` -After personalization, user can run the *.ps1 file in the Powershell/CMD/etc. +After personalization, user can run the '*.ps1' file in the Powershell/CMD/etc. ```bash .\calib.ps1 @@ -69,7 +68,7 @@ After personalization, user can run the *.ps1 file in the Powershell/CMD/etc. ## Compiling the MC-Calib repository -Once we are in the docker container successfully, we are ready to compile the MC-Calib repository. We will utilize CMake to link our files together and make a compile-ready object file for us. +Once we are in the docker container, we are ready to compile the MC-Calib repository. We will utilize CMake to link our files together and make a compile-ready object file for us. First, head to `/home/MC-Calib` directory, where the user should already have placed the downloaded github repository of our toolbox. From b2909973969ac0c9fdc1de3063d05469f3b7e96c Mon Sep 17 00:00:00 2001 From: Jungha Cho Date: Fri, 19 Jan 2024 11:24:16 +0900 Subject: [PATCH 10/10] windows.md path fixed --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 690927c7..6f26ac0a 100755 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Toolbox described in the paper ["MC-Calib: A generic and robust calibration tool Requirements: Ceres, Boost, OpenCV 4.5.x, c++17 -For Windows users, follow [this installation guide](/Windows.md) +For Windows users, follow [this installation guide](/docs/Windows.md) There are several ways to get the environment ready. Choose any of them: