Common Utility Functions

Configuration Parameter Access

The following utility functions are member functions of the MethodPreset class and can be called directly by its derived classes to safely obtain various types of parameter values from method configuration.

GetOptionAsIndexT

  • Function: Get unsigned integer value (IndexT/uint32_t) from method configuration.

  • Calling Method: this->GetOptionAsIndexT(key, default_value) or directly call GetOptionAsIndexT(key, default_value) in member functions.

  • Parameters:

    • key: const MethodParams& - Parameter key name.

    • default_value: IndexT - Default value returned when key does not exist or conversion fails, defaults to 0.

  • Return Value: Parameter value of IndexT type.

  • Usage Example:

    // In MethodPreset derived class member function:
// IndexT max_iterations = this->GetOptionAsIndexT("max_iterations", 100);
IndexT max_iterations = GetOptionAsIndexT("max_iterations", 100);

GetOptionAsInt

  • Function: Get signed integer value (int) from method configuration.

  • Calling Method: this->GetOptionAsInt(key, default_value) or GetOptionAsInt(key, default_value).

  • Parameters:

    • key: const MethodParams& - Parameter key name.

    • default_value: int - Default value returned when key does not exist or conversion fails, defaults to 0.

  • Return Value: Parameter value of int type.

  • Usage Example:

    // int step_size = this->GetOptionAsInt("step_size", -1);
int step_size = GetOptionAsInt("step_size", -1);

GetOptionAsFloat

  • Function: Get float value from method configuration.

  • Calling Method: this->GetOptionAsFloat(key, default_value) or GetOptionAsFloat(key, default_value).

  • Parameters:

    • key: const MethodParams& - Parameter key name.

    • default_value: float - Default value returned when key does not exist or conversion fails, defaults to 0.0f.

  • Return Value: Parameter value of float type.

  • Usage Example:

    // float threshold = this->GetOptionAsFloat("threshold", 0.5f);
float threshold = GetOptionAsFloat("threshold", 0.5f);

GetOptionAsDouble

  • Function: Get double precision floating point value from method configuration.

  • Calling Method: this->GetOptionAsDouble(key, default_value) or GetOptionAsDouble(key, default_value).

  • Parameters:

    • key: const MethodParams& - Parameter key name.

    • default_value: double - Default value returned when key does not exist or conversion fails, defaults to 0.0.

  • Return Value: Parameter value of double type.

  • Usage Example:

    // double precision_value = this->GetOptionAsDouble("precision", 1e-6);
double precision_value = GetOptionAsDouble("precision", 1e-6);

GetOptionAsBool

  • Function: Get bool value from method configuration.

  • Calling Method: this->GetOptionAsBool(key, default_value) or GetOptionAsBool(key, default_value).

  • Parameters:

    • key: const MethodParams& - Parameter key name.

    • default_value: bool - Default value returned when key does not exist or conversion fails, defaults to false.

  • Return Value: Parameter value of bool type.

  • Note: “true”, “yes”, “1”, “on” in configuration are recognized as true; “false”, “no”, “0”, “off” are recognized as false.

  • Usage Example:

    // bool enable_feature = this->GetOptionAsBool("enable_feature", false);
bool enable_feature = GetOptionAsBool("enable_feature", false);

GetOptionAsString

  • Function: Get string value from method configuration.

  • Calling Method: this->GetOptionAsString(key, default_value) or GetOptionAsString(key, default_value).

  • Parameters:

    • key: const MethodParams& - Parameter key name.

    • default_value: const std::string& - Default value returned when key does not exist, defaults to empty string.

  • Return Value: Parameter value of std::string type.

  • Usage Example:

    // std::string mode = this->GetOptionAsString("algorithm_mode", "default");
std::string mode = GetOptionAsString("algorithm_mode", "default");

GetOptionAsPath

  • Function: Get path value from method configuration with placeholder support. Supports {exe_dir}, {root_dir}, and generic {key_name} placeholders.

  • Calling Method: this->GetOptionAsPath(key, root_dir, default_value) or GetOptionAsPath(key, root_dir, default_value).

  • Parameters:

    • key: const MethodParams& - Parameter key name.

    • root_dir: const std::string& - Root directory path for {root_dir} placeholder replacement. If empty, gets from method_options_. Defaults to empty string.

    • default_value: const std::string& - Default value returned when key does not exist, defaults to empty string.

  • Return Value: Parameter value of std::string type with placeholders replaced.

  • Supported Placeholders:

    • {root_dir}: Root directory path. Prioritizes the root_dir parameter, otherwise gets from method_options_.

    • {exe_dir}: Executable file directory.

    • {key_name}: Reference other key values in method_options_ (note: referenced keys need to exist first).

  • Usage Example:

    // Get path with placeholders
std::string output_path = GetOptionAsPath("output_dir", "/project/root");
// If config contains: "output_dir = {root_dir}/results/{dataset_name}"
// And method_options_ contains: "dataset_name = test_data"
// Result: "/project/root/results/test_data"

// Get path with exe_dir placeholder
std::string config_path = GetOptionAsPath("config_file");
// If config contains: "config_file = {exe_dir}/../configs/settings.ini"
// Result: "/path/to/executable/../configs/settings.ini"

Data Type Conversion and Access

GetDataPtr Function

  • Function: Safely get and convert data pointer to specified type. This function can intelligently handle both regular DataPtr and DataPackage that encapsulates multiple data items.

  • Template Parameters:

    • T: Target data structure type to convert to (e.g., GlobalPoses, Tracks).

  • Parameters:

    • data_ptr_or_package_ptr: const Interface::DataPtr& - Smart pointer pointing to a single DataIO object or DataPackage object.

    • data_name_in_package (optional): const std::string& - If the first parameter is a DataPackage, this parameter specifies the name of the target data item in the package. Defaults to empty string.

  • Return Value: std::shared_ptr<T>, pointing to data of type T. Returns nullptr if conversion fails or data item is not found.

  • How It Works:

    1. Check if input data_ptr_or_package_ptr is nullptr.

    2. Determine if input points to DataPackage or regular DataIO object:

      • If DataPackage:

        • Requires data_name_in_package must be provided.

        • Extract target DataIO object from DataPackage by name.

      • If regular DataIO object:

        • data_name_in_package parameter (if provided) will be ignored.

        • Directly use this DataIO object.

    3. Call GetData() from target DataIO object to get raw void* pointer.

    4. static_cast void* pointer to T*.

    5. Use std::shared_ptr’s aliasing constructor to create a new std::shared_ptr<T> that points to internal T type data but shares ownership with the original DataIO object (or DataIO object in DataPackage). This ensures that as long as the returned std::shared_ptr<T> exists, the underlying data will not be released.

  • Usage Example:

    // Example 1: Get GlobalPoses from regular DataPtr
Interface::DataPtr single_pose_data_ptr = some_plugin->Run(); // Assume returns single pose data
auto poses = GetDataPtr<GlobalPoses>(single_pose_data_ptr);
if (poses) {
    // Use poses
}

// Example 2: Get Tracks data from DataPackage
Interface::DataPtr package_ptr = another_plugin->Run(); // Assume returns a DataPackage
auto tracks = GetDataPtr<Tracks>(package_ptr, "output_tracks"); // "output_tracks" is the name defined in package
if (tracks) {
    // Use tracks
}

String Conversion Utilities

String2Float

  • Function: Convert string to float type

  • Parameters:

    • value: const std::string& - Input string

    • default_value: float - Default value returned when conversion fails, defaults to 0.0f

  • Return Value: Converted float value

  • Usage Scenario: Used for safe conversion of configuration file string values to floating point numbers

  • Usage Example:

    float threshold = String2Float("0.75", 0.5f); // Returns 0.75
float invalid = String2Float("xyz", 0.5f);    // Returns 0.5

String2Bool

  • Function: Convert string to bool type

  • Parameters:

    • str: const std::string& - Input string

    • default_value: bool - Default value returned when conversion fails, defaults to false

  • Return Value: Converted bool value

  • Note: “true”, “yes”, “1”, “on” are converted to true; “false”, “no”, “0”, “off” are converted to false

  • Usage Example:

    bool enabled = String2Bool("yes", false);    // Returns true
bool disabled = String2Bool("off", true);    // Returns false
bool invalid = String2Bool("maybe", false);  // Returns default value false

Deprecated Functions

  • String2IndexT (Deprecated): This function has been removed from types.hpp, related functionality is replaced by MethodPreset::GetOptionAsIndexT().