{"id":14761923,"url":"https://github.com/codebydant/DBScan-PCL-Optimized","last_synced_at":"2025-09-13T10:30:43.691Z","repository":{"id":37840479,"uuid":"149876059","full_name":"codebydant/DBScan-PCL-Optimized","owner":"codebydant","description":"DBScan algorithm using Octrees to cluster 3D points in a space with PCL Library","archived":false,"fork":false,"pushed_at":"2022-08-23T11:26:54.000Z","size":56529,"stargazers_count":188,"open_issues_count":2,"forks_count":43,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-01-07T08:32:56.999Z","etag":null,"topics":["c-plus-plus","cluster-coloring","cmake","cmakelists","dbscan","octree","octrees","optimize","pcd","pcl","pcl-library","pcl-viewer","ply","point-cloud","txt"],"latest_commit_sha":null,"homepage":"https://github.com/danielTobon43/DBScan-PCL-Optimized/blob/master/example/example2.png?raw=true","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codebydant.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-22T12:46:24.000Z","updated_at":"2025-01-07T00:39:47.000Z","dependencies_parsed_at":"2022-07-13T19:10:29.549Z","dependency_job_id":null,"html_url":"https://github.com/codebydant/DBScan-PCL-Optimized","commit_stats":null,"previous_names":["danieltobon43/dbscan-pcl-optimized","codebydant/dbscan-pcl-optimized","dtcmlops/dbscan-pcl-optimized"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/codebydant/DBScan-PCL-Optimized","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codebydant%2FDBScan-PCL-Optimized","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codebydant%2FDBScan-PCL-Optimized/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codebydant%2FDBScan-PCL-Optimized/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codebydant%2FDBScan-PCL-Optimized/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codebydant","download_url":"https://codeload.github.com/codebydant/DBScan-PCL-Optimized/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codebydant%2FDBScan-PCL-Optimized/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274949542,"owners_count":25379446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-13T02:00:10.085Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-plus-plus","cluster-coloring","cmake","cmakelists","dbscan","octree","octrees","optimize","pcd","pcl","pcl-library","pcl-viewer","ply","point-cloud","txt"],"created_at":"2024-09-15T21:01:44.718Z","updated_at":"2025-09-13T10:30:43.410Z","avatar_url":"https://github.com/codebydant.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# DBScan-PCL-Optimized\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/danielTobon43/cloudparse/actions/workflows/ci.yml/badge.svg?branch=master\" alt=\"travis\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/version-1.0.8-blue.svg?cacheSeconds=2592000\" alt=\"version\"/\u003e\n\u003c/p\u003e\n\nThis project is taken from: **Navarro-Hinojosa, Octavio, y Moisés Alencastre-Miranda. \"DBSCAN modificado con Octrees para agrupar nubes de puntos en tiempo real.\" Research in Computing Science, Vol. 114: Advances in Image Processing and Computer Vision, pp. 173–186, 2016.** Github: https://github.com/Hagen23/DBScan_Octrees\n\nIt was modified with:\n\n* It was added a CMakeList.txt for cmake compilation with PCL 1.9.0 (support 1.9.1)\n* It was added an argument param option\n* It was added a pcl visualizer\n* It was deleted the Glut visualizer\n* It was added a cluster saving method\n* It was added a cluster coloring method\n* It was replaced the input file from CSV to PCD \n* It was added a cluster coloring method for original color of the point cloud\n\n## Input file extension supported\n\n| Format      | Description |\n| ----------- | ----------- |\n| .pcd      | Point Cloud Data file format       |\n| .ply   | Polygon file format        |\n| .txt   | Text file format        |\n| .xyz      | X Y Z Text file format       |\n\n## Command line\n```\n➜ ./app --help                                                                                  \n\n*************************************\n*** DBSCAN Cluster Segmentation *** \n*************************************\nUsage: ./app [options] \n\nOptional arguments:\n-h --help       \tshows help message and exits [default: false]\n-v --version    \tprints version information and exits [default: false]\n--cloudfile     \tinput cloud file [required]\n--octree-res    \toctree resolution [default: 120]\n--eps           \tepsilon value [default: 40]\n--minPtsAux     \tminimum auxiliar points [default: 5]\n--minPts        \tminimum points [default: 5]\n-o --output-dir \toutput dir to save clusters [default: \"-\"]\n--ext           \tcluster output extension [pcd, ply, txt, xyz] [default: \"pcd\"]\n-d --display    \tdisplay clusters in the pcl visualizer [default: false]\n--cal-eps       \tcalculate the value of epsilon with the distance to the nearest n points [default: false]\n```\n\n## Example\n![Screenshot from 2022-06-23 10-21-38](https://user-images.githubusercontent.com/35694200/175337968-275c9420-85b7-4f89-a626-4d1eefd06499.png)\n\n\u003cimg src=\"./example/scan1.png\" align=\"center\"\u003e\n\n\u003cimg src=\"./example/example2.png\" align=\"center\"\u003e\u003cbr\u003e\n\n-------------------\n\n## Dependencies\nThis projects depends on the Point Cloud Library (it works with version `1.8...1.12.1`) and its dependencies.\n|     Package      |   Version      |                             Description                                                                                                                  |\n|     -----------       |   -----------      |                                  -----------                                                                                                                     |\n|        VTK           |    9.0.0          |   Visualization toolkit                                                           |\n|        PCL           |     1.12.1       |                    The Point Cloud Library (PCL)                                            |\n|        Eigen        |     3.7.7         |  Eigen is a library of template headers for linear algebra                                 |\n|        Flann        |     1.9.1         |      Fast Library for Approximate Nearest Neighbors                                  |\n|       Boost         |    1.77.0        | Provides support for linear algebra, pseudorandom number generation, multithreading      |\n|       OpenGL      |     21.2.6       | Programming interface for rendering 2D and 3D vector graphics.                    |\n\n\nThis project has been tested with VTK `8.1...9.1` and CMake from `3.5...3.21`\n\n\n## Compilation\nYou can build the project from source or download a docker image stored in docker hub, [here](https://hub.docker.com/r/danieltobon43/dbscan-octrees). This image is compiled with [pcl-docker-1.12.1](https://hub.docker.com/r/danieltobon43/pcl-docker), Alpine linux 3.15 and the DBscan project (`1.32GB`).\n\n### Compile from source\n\n1. Download source code\n\n```\ngit clone --recursive https://github.com/danielTobon43/DBScan-PCL-Optimized.git\n```\n\n2. Create a \"build\" folder at the top level of the DBScan-PCL-Optimized project\n\n```\ncd DBScan-PCL-Optimized/ \u0026\u0026 mkdir build\n```\n\n3. Compile with CMake\n\n```\ncd build/ \u0026\u0026 cmake ../ \u0026\u0026 make\n```\n\n#### How to run project\nIn the build folder run the following command:\n\n```\n./app --cloudfile PATH/TO/YOUR/CLOUDFILE\n```\n\n**Note**\n¡You can modify the parameters to obtain better results!\nI recommend modifying only the eps value, between 40 - 60 you can get better clusters, or 0.5 to 10. \n\nThere is a flag to calculate epsilon using 100 points with `--cal-eps`. Please check [Command line](https://github.com/danielTobon43/DBScan-PCL-Optimized/edit/master/README.md#command-line).\n\n\n### Download docker image\nTo use it you have to install [docker-engine](https://docs.docker.com/engine/install/) in your host machine:\n\nDocker multi-stage graph generated with: [dockerfilegraph](https://github.com/patrickhoefler/dockerfilegraph)\n\u003cimg src=\"./example/Dockerfile2.png\" align=\"center\"\u003e\u003cbr\u003e\n\n```\ndocker pull ghcr.io/danieltobon43/dbscan-octrees:latest\n```\n\n#### Check downloaded image\n```\ndocker images\n```\n\n#### Run a docker container Linux\nYou can either run a docker command or create a shell script.\n\n**1. Option 1: Docker command**\n```\ndocker run --rm -it \\\n           --volume=/tmp/.X11-unix:/tmp/.X11-unix:rw \\\n           --volume=/tmp/.docker.xauth:/tmp/.docker.xauth:rw \\\n           --env=\"XAUTHORITY=/tmp/.docker.xauth\" \\\n           --env=\"DISPLAY\" \\\n           --name=\"dbscan\" \\\n           --volume=[PATH TO YOUR PCD FOLDER]:/tmp \\\n           -t ghcr.io/danieltobon43/dbscan-octrees:latest --cloudfile /tmp/[YOUR PCD FILENAME]\n```\n\nIf you get something like this after setting `--display` flag it might be related to [this](https://stackoverflow.com/questions/48833451/no-protocol-specified-when-running-a-sudo-su-app-on-ubuntu-linux):\n\n```bash\nNo protocol specified\n```\nTry running with the following command belowe or use the provided `.sh` [script](https://github.com/danielTobon43/DBScan-PCL-Optimized/blob/master/scripts/run_dbscan.sh):\n```\nsudo -sE docker run --rm -it \\\n           --env=\"DISPLAY\" \\\n           --volume=/tmp/.X11-unix:/tmp/.X11-unix:rw \\\n           --volume=/tmp/.docker.xauth:/tmp/.docker.xauth:rw \\\n           --name=\"dbscan\" \\\n           --volume=[PATH TO YOUR PCD FOLDER]:/tmp \\\n           -t ghcr.io/danieltobon43/dbscan-octrees:latest --cloudfile /tmp/[YOUR PCD FILENAME] --display\n```\n\nIf this still does not work to display, run: `xhost +local:docker` and then run the option 1 command.\n\n**2. Option 2: shell script**\n\n- Create a `visualizer.sh` file with executable permissions (check this shell script [dbscan-shell-script](https://github.com/danielTobon43/DBScan-PCL-Optimized/blob/master/scripts/run_dbscan.sh)).\n\n![Screenshot from 2022-06-03 10-16-13](https://user-images.githubusercontent.com/35694200/171882906-75831bea-64f5-4cd6-9220-2d7a0ef46616.png)\n\n- Copy the next content into the `visualizer.sh` file (remember to update PATH/TO/YOUR/PCD/PLY/FOLDER accordingly):\n```\n# Allow X server connection\nxhost +local:root\ndocker run -it --rm \\\n    --env=\"DISPLAY\" \\\n    --env=\"QT_X11_NO_MITSHM=1\" \\\n    --name=\"pcl-container\" \\\n    --volume=\"/tmp/.X11-unix:/tmp/.X11-unix:rw\" \\\n    --volume=PATH/TO/YOUR/PCD/PLY/FOLDER:/tmp \\\n    ghcr.io/danieltobon43/dbscan-octrees:latest /tmp/$1\n# Disallow X server connection\nxhost -local:root\n```\n\n- Run the docker container\n```\n./visualizer YOUR/CLOUD/FILENAME\n```\n\n#### Run docker container Windows\n1. Install a Xserver on Windows, [XLaunch](https://sourceforge.net/projects/vcxsrv/)\n\n![xlaunch](https://user-images.githubusercontent.com/35694200/178142265-9194636c-31a4-451e-b58e-7d13655c3742.png)\n\n2. Run the docker container: Open a PowerShell Terminal with Administrator privileges and run the following command\n```\ndocker run --rm -it `\n           --env DISPLAY=host.docker.internal:0.0 `\n           --volume //c/Users/YOURUSERNAME/Downloads/pcds:/tmp `\n           -t ghcr.io/danieltobon43/dbscan-octrees:latest `\n           --cloudfile /tmp/YOURFILENAME `\n           --display\n```\n\n![windows-command](https://user-images.githubusercontent.com/35694200/178142667-b3c64d99-ff7b-4057-ae12-0c629a4f0952.png)\n\n\nMore info about running Docker GUI containers on Windows, check this [video](https://www.youtube.com/watch?v=BDilFZ9C9mw)\n\n**example:**\nI have a `.pcd` file called [Tree2.pcd](https://drive.google.com/file/d/1jyE85Dt51LqQmCdbWaXeE_TGrRCpOgS-/view?usp=sharing) stored in:\n```\n/home/user/Downloads/pcd/Tree2.pcd\n```\nTo run a docker container with the previous `.pcd` file I will open a terminal in \"Downloads folder\" and use `pwd` from ubuntu to get my current directory path in the terminal and then:\n```\ndocker run --rm -it \\\n           --volume=/tmp/.X11-unix:/tmp/.X11-unix:rw \\\n           --volume=/tmp/.docker.xauth:/tmp/.docker.xauth:rw \\\n           --env=\"XAUTHORITY=/tmp/.docker.xauth\" \\\n           --env=\"DISPLAY\" \\\n           --name=\"dbscan\" \\\n           --cap-add sys_ptrace \\\n           -p 127.0.0.1:2222:22 \\\n           --user=pcl \\\n           --volume=`pwd`/pcd:/tmp \\\n           -t ghcr.io/danieltobon43/dbscan-octrees:latest --cloudfile /tmp/Tree2.pcd\n```\n\nThe previous command will run a docker container with the `dbscan-octrees:1.1-alpine3.15` image and will share a `.pcd` file from the host machine (`[PATH TO YOUR PCD FOLDER]`) to the tmp folder in the container.\n\n#### Note\nBe aware that, the mounted directory in the host machine will copy all the files in the target directory in the container. That's why I recommend to create a folder to store just .pcd/.ply/etc files that will be use with the container.\n\nMore information about this docker image can be found in the docker hub repository.\n\n    \n## Epsilon calculation (experimental)\nHow to choose epsilon value:\n\n\u003cimg src=\"./example/epsilon.png\" align=\"center\"\u003e\u003cbr\u003e\n\nWhere **K-distance** is the distance from each point to its closest neighbour using the K-NearestNeighbors. The point itself is included in n_neighbors. The kneighbors method returns two arrays, one which contains the distance to the closest n_neighbors points and the other which contains the index for each of those points.\n\nThe graph is built with:\n\n```\nX_array = [0,1,2,3,4, ...1000]\nY_array = [0.0,0.1,0.2,...1.0]\nX_array.size() = Y_array.size()\n```\n\nEnable `--cal-eps` flag:\n\n![Screenshot from 2022-06-23 10-24-01](https://user-images.githubusercontent.com/35694200/175337506-711c168d-833c-4449-9589-294e9a56776d.png)\n\n## Exporting clusters\nYou can export the generated clusters by providing the `--output-dir` flag. This will save the clusters in the specified directoy. The default format is `pcd`, but you can choose from: `ply`, `txt`, `xyz` using the `--ext` flag.\n\n**Note:**\nThere is a bug with the PCL visualizer using VTK 9.1 which causes a segmentation default core dumped after the visualizer is closed. This might cause crash the program before exporting the clusters. I recommend enable the `--output-dir` flag without the `-d` or `--display` flag for visualization.\n\n## Display clusters\nTo display the generated clusters enable the `-d` or `--display` flag in the command line.\n\n## Troubleshoot PCL-1.9.1\nif compiling the project with PCL-1.9.1 this occurs:\n\n        -- Build files have been written to: /home/t00215031/Downloads/DBScan-PCL-Optimized-master/build\n        [ 20%] Building CXX object CMakeFiles/dbscan.dir/main.cpp.o\n        In file included from /opt/pcl-1.9.1/common/include/pcl/pcl_macros.h:75:0,\n                         from /opt/pcl-1.9.1/octree/include/pcl/octree/octree_nodes.h:47,\n                         .\n                         .\n                         .\n\n        /opt/pcl-1.9.1/build/include/pcl/pcl_config.h:7:4: error: #error PCL requires C++14 or above\n           #error PCL requires C++14 or above\n            ^\n        CMakeFiles/dbscan.dir/build.make:62: recipe for target 'CMakeFiles/dbscan.dir/main.cpp.o' failed\n        make[2]: *** [CMakeFiles/dbscan.dir/main.cpp.o] Error 1\n        CMakeFiles/Makefile2:67: recipe for target 'CMakeFiles/dbscan.dir/all' failed\n        make[1]: *** [CMakeFiles/dbscan.dir/all] Error 2\n        Makefile:83: recipe for target 'all' failed\n        make: *** [all] Error 2\n        \n        ## Solution\n        1. Update gcc and g++ to version 6:\n           $    sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test\n           $    sudo apt-get update -y\n           $    sudo apt-get install -y gcc-6 g++-6 clang-3.8\n           $    sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-6 70 --slave /usr/bin/g++ g++ /usr/bin/g++-6\n           \n           --\u003e check gcc and g++ version:\n           $    gcc --version\n           $    g++ --version\n           \n                g++ (Ubuntu 6.5.0-2ubuntu1~16.04) 6.5.0 20181026\n                Copyright (C) 2017 Free Software Foundation, Inc.\n                This is free software; see the source for copying conditions.  There is NO\n                warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n                \n         2. Compile again \n            $    cmake../ \u0026\u0026 make\n         \nif: \n\n        ../../../bin/librtabmap_core.so.0.11.11: undefined reference to `pcl::search::Search\u003cpcl::PointXYZRGBNormal\u003e::getName[abi:cxx11]() const'\n        ../../../bin/librtabmap_core.so.0.11.11: undefined reference to `pcl::search::Search\u003cpcl::PointXYZRGB\u003e::getName[abi:cxx11]() const'\n        ../../../bin/librtabmap_core.so.0.11.11: undefined reference to `pcl::search::Search\u003cpcl::PointXYZ\u003e::getName[abi:cxx11]() const'\n        collect2: error: ld returned 1 exit status\n        \n        Solution:\n\n                #include \u003cpcl/search/impl/search.hpp\u003e\n\n                #ifndef PCL_NO_PRECOMPILE\n                #include \u003cpcl/impl/instantiate.hpp\u003e\n                #include \u003cpcl/point_types.h\u003e\n                PCL_INSTANTIATE(Search, PCL_POINT_TYPES)\n                #endif // PCL_NO_PRECOMPILE\n\n           \n\n                \n        \n        \n      \n     \n\n    \n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodebydant%2FDBScan-PCL-Optimized","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodebydant%2FDBScan-PCL-Optimized","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodebydant%2FDBScan-PCL-Optimized/lists"}