added documentation + cleanup

3d-scanner.cpp

@@ -101,13 +101,12 @@ catch (const std::exception &e)
 void configure_filters(rs2::decimation_filter &dec_filter, rs2::threshold_filter &thr_filter, rs2::spatial_filter &spat_filter, int dec_filter_magnitude, float min_dist, float max_dist, int magnitude, int smooth_alpha, int smooth_delta, int holes_fill)
 {
     dec_filter.set_option(RS2_OPTION_FILTER_MAGNITUDE, dec_filter_magnitude);
-    thr_filter.set_option(RS2_OPTION_MIN_DISTANCE, min_dist);             // 0.0
-    thr_filter.set_option(RS2_OPTION_MAX_DISTANCE, max_dist);             // 0.5
-    spat_filter.set_option(RS2_OPTION_FILTER_MAGNITUDE, magnitude);       // 5
-    spat_filter.set_option(RS2_OPTION_FILTER_SMOOTH_ALPHA, smooth_alpha); // 1
-    spat_filter.set_option(RS2_OPTION_FILTER_SMOOTH_DELTA, smooth_delta); // 1
-    spat_filter.set_option(RS2_OPTION_HOLES_FILL, holes_fill);            // 5
-    // hole_filter.set_option(RS2_OPTION_HOLES_FILL, 1); //1
+    thr_filter.set_option(RS2_OPTION_MIN_DISTANCE, min_dist);
+    thr_filter.set_option(RS2_OPTION_MAX_DISTANCE, max_dist);
+    spat_filter.set_option(RS2_OPTION_FILTER_MAGNITUDE, magnitude);
+    spat_filter.set_option(RS2_OPTION_FILTER_SMOOTH_ALPHA, smooth_alpha);
+    spat_filter.set_option(RS2_OPTION_FILTER_SMOOTH_DELTA, smooth_delta);
+    spat_filter.set_option(RS2_OPTION_HOLES_FILL, holes_fill);
 }
 
 /* Apply filters.
@@ -127,7 +126,6 @@ void apply_filters(rs2::decimation_filter &dec_filter, rs2::threshold_filter &th
     depth_frame = depth_to_disparity.process(depth_frame);
     depth_frame = spat_filter.process(depth_frame);
     depth_frame = disparity_to_depth.process(depth_frame);
-    // filtered = hole_filter.process(depth_frame);
 }
 
 ColoredPoints scan(rs2::decimation_filter &dec_filter, rs2::threshold_filter &thr_filter, rs2::spatial_filter &spat_filter, rs2::disparity_transform &depth_to_disparity, rs2::disparity_transform &disparity_to_depth, rs2::pipeline &pipe)
@@ -160,8 +158,6 @@ void scan_and_convert(rs2::decimation_filter &dec_filter, rs2::threshold_filter
     ColoredPoints scanned_points = scan(dec_filter, thr_filter, spat_filter, depth_to_disparity, disparity_to_depth, pipe);
     std::cout << "\nConverting... ";
     PCLHelper::PtrCloud converted_points = PCLHelper::points_to_pcl(scanned_points.points, scanned_points.color);
-    // PCLHelper::PtrCloud cropped_points = PCLHelper::crop_cloud(converted_points, -0.15, -0.2, 0.0, 0.15, 0.05, 0.3);
-    // pointclouds.push_back(cropped_points);
     pointclouds.push_back(converted_points);
 }
 

CMakeLists.txt

@@ -1,12 +1,9 @@
-#  minimum required cmake version: 3.1.0
 cmake_minimum_required(VERSION 3.1.0)
 
 project(3d-scanner)
 
-# Save the command line compile commands in the build output
 set(CMAKE_EXPORT_COMPILE_COMMANDS 1)
 
-# Make project require C++11
 include(CheckCXXCompilerFlag)
 CHECK_CXX_COMPILER_FLAG("-std=c++11" COMPILER_SUPPORTS_CXX11)
 CHECK_CXX_COMPILER_FLAG("-std=c++0x" COMPILER_SUPPORTS_CXX0X)
@@ -17,54 +14,17 @@ elseif(COMPILER_SUPPORTS_CXX0X)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++0x")
 endif()
 
-# commented all Windows related lines, might add later for Windows support
-
-# Simple non robust way to find the librealsense library
-# if(WIN32)
-#     if("${CMAKE_SIZEOF_VOID_P}" STREQUAL "8")
-#         set(LIBRARY_DIR "C:\\Program Files (x86)\\Intel RealSense SDK 2.0\\lib\\x64")          # TODO: Update this variable to correct path - folder where realsense2.lib is found
-#         set(DLL_DIR "C:\\Program Files (x86)\\Intel RealSense SDK 2.0\\bin\\x64")              # TODO: Update this variable to correct path - folder where realsense2.dll is found
-#     else()
-#         set(LIBRARY_DIR "C:\\Program Files (x86)\\Intel RealSense SDK 2.0\\lib\\x86")          # TODO: Update this variable to correct path - folder where realsense2.lib is found
-#         set(DLL_DIR "C:\\Program Files (x86)\\Intel RealSense SDK 2.0\\bin\\x86")              # TODO: Update this variable to correct path - folder where realsense2.dll is found
-#     endif()
-#     set(PROJECT_BINARY_OUTPUT_PATH "${PROJECT_BINARY_DIR}/\$\(Configuration\)")                # TODO: Update this variable to correct path - folder to which your project will compile
-#     set(ADDITIONAL_INCLUDE_DIRS "C:\\Program Files (x86)\\Intel RealSense SDK 2.0\\include")   # TODO: Update this variable to correct path - folder where librealsense2 folder is found
-# endif()
-
-
-# find_library(REALSENSE2_FOUND realsense2 HINTS ${LIBRARY_DIR} REQUIRED)
-# if(NOT REALSENSE2_FOUND)
-#     SET(REALSENSE2_FOUND "realsense2")
-#     message(WARN "Failed to find_library(realsense2)")
-# endif()
 find_package(realsense2 REQUIRED)
 find_package(PCL 1.3 REQUIRED)
-# find_package(GLFW3 REQUIRED)
 
-# set(SOURCES 3d-scanner.cpp ${CMAKE_CURRENT_SOURCE_DIR}/thirdParty/openglHelper.hpp)
 include_directories(${PCL_INCLUDE_DIRS})
 link_directories(${PCL_LIBRARY_DIRS})
 add_definitions(${PCL_DEFINITIONS})
 add_executable(3d-scanner 3d-scanner.cpp pcl-helper.cpp) 
 include_directories(3d-scanner ${realsense2_INCLUDE_DIR})
-# include_directories(${CMAKE_CURRENT_SOURCE_DIR}/thirdParty)
-# include_directories(/opt/homebrew/include/)
-# target_link_libraries(3d-scanner ${DEPENDENCIES})
 target_link_libraries(3d-scanner ${PCL_LIBRARIES})
 target_link_libraries(3d-scanner ${realsense2_LIBRARY})
-# target_link_libraries(3d-scanner glfw)
-# set_target_properties (3d-scanner PROPERTIES FOLDER Examples)s
 
-# Post Build script to copy realsense2.dll
-# if(WIN32)
-# message(STATUS "Adding Post build script to copy realsense2.dll to project's binary folder")
-# message(STATUS "Will try to copy from ${DLL_DIR} to ${PROJECT_BINARY_OUTPUT_PATH}")
-# add_custom_command(TARGET 3d-scanner POST_BUILD        # Adds a post-build event to 3d-scanner
-#     COMMAND ${CMAKE_COMMAND} -E copy_if_different              # which executes "cmake - E copy_if_different..."
-#         "${DLL_DIR}/realsense2.dll"                            # <--this is in-file
-#         ${PROJECT_BINARY_OUTPUT_PATH})                 # <--this is out-file path
-# endif()
 
 install(
     TARGETS

README.md

@@ -22,13 +22,68 @@ Execute the compiled project (use sudo when on macOS, see *known issue(s)*)
 ./3d-scanner
 ```
 
+## How to use
+After startup you will be presented with a small Menu:
+```bash
+Welcome to the 3d-scanner, choose your option: 
+(1) Scan
+(2) Align and save pointclouds
+(3) Wipe old scans
+(4) exit 
+```
+
+(1) - will do exactly one scan in the current position and sae it. You will have to do multiple scans from different perspectives to align them later on.
+
+(2) - will take your scans and use the iterative closest point algorithm to stitch them together (this takes ages in the current version and definitly needs improvement). After the stitching is finished the scans will be saved seperately in the "scans_fitted" folder and the originals will be saved in the "scans_original" folder as .ply files.
+
+Afterwards all the aligned files can be imported in a programm which allows viewing .ply files (like Meshlab).
+
+(3) - will delete all scans scince startup
+
+(4) - will shutdown the 3d-scanner
+
+## How it works
+
+#### 1. scanning
+When scanning an object, the intel realsense camera will take multiple pictures to adjust the autofocus. Then the software extracts the depth image, appliies a couple of filters to enhance the image and finally creates a pointcloud from it. 
+
+This pointcloud will then be transformed from the "realsense" pointcloud format to the "pointcloudlibrary" format for further processing.
+
+Multiple scans will create multiple pointclouds.
+
+#### 2. alignment of multiple scans
+When there are multiple scans from more than one perspective they need alignment so they are not floating at different locations when viewing them. Therefore the iterative closest point alorithm is used. Simplified, this alorithm matches each point of one pointcloud to each point of the base pointcloud (the first scan) and then transforms it so its points are aligned with the base cloud to create a coherent scan.
+
+At the end of this process there are still as many pointclouds as scnans. However they are now aligned with each other.
+
+#### 3. saving the scans
+When the alignment is done, all the pointclouds will get exported as .ply files and saved in a folder named "scans_fitted".
+The original scans without alignment will be saved in a folder called "scans_original" beforehand.
+
+All of them need to get imported in Meshlab or a similar tool in order to view the whole scan.
+
+## What is there still to do?
+#### 1. everything is reaaaally slow
+- doing one scan takes a while, because its always necessary to take a couple of shots for the autofocus to settle
+    - How to fix it: Maybe it is possible to take all scnas by using one videostream instead of taking pictures 
+- the ICP Algorithm is the slowest part because it is not optimized yet
+    - How to fix it: Optimize the ICP by setting an initial matrix which guids it towards the right transformation. There shoudl also be a couple more options for optimization
+
+#### 2. improve the scan in order to improve the alignment
+- when the scan covers not only the desired object but also the floor or other surroundings the alignemnt doesnt work. Therefore the scan needs to get cropped or somehow seperated from its surroundings
+
+#### 3. transform the pointclouds to a mesh
+- currently all pointclouds are seperate .ply files at the end. However it would be nice to merge all of them together and then create a mesh from them.
+
+#### 4. an interface
+- When everything else works it would be great to have a grfaphical user interface to interact with the scanning software.
 
 ## known issue(s)
 
-On Mac there can occure either segmentation faults or a realsense error, that the program is waiting too long for frames, when running the executable.
+On Mac there can occure either segmentation faults or a realsense error (Timeout when waiting for camera frames) when running the executable.
 Somehow it will work again if you just execute the 3d-scanner-startup-helper often enough (this is basically the realsense hello-world example).
-This will also fail a lot with a segmentation faults but after a while it will work again. At least as long as the camera is connected, when reconnecting the error usually appears again.
+This will also fail a lot with segmentation faults but after a while it will work again. At least as long as the camera is connected, when reconnecting the error usually appears again.
 I am not sure if this Error is Mac specific or wheater I am doing something wrong. However I did not manage to resolve it properly.
-If you have any Idea what the reason could be, feel free to contact me.
+If you have any Idea what the reason could be, feel free to fix it.
 
 Another inconvenience I discovered on Mac is, that the executable can only be executed using `sudo`, otherwise it will always fail with a segmentation fault.

pcl-helper.cpp

@@ -29,8 +29,7 @@ PtrCloud PCLHelper::points_to_pcl(const rs2::points &points, const rs2::video_fr
     auto tex_coords = points.get_texture_coordinates();
     auto vertices = points.get_vertices();
 
-    // Iterating through all points and setting XYZ coordinates
-    // and RGB values
+    // Iterating through all points and setting XYZ coordinates and RGB values
     for (int i = 0; i < points.size(); ++i)
     {
         cloud->points[i].x = vertices[i].x;
@@ -65,7 +64,7 @@ int PCLHelper::icp(PtrCloud &cloud_target, PtrCloud &cloud_source, int iteration
 {
     std::cout << "\ntarget cloud size is: " << cloud_target->size() << std::endl;
     std::cout << "\nsource cloud size is: " << cloud_source->size() << std::endl;
-    // TODO: make faster
+    // TODO: make this faster
     // icp algo will align source pointcloud to fit target pointcloud
     pcl::IterativeClosestPoint<PointRGB, PointRGB> icp;
     icp.setMaximumIterations(iterations);

pcl-helper.hpp

@@ -26,5 +26,3 @@ public:
 private:
     static std::tuple<uint8_t, uint8_t, uint8_t> get_texcolor(rs2::video_frame texture, rs2::texture_coordinate texcoords);
 };
-
-// test