Skip to content

Commit

Permalink
Feature/improved-documentation (#59)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
Harvendois authored Jan 18, 2024
1 parent b862d3f commit f6d6b7f
Show file tree
Hide file tree
Showing 5 changed files with 139 additions and 17 deletions.
7 changes: 7 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
10 changes: 2 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down
4 changes: 2 additions & 2 deletions apps/create_charuco_boards/src/create_charuco_boards.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
96 changes: 96 additions & 0 deletions docs/Windows.md
Original file line number Diff line number Diff line change
@@ -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.
39 changes: 32 additions & 7 deletions docs/contributing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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>)
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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:
Expand Down

0 comments on commit f6d6b7f

Please sign in to comment.