GDK Map Interface Documentation (Python)

Overview

The Map module provides the G02 robot with map management functionality. Through the Python interface, developers can conveniently obtain, switch, and manage the maps built by the robot, suitable for map storage, map switching, map management, and many other scenarios.

Interface Description

Map Class

This class encapsulates the main functional interfaces for map management.

1. get_curr_map()

• Function: Get information about the currently used map

• Parameters: None

• Return value: A MapName object, containing the following attributes:

Attribute	Type	Description	Unit
id	int	Map ID	integer
name	str	Map name	string
is_curr_map	bool	Whether this is the current map	boolean

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

map_manager = agibot_gdk.Map()
time.sleep(2)  # Wait for the map manager to initialize

# Get the current map
current_map = map_manager.get_curr_map()
print(f"Current map:")
print(f"  Map ID: {current_map.id}")
print(f"  Map name: {current_map.name}")
print(f"  Is current map: {current_map.is_curr_map}")

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

2. get_all_map()

• Function: Get a list of all available maps

• Parameters: None

• Return value: list[MapName], a list of map names

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

map_manager = agibot_gdk.Map()
time.sleep(2)  # Wait for the map manager to initialize

# Get all maps
all_maps = map_manager.get_all_map()
print(f"Total number of maps: {len(all_maps)}")

for i, map_name in enumerate(all_maps):
    print(f"Map {i+1}:")
    print(f"  ID: {map_name.id}")
    print(f"  Name: {map_name.name}")
    print(f"  Is current map: {map_name.is_curr_map}")

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

3. switch_map()

• Function: Switch to the specified map
• Parameters:

Parameter	Type	Description
map_id	int	Target map ID

• Return value: None (no return value on success; 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")

map_manager = agibot_gdk.Map()
time.sleep(2)  # Wait for the map manager to initialize

try:
    # Switch to the specified map
    map_manager.switch_map(1)
    print("Map switched successfully")

    # Verify the switch result
    current_map = map_manager.get_curr_map()
    print(f"Current map ID: {current_map.id}")
    print(f"Current map name: {current_map.name}")
except Exception as e:
    print(f"Failed to switch map: {e}")

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

4. remove_map()

• Function: Delete the specified map
• Parameters:

Parameter	Type	Description
map_id	int	ID of the map to delete

• Return value: None (no return value on success; 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")

map_manager = agibot_gdk.Map()
time.sleep(2)  # Wait for the map manager to initialize

try:
    # Delete the specified map
    map_manager.remove_map(2)
    print("Map deleted successfully")

    # Verify the deletion result
    all_maps = map_manager.get_all_map()
    print(f"Remaining number of maps: {len(all_maps)}")
except Exception as e:
    print(f"Failed to delete map: {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

1. GDK initialization: You must call agibot_gdk.gdk_init() to initialize the GDK system before using the map functionality
2. GDK release: You must call agibot_gdk.gdk_release() to release GDK system resources before the program ends
3. Initialization wait: After creating a Map object, it is recommended to wait 2 seconds to ensure system initialization completes
4. Map ID: Make sure to use a valid map ID to avoid accessing a nonexistent map
5. Map switching: When switching maps, make sure there is no navigation task currently in progress
6. Map deletion: Before deleting a map, confirm that it is no longer needed — the delete operation cannot be undone
7. Storage space: Pay attention to the storage space occupied by map files, and clean up unneeded maps promptly
8. Exception handling: All interfaces throw a std::runtime_error exception on failure and need to be handled appropriately
9. Data type: The map ID uses the uint8_t type, with a range of 0-255
10. Timestamp precision: The timestamp unit is nanoseconds, which can be used for precise time synchronization

Application Scenarios

• Map management: Managing multiple maps built by the robot
• Environment switching: Switching maps between different working environments
• Map backup: Saving and restoring important map data
• Storage optimization: Cleaning up unneeded maps to save storage space
• Environment perception: Using wall and infeasible-area information in the map
• Guide point navigation: Using guide points in the map for precise navigation