GDK SLAM Interface Documentation (Python)¶

Overview¶

The SLAM (Simultaneous Localization and Mapping) module provides the G02 robot with real-time mapping and localization functionality. Through the Python interface, developers can conveniently implement the robot's environment perception, map building, and position estimation functionality, suitable for autonomous navigation, environment modeling, localization services, and many other scenarios.

Interface Description¶

Slam Class¶

This class encapsulates the main functional interfaces of the SLAM system.

1. `get_slam_state()`¶

Function: Get the current state of the SLAM system
Parameters: None
Return value: int, the SLAM state code; throws an exception on failure (1: mapping started, 2: mapping stopped, 0: mapping cancelled)
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")

slam = agibot_gdk.Slam()
time.sleep(2)  # Wait for SLAM to initialize

# Get the SLAM state
slam_state = slam.get_slam_state()
print(f"SLAM state: {slam_state}")

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

2. `start_mapping()`¶

Function: Start mapping
Parameters: None
Return value: None; throws an exception on failure
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")

slam = agibot_gdk.Slam()
time.sleep(2)  # Wait for SLAM to initialize

# Start mapping
try:
    slam.start_mapping()
    print("Mapping started successfully")
except Exception as e:
    print(f"Failed to start mapping: {e}")

# Check the mapping state
time.sleep(2)
slam_state = slam.get_slam_state()
print(f"Mapping state: {slam_state}")

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

3. `stop_mapping()`¶

Function: Stop and save the mapping
Parameters: None
Return value: None; throws an exception on failure
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")

slam = agibot_gdk.Slam()
time.sleep(2)  # Wait for SLAM to initialize

# Stop mapping
try:
    slam.stop_mapping()
    print("Mapping stopped successfully")
except Exception as e:
    print(f"Failed to stop mapping: {e}")

# Check the mapping state
time.sleep(2)
slam_state = slam.get_slam_state()
print(f"Mapping state: {slam_state}")

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

4. `cancel_mapping()`¶

Function: Cancel mapping
Parameters: None
Return value: None; throws an exception on failure
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")

slam = agibot_gdk.Slam()
time.sleep(2)  # Wait for SLAM to initialize

# Cancel mapping
try:
    slam.cancel_mapping()
    print("Mapping cancelled successfully")
except Exception as e:
    print(f"Failed to cancel mapping: {e}")

# Check the mapping state
time.sleep(2)
slam_state = slam.get_slam_state()
print(f"Mapping state: {slam_state}")

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

5. `get_odom_info()`¶

Function: Get odometry information
Parameters: None
Return value: An OdomInfo object, containing the following attributes:

Attribute	Type	Description	Unit
`pose.position.x`	`float`	Current position X coordinate	meters
`pose.position.y`	`float`	Current position Y coordinate	meters
`pose.position.z`	`float`	Current position Z coordinate	meters
`pose.orientation.x`	`float`	Current orientation quaternion X component	unitless
`pose.orientation.y`	`float`	Current orientation quaternion Y component	unitless
`pose.orientation.z`	`float`	Current orientation quaternion Z component	unitless
`pose.orientation.w`	`float`	Current orientation quaternion W component	unitless
`twist.linear.x`	`float`	Linear velocity X component	meters/second
`twist.linear.y`	`float`	Linear velocity Y component	meters/second
`twist.linear.z`	`float`	Linear velocity Z component	meters/second
`twist.angular.x`	`float`	Angular velocity X component	radians/second
`twist.angular.y`	`float`	Angular velocity Y component	radians/second
`twist.angular.z`	`float`	Angular velocity Z component	radians/second
`is_stationary`	`bool`	Whether stationary	boolean
`is_sliping`	`bool`	Whether slipping	boolean
`loc_confidence`	`float`	Localization confidence	unitless
`loc_state`	`int`	Localization state	integer
`velocity`	`Vector3`	Velocity vector	meters/second
`velocity_body`	`Vector3`	Velocity in the body frame	meters/second
`acceleration`	`Vector3`	Acceleration vector	meters/second²
`ang_vel`	`Vector3`	Angular velocity vector	radians/second
`orientation_euler`	`Vector3`	Euler angle orientation	radians

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")

slam = agibot_gdk.Slam()
time.sleep(2)  # Wait for SLAM to initialize

# Get odometry information
odom_info = slam.get_odom_info()
print(f"Position: ({odom_info.pose.position.x:.3f}, {odom_info.pose.position.y:.3f}, {odom_info.pose.position.z:.3f})")
print(f"Orientation: ({odom_info.pose.orientation.x:.3f}, {odom_info.pose.orientation.y:.3f}, {odom_info.pose.orientation.z:.3f}, {odom_info.pose.orientation.w:.3f})")
print(f"Linear velocity: ({odom_info.twist.linear.x:.3f}, {odom_info.twist.linear.y:.3f}, {odom_info.twist.linear.z:.3f})")
print(f"Angular velocity: ({odom_info.twist.angular.x:.3f}, {odom_info.twist.angular.y:.3f}, {odom_info.twist.angular.z:.3f})")
print(f"Is stationary: {odom_info.is_stationary}")
print(f"Is slipping: {odom_info.is_sliping}")
print(f"Localization confidence: {odom_info.loc_confidence:.3f}")
print(f"Localization state: {odom_info.loc_state}")

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

6. `record_spec_loc()` (this interface is not yet available)¶

Function: Record the current position as the charging point position
Parameters: None
Return value: None; throws an exception on failure
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")

slam = agibot_gdk.Slam()
time.sleep(2)  # Wait for SLAM to initialize

# Record a specific position
try:
    slam.record_spec_loc()
    print("Specific position recorded successfully")
except Exception as e:
    print(f"Failed to record specific position: {e}")

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

7. `get_curr_pose()`¶

Function: Get the current pose
Parameters: None
Return value: A Pose object, containing the following attributes:

Attribute	Type	Description	Unit
`position.x`	`float`	Position X coordinate	meters
`position.y`	`float`	Position Y coordinate	meters
`position.z`	`float`	Position Z coordinate	meters
`orientation.x`	`float`	Orientation quaternion X component	unitless
`orientation.y`	`float`	Orientation quaternion Y component	unitless
`orientation.z`	`float`	Orientation quaternion Z component	unitless
`orientation.w`	`float`	Orientation quaternion W component	unitless

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")

slam = agibot_gdk.Slam()
time.sleep(2)  # Wait for SLAM to initialize

# Get the current pose
pose = slam.get_curr_pose()
print(f"Current position: ({pose.position.x:.3f}, {pose.position.y:.3f}, {pose.position.z:.3f})")
print(f"Current orientation: ({pose.orientation.x:.3f}, {pose.orientation.y:.3f}, {pose.orientation.z:.3f}, {pose.orientation.w:.3f})")

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

8. Complete Usage Example¶

Function: Demonstrates the complete usage flow of the SLAM module
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")

# Initialize the SLAM module
slam = agibot_gdk.Slam()
time.sleep(2)  # Wait for SLAM to initialize

# Start mapping
try:
    slam.start_mapping()
    print("Mapping started successfully")
except Exception as e:
    print(f"Failed to start mapping: {e}")

# Monitor state and position during mapping
for i in range(10):
    try:
        odom_info = slam.get_odom_info()
        print(f"Odometry position: ({odom_info.pose.position.x:.3f}, {odom_info.pose.position.y:.3f}, {odom_info.pose.position.z:.3f})")
        print(f"Odometry orientation: ({odom_info.pose.orientation.x:.3f}, {odom_info.pose.orientation.y:.3f}, {odom_info.pose.orientation.z:.3f}, {odom_info.pose.orientation.w:.3f})")

        slam_state = slam.get_slam_state()
        print(f"SLAM state: {slam_state}")

        pose = slam.get_curr_pose()
        print(f"Current pose: ({pose.position.x:.3f}, {pose.position.y:.3f}, {pose.position.z:.3f})")

    except Exception as e:
        print(f"Failed to get information: {e}")

    time.sleep(1)

# Record a specific position
try:
    slam.record_spec_loc()
    print("Specific position recorded successfully")
except Exception as e:
    print(f"Failed to record specific position: {e}")

# Stop mapping
try:
    slam.stop_mapping()
    print("Mapping stopped successfully")
except Exception as e:
    print(f"Failed to stop mapping: {e}")

# 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 SLAM functionality
GDK release: You must call agibot_gdk.gdk_release() to release GDK system resources before the program ends
Initialization wait: After creating a Slam object, it is recommended to wait 2 seconds to ensure system initialization completes
Mapping environment: Make sure the mapping environment has sufficient feature points, and avoid mapping in open or highly repetitive environments
State monitoring: Check the SLAM state promptly to ensure the system is running normally
Data quality: Ensure sensor data quality, and avoid mapping when a sensor malfunction occurs
Computing resources: The SLAM algorithm is computationally intensive, so pay attention to system resource usage
Exception handling: All interfaces throw a std::runtime_error exception on failure and need to be handled appropriately
Pose accuracy: SLAM pose estimation may drift, so periodic correction is recommended
Map saving: Save the map promptly after mapping is complete, to avoid data loss

Application Scenarios¶

Environment mapping: Building a detailed map of the robot's working environment
Autonomous localization: Achieving precise localization in a known environment
Navigation services: Providing environmental information for path planning
Environment monitoring: Real-time monitoring of environmental changes
Data collection: Collecting environmental data for subsequent analysis
Position recording: Marking and recording important position points
Trajectory tracking: Tracking the robot's motion trajectory
Map updating: Dynamically updating environmental map information

GDK SLAM Interface Documentation (Python)¶

Overview¶

Interface Description¶

Slam Class¶

1. get_slam_state()¶

2. start_mapping()¶

3. stop_mapping()¶

4. cancel_mapping()¶

5. get_odom_info()¶

6. record_spec_loc() (this interface is not yet available)¶

7. get_curr_pose()¶