# Xavia SDK for C++

> Version: 2.0
> Date: 24/12/2025

**Contents:**

- [1. Introduction](#introduction)
- [2. Basic example](#basic-example)
- [3. Available data](#available-data)
- [4. Compatibility](#compatibility)

<a name="introduction"></a>

## 1. Introduction

The Xavia SDK is a C++ library to interact with the Xavia sensor.
The SDK provides a set of objects that allow developers to easily integrate these sensors into their applications.

With this SDK you will be able to:

- Start and stop the sensor from code.
- Receive point cloud data in your code.
- Store and read the point cloud data in the XenomatiX format.
- Receive errors and status changes from the sensor.
- Control multiple sensors from the same code.

Main features:

- Created with C++17 and modern C++ design principles.
- Fully object oriented.
- Easy to use. You can get started in 10 lines of code.
- Tested for performance.
- Fully unit tested.

---

<a name="basic-example"></a>

## 2. Basic example

Since a picture is worth more than 1000 words, here is a basic point cloud recorder that shows how to use the Xavia SDK:

```c++ {.numberLines}
#include "xavia/sensorFactory.h"
#include "xavia/iSensor.h"
#include "xavia/iPointCloud.h"

#include <thread>
#include <chrono>
#include <fstream>

namespace xsdk = xavia::sdk;

void main()
{
    xsdk::SensorFactory factory;

    // prepare the point cloud recording
    std::ofstream pointCloudFile;
    pointCloudFile.open("pcFile.xpc", std::ios_base::binary);
    auto PointCloudCallback = [&](const std::unique_ptr<xsdk::IPointCloud> pc)
      { 
        std::vector<std::byte> pcData = pc->Serialize();
        pointCloudFile.write(pcData.data(), pcData.size());
      };

    // register your point cloud handling
    factory.SetPointcloudCallback(PointCloudCallback);

    // build sensor
    auto sensor = factory.Build();

    //run
    sensor->Start();
    std::this_thread::sleep_for(std::chrono::seconds(60));
    sensor->Stop();

    // close the output file
    pointCloudFile.close();
}
```

This example shows the usage of the `Sensor` object to operate the status of the sensor during its lifetime. In this example only the `Start` and `Stop` functions are used, but you can use it to query different properties of the sensor.

The `SensorFactory` object is there to do the configuration before connecting to the sensor. In this example we only attached a point cloud callback function to handle the incoming data (which in this case we wrote as a lambda function). This callback will take the point cloud object, ask it to `Serialize` itself, and then writes those bytes to a file. Later, we could use the `IPointCloud::Deserialize()` method to read the point cloud from the buffers in the file and process them.

In a real time application, you would instead keep using the `xavia::sdk::IPointCloud` object to extract e.g. the measured distance or the xyz coordinates of the point cloud.

The `SensorFactory::Build()` function is overloaded to take several arguments that allow you to indicate which sensor you want to connect to. In this way, it is possible to configure the factory once and then use it to build multiple sensor objects, each connected to a different lidar in your network. In line with modern c++, this build method returns objects of type `std::unique_ptr<xavia::sdk::isensor>`, meaning that you will take full control over the lifetime of the sensor object. Proper RAII implementations will ensure that the sensor object is properly destroyed when it goes out of scope.

This example is a minimal software to record data. In a production environment you should add more robustness by also handling errors (which are all passed as `std::exception` derivatives).

---

<a name="available-data"></a>

## 3. Available data

Through the SDK, the following point cloud information is available:

- **XYZ coordinates** of the points, represented in mm, in the coordinate system of the sensor.
- **Measured distance** in mm from the sensor origin.
- **Reflectivity measurement**. It represents the amount of reflected laser light.
- **Ambient measurement**. I represents the amount of light that is not due to the lasers.
- **Confidence**. A confidence value indicating the quality of the measurement.

This information is provided in a vectorized format per topic, grouped per row.
This information is transmitted row per row at the measurement frequency, which is around 1120Hz.

Besides the point cloud data itself, every line is accompanied by 'metadata'. This includes:

- Timestamp of the start of the frame.
- Timestamp of the start of this line. (there are 56 lines in a frame in the default configuration)
- The frame number. An monotonic incrementing number for each frame recorded by the sensor.
- The line number. An identifier for each line within a frame.
- The return index. In future versions the sensor will be able to support multiple returns.
- The trigger counter. A monotonic incrementing number for each trigger received by the sensor. Not every trigger will result in a frame if the triggering frequency is higher than the measurement frequency.
- Relative humidity measured inside the sensor housing
- Temperature measured inside the sensor housing
  
Furthermore, the sensor includes an onboard IMU. In future releases this information will also become available:

- Angular velocity of yaw, pitch and roll (in radian per second)
- Linear acceleration of x, y and z (in m/s^2)

<a name="compatibility"></a>

## 4. Compatibility

The SDK is written in C++17 and compiled using MSVC143 and G++ 9.3.0.
The target platforms are:

- x86_64 Windows
- x86_64 Linux
- arm64 Linux

The SDK is supplied in the form of a precompiled library (.dll and .lib, or .a and .so files), together with the necessary header and documentation files.
It is compatible with cmake.
