philipklaus / octree-cuda

Generate Potree compatible LOD data from 3D point clouds on the GPU using CUDA

About

PotreeConverterGPU generates Potree compatible LOD data structures from point clouds entirely on the GPU using CUDA.

The project is part of a master's thesis with the title In-core level-of-detail generation for point clouds on GPUs using CUDA and is conducted by the Technical Universe of Vienna in corporation with the AIT-Austrian Institute of Technology.

Project Status

This project is a research project!

Feature	Status	Comment
LOD Generation on GPU	✅	Done
Exporting Potree data	✅	Done
Implicit random point subsampling	✅	Done
Explicit random point subsampling	✅	Done
Intra-Cell color filtering	✅	Done
Inter-Cell color filtering	✅	Done
Inter-Cell color filtering + distance weighting	✅	Done
Unit Tests	☑	In Progress...
Source code documentation	☑	In Progress...
Ply Import	❌	Only prepared binary files can be imported and processed
LAZ Import	❌	Only prepared binary files can be imported and processed

Release version

Be aware that the master branch is constantly updated. Therefore you should checkout or download release versions. This releases also contain necessary input files (morrowbay.bin, heidentor.bin, coin.bin) .

Getting started

Building from source

Prerequirements

Name	Minimum Version	Link
CMAKE	3.10	https://cmake.org/
CUDA	11.4	https://developer.nvidia.com/cuda-downloads
Prepared point cloud files	-	Downloads
c++ 17 compiler	-	-

Building instructions

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ../
cmake --build . --config Release

Note:

• -DENABLE_KERNEL_TIMINGS=ON enables CUDA kernel timings (performance drawback)
• -DENABLE_KERNEL_ERROR_CHK=ON performs full error check after each CUDA kernel (performance drawback)

Running PotreeConverterGPU

Put the binary file(s) in the same folder as the PotreeConverterGPU executable and run the program with the following commands:

• morrowbay.bin

PotreeConverterGPU.exe -f morrobay.bin -o .\output -p 119701547 -d 27,0.01 -t double -g 512,128 -i

• heidentor.bin

PotreeConverterGPU.exe -f heidentor.bin -o .\output -p 25836417 -d 15,0.001 -t float -g 512,128 -i

• coin.bin

PotreeConverterGPU.exe -f coin.bin -o .\output -p 5138448 -d 15,0.001 -t float -g 512,128 -i

Program Arguments

Usage:
  PotreeConverterGPU [OPTION...]

  -f, --file arg              File name point cloud
  -a, --averaging-intra       Apply intra-cell color averaging
  -i, --averaging-inter       Apply inter-cell color averaging
  -w, --weight                Apply a weighting function during inter-cell color filtering
  -r, --random                Perform Explicit-Random-Subsampling, otherwise Implicit-Random-Subsampling is applied
  -o, --output arg            Output path for the Potree data
  -p, --points arg            Point amount of the cloud
  -t, --type arg              The datatype of the cloud coordinates: "float" / "double"
  -d, --data arg              Data infos for stride and scale: [float, float]
  -g, --grids arg             Grid sizes for chunking and subsampling: [int, int]
  -m, --merge_threshold arg   The merging threshold (default: 10000)
  -e, --estimated_output arg  The estimated output point amount factor (default: 2.2)
  -h, --help                  Print usage

Output

PotreeConverterGPU generates the following output files:

Filename	Description
hierarchy.bin	Contains information about octree nodes in binary form (required by Potree)
memory_report.html	A diagram which shows the total GPU memory consumption per cudamalloc and cudafree
metadata.json	Octree metadata and data description (required by Potree)
octree.bin	The binary lod cloud data (required by Potree)
point_distribution.html	A diagram which shows the point distribution in the leaf nodes
statistics.json	Octree related statistics and information

The resulting data can be directly rendered using PotreeDesktop.

Project structure

• External/ contains external tools and libraries
• OctreeApi/ Exposes the functionality from the OctreeLibrary using an C-API. The API is compiled to a shared library.
• OctreeApi/OctreeLibrary/ contains the actual LOD generation logic and CUDA kernels. It is compiled to a static library.
• src/ contains the PotreeConverterGPU project. This project builds an executable and links to the OctreeApi.

Python tools

The tools/ folder contains the following Python tools:

• potree_to_ply.py: a tool for converting Potree 2.0 data generated with PotreeConverterGPU into PLY files. A single PLY file is generate per LOD. An additional PLY file containing the content of all leaf nodes is also created.
• memory_consumption.ply: a tool for estimating the minimum required GPU memory space to process a point cloud with a specific amount of points.

External Tools/Libraries

Library	Description	Link
Catch2	Unit Testing framework	https://github.com/catchorg/Catch2
Cxxopts	Command line parsing	https://github.com/jarro2783/cxxopts
Nlohmann	JSON library	https://github.com/nlohmann/json
Spdlog	Logging library	https://github.com/gabime/spdlog

octree-cuda's Issues

Improve random subsampling

Up to now the random subsampling works by generating one random state for each subsampling cell.
Improvement:
Pre-generate 1024 random states (1024 is the maximum thread amount per block)

Support for arbitrary point clouds in gpu memory

Currently the implementation supports only float coordinates as the only attribute for each point.

The goal is to support multiple point attributes, color and coordinate formats:

• Arbitrary point attributes
• Customizeable coordinate type (float, double)
• Customizeable color type (uint_8t, uint16_t, float)
• Add template parameters to the SparseOctree class

Project refactoring

• Separate cuda code and kernels from standard host code
• Remove dense octree data structure
• Introduce octree metadata
• Consistent variable and function naming (rename all occurences of 'voxel' to 'node')

Implement replacement strategy

The current implementation of the octree follows the so-called 'additive' approach where points fromlower levels are added to the points of higher levels during rendering time.
The goal is to implement the octree using a 'replacement' scheme, where points from lower levels replace points from higher levels during rendering time.

Make the subsampling size customizeable

Make the subsampling size customizeable by exposing a parameter through the API

Add possibility to switch between additive and replacement octree

For backwards-compatibility and performance / quality evaluation it would be useful to switch between additive and replacement octree

Add getRootIndex method

Add a public getTootIndex() method to the SparseOctree class

Implement support for double coordinate-type and uin8 color-type

Add support for importing and exporting LAZ files

Implement support for automatically reading LIDAR point clouds using the LASzip library:

Estimate amount of used GPU memory and print appropriate error if not enough memory available

Cleanup OctreeApi C-Interface

• Add Integer return values denoting success or error
• Add exception handling to all function implementations
• Avoid using structs in API functions

Include scale and offset in bounding box calculation of subsamples

Up to now the scale and offset is not included in the bounding box calculation of subsamples

Support random point subsampling and first point subsampling

Implement random point subsampling

Fix CMake project setup

• Fix PotreeConverter CMakeLists.txt
• Fix OctreeApi CMakeLists.txt
• Fix OctreeLibrary CMakeLists.txt
• Fix upwards propagation of include files
• Fix Unit test setup
• Movecloud copy from host to device to SparseOctree

Leaf node histogram

Create a histogram showing the point distribution inside all leaf nodes

Implement Pimpl-Pattern for OctreeProcessor

This would have the advantage that includes could be hidden from from the OctreeApi

Perform averaging of colors

To perform Anti-Aliasing within higher levels of the octree, beside the replacement strategy, color averaging has to be performed

Support interleaved and non-interleaved point cloud data

• Add support to process interleaved (e.g. xyzrgbxyzrgb,...) and non interleaved data (xyzxyzrgbrgb).
• Add ability to specify a separate coordinate and color pointer

Set up a continuous integration pipeline

Set up a continuous integration pipeline using CircleCi

Add export to PotreeFormat

Add ability to process point clouds residing on GPU memory

Introduce PointCloud class

Introduce a PointCloud class which hides the copying of the cloud data from and to the GPU.
This would lead to another performance improvement as it is only necessary to copy the whole cloud once.

Add possibility to switch between averaged and non-averaged data export

For quality and performance benchmarking it would be useful to switch between averaged and non-averaged data export

Fix child node storing

Up to now child nodes are stored in parents in arbitrary order, one after the other.
The problem is that with this type of storing it is not able to deduce the spatial position of the child node.
Therefore the children nodes have to be stored in the following way:

2 x 2 x 2 neighbouring child nodes - B (Bottom) T(Top)

     2 -----  6         3 ------ 7 
   /        /          /        /
  /    B  /          /     T   /
0 ----- 4           1 ------ 5