LiGuard: A Research-Purposed Framework for Processing LIDAR and Image Data

Introduction | Installation | Usage | Documentation | Contributing | License

Introduction

LiGuard is a research-purposed framework for LiDAR (and corresponding image) data. It provides an easy-to-use graphical user interface (GUI) that helps researchers interactively create algorithms by allowing them to dynamically create, enable or disable components, adjust parameters, and instantly visualize results.

LiGuard features, out of the box, data reading for many common dataset formats including support for reading calibration and label data. Moreover, it provides (an increasing list of) commonly used algorithm components ranging from basic data preprocessors to advanced object detection and tracking algorithms. Additionally, it establishes a straightforward standard for adding custom functions/algorithms, allowing users to integrate unique components into their pipelines. Pipelines created in LiGuard are saved in structured directories, making it easy to share and reproduce results.

LiGuard Main Interface LiGuard’s GUI Layout (from left to right): Configuration Window, Visualization Windows (Point Cloud Feed and Image Feed), and Log Window.

Installation

Requirements:

  • OS

    • Windows 10 or later

    • macOS 10.14 Mojave or later

    • Ubuntu 18.04 or later

  • Python 3.10 or later

Install LiGuard with pip (from PyPI):

pip install LiGuard

Run LiGuard by executing the following command in the terminal:

liguard-gui

Alternative Quick Launch:
If you have uv installed, you can start the GUI directly without installing the package:

uvx --from LiGuard liguard-gui

Developmental Build

Install the latest development version directly from GitHub:

pip install git+https://github.com/m-shahbaz-kharal/LiGuard-2.x.git@dev_2.x

Alternatively, clone and install in editable mode:

git clone https://github.com/m-shahbaz-kharal/LiGuard-2.x.git
cd LiGuard-2.x
pip install -e .

Note to macOS Users: When launching liguard-gui for the first time on macOS, liguard-gui may request accessibility permissions in order to control this computer. This is a requirement for the keybindings to function properly. To grant these permissions, go to System Preferences > Privacy & Security > Accessibility and toggle the button next to “Terminal”.

Usage

Test an example pipeline:

  1. In the Configuration windows, click the Open button.

  2. Navigate to examples/simple_pipeline, click open, and then click Apply.

  3. Explore various functions under proc dropdown in the Configuration window. For example, under proc/lidar/crop, check the enabled checkbox, and click Apply to see the cropped LIDAR data.

  4. Press left arrow or right arrow to navigate through the frames. A list of all key bindings is available here.

  5. To save the pipeline, click the Save button in the Configuration window.

For more details on pipelines, see LiGuard Pipelines.

Documentation

A detailed documentation for LiGuard is available at GitHub Pages.

Contributing

We welcome contributions to the LiGuard framework. Please follow the guidelines below to contribute to the framework:

  • Fork the repository.

  • Create a new branch for your feature or bug fix.

  • Make your changes and add comments.

  • Write tests for your changes.

  • Run the tests.

  • Create a pull request.

License

MIT License Copyright (c) 2024 Muhammad Shahbaz - see the LICENSE file for details.