{"id":13441972,"url":"https://github.com/Yarroudh/segment-lidar","last_synced_at":"2025-03-20T13:31:43.801Z","repository":{"id":173649465,"uuid":"649492480","full_name":"Yarroudh/segment-lidar","owner":"Yarroudh","description":"Python package for segmenting LiDAR data using Segment-Anything Model (SAM) from Meta AI.","archived":false,"fork":false,"pushed_at":"2023-12-07T13:16:28.000Z","size":25609,"stargazers_count":335,"open_issues_count":5,"forks_count":36,"subscribers_count":12,"default_branch":"main","last_synced_at":"2024-10-01T08:07:48.030Z","etag":null,"topics":["artificial-intelligence","deep-learning","lidar","machine-learning","python","segmentation"],"latest_commit_sha":null,"homepage":"https://yarroudh.github.io/segment-lidar/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yarroudh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.bib","codeowners":null,"security":null,"support":null,"governance":null},"funding":{"github":["yarroudh"]}},"created_at":"2023-06-05T01:52:34.000Z","updated_at":"2024-09-24T07:31:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"6bf96f0b-c0eb-4324-bd8b-c66c351246b5","html_url":"https://github.com/Yarroudh/segment-lidar","commit_stats":null,"previous_names":["yarroudh/segment-lidar"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yarroudh%2Fsegment-lidar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yarroudh%2Fsegment-lidar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yarroudh%2Fsegment-lidar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yarroudh%2Fsegment-lidar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yarroudh","download_url":"https://codeload.github.com/Yarroudh/segment-lidar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221768427,"owners_count":16877638,"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","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":["artificial-intelligence","deep-learning","lidar","machine-learning","python","segmentation"],"created_at":"2024-07-31T03:01:40.219Z","updated_at":"2025-03-20T13:31:43.789Z","avatar_url":"https://github.com/Yarroudh.png","language":"Python","funding_links":["https://github.com/sponsors/yarroudh"],"categories":["Python"],"sub_categories":[],"readme":"\u003cimg src=\"https://user-images.githubusercontent.com/72500344/210864557-4078754f-86c1-4e7c-b291-73223bdf4e4d.png\" alt=\"logo\" width=\"200\"/\u003e\n\n# segment-lidar\n[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://github.com/Yarroudh/ZRect3D/blob/main/LICENSE)\n[![Geomatics Unit of ULiege - Development](https://img.shields.io/badge/Geomatics_Unit_of_ULiege-Development-2ea44f)](http://geomatics.ulg.ac.be/)\n[![read - documentation](https://img.shields.io/static/v1?label=read\u0026message=documentation\u0026color=orange)](https://yarroudh.github.io/segment-lidar/)\n\n\u003cimg src=\"https://github.com/Yarroudh/segment-lidar/assets/72500344/0b9450b3-3a2a-4644-b61f-3d5deaa3d077\" alt=\"logo\" width=200 /\u003e\n\n*Python package for segmenting aerial LiDAR data using Segment-Anything Model (SAM) from Meta AI.*\n\nThis package is specifically designed for **unsupervised instance segmentation** of **LiDAR data**. It brings together the power of the **Segment-Anything Model (SAM)** developed by [Meta Research](https://github.com/facebookresearch) and the **segment-geospatial** package from [Open Geospatial Solutions](https://github.com/opengeos) to automatize instance segmentation of 3D point cloud data.\n\n![results](https://github.com/Yarroudh/segment-lidar/assets/72500344/089a603b-697e-4483-af1e-3687a79adcc1)\n\n## Installation\n\nWe recommand using `Python\u003e=3.9`. First, you need to install `PyTorch`. Please follow the instructions [here](https://pytorch.org/).\n\nThen, you can easily install `segment-lidar` from [PyPI](https://pypi.org/project/segment-lidar/):\n\n```bash\npip install segment-lidar\n```\n\nOr, you can install it from source by running the following commands:\n\n```bash\ngit clone https://github.com/Yarroudh/segment-lidar\ncd segment-lidar\npython setup.py install\n```\n\nPlease, note that the actual version is always under tests. If you find any issues or bugs, please report them in [issues](https://github.com/Yarroudh/segment-lidar/issues) section. The second version should implement more advanced features and fonctionalities.\n\n## Documentation\n\nIf you are using `segment-lidar`, we highly recommend that you take the time to read the [documentation](https://yarroudh.gitbook.io/segment-lidar/). The documentation is an essential resource that will help you understand the features of the package, as well as provide guidance on how to use it effectively.\n\n## Basic tutorial\n\nA basic tutorial is available [here](https://yarroudh.github.io/segment-lidar/tutorial.html).\n\nYou can also refer to [API](https://yarroudh.github.io/segment-lidar/module.html) for more information about different parameters.\n\n### Without ground filtering\n\n```python\nfrom segment_lidar import samlidar, view\n\nviewpoint = view.TopView()\n\nmodel = samlidar.SamLidar(ckpt_path=\"sam_vit_h_4b8939.pth\")\npoints = model.read(\"pointcloud.las\")\nlabels, *_ = model.segment(points=points, view=viewpoint, image_path=\"raster.tif\", labels_path=\"labeled.tif\")\nmodel.write(points=points, segment_ids=labels, save_path=\"segmented.las\")\n```\n\n### With ground filtering\n\n```python\nfrom segment_lidar import samlidar, view\n\nviewpoint = view.TopView()\n\nmodel = samlidar.SamLidar(ckpt_path=\"sam_vit_h_4b8939.pth\")\npoints = model.read(\"pointcloud.las\")\ncloud, non_ground, ground = model.csf(points)\nlabels, *_ = model.segment(points=cloud, view=viewpoint, image_path=\"raster.tif\", labels_path=\"labeled.tif\")\nmodel.write(points=points, non_ground=non_ground, ground=ground, segment_ids=labels, save_path=\"segmented.las\")\n```\n\n**Note**: The latest version of `segment-lidar` supports defining a custom pinhole camera, with or without interactive visualization, and save the view as an image. Please, refer to the [documentation](https://yarroudh.github.io/segment-lidar/tutorial.html#interactive-mode) for more details.\n\n## Sample data\n\nFor testing purposes, you can download a sample here: [pointcloud.las](https://drive.google.com/file/d/16EF2aRSvo8u0pXvwtaQ6sjhP5h0sWw3o/view?usp=sharing).\n\nThis data was retrieved from **AHN-4**. For more data, please visit [GeoTiles.nl](https://geotiles.nl/).\n\n## Model checkpoints\n\nClick the links below to download the checkpoint for the corresponding model type.\n\n- `vit_h`: [ViT-H SAM model.](https://dl.fbaipublicfiles.com/segment_anything/sam_vit_h_4b8939.pth)\n- `vit_l`: [ViT-L SAM model.](https://dl.fbaipublicfiles.com/segment_anything/sam_vit_l_0b3195.pth)\n- `vit_b`: [ViT-B SAM model.](https://dl.fbaipublicfiles.com/segment_anything/sam_vit_b_01ec64.pth)\n\n## Docker Image\n\n**segment-lidar** is also available as [Docker image](https://hub.docker.com/r/yarroudh/segment-lidar).\n\nThese are the steps to run `segment-lidar` as a Docker container:\n\n1. First pull the image using the \u003ccode\u003edocker pull\u003c/code\u003e command:\n\n```bash\ndocker pull yarroudh/segment-lidar\n```\n\n2. To run the Docker container and mount your data and script file inside it, use the \u003ccode\u003edocker run\u003c/code\u003e command with the \u003ccode\u003e-v\u003c/code\u003e option to specify the path to the host directory and the path to the container directory where you want to mount the data folder. For example:\n\n```bash\ndocker run -d -v ABSOLUTE_PATH_TO_HOST_DATA:/home/user yarroudh/segment-lidar\n```\n\nThis command will start a Docker container in detached mode, mount the **ABSOLUTE_PATH_TO_HOST_DATA** directory on the host machine to the **/home/user/data** directory inside the container, and run the \u003ccode\u003eyarroudh/segment-lidar\u003c/code\u003e image. Do not change the path of the directory inside the container.\n\n3. Find the container ID and copy it. You can use the \u003ccode\u003edocker ps\u003c/code\u003e command to list all running containers and their IDs.\n4. Launch a command inside the container using \u003ccode\u003edocker exec\u003c/code\u003e, use the container ID or name and the command you want to run. For example:\n\n```bash\ndocker exec CONTAINER_ID python SCRIPT_FILE\n```\n\n5. To copy the output of the command from the container to a local path, use the \u003ccode\u003edocker cp\u003c/code\u003e command with the container ID or name, the path to the file inside the container, and the path to the destination on the host machine. For example:\n\n```bash\ndocker cp CONTAINER_ID:/home/user/PATH_TO_OUTPUT PATH_ON_HOST_MACHINE\n```\n\n6. Finally, after executing all the commands and copying the results to your local machine, you can stop the Docker container using the \u003ccode\u003edocker stop\u003c/code\u003e command followed by the container ID or name:\n\n```bash\ndocker stop CONTAINER_ID\n```\n\n## Related repositories\n\nWe would like to express our acknowledgments to the creators of:\n\n- [segment-anything](https://github.com/facebookresearch/segment-anything)\n- [segment-geospatial](https://github.com/opengeos/segment-geospatial)\n\nPlease, visit these repositories for more information about image raster automatic segmentation using SAM from Meta AI.\n\n## License\n\nThis software is under the BSD 3-Clause \"New\" or \"Revised\" license which is a permissive license that allows you almost unlimited freedom with the software so long as you include the BSD copyright and license notice in it. Please refer to the [LICENSE](https://github.com/Yarroudh/segment-lidar/blob/main/LICENSE) file for more detailed information.\n\n## Citation\n\nThe use of open-source software repositories has become increasingly prevalent in scientific research. If you use this repository for your research, please make sure to cite it appropriately in your work. The recommended citation format for this repository is provided in the accompanying [BibTeX citation](https://github.com/Yarroudh/segment-lidar/blob/main/CITATION.bib). Additionally, please make sure to comply with any licensing terms and conditions associated with the use of this repository.\n\n```bib\n@misc{yarroudh:2023:samlidar,\n  author = {Yarroudh, Anass},\n  title = {LiDAR Automatic Unsupervised Segmentation using Segment-Anything Model (SAM) from Meta AI},\n  year = {2023},\n  howpublished = {GitHub Repository},\n  url = {https://github.com/Yarroudh/segment-lidar}\n}\n```\n\nYarroudh, A. (2023). *LiDAR Automatic Unsupervised Segmentation using Segment-Anything Model (SAM) from Meta AI* [GitHub repository]. Retrieved from https://github.com/Yarroudh/segment-lidar\n\n## Author\n\nThis software was developped by [Anass Yarroudh](https://www.linkedin.com/in/anass-yarroudh/), a Research Engineer in the [Geomatics Unit of the University of Liege](http://geomatics.ulg.ac.be/fr/home.php).\nFor more detailed information please contact us via \u003cayarroudh@uliege.be\u003e, we are pleased to send you the necessary information.\n\n-----\n\nCopyright © 2023, [Geomatics Unit of ULiège](http://geomatics.ulg.ac.be/fr/home.php). Released under [BSD-3 Clause License](https://github.com/Yarroudh/segment-lidar/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYarroudh%2Fsegment-lidar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FYarroudh%2Fsegment-lidar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYarroudh%2Fsegment-lidar/lists"}