GDK Lidar Interface Documentation (Python)¶

Overview¶

The Lidar module provides the G02 robot with the ability to acquire real-time point cloud data. Through the Python interface, developers can conveniently obtain the robot's environmental perception data, suitable for SLAM mapping, obstacle detection, navigation and obstacle avoidance, environment modeling, and many other scenarios.

Interface Description¶

Lidar Class¶

This class encapsulates the main data acquisition interfaces of the lidar sensor.

1. `get_latest_pointcloud()`¶

Function: Get the latest point cloud data
Parameters:

Parameter	Type	Description
`type`	`LidarType`	Lidar type enum value
`timeout`	`float`	Timeout duration (milliseconds)

Return value: A PointCloud object, containing the following attributes:

Attribute	Type	Description	Unit
`timestamp_ns`	`int`	Timestamp of point cloud data acquisition	nanoseconds
`width`	`int`	Point cloud width (number of points)	points
`height`	`int`	Point cloud height (number of points)	points
`point_step`	`int`	Number of bytes occupied by each point	bytes
`row_step`	`int`	Number of bytes occupied by each row	bytes
`is_bigendian`	`bool`	Whether the data is big-endian	boolean
`is_dense`	`bool`	Whether it is a dense point cloud (no invalid points)	boolean
`fields`	`list`	List of field information defining the attribute structure of each point in the point cloud	unitless
`data`	`bytes`	Raw binary data of the point cloud	bytes

Detailed Description of the PointCloud Object¶

fields (field information list):

Each field contains the following attributes:

name: Field name (e.g. "x", "y", "z", "intensity")
offset: Offset within the point data
datatype: Data type
count: Number of elements for this field

data (raw data):

Type: bytes
Description: Raw binary data of the point cloud
Note: Needs to be parsed according to the fields information

Lidar types: - kLidarUnknown: Unknown lidar - kLidarFront: Front lidar - kLidarBack: Rear lidar

Example:

import agibot_gdk
import time

# Initialize the GDK system
if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)
print("GDK initialized successfully")

lidar = agibot_gdk.Lidar()
time.sleep(2)  # Wait for the lidar to initialize

pointcloud = lidar.get_latest_pointcloud(agibot_gdk.LidarType.kLidarFront, 1000.0)

if pointcloud is not None:
    print(f"✅ Timestamp: {pointcloud.timestamp_ns}")
    print(f"Point cloud size: {pointcloud.width} x {pointcloud.height}")
    print(f"Point step: {pointcloud.point_step}")
    print(f"Row step: {pointcloud.row_step}")
    print(f"Is big-endian: {pointcloud.is_bigendian}")
    print(f"Is dense: {pointcloud.is_dense}")
    print(f"Data size: {pointcloud.data_size} bytes")

    # Print field information
    print(f"Number of fields: {len(pointcloud.fields)}")
    for j, field in enumerate(pointcloud.fields):
        print(f"  Field {j+1}: {field.name} (offset: {field.offset}, "
              f"type: {field.datatype}, count: {field.count})")
else:
    print("No point cloud data obtained")

# Close the lidar
lidar.close_lidar()

# Release GDK system resources
if agibot_gdk.gdk_release() != agibot_gdk.GDKRes.kSuccess:
    print("GDK release failed")
else:
    print("GDK released successfully")

2. `get_nearest_pointcloud()`¶

Function: Get the point cloud data nearest to a specified timestamp
Parameters:

Parameter	Type	Description
`type`	`LidarType`	Lidar type enum value
`timestamp`	`int`	Target timestamp (nanoseconds)
`timeout`	`float`	Timeout duration (milliseconds)

Return value: A PointCloud object, with the same structure as get_latest_pointcloud()
Example:

import agibot_gdk
import time

# Initialize the GDK system
if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)
print("GDK initialized successfully")

lidar = agibot_gdk.Lidar()
time.sleep(1.0)

# First get the latest point cloud data
pointcloud = lidar.get_latest_pointcloud(agibot_gdk.LidarType.kLidarFront, 1000.0)

if pointcloud is not None:
    # Get historical point cloud data (1 second earlier)
    pointcloud_nearest = lidar.get_nearest_pointcloud(
        agibot_gdk.LidarType.kLidarFront, 
        pointcloud.timestamp_ns - 1000000000, 
        1000.0
    )

    if pointcloud_nearest is not None:
        print(f"✅ Nearest point cloud data: {pointcloud_nearest.timestamp_ns}")
        print(f"Point cloud size: {pointcloud_nearest.width} x {pointcloud_nearest.height}")
        print(f"Point step: {pointcloud_nearest.point_step}")
        print(f"Row step: {pointcloud_nearest.row_step}")
        print(f"Data size: {pointcloud_nearest.data_size} bytes")
    else:
        print("❌ No nearest point cloud data found")
else:
    print("Failed to obtain the latest point cloud data")

# Close the lidar
lidar.close_lidar()

# Release GDK system resources
if agibot_gdk.gdk_release() != agibot_gdk.GDKRes.kSuccess:
    print("GDK release failed")
else:
    print("GDK released successfully")

3. `get_lidar_fps()`¶

Function: Get the lidar data acquisition frame rate
Parameters:

Parameter	Type	Description
`type`	`LidarType`	Lidar type enum value

Return value: float, the lidar frame rate (FPS)
Example:

import agibot_gdk
import time

# Initialize the GDK system
if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)
print("GDK initialized successfully")

lidar = agibot_gdk.Lidar()
time.sleep(2)  # Wait for the lidar to initialize

lidar_type = agibot_gdk.LidarType.kLidarFront

try:
    fps = lidar.get_lidar_fps(lidar_type)
    print(f"Lidar frame rate: {fps} FPS")
except RuntimeError as e:
    print(f"Failed to get frame rate: {e}")

# Close the lidar
lidar.close_lidar()

# Release GDK system resources
if agibot_gdk.gdk_release() != agibot_gdk.GDKRes.kSuccess:
    print("GDK release failed")
else:
    print("GDK released successfully")

4. `get_lidar_latency()`¶

Note: Before obtaining lidar data latency statistics, time synchronization must first be performed, otherwise the latency statistics results will be inaccurate
Function: Get lidar data latency statistics
Parameters:

Parameter	Type	Description
`type`	`LidarType`	Lidar type enum value
`window_seconds`	`float`	Statistics window duration (seconds)

Return value: A LatencyStats object, containing the following attributes:

Attribute	Type	Description	Unit
`max_latency_ms`	`float`	Maximum latency	milliseconds
`avg_latency_ms`	`float`	Average latency	milliseconds
`p99_latency_ms`	`float`	99^th percentile latency	milliseconds
`p999_latency_ms`	`float`	99.9^th percentile latency	milliseconds
`p9999_latency_ms`	`float`	99.99^th percentile latency	milliseconds

Example:

import agibot_gdk
import time

# Initialize the GDK system
if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)
print("GDK initialized successfully")

lidar = agibot_gdk.Lidar()
time.sleep(2)  # Wait for the lidar to initialize

lidar_type = agibot_gdk.LidarType.kLidarFront

try:
    latency = lidar.get_lidar_latency(lidar_type, 1.0)
    print("Lidar latency statistics:")
    print(f"  Max latency: {latency.max_latency_ms}ms")
    print(f"  Average latency: {latency.avg_latency_ms}ms")
    print(f"  P99 latency: {latency.p99_latency_ms}ms")
    print(f"  P99.9 latency: {latency.p999_latency_ms}ms")
    print(f"  P99.99 latency: {latency.p9999_latency_ms}ms")
except RuntimeError as e:
    print(f"Failed to get latency statistics: {e}")

# Close the lidar
lidar.close_lidar()

# Release GDK system resources
if agibot_gdk.gdk_release() != agibot_gdk.GDKRes.kSuccess:
    print("GDK release failed")
else:
    print("GDK released successfully")

5. `close_lidar()`¶

Function: Close the lidar connection
Parameters: None
Return value: GDKRes, the operation result status code
Example:

import agibot_gdk

# Initialize the GDK system
if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)
print("GDK initialized successfully")

lidar = agibot_gdk.Lidar()

# Use the lidar...

# Close the lidar
result = lidar.close_lidar()
if result == agibot_gdk.GDKRes.kSuccess:
    print("Lidar closed successfully")
else:
    print("Failed to close the lidar")

# Release GDK system resources
if agibot_gdk.gdk_release() != agibot_gdk.GDKRes.kSuccess:
    print("GDK release failed")
else:
    print("GDK released successfully")

Usage Notes¶

GDK initialization: You must call agibot_gdk.gdk_init() to initialize the GDK system before using the lidar functionality
GDK release: You must call agibot_gdk.gdk_release() to release GDK system resources before the program ends
Initialization wait: After creating a Lidar object, it is recommended to wait 2 seconds to ensure the DDS connection is established
Timeout setting: Set an appropriate timeout duration based on actual needs to avoid long blocking periods
Data validity: Check whether the returned point cloud data is None before use
Timestamp precision: The timestamp unit is nanoseconds, which can be used for precise time synchronization
Point cloud processing: Point cloud data volume is relatively large, so pay attention to memory usage during processing
Lidar selection: Choose the appropriate lidar type (front/rear) based on the application scenario
Resource management: Call close_lidar() to release lidar resources after use
Exception handling: All interfaces throw a std::runtime_error exception on failure and need to be handled appropriately
Unimplemented methods: get_lidar_fps() and get_lidar_latency() are currently not implemented, so use them with caution

Application Scenarios¶

SLAM mapping: Using point cloud data for simultaneous localization and mapping
Obstacle detection: Real-time detection of obstacles in the environment
Navigation and obstacle avoidance: Providing environmental perception information for robot navigation
Environment modeling: Building 3D environment models
Object recognition: Combining point cloud data for object detection and recognition
Path planning: Planning safe paths based on point cloud data
Data fusion: Fusing with other sensor data to improve perception accuracy