GDK Map Interface Documentation (C++)

Overview

The Map module provides map management functionality for the G02 robot. Through the C++ interface, developers can easily retrieve, switch, and manage maps built by the robot, suitable for various scenarios such as map storage, map switching, and map management.

Interface Description

Map Class

This class encapsulates the main functional interfaces for map management.

1. GetCurrMap()

• Function: Get information about the currently used map
• Parameters:

Parameter	Type	Description
map_name	MapName&	Output parameter, the current map name information

• Return value: GDKRes, the operation result status code. Returns GDKRes::kSuccess on success; the map_name parameter contains the current map information

MapName Object Details

The MapName struct contains the following members:

Member	Type	Description	Unit
id	uint32_t	Map ID	None
name	std::string	Map name	String
is_curr_map	bool	Whether this is the current map	Boolean

• Example:

#include "gdk/gdk.h"
#include <iostream>
#include <chrono>
#include <thread>
using namespace agibot::gdk;

int main() {
    // Initialize the GDK system
    if (agibot::gdk::GDKInit() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK initialization failed" << std::endl;
        return -1;
    }
    std::cout << "GDK initialized successfully" << std::endl;

    Map map_manager;
    std::this_thread::sleep_for(std::chrono::seconds(1)); // Wait 1 second to ensure the DDS connection is established
    MapName current_map;
    GDKRes result = map_manager.GetCurrMap(current_map);

    if (result == GDKRes::kSuccess) {
        std::cout << "Current map: " << std::endl;
        std::cout << "Current map ID: " << current_map.id << std::endl;
        std::cout << "Current map name: " << current_map.name << std::endl;
        std::cout << "Is current map: " << (current_map.is_curr_map ? "Yes" : "No") << std::endl;
    } else {
        std::cout << "Failed to get current map" << std::endl;
    }

    // Release GDK system resources
    if (agibot::gdk::GDKRelease() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK release failed" << std::endl;
        return -1;
    }
    std::cout << "GDK released successfully" << std::endl;

    return 0;
}

2. GetAllMap()

• Function: Get the list of all available maps
• Parameters:

Parameter	Type	Description
map_names	std::vector<MapName>&	Output parameter, the list of map names

• Return value: GDKRes, the operation result status code. Returns GDKRes::kSuccess on success; the map_names parameter contains information about all maps

• Example:

#include "gdk/gdk.h"
#include <iostream>
#include <chrono>
#include <thread>
using namespace agibot::gdk;

int main() {
    // Initialize the GDK system
    if (agibot::gdk::GDKInit() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK initialization failed" << std::endl;
        return -1;
    }
    std::cout << "GDK initialized successfully" << std::endl;

    Map map_manager;
    std::this_thread::sleep_for(std::chrono::seconds(1)); // Wait 1 second to ensure the DDS connection is established      
    std::vector<MapName> map_names;
    GDKRes result = map_manager.GetAllMap(map_names);

    if (result == GDKRes::kSuccess) {
        std::cout << "Map list: " << std::endl;
        std::cout << "Number of maps: " << map_names.size() << std::endl;

        for (const auto& map_name : map_names) {
            std::cout << "Map ID: " << map_name.id 
                      << ", Name: " << map_name.name
                      << ", Current map: " << (map_name.is_curr_map ? "Yes" : "No") << std::endl;
        }
    } else {
        std::cout << "Failed to get map list" << std::endl;
    }

    // Release GDK system resources
    if (agibot::gdk::GDKRelease() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK release failed" << std::endl;
        return -1;
    }
    std::cout << "GDK released successfully" << std::endl;

    return 0;
}

3. SwitchMap()

• Function: Switch to the map with the specified ID
• Parameters:

Parameter	Type	Description
map_id	const uint8_t	Map ID

• Return value: GDKRes, the operation result status code. Returns GDKRes::kSuccess on success

• Example:

#include "gdk/gdk.h"
#include <iostream>
#include <chrono>
#include <thread>
using namespace agibot::gdk;

int main() {
    // Initialize the GDK system
    if (agibot::gdk::GDKInit() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK initialization failed" << std::endl;
        return -1;
    }
    std::cout << "GDK initialized successfully" << std::endl;

    Map map_manager;
    std::this_thread::sleep_for(std::chrono::seconds(1)); // Wait 1 second to ensure the DDS connection is established      
    // Switch to the map with ID 1
    GDKRes result = map_manager.SwitchMap(1);

    if (result == GDKRes::kSuccess) {
        std::cout << "Map switched successfully" << std::endl;

        // Verify the switch result
        MapName current_map;
        result = map_manager.GetCurrMap(current_map);
        if (result == GDKRes::kSuccess) {
            std::cout << "Current map ID: " << current_map.id << std::endl;
        }
    } else {
        std::cout << "Failed to switch map" << std::endl;
    }

    // Release GDK system resources
    if (agibot::gdk::GDKRelease() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK release failed" << std::endl;
        return -1;
    }
    std::cout << "GDK released successfully" << std::endl;

    return 0;
}

4. RemoveMap()

• Function: Delete the map with the specified ID
• Parameters:

Parameter	Type	Description
map_id	const uint8_t	Map ID

• Return value: GDKRes, the operation result status code. Returns GDKRes::kSuccess on success

• Example:

#include "gdk/gdk.h"
#include <iostream>
#include <chrono>
#include <thread>
using namespace agibot::gdk;

int main() {
    // Initialize the GDK system
    if (agibot::gdk::GDKInit() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK initialization failed" << std::endl;
        return -1;
    }
    std::cout << "GDK initialized successfully" << std::endl;

    Map map_manager;
    std::this_thread::sleep_for(std::chrono::seconds(1)); // Wait 1 second to ensure the DDS connection is established 
    // Delete the map with ID 2
    GDKRes result = map_manager.RemoveMap(2);

    if (result == GDKRes::kSuccess) {
        std::cout << "Map deleted successfully" << std::endl;
    } else {
        std::cout << "Failed to delete map" << std::endl;
    }

    // Release GDK system resources
    if (agibot::gdk::GDKRelease() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK release failed" << std::endl;
        return -1;
    }
    std::cout << "GDK released successfully" << std::endl;

    return 0;
}

Usage Notes

1. GDK initialization: Before using Map functions, you must first call agibot::gdk::GDKInit() to initialize the GDK system
2. GDK release: Before the program ends, you must call agibot::gdk::GDKRelease() to release GDK system resources
3. Initialization wait: After creating a Map object, it is recommended to wait 1 second to ensure the DDS connection is established
4. Map ID validity: Before use, make sure the map ID exists and is valid
5. Return value check: Before use, check whether the GDKRes return value is kSuccess
6. Map switching: When switching maps, make sure there is no navigation task currently in progress
7. Map updates: When updating a map, pay attention to the correctness of the data format
8. Resource management: Be mindful of memory usage for map data, especially for large maps
9. Error handling: Always check the GDKRes return value to ensure the operation succeeded

Application Scenarios

• Map storage: Manage and store map data built by the robot
• Map switching: Switch between different maps for different environments
• Map management: Add, delete, and update map information
• Navigation support: Provide map data support for the navigation system
• Environment modeling: Build and maintain a spatial model of the environment
• Path planning: Provide the underlying map data for path planning
• Waypoint management: Manage key location points within a map
• Zone marking: Mark impassable areas and special zones