Feature/improved-documentation (#59)

* Installation issues resolved

* contributing.rst fixed pt1

* ASan and Valgrind both available

* contributing.rst for Linux & Windows

* contributing.rst edited

* finalizing contributing.rst

* small revision to clarify text

* finalizing for PR

* minor revisions based on review comments

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)

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

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;

docs/Windows.md

@@ -0,0 +1,96 @@
+# MC-Calib Installation for Windows Users
+**By @Harvendois**  
+
+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 
+- 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 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)`  
+
+   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, 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.

docs/contributing.rst

@@ -23,18 +23,28 @@ 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 <https://bosch.frameau.xyz/index.php/s/pLc2T9bApbeLmSz>`_. 
-Extract that and place (or symlink) Blender_Images folder under MC-Calib/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. 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 <https://drive.google.com/file/d/1CxaXUbO4E9WmaVrYy5aMeRLKmrFB_ARl/view?usp=sharing>`_. 
+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
 
 6. Run static analysis tools and fix introduced dangerous code constructs:
@@ -43,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<boost::log::trivial::severity_level>)
@@ -53,9 +63,24 @@ 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. 
+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
+
+    ./apps/calibrate/calibrate ../tests/configs_for_end2end_tests/calib_param_synth_Scenario1.yml
+
+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 with the ASanitizer option turned off.
+
+.. code-block:: bash
+
+    cd build
+    cmake -DCMAKE_BUILD_TYPE=Debug -DUSE_SANITIZERS=OFF ..
+    make -j10
 
-7. Perform valgrind test and fix introduced memory leaks:
+Then, run the valgrind test:
 
 .. code-block:: bash
 
@@ -72,7 +97,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:
@@ -82,7 +107,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: