-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathREADME.html
509 lines (355 loc) · 22.5 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
<HEAD>
<TITLE>FUSION3D 3D TERRAIN VISUALIZATION TOOL</TITLE>
</HEAD>
<BODY>
<H1>FUSION3D README</H1>
<HR>
<H2>INDEX</H2>
<UL>
<LI><A HREF="#fusion3d_intro">Fusion3D 3D Terrain Visualization Tool</A>
<P>
<LI><A HREF="#fusion3d_org">Organization</A>
<P>
<LI><A HREF="./LICENSE.txt">Apache 2.0 License for Fusion3D</A>
<P>
<LI><A HREF="./README_SAMPLE_DATA.html">Sample 3D Terrain Map</A>
<P>
<LI><A HREF="#fusion3d_libs">External Libraries</A>
<P>
<LI><A HREF="#fusion3d_windows_vs">Building for Windows Using Premade Visual Studio Solution</A>
<P>
<LI><A HREF="#fusion3d_windows_cmake">Building for Windows Using CMake</A>
<P>
<LI><A HREF="#fusion3d_linux">Building for Linux Using CMake</A>
<P>
<LI><A HREF="#fusion3d_other">Other Issues</A>
<P>
</UL>
<H2><A NAME="fusion3d_intro">FUSION3D 3D TERRAIN VISUALIZATION TOOL</A></H2>
The Fusion3D viewer was written to provide the simplest, most natural and useful visualization of 3D terrain maps based on Digital Surface Models (DSMs).
It can fuse the DSM maps with orthophotos, point clouds and annotation overlays to increase their utility.
It has many features that facilitate visualization including the following:
<dl>
<dt>Built-in capability for 3D stereo display.
<dd>3D terrain data is a natural for 3D display, making the maps much easier to interpret.
Athough stereo is not in fashion at this moment, if you have access to the proper hardware, stereo dramatically improves the viewing experience.
The viewer automatically manages the stereo parameters, always keeping the stereo separation at comfortable levels and convergence at the depth of the screen
no matter how you zoom, pan or move around the scane.
<P>
<dt>A unique visualization approach.
<dd>gives a much more natural visualization of the terrain, avoiding the 'melted chocolate' look typical of other viewers.
This patented technique, described in more detail in the accompanying documentation, combines the best aspects DSMs and point clouds.
It provides a much more natural depiction of trees, bushes and small man-made objects like power lines, poles, fences and the like.
<P>
<dt>Fusion of DSMs with full-resolution orthophotos.
<dd>Orthophotos can have as much as 10 times the resolution of the associated DSMs.
Using them at full resolution provides crucial detail that complements the elevation information in the DSMs.
Many viewers force you to downsample the orthophoto to the resolution of the DSM.
<P>
<dt>Fusion of DSMs with point clouds.
<dd>The visualization technique used by Fusion3D allows both DSMs and point clouds to be displayed together without any preprocessing.
The DSM draping in other viewers that covers important point cloud features is avoided in this viewer.
<P>
<dt>Very large maps
<dd>The viewer handles province sized maps, allowing the user to zoom in and out and move freely without reloading map tiles.
Maps as large as 100km by 70km have been tested.
</dl>
<BR>
<BR>
<BR>
<img SRC="./doc/Tutorials/GettingStarted/StartAnaglyph.JPG" ALIGN=CENTER>
<BR>
<BR>
<BR>
The picture above shows part of a elevation map of Ottawa featuring a bridge and both rough areas with trees and smooth areas with grass and roads.
The data is a DSM (DSM only, no point clouds) captured with a lidar sensor.
The picture shows the anaglyph stereo 3D available with the Fusion3D viewer.
Of course the quadbuffered stereo, also supported, shows the scene in much higher quality.
<P>
The rendering of the bridge shows the advantages of the Fusion3D visualization technique where the standard approach of draping the DSM
obscures all the important bridge detail (see image below).
Trees look rough and approximate what you would see with a point cloud.
The smooth areas, however, remain smooth and unbroken even when you zoom in closely.
Contrast this with the image below as would be rendered with other viewers.
<P>
Also, note that there is a sign and a light pole on the right side of the road at the lower left of the picture.
The top edge of these were sampled by the lidar and they show up correctly in the Fusion3D rendering (just visible in this image).
In the draped image below, the poles look virtually identical to the trees and could easily be missed.
<BR>
<BR>
<BR>
<img SRC="./doc/Tutorials/GettingStarted/BridgeDraped.jpg" ALIGN=CENTER>
<BR>
<BR>
<BR>
The second picture shows the same bridge in Ottawa as it would be rendered with any other viewer that we know of.
These viewers drape the DSM with a single surface, causing the unnatural 'melted chocolate' look and obscuring detail.
<P>
<H2><A NAME="fusion3d_org">ORGANIZATION</A></H2>
The Fusion3D terrain viewer was developed internally at the US Army Research Laboratory.
As of November 2020, it is being transitioned to open source in the hope that it will be useful to a larger community.
The primary developer is Jeff Dammann and we would welcome comments or questions to him at [email protected].
We are hoping for interest in the viewer and, should that develop, we will develop a FAQ, a site for comments/questions, and other community structures.
<P>
There is a user's manual that can be accessed either through the 'Help' menu in the Fusion3D viewer
or by setting your browser to the file 'doc/index.html'.
In the user's manual there are PowerPoint tutorials on 'Getting Started' as well as other basic features.
<P>
There is a sample map provided in the distribution that includes both DSMs and point clouds.
This map is described in file 'README_SAMPLE_DATA.html'.
<P>
There is also a Reference Manual currently under development.
If there is interest, this manual will be added to the distribution.
<P>
Below are instructions for building the Fusion3D viewer.
Note that it does not require formal installation
A Visual Studio 2017 solution is provided as well as CMake files that have been tested on Windows and Linux (Ubuntu) system.
<P>
<H2><A NAME="fusion3d_libs">EXTERNAL OPEN-SOURCE LIBRARIES</A></H2>
<TABLE BORDER>
<CAPTION>External Open-Source Libraries for Fusion3D</CAPTION>
<TR><TH>Library<TH>Required<TH>Preprocessor<TH>Notes
<TR><TH> <TH> <TH>Flag <TH>
<TR><TD>Coin3d <TD>Required <TD>LIBS_COIN <TD>Core graphics library inplementing the OpenInventor API
<TR><TD>SoQt <TD>Required <TD>LIBS_SOQT <TD>Bridge library implementing OS-dependent OpenInventor functions through Qt
<TR><TD>Qt <TD>Required <TD>LIBS_QT <TD>Multi-platform operating system interface
<TR><TD>GDAL <TD>Required <TD>LIBS_GDAL <TD>General-purpose library for import/export of vector and raster file formats
<TR><TD>MrSID <TD>Required <TD>LIBS_MRSID <TD>Import only library for MrSID images (used for texturing the DEM maps)
<TR><TD>Libkml <TD>VS Debug Only<TD>LIBS_KML <TD>Import/export of KML files
<TR><TD>assimp <TD>Optional <TD>LIBS_ASSIMP <TD>No core functionality but necessary to overlay CAD models onto the maps
</TABLE
<BR><BR><BR>
<PRE>
1. Assimp library is required only to overlay CAD models onto the terrain maps.
It can import many CAD formats including .obj, COLLADA
2. GDAL includes a release version of the KML libraries
However, for Visual Studio Libkml is written to be internal to the calling code rather than accessed through a .dll,
the release libraries are inconsistent with the debug version, and a debug version of Libkml is required.
</PRE>
<H3></H3>
<H4><A NAME="fusion3d_libs_coin">COIN3D</A></H4>
Coin3d is the basic graphics library used by Fusion3D.
It is an independently-derived implementation of the OpenInventor API which is a high-level code based on OpenGL.
<P>
There are Coin3d binaries available for Windows (both 32- and 64-bit).
For other OSs, there are CMake files for building.
<P>
<H4><A NAME="fusion3d_libs_soqt">SOQT</A></H4>
The core of OpenInventor is OS independent as is the Coin3d library implementation.
Low-level OS-dependent functions are implemented in several bridge libraries.
SoQt is a bridge to Qt which in turn interfaces with a number of OSs.
(Quarter is a newer bridge library to Qt but is lighter weight and does not have some of the key viewer functionality that Fusion3D depends on.)
<P>
There are SoQt binaries available for Windows (both 32- and 64-bit).
For other OSs, there are CMake files for building.
<P>
<H4><A NAME="fusion3d_libs_qt">QT</A></H4>
There are Qt binaries available for Windows (both 32- and 64-bit) and other common OS configurations.
Also, there CMake files for building.
<P>
<H4><A NAME="fusion3d_libs_gdal">GDAL</A></H4>
There are GDAL binaries available for Windows (both 32- and 64-bit), Mac and a variety of Linux variants.
As far as I can find, only Release binaries are available.
<P>
<H4><A NAME="fusion3d_libs_mrsid">MRSID</A></H4>
There are MrSID binaries available for Windows and Visual Studio 2019/2017/2015/2013 (both 32- and 64-bit).
For Linux (GCC), Mac (Clang), IOS (Clang) and Android (GCC).
<P>
<H4><A NAME="fusion3d_libs_assimp">ASSIMP</A></H4>
There are virtually no Assimp binaries available for any OS
However, there are well-maintained CMake files for building.
<P>
<H2><A NAME="fusion3d_windows_vs">BUILDING FOR WINDOWS AND VISUAL STUDIO</A></H2>
<TABLE BORDER>
<CAPTION>External Open-Source Libraries for Windows</CAPTION>
<TR><TH>Library<TH>Version<TH>Release<TH>Debug<TH>Notes
<TR><TH> <TH>Tested <TH> <TH> <TH>
<TR><TD>Coin3d <TD>4.0 <TD>Required <TD>Required <TD>Core graphics library inplementing the OpenInventor API
<TR><TD>SoQt <TD>1.6.0 <TD>Required <TD>Required <TD>Bridge library implementing OS-dependent OpenInventor functions through Qt
<TR><TD>Qt <TD>5.12.6<TD>Required <TD>Required <TD>Multi-platform operating system interface
<TR><TD>GDAL <TD>2.4.0 <TD>Required <TD>Required <TD>General-purpose library for import/export of vector and raster file formats
<TR><TD>MrSID <TD>9.5.4 <TD>Required <TD>Required <TD>Import only library for MrSID images (used for texturing the DEM maps)
<TR><TD>Libkml <TD>2.2 <TD>Not Needed<TD>Required <TD>Import/export of KML files
<TR><TD>assimp <TD>5.0.1 <TD>Optional <TD>Optional <TD>No core functionality but necessary to overlay CAD models onto the maps
</TABLE
<BR><BR><BR>
<pre>
Set environment variable to provide the path to platform-specific plugins:
QT_QPA_PLATFORM_PLUGIN = <path to Qt library like msvc2017_64>\plugins\platforms
</pre>
<H2><A NAME="fusion3d_windows_vs">BUILDING FOR WINDOWS AND VISUAL STUDIO -- PREMADE VISUAL STUDIO SOLUTION</A></H2>
The premade solution is set up to build both Release and Debug in x64.
It is included in subdirectory build/msvc2017.
The Visual Studio solution can be extended to x86 but this will require extra editing.
<P>
Building with Visual Studio and Qt requires that the Visual Studio Qt Addin be installed.
This addin is available free as a .vsix file that will automatically install when opened.
<P>
The following changes will probably have to be made to the solution:
<PRE>
The optional Assimp library:
Library included in the premade solution
To remove it:
All Projects -> Properties -> C/C++ -> Preprocessor -> Preproc Defs: Delete LIBS_ASSIMP
Fusion3D/TestAdelaide Projects -> Properties -> Linker -> Input: delete assimp-vc141-mt.lib
Modify paths to Include Directories for the external libraries listed above
lfusion3d Project -> Properties -> C/C++ -> General -> Additional Include Dirs: modify paths
Modify paths to Library Directories for the external libraries listed above
Fusion3D/TestAdelaide Projects -> Properties -> Linker -> General: modify paths
</PRE>
<H2><A NAME="fusion3d_windows_cmake">BUILDING FOR WINDOWS AND VISUAL STUDIO -- USING CMAKE</A></H2>
The basic approach to CMake taken here is to keep the CMake file simple and direct.
With apologies to CMake experts, this will require more editing of the CMake files but should be simpler
for non-experts and hopefully more robust.
The user will have to edit some paths to external libraries and perhaps some basic build configurations before running CMake.
<P>
First, the external libraries are built separately rather than being built within the Fusion3D CMake structure.
In many cases, the easiest way to get the libraries is to get the binaries.
Also, the Coin and SoQt libraries are not heavily maintained and may have issues building with CMake.
It should be easier to deal with potential problems building them separately.
Paths to the external libraries are defined near the top of the root CMake file and must be edited
to point the the installed location of the libraries.
<P>
Second, Visual Studio by convention builds multiple configurations in the same solution.
Typically, these are 'x86' (the 32-bit version) 'Release' and 'Debug' and 'x64' (the 64-bit version) 'Release' and 'Debug'.
The default in the root CMakeLists.txt is to build both Release and Debug for x64.
At the top of that file you can choose instead to build a single configuration or to build x86.
<P>
The Visual Studio solution will have the correct parameters for the chosen configurations, but parameters
for other configurations will be wrong.
One can either generate separate Visual Studio Solutions for each configuration or modify the single
Visual Studio solution for other configurations.
Most of the necessary parameters, particularly ones internal to Visual Studio, are modified appropriatly.
Others, like external library '.lib' files will be copied without changes and will need to be edited.
<P>
<PRE>
Building with Visual Studio and Qt requires that the Visual Studio Qt Addin be installed.
This addin is available free as a .vsix file that will automatically install when opened.
CMake for Windows/VisualStudio requires the UCRT SDK (Universal C Runtime Library)
If it does not find this, then it will not find the C++ compiler and abort
This should be standard in Windows10 but is an optional component of Visual Studio and may need an additional install
</PRE>
<H3><A NAME="fusion3d_windows_cmake_gui">Using the CMake GUI</A></H3>
<PRE>
Editing the CMake file
As described in more detail above, the root CMake file must be edited to establish the basic
configuration and pathnames to libraries will also have to be modified.
Basic GUI parameters:
Where is the source code: The Fusion3D root directory (with root CmakeLists.txt file)
Where to build the binaries: Conventionally this is done in a Fusion3d subdirectory like 'build'
After pressing Configure button, on the resulting submenu:
Specify the generator for this project: From the pulldown, enter the IDE or compiler of choice
Optional platform for generator (if empty, uses Win32):
For x64, select 'x64' from the pulldown menu
Generate: This should create a Visual Studio solution
Comments:
Choosing the x64 platform from the submenu will cause Visual Studio to default to 64-bit configuration
(both Release and Debug). As described above, the x86 Release/Debug can also be generated from
the single Visual Studio solution. Parameters for the chosen configuration will be correct, but
other configurations will not. Some of the parameters will be correctly modified but others
will have to be edited by hand.
</PRE>
<H3><A NAME="fusion3d_windows_cmake_cl">Using the CMake Command Line</A></H3>
<PRE>
1. Go to Fusion3D root directory (with root CmakeLists.txt file)
2. For x64 Release/Debug
cmake -A x64 -H"." -B"./build"
For x86 Release/Debug (Visual Studio defaults to x86)
cmake -H"." -B"./build"
</PRE>
<H2><A NAME="fusion3d_linux">BUILDING FOR LINUX USING CMAKE</A></H2>
Fusion3D was tested on Ubuntu Linux version 16.04 and the Code::Blocks IDE.
<P>
<H3><A NAME="fusion3d_libs">External Libraries for Linux</A></H3>
<TABLE BORDER>
<CAPTION>External Open-Source Libraries for Fusion3D</CAPTION>
<TR><TH>Library<TH>Version<TH>Required<TH>Method<TH>Package<TH>Notes
<TR><TH> <TH>Tested <TH> <TH> <TH> <TH>
<TR><TD>Coin3d <TD>4.0 <TD>Required <TD>Made from source using CMake<TD> <TD>Core graphics library inplementing the OpenInventor API
<TR><TD>SoQt <TD>1.6.0 <TD>Required <TD>Made from source using CMake<TD> <TD>Bridge library for OS-dependent OpenInventor functions through Qt
<TR><TD>Qt <TD>5.5.1 <TD>Required <TD>Ubuntu standard install <TD>qt5-default <TD>Multi-platform operating system interface
<TR><TD>GDAL <TD>2.2.1/3.0.4<TD>Required <TD>Ubuntu standard install <TD>libgdal-dev <TD>General-purpose library for import/export of vector/raster formats
<TR><TD>MrSID <TD>9.5.4 <TD>Required <TD>Download bin from Lizardtech<TD> <TD>Import only library for MrSID images (used for texturing DEM maps)
<TR><TD>Libkml <TD> <TD>Not Needed<TD>Should be included in GDAL <TD> <TD>Import/export of KML files
<TR><TD>assimp <TD>3.2 <TD>Optional <TD>Ubuntu standard install <TD>libassimp-dev<TD>No core functionality but necessary to overlay CAD onto maps
</TABLE
<BR><BR><BR>
<PRE>
1. It is important that Qt be installed using the standard Ubuntu install procedure ('sudo apt-get install qt5-default') rather than downloaded
from the Qt website using their online installer. Otherwise there can be errors Qt platform plugin cant be found/loaded.
</PRE>
<H3><A NAME="fusion3d_libs">Linking External Library .so Files</A></H3>
You will need to link the Fusion3D executable to external library .so files for any external libraries that have not been installed and are already in standard locations.
One can copy or link the .so files into the /usr/lib (or other standard location of choice) or one can do the following:
<P>
<PRE>
In /etc/ld.conf.so
Create file 'randomLibs.conf'
Enter complete pathnames to all required .so files (eg. /home/arl/coin-4.0.0-x64/lib)
Update the the system by running
sudo ldconfig
</PRE>
<H3><A NAME="fusion3d_libs">Required Changes to Main CMake File CMakeLists.txt </A></H3>
The main CMake file Fusion3D/CMakeLists.txt is configured for Windows/Visual Studio and external libraries that are stored locally rather than installed.
This file must be edited to work on Linux, but the edits should not be difficult.
Roughly, they are as follows:
<P>
<PRE>
1. As provided, both Debug and Release versions are made simultaneously to be combined into a single Visual Studio solution.
Command line CMake and many linux IDEs like Code::Blocks allow only one Debug/Release version at a time.
Uncomment the line to make the desired option:
# set(CMAKE_BUILD_TYPE Release) # Debug / Release
2. Set the desired install directory by modifying the following line:
set(CMAKE_INSTALL_PREFIX "C:/Fusion3D") #
3. Some external libraries like GDAL and KML will probably be installed so CMake will find them in standard directories
In this case, you can modify the lines that cause CMake to look for them in specified directories:
option(ADD_DIRS_GDAL "Libs and includes not in default dirs -- GDAL" OFF)
option(ADD_DIRS_KML "Libs and includes not in default dirs -- KML" OFF)
4. Other external libraries like Coin and SoQt may not be installed
In this case do not modify lines like
option(ADD_DIRS_COIN "Libs and includes not in default dirs -- Coin" ON)
The path to the library will have to be modified and one would need to edit the line:
set(PATH_COIN "C:/coin-4.0.0-msvc15-x64/Coin3D")
</PRE>
<H2><A NAME="fusion3d_other">OTHER ISSUES</A></H2>
<H3><A NAME="fusion3d_libs">MrSID Linux Version Problems with Newer Compilers</A></H3>
The latest (Oct 2020) download of the MrSID SDK for linux generates compile errors for gcc compiler versions greater than version 5.
It was verified with gcc version 5, checks the gcc version number and will not compile for newer gcc versions.
The best fix for this problem is to edit a .h file in the MrSID distribution:
<PRE>
In file: <install dir>\MrSID_DSDK-9.5.4.4709-win64-vc15\Raster_DSDK\include\lt_platform.h
Change line: #if (defined(__GNUC__) || defined(__GNUG__)) && (3 <= __GNUC__ && __GNUC__ <= 5)
To line: #if (defined(__GNUC__) || defined(__GNUG__)) && (3 <= __GNUC__ && __GNUC__ <= 9) // Any number >= to current compiler version
</PRE>
If this is not possible, then you can redefine the the __GNUC__ value in the internals.h file like the following
<PRE>
#define __GNUC__ 5
</PRE>
This will generate warnings but it appears it has no ill effect.
<P>
<H3><A NAME="fusion3d_libs">GDAL Environment Variables</A></H3>
The GDAL library requires an environment variable GDAL_DATA that points to text files that are used to help implement
the large variety of potential coordinate systems.
As of GDAL 3.0, a second environment variable is also required: PROJ_LIB which must point to the directory that has the file proj.db.
As of this rev, GDAL uses the Proj library to help determine coordinate systems.
<P>
If GDAL is installed then this environment variable may be set, but if it is not then try the following options:
<PRE>
GDAL_DATA should point to a subdirectory supplied with the GDAL distribution where various .csv files and other text files
describe various coordinate systems (directory 'gdal_data' in some Windows distributions, 'share/gdal' in some linux distributions).
PROJ_LIB should be the path to the file proj.db (not including the filename itself).
1. If possible, add the definitions to the system or user environment variables.
For linux, add the paths to the file '/etc/environment' something like
GDAL_DATA="/usr/share/gdal"
PROJ_LIB="/usr/share/proj"
Restart or otherwise ensure that the new environment variables are incorporated
2a. If GDAL_DATA is unset at runtime, Fusion3D will set it to a subdirectory within the install directory
GDAL_DATA=<install-dir>/Fusion3D/bin/GDAL/gdal-data
This works on Windows for the Release version of the code but not the Debug version
2b. If PROJ_LIB is unset at runtime, Fusion3D will set it to a subdirectory within the install directory
PROJ_LIB=<install-dir>/Fusion3D/bin/GDAL/proj6/share
This works on Windows for the Release version of the code but not the Debug version
3. For Windows and Visual Studio, you can set an environment variable within Visual Studio
Project Properties -> Configuration Properties -> Debugging -> Environment
set environment variable (eg GDAL_DATA=C:\Fusion3D\bin\GDAL\gdal-data)
</PRE>