PCL Tutorial

A hands-on, browser-based tutorial for the Point Cloud Library.

English · 한국어

---

🚀 Overview

This tutorial focuses on how to actually use PCL well rather than deriving optimization math or diving deep into C++ syntax. Each chapter is paired 1:1 with a blog post, and this repo serves as the maintained home for every code sample referenced in those posts.

• Original author: Hyungtae Lim (shapelim at mit dot edu)
• Tested OS: Ubuntu 24.04

---

✨ Interactive Demo (web/)

Play with the sliders right in your browser to see each chapter in action — https://limhyungtae.github.io/pcl_tutorial/.

Every interactive demo runs entirely in the browser, with the algorithms reimplemented in TypeScript (no remote compute). Inputs include KITTI (outdoor LiDAR), NaverLabs (indoor LiDAR), and Stanford Bunny (CAD) presets, plus drag-and-drop for your own data.

#	Chapter	Highlights
1	Voxelization	leaf size slider, synced before/after view
2	PassThrough	axis + min/max + negative toggle, synced before/after
3	Transformation	tx/ty/tz/rx/ry/rz, random offset on entry
4	Statistical Outlier Removal	mean K + stddev mult, inlier/outlier split
5	Radius Search	KdTree-based; click any point to set the query
6	K-Nearest Neighbor	KdTree-based K-NN; click any point to set the query
7	Normal Estimation	KdTree + SVD; normals overlaid as white line segments
8	RANSAC Plane Segmentation	ground / wall detection (extra)
9	Patchwork — Ground Segmentation	CZM zones × rings colored per region (VLP-16 / HDL-64)
10	Euclidean Clustering	stable per-cluster colors across slider changes (extra)
11	TRAVEL — Range Image Clustering	3D + 2D range image, same cluster colors (VLP-16 / HDL-64)
12	Iterative Closest Point	Step / Play to watch each iteration's correspondences
13	GenZ-ICP — adaptive ICP	per-iteration α-blend of point-to-plane / point-to-point
14	KISS-Matcher — global registration	FasterPFH + ROBIN + GNC; pre-computed via Python wrapper

Chapters 9 and 11 are sensor-specific demos: parameters are baked in for VLP-16 (NaverLabs preset) and HDL-64 (KITTI preset) only. Each page links out to the upstream Patchwork and TRAVEL repos for running on your own data.

Run the site locally

cd web
npm install
npm run dev          # http://localhost:5173/pcl_tutorial/

The predev / prebuild hooks automatically copy data files (.bin / .pcd / .ply) from materials/ into web/public/data/.

Deployment

When changes under web/** are pushed to main, GitHub Actions (.github/workflows/deploy.yml) builds the site and deploys it to GitHub Pages. Before the first deploy, set the repo's Settings → Pages → Source to GitHub Actions.

---

🔨 Prerequisites & Build

Prerequisites

• CMake ≥ 3.10
• PCL ≥ 1.8
• Boost ≥ 1.58

Build

mkdir build && cd build
cmake ..
make -j$(nproc)

The build step copies the data files (.bin, .pcd, .ply) under materials/ into build/auxiliary/, so always run the executables from inside the build/ directory:

cd build
./lec00_usage
./lec04_visualization
# ...

---

📚 Chapters & Source (Blog posts are written in Korean)

#	Code	Topic	Blog post
0	lec00_usage.cpp	PCL basics	0. Tutorial 및 기본 사용법
1-1	lec01_1_shared_ptr.cpp	shared_ptr fundamentals	1-(1). Ptr/ConstPtr의 완벽 이해 — shared_ptr
1-2	lec01_2_ptr.cpp	Using Ptr in PCL	1-(2). Ptr/ConstPtr의 완벽 이해 — Ptr in PCL
1-3	lec01_3_ptr_in_class.cpp	Ptr as a class member	1-(3). Ptr/ConstPtr의 완벽 이해 — Ptr in 클래스 멤버변수
2	(no code)	Conversions — toROSMsg / fromROSMsg	2. 형변환 — toROSMsg, fromROSMsg
3	lec03_transformation.cpp	4×4 matrix transforms	3. Transformation
4	lec04_visualization.cpp	Using PCLVisualizer	4. Viewer로 visualization하는 법
5	lec05_voxelization.cpp	Voxel Grid downsampling	5. Voxelization
6	lec06_pass_through.cpp	PassThrough filtering	6. PassThrough
7	lec07_sor.cpp	Statistical Outlier Removal	7. Statistical Outlier Removal
8	lec08_radius_search.cpp	KdTree-based radius search	8. KdTree를 활용한 Radius Search
9	lec09_knn.cpp	K-Nearest Neighbor search	9. KdTree를 활용한 K-NN Search
10-1	lec10_1_normal.cpp	Normal estimation via KdTree + SVD	10. Normal Estimation
10-2	lec10_2_normal_corner.cpp	Normal computation in a simple case	(corner-case example for the post above)
11	lec11_icp.cpp	Iterative Closest Point	11. Iterative Closest Point (ICP)
12	lec12_gicp.cpp	Generalized ICP	12. Generalized ICP (G-ICP)

Note: auxiliary/pass_by_address.cpp is a side snippet (a Ceres + Eigen learning example) and is not part of the main build.

---

📁 Directory layout

pcl_tutorial/
├── CMakeLists.txt
├── lec*.cpp                         # per-chapter examples (PCL/C++)
├── auxiliary/                       # side snippets, not part of the main build
├── img/                             # images for README and blog posts
├── materials/                       # sample point cloud data (.bin / .pcd / .ply)
└── web/                             # interactive site (React + Vite)
    ├── src/
    │   ├── pages/                   # one page per chapter
    │   ├── components/              # viewer, sliders, drop zone
    │   ├── i18n/                    # EN/KO dictionaries + toggle
    │   └── lib/                     # KdTree, PCD/BIN/PLY parsers,
    │       └── filters/             # voxel · passthrough · sor · normal ·
    │                                #   ransacPlane · euclideanCluster · icp ·
    │                                #   transform (all reimplemented in TS)
    └── public/data/                 # auto-copied from materials/ at build time

---

📄 License

MIT License. See package.xml for the license declaration.