Getting Started Guide | LGSx SDK 2026.0.0

Leica Geosystems

Leica LGSx SDK Getting Started Guide

Overview

This guide is intended for Windows and Linux developers. Each LGSx SDK release includes one or more sample programs that demonstrate the available API functions.

Windows Integration

The following steps outline the process for utilizing the LGSx SDK:

Extract the provided .zip file containing the LGSx SDK. The extracted file structure should appear as follows:

\acknowledgements \bin \doc \include \lib \samples VC_redist.x64.exe

After extraction, install VC_redist.x64.
The full SDK documentation is located in the \doc folder.
A sample program executable, LgsxProjectInfoExample.exe, is located in the \bin folder. This sample can be used to output key metadata from an LGSx file. A sample LGSx file, testMobile.lgsx, is included in the \samples folder. To test the executable, use the following command: LgsxProjectInfoExample -i ../samples/testMobile.lgsx
The following steps describe how to build and run the provided sample programs from source code. Visual Studio 2022 and CMake 3.16 (or newer) are required.

From the command line, starting in the extracted LGSx SDK root folder:

cd samples cmake -S . -B ./msvc2022_64

This command generates a Visual Studio solution file in a new targets folder located at samples\msvc2022_64.

cd msvc2022_64 LgsxSdk-Examples.sln

This command navigates to the new targets folder and launches Visual Studio with the newly created solution. The sample program can be built and run from within Visual Studio.

Linux Integration

Extract the provided LGSx SDK package:

sudo tar -xvzf <LGSx SDK Package>.tar.gz

The extracted directory structure should appear as follows:

/acknowledgements /bin /doc /include /lib /samples
The full SDK documentation is located in the doc folder.
The LGSx package includes a sample application, LgsxProjectInfoExample, which outputs key project metadata from an LGSx file. Both the source and executable for provided examples can be found in the SDK. The following steps outline how to run the executable, starting in the LGSx SDK root directory:

cd bin ./LgsxProjectInfoExample -i ../samples/testMobile.lgsx
To build provided examples from source code, gcc 11 and CMake 3.16` (or newer) are required.

A. Setting up the environment

The required development tools can be installed using the following commands:

sudo apt-get update sudo apt-get install --no-install-recommends -y \ build-essential \ gcc-multilib g++-multilib \ cmake ninja-build

Install the necessary library dependencies using:

sudo apt-get install --no-install-recommends -y \ libgomp1 libcurl4 libgl1 libglu1

B. Building and running examples

Use the following steps to build and run provided examples (starting in the LGSx SDK root directory):

cd samples cmake -S . -B ./build cd build cmake --build .

This process creates a targets directory samples/build and builds provided examples executables there.

To test LgsxProjectInfoExample, use the same command as previously:

./LgsxProjectInfoExample -i ../testMobile.lgsx

WSL Integration

The following steps outline the process for utilizing the LGSx SDK under Windows Subsystem for Linux (WSL):

Enable "Virtualization in BIOS."
Enable Hyper-V in Windows.
Install WSL. Install the supported Ubuntu release from Microsoft Store (Ubuntu 22.04.5 LTS).

LgsxSensorProcessingInfoExample

An example focused on reading and displaying SensorInfo and ProcessingInfo data associated with setups and runs. This example iterates through all TLS setups and mobile runs, printing detailed sensor and processing information for each context.

Sample file: testMobile.lgsx

Basic usage: LgsxSensorProcessingInfoExample -i testMobile.lgsx

Key features demonstrated: - Reading SensorInfo for TLS setups (Lgsx_ReaderHasSetupSensorInfo, Lgsx_ReaderGetSetupSensorInfo) - Reading ProcessingInfo for TLS setups (Lgsx_ReaderEnumSetupProcessingInfos, Lgsx_ReaderGetSetupProcessingInfo) - Reading SensorInfo for runs (Lgsx_ReaderHasRunSensorInfo, Lgsx_ReaderGetRunSensorInfo) - Reading ProcessingInfo for runs (Lgsx_ReaderEnumRunProcessingInfos, Lgsx_ReaderGetRunProcessingInfo) - Displaying all SensorInfo fields: scanner type, serial number, firmware/hardware version, manufacturer, article number, capture timestamp, and device info snapshot metadata - Displaying all ProcessingInfo fields: application name/version, processing timestamp, library version, order index, and pipeline info metadata

Large Point Cloud Considerations

When working with large point cloud files, the SDK may open a significant number of file descriptors. This is particularly important on Linux and Unix-like systems where file descriptor limits can impact application performance and stability.

File Descriptor Limits

Large point cloud files can require many open files simultaneously. For example, processing a point cloud with 7.66 billion points distributed across 342 setups peaked at 6150 simultaneously open file descriptors, far exceeding typical system defaults (usually 1024).

Checking Current Limits (Linux/Unix):

# Check soft limit
ulimit -n

# Check hard limit
ulimit -Hn

# Check process limits
cat /proc/sys/fs/file-max
cat /proc/[PID]/limits

# Check actual usage (replace [PID] with process ID)
ls /proc/[PID]/fd | wc -l

Increasing File Descriptor Limits (Linux/Unix):

To increase limits temporarily (for current session):

 ulimit -n 8192   # Set soft limit to 8192

To increase limits permanently, edit /etc/security/limits.conf:

* soft nofile 8192
username soft nofile 8192

Or edit /etc/systemd/system.conf for system-wide limits:

DefaultLimitNOFILE=8192

For systemd services, edit the service file:

[Service]
LimitNOFILE=8192

On Windows: Windows typically has much higher file descriptor limits and rarely encounters this issue. However, ensure your system has adequate resources for large file access.

Point Cloud Size and File Descriptor Impact

File descriptor usage is primarily correlated with point cloud size (number of points), not the number of setups. The SDK partitions large point clouds into multiple files for efficient access and processing.

Size-to-descriptor relationship: - 7.66 billion points: Peak of 6150 file descriptors (range: 46-6150) - Point cloud partitioning: Large point datasets are split into multiple files (chunks/tiles), requiring an open file descriptor for each chunk being processed - Recommended minimum soft limit for large point cloud processing: 8192

Before processing large point cloud files, especially those with billions of points, ensure your system's file descriptor limit is set appropriately to prevent "too many open files" errors. Use the checking commands above to monitor actual usage during processing.

Rule of thumb: If processing files with point counts in the billions, set the soft file descriptor limit to at least 8192.

SDK Know-How

Most SDK functionality is located in the include/LgsxSdk/LgsxReader.h header file. This file should be included in the application.
All sample programs follow a standard workflow pattern. Refer to the LgsxProjectInfoExample main function for the typical initialization and cleanup sequence. Additional details can be found in the SDK documentation.

Examples

The SDK package includes a curated set of sample programs shipped under samples/ (source) and bin/ (executables).

The examples are organized as: - Fundamentals for first-time SDK usage. - Focused reader examples for individual data domains. - Advanced examples for end-to-end workflows. - Extraction utilities for export scenarios.

The full examples catalog and task-oriented snippets are maintained in the dedicated Examples documentation section generated from shipped source code.