Assignment 03

Plane detection with RANSAC

Deadline is 2021-01-18 10:00am

Late submission? 10% will be removed for each day that you are late.

You’re allowed for this assignment to work in a group of 2 (and thus submit only one solution for both of you). If you prefer to work alone it’s also fine.

• Changelog
• Overview
• The code
  • To compile and run the program
    • Windows
    • Mac
    • Linux
• The output format
• Good to know
• What to submit and how to submit it
• Marking

Changelog

• 04-01-2021
  • fixed problem with provided dataset (there was a decimal rounding error). Make sure to use the latest PLY files from gitlab! (and the ahn3.ply)
  • add bk_sub25m.ply dataset for testing, this is a 25x25 meter crop from bk.ply.
  • add 2 more tips in the Good to know section
• 24-12-2020
  • make project easier to install
  • add more detailed installation instructions

Overview

The aim of this assignment is to implement and improve/extend the RANSAC algorithm for plane detection in a point cloud as described in Section 12.5.1 of the book.

You will need to implement the RANSAC algorithm in such a way that multiple planes can be detected in the point cloud. The point cloud is read from an ASCII PLY file (see Section 12.1.2), and the final result should also be written to an ASCII PLY file. In the output PLY file, each point should be labeled with a segment_id that indicates to which plane that point belongs.

This assignment must be implemented in C++.

Too aid you with inspecting the output of your RANSAC implementation the code contains a simple 3D viewer that you can use to inspect your output. See the figure below.

I gave a live introduction the assignment on december 18 2020, you can find the recording on surfdrive starting at 38:50.

The code

Code is in the /hw/03/ folder of the GitLab repository of the course. I recommend that you use git to clone the repository to your machine.

We give you the skeleton of the program:

1. /src/main.cpp is contains the main() function where the execution of the program starts. You do not need to modify this file (except for adding your name in the header).
2. /src/PlaneDetector.h declares the PlaneDetector class that holds all the important functions for this assignment. You may modify this class to add your own variables/functions.
3. /src/PlaneDetector.cpp this is where most of your implementation should go. It contains the implementation of the functions declared in PlaneDetector.h. You need to complete at least the detect_plane() and the write_ply() functions. See the source code for more information on these functions.
4. /data/params.json: a simple JSON file that defines the input and output PLY files and the RANSAC parameters (parameters are explained in PlaneDetector.cpp above the detect_plane() function).
5. /data/*.ply: contains several input files that you can use, and one example output file (bk_example_output.ply) that contains the segment_id property.

The input file params.json doesn’t need to be validated (no wrong parameters can be in a given file), and the input/output and parameters are also valid.

To compile and run the program

Below are instruction to get you up and running from scratch. It is highly recommended that you use an IDE with debug functionality such as CLion (all platforms) or Visual Studio 2019 (windows only).

Once you have succesfully completed the instructions below (and you have the point viewer running) you can start editing the source files.

Windows

1. Download and install Visual Studio 2019 Community Edition (not Visual Studio Code, this is a different program). Make sure to select the component Desktop Development with C++ during the installation.

2. Open Visual Studio 2019. In the start-up screen choose for Open a local folder. Choose the /hw/03 folder.

3. Select hw03.exe as the Startup Item, as shown below  

4. Compile and run the program by pressing the button with the green triangle. After compiling has finished you should see the built-in point cloud viewer with a point cloud of the BK building.

Alternatively you can also use CLion on windows, but you still need to install Visual Studio 2019 for the C++ compiler (Other compilers like MinGW, Cygwin are not recommended).

Mac

1. Open a terminal window and type xcode-select --install to install the C++ compiler on your system.

2. Install homebrew and enter the command brew install sdl2 in the terminal.

3. Install CLion (you can request a free education license).

4. Open CLion, click the Open button and select the /hw/03 folder (do not create a new project).

5. Select the hw03 target as shown below.  

6. Compile and run the program by pressing the button with the big green triangle. After compiling has finished you should see the built-in point cloud viewer with a point cloud of the BK building.

Linux

Similar to Mac only step 1 and 2 are different depending on your distribution (eg. on ubuntu you would use apt-get to install the C++ compiler and sdl2).

The output format

Your output file has to be an PLY file as explained in the book (Section 12.1.2). In addition to the point coordinates it should contain a property segment_id of type int. This property indicates for each point to which plane it belongs (as each plane should have a unique segment_id).

ply
format ascii 1.0
element vertex 10000
property float x
property float y
property float z
property int segment_id
end_header
85176.77 446742.10 1.49 0
85175.69 446742.58 1.52 1
85174.45 446741.94 9.52 1

Note that the value segment_id==0 is special! This means a point does not belong to any plane. The segment_id’s of your planes should thus start at 1. See the /data/bk_example_output.ply file for an example.

Good to know

• the linalg.h library is included in the project. This library makes it easier to do basic linear algebra operations.
• you are allowed to use all the modules from the C++ standard library (C++17). If you want to use something else ask me first.
• you can override what .json file is loaded by specifying it as the first argument to the program (on command line or in the settings of your IDE).
• you may assume the input coordinates are always in meters
• to check if your output PLY file is correct you can open it in CloudCompare or simply use the integrated 3D viewer (set n_planes=0 in params.json to just read and show the file).
• start testing and developing your code with the bk_sub25m.ply dataset. Once you get good results on this dataset, start testing with the others (bk.ply and ahn3.ply).
• to get good plane detection results with the bk.ply and ahn3.ply datasets you need to improve/extend the basic RANSAC algorithm from the book.

What to submit and how to submit it

You have to submit a total of 4 files:

1. the C++ files main.cpp, PlaneDetector.h and PlaneDetector.cpp, where your names are clearly identified at the top of the file.
2. your optimal parameters for the bk.ply dataset: params-bk.json and the resulting output file out-bk.ply. Optimal here means a good trade-off between the number of detected planes, the quality of the detected planes, and a reasonable running time.
3. your optimal parameters for the ahn3.ply dataset: params-ahn3.json and the resulting output file out-ahn3.ply
4. a PDF document (no Word file please) where you elaborate specifically on these 4 items (make one section per item and use figures to illustrate):
   • How does your implementation work? Give a brief overview.
   • Did you encounter any unexpected results? Eg. planes fitted to points where you don’t want it. Show examples and explain why that happened.
   • How did you choose the optimal parameters for the bk.ply dataset? Why are they optimal?
   • How did you choose the optimal parameters for the ahn3.ply dataset? Are they different from bk.ply? Why (not)?
   • Reflect on the time-efficiency of your implementation. The basic RANSAC algorithm as given in the book is not particularly time efficient. Why is this? How do you think you could make the basic RANSAC algorithm faster without compromising the quality of the results?

Those 8 files need to be zipped and the name of the file consists of the studentIDs of the members separated by a “_”, for example 5015199_4018169.zip.

Upload the ZIP file to this surfdrive page.

Marking

[last updated: 2020-12-24 9:30]