Attention

You are viewing an older version of the documentation. The latest version is 2.2.

Overview and Installation¶

Overview¶

Intel PCL optimization is accomplished using Intel® oneAPI Base Toolkit, which comprises components such as the oneAPI™ DPC++ Compiler, OpenMP and oneAPI™ Threading Building Blocks (oneTBB). This optimization maximizes performance by fully utilizing the hardware’s available resources.

Only selected PCL modules listed in this modules table are available in oneAPI™ version. Most of the optimized module closely follow original PCL modules APIs except with additional oneAPI™ namespace. For example

PCL KdTree class

pcl::KdTreeFLANN<pcl::PointXYZ> kdtree;
kdtree.setInputCloud (cloud.makeShared())

oneAPI™ PCL KdTree class

pcl::oneapi::KdTreeFLANN<pcl::PointXYZ> kdtree;
kdtree.setInputCloud (cloud.makeShared())

Below are PCL modules optimized through Intel® oneAPI Base Toolkit

Optimized oneAPI PCL modules¶
Modules	Class	Supported HW
filters	PassThrough	CPU/GPU
	StatisticalOutlierRemoval	CPU/GPU
	VoxelGrid	CPU/GPU
features	NormalEstimation	CPU/GPU
KdTree	KdTreeFLANN (radiusSearch, nearestKSearch)	CPU/GPU
octree	Octree (radiusSearch, nearestKSearchBatch, approxNearestSearch)	CPU/GPU
registration	IterativeClosestPoint (ICP)	CPU/GPU
	IterativeClosestPointWithNormals	CPU/GPU
	SampleConsensusInitialAlignment	CPU/GPU
segmentation	SACSegmentation	CPU/GPU
sample_consensus	RandomSampleConsensus	CPU/GPU
	SampleConsensusModelPlane	CPU/GPU
surface	MovingLeastSquares	CPU/GPU
	GreedyProjectionTriangulation	CPU

Supported Hardware¶

CPUs:

Systems based on Intel® 64 architectures below are supported

Intel® Core™ processor family
Intel® Xeon® processor family

GPUs:

Integrated Processor Graphics site Skylake or higher

Supported Operating System¶

Ubuntu 22.04 LTS
Microsoft Windows 10/11

PCL oneAPI™ Installation¶

The PCL oneAPI™ version depends on the oneAPI™ runtime library. By installing the libpcl-oneapi Debian package, it will install all dependencies include libpcl and pcl dependency libraries, oneAPI™ runtime library and GPU runtime library.

Install PCL oneAPI™ version
```
sudo apt install libpcl-oneapi
```
To develop with the PCL oneAPI™ library or build PCL oneAPI™ tutorials, you need the Intel® oneAPI Base Toolkit. To install Intel® oneAPI Base Toolkit,

For docker environment:
sudo apt install intel-oneapi-compiler-dpcpp-cpp-2024.0 intel-oneapi-dpcpp-ct-2024.0
For host environment, refer to ` Get the Intel® oneAPI Base Toolkit Page <https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html>`__ to download and install. Choose Linux, and then APT Package Manager. Follow the instructions to set up APT repository for first-time users, then proceed with the apt command.
sudo apt install intel-oneapi-compiler-dpcpp-cpp-2024.0 intel-oneapi-dpcpp-ct-2024.0

Install PCL oneAPI™ tutorials. Refer to individual PCL modules table for more information
```
sudo apt install pcl-oneapi-tutorials
```

Runtime Device Selection¶

oneAPI™ runtime library will choose a default device for a platform, either CPU or GPU. Currently, the oneAPI™ version of PCL modules does not support the API to switch between different devices. To switch to device from default device, the only option is to select through oneAPI™ environment variable.

To find devices supported for given platform

Initialize oneAPI™ environment variable.

source /opt/intel/oneapi/setvars.sh

Find all devices supported

sycl-ls

Example of sycl-ls output

[opencl:cpu:0] Intel(R) OpenCL, 12th Gen Intel(R) Core(TM) i7-1270PE 3.0 [2023.16.6.0.22_223734]
[opencl:gpu:1] Intel(R) OpenCL Graphics, Intel(R) Graphics [0x46a6] 3.0 [23.22.26516.18]
[opencl:acc:2] Intel(R) FPGA Emulation Platform for OpenCL(TM), Intel(R) FPGA Emulation Device 1.2 [2023.16.6.0.22_223734]
[opencl:cpu:3] Intel(R) OpenCL, 12th Gen Intel(R) Core(TM) i7-1270PE 3.0 [2023.16.6.0.22_223734]
[ext_oneapi_level_zero:gpu:0] Intel(R) Level-Zero, Intel(R) Graphics [0x46a6] 1.3 [1.3.26516]

      
    

Select device for computation. For example

Select CPU device

export ONEAPI_DEVICE_SELECTOR=opencl:cpu
sycl-ls

Warning: ONEAPI_DEVICE_SELECTOR environment variable is set to opencl:cpu.
To see the correct device id, please unset ONEAPI_DEVICE_SELECTOR.

[opencl:cpu:0] Intel(R) OpenCL, 12th Gen Intel(R) Core(TM) i7-1270PE 3.0 [2023.16.6.0.22_223734]
[opencl:cpu:1] Intel(R) OpenCL, 12th Gen Intel(R) Core(TM) i7-1270PE 3.0 [2023.16.6.0.22_223734]

Select GPU device

export ONEAPI_DEVICE_SELECTOR=level_zero:gpu
sycl-ls

Warning: ONEAPI_DEVICE_SELECTOR environment variable is set to level_zero:gpu.
To see the correct device id, please unset ONEAPI_DEVICE_SELECTOR.

[ext_oneapi_level_zero:gpu:0] Intel(R) Level-Zero, Intel(R) Graphics [0x46a6] 1.3 [1.3.26516]

For more information of SYCL environment variables supported by oneAPI™, refer to this page for all supported environment variables.

JIT Limitation¶

Most oneAPI™ PCL modules are implemented with the Intel® oneAPI™ DPC++ Compiler. The Intel® oneAPI™ DPC++ Compiler converts a DPC++ program into an intermediate language called SPIR-V (Standard Portable Intermediate Representation). The SPIR-V code is stored in the binary produced by the compilation process. The SPIR-V code has the advantage that it can be run on any hardware platform by translating the SPIR-V code into the assembly code of the given platform at runtime. This process of translating the intermediate code present in the binary is called Just-In-Time (JIT) compilation. Since JIT compilation happens at the beginning of the execution of the first offloaded kernel, the performance is impacted. This issue can be mitigated by setting the system environment variable to cache and reuse JIT-compiled binaries.

Set the system environment variable to cache and reuse JIT-compiled binaries.
```
export SYCL_CACHE_PERSISTENT=1
```

Set the environment variable permanently.

echo "export SYCL_CACHE_PERSISTENT=1" >> ~/.bashrc
source ~/.bashrc

Execute the program once to generate the JIT-compiled binaries. Subsequent executions will reuse the cached JIT-compiled binaries.

Note

For an accurate PCL optimization performance number, set this system environment variable, and execute the program once to generate and cache the JIT-compiled binaries.