LidarView_Developer_Guide.md 10.1 KB
Newer Older
1
# LidarView Developer Guide
Arnaud Billon's avatar
Arnaud Billon committed
2
This documents gather all information needed to build LidarView-based Applications.
3

Arnaud Billon's avatar
Arnaud Billon committed
4
5
6
7
8
9
10
11
12
13
14
15
This document mirrors some information from the [Installation Guide](Documentation/INSTALLATION.md).

1. [Overview](#lv-compilation-overview)
2. [Configure & Build instructions](#congfigure-build)
    0. [Crossplatform](#crossplatform-instructions)
    1. [Windows](#windows-instructions)
    2. [Ubuntu](#linux-instructions)
3. [Enabling Additional Features](#enabling-additional-lidarview-features)
4. [Incremental Build Instructions](#incremental-build)
4. [Packaging Instructions](#packaging)
4. [Testing Instructions](#testing)
5. [Troubleshooting / FAQ ](#faq-instructions)
16

17
## LidarView Compilation Overview <a name="lv-compilation-overview"></a>
Arnaud Billon's avatar
Arnaud Billon committed
18
LidarView relies primarily on a CMake and the *superbuild* system, it handles the download and compilation of most, if not all, necessary dependencies.
19

Arnaud Billon's avatar
Arnaud Billon committed
20
21
However some dependencies, may or may not be supplied by the superbuild for various reasons and must obtained externally on some platform,
 see the following sections for per platform instructions.
22

Arnaud Billon's avatar
Arnaud Billon committed
23
LidarView is actively Maintained on Windows, Ubuntu18.04, Ubuntu20.04 and OSX.
24

Arnaud Billon's avatar
Arnaud Billon committed
25
## Configure and build instructions <a name="configure-build"></a>
26

Arnaud Billon's avatar
Arnaud Billon committed
27
### Crossplatform Instructions <a name="crossplatform-instructions"></a>
28

Arnaud Billon's avatar
Arnaud Billon committed
29
**Crossplatform Dependencies and Tools**
30

Arnaud Billon's avatar
Arnaud Billon committed
31
The specific version of the following tools may or may not be available in your OS package manager.
32

Arnaud Billon's avatar
Arnaud Billon committed
33
34
35
36
37
 - **[Required] CMake 3.18 or 3.19** Get it at <https://cmake.org/> 
 
 - **[Recommended] Ninja 1.8.2+** Get it at <https://ninja-build.org/> 
 
    Using Ninja is strongly recommended on all platforms to speed up compilation, if you do not wish to use it, make sure to remove the `-GNinja` options from the configuration command.
38

Arnaud Billon's avatar
Arnaud Billon committed
39
### Windows Instructions <a name="windows-instructions"></a>
40

Arnaud Billon's avatar
Arnaud Billon committed
41
#### Windows specific dependencies <a name="windows-dependencies"></a>
42

Arnaud Billon's avatar
Arnaud Billon committed
43
44
45
46
47
 - **Microsoft Visual Studio 14 (2015) Express** Get it at <http://go.microsoft.com/fwlink/?LinkId=615464>
    
    You may need to use the `/layout` option to generate an offline installer : <https://docs.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2015/install/create-an-offline-installation-of-visual-studio?view=vs-2015>
   
    Alternatively, link to an ISO image: <https://go.microsoft.com/fwlink/?LinkId=615448>
48

Arnaud Billon's avatar
Arnaud Billon committed
49
50
51
 - **Qt 5.12.9** You can download the installer here: <https://download.qt.io/official_releases/qt/5.12/5.12.9/>
 
    To alleviate the need for registration, disconnect your internet connection before starting the installer.
52

Arnaud Billon's avatar
Arnaud Billon committed
53
 - **[only for packaging]** **NSIS version 3.04 or higher** Get it at <https://nsis.sourceforge.io/Download>
54

Arnaud Billon's avatar
Arnaud Billon committed
55
#### Windows Guidelines <a name="windows-guidelines"></a>
56

Arnaud Billon's avatar
Arnaud Billon committed
57
 - **Must Use MSVC build environment Command Prompt (installed with MSVC)**
58

Arnaud Billon's avatar
Arnaud Billon committed
59
60
61
    It is located at `Windows Start Menu > Visual Studio 2015 > "VS2015 x64 Native Tools Command Prompt"`
    
    If you are unfamilliar with Windows Development, using this Prompt is mandatory for building as it sets appropriate build environement in contrast with a regular cmd.exe Prompt
62

Arnaud Billon's avatar
Arnaud Billon committed
63
 - **Work Directory, source and build paths must be short and close to the root Drive**
64

Arnaud Billon's avatar
Arnaud Billon committed
65
66
67
68
69
70
71
72
73
74
75
76
77
    The path to those directories must be short because Windows has limitations on the maximum length of file paths and commands.
    Those paths will appear numerous times in the build process, it can quickly reach the maximum limit.
     
  - **The source directory must not be inside the LidarView source code directory**.
  
    Prefer an Architecture like so :
    
    | C:\      | work dir   |
    |----------|------------|
    | C:\src   | source dir |
    | C:\build | build dir  |
    
  - **Moving these directories after configuration or compilation, will break all build environnements and require a full rebuild.**
78

79
#### Windows build instructions <a name="windows-build-instructions"></a>
80

Arnaud Billon's avatar
Arnaud Billon committed
81
82
83
84
85
 - Note that the configuration command mentions the subdirectory "*Superbuild*" dir inside the source directory and not the source directory itself.
 - Note that the CMake `Qt5_DIR` path argument must use **forward slashes** on all platforms (Unix PATH format), MSVC would otherwise take `\\Q` as a build option.
 - If you changed the default Qt installation path, you will have to adapt the configuration command.
 - Building from scratch can take from 45 minutes to 2 hours depending on your hardware.
 - By default `-j` will use all cores on your machine, but you can specify the number of cores to use with `-j N`.
86
87

    `cd <work-directory>`
Arnaud Billon's avatar
Arnaud Billon committed
88
89
90
91
92
93
94
95
96
97
98
99
    
    `git clone <git url to LidarView-based app repository> --recursive src`
    
    `mkdir <work-directory>\build`
    
    `cd <work-directory>\build`
    
    `cmake <work-directory>\src\Superbuild -GNinja -DCMAKE_BUILD_TYPE=Release -DUSE_SYSTEM_qt5=True -DQt5_DIR="C:/Qt/Qt5.12.9/5.12.9/msvc2015_64/lib/cmake/Qt5"`
    
    `cmake --build . -j`
    
    `install\bin\<LidarView-based app name>`
100

Arnaud Billon's avatar
Arnaud Billon committed
101
102
---

103
### Linux build Instructions <a name="linux-instructions"></a>
104

Arnaud Billon's avatar
Arnaud Billon committed
105
#### Linux specific dependencies <a name="linux-dependencies"></a>
106

Arnaud Billon's avatar
Arnaud Billon committed
107
108
**Packages**
 - The packages from the following one-liner are needed to build on Ubuntu 18.04 and higher:
109

Arnaud Billon's avatar
Arnaud Billon committed
110
    `sudo apt-get install build-essential flex byacc python3.7-dev libxext-dev libxt-dev libbz2-dev zlib1g-dev freeglut3-dev pkg-config libffi-dev libnl-genl-3-dev libprotobuf-dev protobuf-compiler patchelf libopengl0 liblapack3`
111

Arnaud Billon's avatar
Arnaud Billon committed
112
    **If using Ubuntu 20.04**
113

Arnaud Billon's avatar
Arnaud Billon committed
114
    Add this package: `sudo apt-get install libfreetype-dev` (will change in the future)
115

Arnaud Billon's avatar
Arnaud Billon committed
116
**Qt5:**
117

Arnaud Billon's avatar
Arnaud Billon committed
118
 - If you system's package manager offers Qt5 with version 5.12.9 or higher (e.g Ubuntu20.04) use:
119

Arnaud Billon's avatar
Arnaud Billon committed
120
    `qtbase5-dev qtmultimedia5-dev qttools5-dev qtbase5-private-dev libqt5x11extras5-dev libqt5svg5-dev`
MelanieCarriere's avatar
MelanieCarriere committed
121

Arnaud Billon's avatar
Arnaud Billon committed
122
 - On other systems, we recommend you use offline installers from:
123

Arnaud Billon's avatar
Arnaud Billon committed
124
125
126
    <https://download.qt.io/official_releases/qt/5.12/5.12.9/>
    
**Python3.7.10**
127

Arnaud Billon's avatar
Arnaud Billon committed
128
 - If you system's package manager offers Python3 with version 3.7 (e.g Ubuntu18.04) use:
129

Arnaud Billon's avatar
Arnaud Billon committed
130
131
132
    `sudo apt-get install python3.7-dev`
    
 - On other systems, you can get it from this unofficial repository:
133

Arnaud Billon's avatar
Arnaud Billon committed
134
    `sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt-get install python3.7-dev`
135

Arnaud Billon's avatar
Arnaud Billon committed
136
 - Or build it from [Official Source](https://www.python.org/downloads/release/python-3710/)
137

Arnaud Billon's avatar
Arnaud Billon committed
138
139
140
    `sudo apt-get install build-essentials zlib1g-dev`
    
    `./configure --enable-shared && sudo make install`
141

Arnaud Billon's avatar
Arnaud Billon committed
142
#### Linux Guidelines <a name="linux-guidelines"></a>
143

Arnaud Billon's avatar
Arnaud Billon committed
144
145
146
147
148
149
150
151
152
153
  - **The source directory must not be inside the LidarView source code directory**.
  
    Prefer an Architecture like so :
    
    | /home/username/lidarview       | work dir   |
    |--------------------------------|------------|
    | /home/username/lidarview/src   | source dir |
    | /home/username/lidarview/build | build dir  |
    
  - **Moving these directories after configuration or compilation, will break all build environnements and require a full rebuild.**
154

Arnaud Billon's avatar
Arnaud Billon committed
155
#### Linux compiling instructions <a name="linux-build-instructions"></a>
156

Arnaud Billon's avatar
Arnaud Billon committed
157
158
159
160
161
162
 - Note that the configuration command mentions the subdirectory "*Superbuild*" dir inside the source directory and not the source directory itself.
 - If you changed the default Qt installation path, you will have to adapt the configuration command.
 - Building from scratch can take from 45 minutes to 2 hours depending on your hardware.
 - By default `-j` will use all cores on your machine, but you can specify the number of cores to use with `-j N`.
 
    `cd <work-directory>`
163

Arnaud Billon's avatar
Arnaud Billon committed
164
    `git clone <git url to LidarView-based app repository> --recursive src`
165

Arnaud Billon's avatar
Arnaud Billon committed
166
    `mkdir <work-directory>/build`
167

Arnaud Billon's avatar
Arnaud Billon committed
168
    `cd <work-directory>/build`
169

Arnaud Billon's avatar
Arnaud Billon committed
170
171
172
173
174
175
176
177
178
179
180
     - If you installed Qt5 through your package manager, simply use:
     
    `cmake <work-directory>/src/Superbuild -GNinja -DCMAKE_BUILD_TYPE=Release -DUSE_SYSTEM_qt5=True`
    
     - Otherwise, also specify this path from the offline installer:
    
    `cmake <work-directory>/src/Superbuild -GNinja -DCMAKE_BUILD_TYPE=Release -DUSE_SYSTEM_qt5=True -DQt5_DIR="/opt/Qt/Qt5.12.9/5.12.9/msvc2015_64/lib/cmake/Qt5"`
    
    `cmake --build . -j`
    
    `./install/bin/<LidarView-based app name>`
181

Arnaud Billon's avatar
Arnaud Billon committed
182
## Enabling additional LidarView features <a name="enabling-additional-lidarview-features"></a>
183

Arnaud Billon's avatar
Arnaud Billon committed
184
**Enable SLAM features**
185

Arnaud Billon's avatar
Arnaud Billon committed
186
187
188
 - Run or re-run CMake configuration command with these additional parameters:
 
    `-DENABLE_ceres=True -DENABLE_nanoflann=True -DENABLE_pcl=True -DLIDARVIEW_BUILD_SLAM=True`
189

Arnaud Billon's avatar
Arnaud Billon committed
190
191
192
 - Run or re-run CMake build command.
 
    `cmake --build . -j`
193

Arnaud Billon's avatar
Arnaud Billon committed
194
  More info about SLAM is available at [How to SLAM with LidarView](https://gitlab.kitware.com/keu-computervision/slam/-/blob/master/paraview_wrapping/doc/How_to_SLAM_with_LidarView.md).
195

MelanieCarriere's avatar
MelanieCarriere committed
196

Arnaud Billon's avatar
Arnaud Billon committed
197
**Enable OpenCV features**
MelanieCarriere's avatar
MelanieCarriere committed
198

Arnaud Billon's avatar
Arnaud Billon committed
199
200
201
202
203
 - Install OpenCV
 
    Get it at <https://opencv.org/>
    
    On UNIX you can use: `sudo apt-get install libavformat-dev libavdevice-dev libavcodec-dev`
MelanieCarriere's avatar
MelanieCarriere committed
204

Arnaud Billon's avatar
Arnaud Billon committed
205
206
207
 - Run or re-run CMake configuration command with these additional parameters:
 
    `-DENABLE_opencv=True`
MelanieCarriere's avatar
MelanieCarriere committed
208

Arnaud Billon's avatar
Arnaud Billon committed
209
210
211
 - Run or re-run CMake build command.
 
    `cmake --build . -j`
Arnaud Billon's avatar
Arnaud Billon committed
212

Arnaud Billon's avatar
Arnaud Billon committed
213
## Incremental build instructions <a name="incremental-build"></a>
214

Arnaud Billon's avatar
Arnaud Billon committed
215
 - If you modified only LidarView sources, you may want to build incrementally as it is much faster than the full build command:
216

Arnaud Billon's avatar
Arnaud Billon committed
217
    `cd <work-directory>\build\common-superbuild\lidarview\build`
218

Arnaud Billon's avatar
Arnaud Billon committed
219
    `cmake --build . -j --target install`
220

221
## Packaging instructions <a name="packaging"></a>
MelanieCarriere's avatar
MelanieCarriere committed
222

Arnaud Billon's avatar
Arnaud Billon committed
223
 - Activate the build of tests through a CMake configuration:
224

Arnaud Billon's avatar
Arnaud Billon committed
225
    `cd <work-directory>/build`
226
227
228

    `cmake . -DBUILD_TESTING=True`

Arnaud Billon's avatar
Arnaud Billon committed
229
 - Build with the new configuration:
230

Arnaud Billon's avatar
Arnaud Billon committed
231
    `cmake --build . -j`
232

Arnaud Billon's avatar
Arnaud Billon committed
233
 - Package using cpack:
234

Arnaud Billon's avatar
Arnaud Billon committed
235
    `ctest`
236

Arnaud Billon's avatar
Arnaud Billon committed
237
238
## Testing instructions <a name="testing"></a>
Detailed Instructions to run LidarView-based app Tests: [LidarView Testing Guide](LidarPlugin/Testing/README.md).
239

Arnaud Billon's avatar
Arnaud Billon committed
240
## Troubleshooting / FAQ <a name="faq-instructions"></a>
241

Arnaud Billon's avatar
Arnaud Billon committed
242
### Superbuild failure with PCL enabled
243

Arnaud Billon's avatar
Arnaud Billon committed
244
Depending on your hardware, when enabling (`-DENABLE_pcl=True`) the superbuild might fail during PCL compilation with an *Internal compiler error* due to intense memory allocation.
245

Arnaud Billon's avatar
Arnaud Billon committed
246
247
248
To work aroudn this issue you can try:
 - Re-running the build command, as successive incremental builds may eventually succeed.
 - Lowering the number of compilation jobs in the build command using the `-j N` option.