segment-lidar

Python CLI for segmenting LiDAR data using Segment-Anything Model (SAM) from Meta Research.

This package is specifically designed for unsupervised instance segmentation of aerial LiDAR data. It brings together the power of the Segment-Anything Model (SAM) developed by Meta Research and the segment-geospatial package from Open Geospatial Solutions. Whether you're a researcher, developer, or a geospatial enthusiast, segment-lidar opens up new possibilities for automatic processing of aerial LiDAR data and enables further applications. We encourage you to explore our code, contribute to its development and leverage its capabilities for your segmentation tasks.

Installation

We recommand using python==3.9. First, you need to install PyTorch. Please follow the instructions here.

Then, you can easily install segment-lidar from PyPI:

pip install segment-lidar

Or, you can install it from source by running the following commands:

git clone https://github.com/Yarroudh/segment-lidar
cd segment-lidar
python setup.py install

Usage of the package

After installation, you have a small program called segment-lidar. Use segment-lidar --help to see the detailed help:

Usage: segment-lidar [OPTIONS] COMMAND [ARGS]...

  A package for segmenting LiDAR data using Segment-Anything from Meta AI
  Research.

Options:
  --help  Show this message and exit.

Commands:
  create-config  Create a configuration YAML file.
  segment        Segment LiDAR data.

The package reads .las or .laz file, then perform instance segmentation using segment-geospatial or/and segment-anything algorithms. The user should first create the configuration file by running:

segment-lidar create-config -o config.yaml

This will create a configuration file as follow:

algorithm: segment-geospatial
classification: null
csf_filter: true
csf_params:
  class_threshold: 0.5
  cloth_resolution: 0.2
  interations: 500
  slope_smooth: false
device: cuda:0
image_path: raster.tif
input_path: pointcloud.las
model_path: sam_vit_h_4b8939.pth
model_type: vit_h
output_path: classified.las
resolution: 0.15
sam_geo:
  automatic: true
  box_threshold: 0.24
  erosion_kernel_size: 3
  sam_kwargs: true
  text_prompt: null
  text_threshold: 0.3
sam_kwargs:
  crop_n_layers: 1
  crop_n_points_downscale_factor: 1
  min_mask_region_area: 1000
  points_per_side: 32
  pred_iou_thresh: 0.95
  stability_score_thresh: 0.92

The second step is to run the segmentation:

segment-lidar segment --config config.yaml

The resulted point cloud contains a new scalar field called segment_id. For visualization and further processing, we recommand using CloudCompare.

Testing data

For testing purposes, you can download a sample here: pointcloud.las.

This data was retrieved from AHN-4. For more data, please visit AHN-Viewer

Model checkpoints

Click the links below to download the checkpoint for the corresponding Segment-Anything model (SAM) type.

• default or vit_h: ViT-H SAM model.
• vit_l: ViT-L SAM model.
• vit_b: ViT-B SAM model.

Configuration

• algorithm: algorithm to use for instance segmentation [segment-geospatial/segment-anything].
• model_path: path of the model checkpoints. See segment-anything repository for models.
• model_type: SAM model version [vit_h/vit_l/vit_b].
• device: if cpu the prediction will use the CPU, if you have cuda, use cuda:0 instead for GPU.
• input_path: path to your input .las/.laz file.
• output_path: path to your output .las/.laz file. The results will be saved in this file.
• image_path: path to the resulted image. The segmentation results of SAM or segment-geospatial will be saved in this file.
• classification: specify the class number you want to segment. This will limit instance segmentation to specified class.
• csf_filter: apply ground filtering using cloth simulation filter.
• csf_params: refer to Cloth Simulation Filer for additional information.
• resolution: resolution of the image created from the point cloud.
• sam_kwargs: refer to segment-anything for additional information.
• sam_geo: refer to segment-geospatial for additional information.

Please note that the actual version is a pre-release and it's under tests. If you find any issues or bugs, please report them in issues section. The second version will have more advanced features and fonctionalities.

Related repositories

We would like to express our acknowledgments to the creators of:

• segment-anything
• segment-geospatial

Documentation

Coming soon.

License

This 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 file for more detailed information.

Citation

The 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. Additionally, please make sure to comply with any licensing terms and conditions associated with the use of this repository.

@misc{yarroudh:2023:samlidar,
  author = {Yarroudh, Anass},
  title = {LiDAR Automatic Unsurpervised Segmentation using Segment-Anything Model (SAM) from Meta AI},
  year = {2023},
  howpublished = {GitHub Repository},
  url = {https://github.com/Yarroudh/segment-lidar}
}

Yarroudh, A. (2023). LiDAR Automatic Unsurpervised Segmentation using Segment-Anything Model (SAM) from Meta AI [GitHub repository]. Retrieved from https://github.com/Yarroudh/segment-lidar

Author

This software was developped by Anass Yarroudh, a Research Engineer in the Geomatics Unit of the University of Liege. For more detailed information please contact us via [email protected], we are pleased to send you the necessary information.

---

Copyright © 2023, Geomatics Unit of ULiège. Released under BSD-3 Clause License