Method Plugin (Method Plugin)

Method plugins are used to implement specific algorithm logic and data processing workflows.

MethodPreset Common Operation Functions Quick Reference

The following list covers common operation functions of MethodPreset and its derived classes (MethodPresetProfiler). For detailed descriptions, see corresponding section.

Data Management | Data Management

Function	Brief Description
`SetRequiredData()`	Set single required input data
`GetRequiredPackage()`	Get required input data package reference
`GetRequiredDataTypes()`	Get required input data type list
`GetRequiredDataPtr<T>()`	Simplified access to required input data (recommended⭐)
`GetOutputPackage()`	Get output data package pointer
`AddOutputDataPtr()`	Add data to output package
`GetOutputDataTypes()`	Get output data type list
`ClearOutputPackage()`	Clear output data package

Configuration Management | Configuration Management

Function	Brief Description
`LoadMethodOptions()`	Load method options from config file
`SaveMethodOptions()`	Save method options to config file
`GetMethodOptions()`	Get method options dictionary
`SetMethodOptions()`	Batch set method options
`SetMethodOption()`	Set single method option

Parameter Access | Parameter Access

Function	Brief Description
`GetOptionAsIndexT()`	Get IndexT type parameter
`GetOptionAsInt()`	Get int type parameter
`GetOptionAsFloat()`	Get float type parameter
`GetOptionAsDouble()`	Get double type parameter
`GetOptionAsBool()`	Get bool type parameter
`GetOptionAsString()`	Get string type parameter
`GetOptionAsPath()`	Get path parameter (supports placeholders)

Prior Information & Ground Truth | Prior Information & Ground Truth

Function	Brief Description
`SetPriorInfo()`	Set prior information
`ResetPriorInfo()`	Reset prior information
`SetGTData()`	Set ground truth data
`GetGTData()`	Get ground truth data

Profiling (MethodPresetProfiler) | Profiling

Function	Brief Description
`EnableProfiling()`	Enable performance analysis
`DisableProfiling()`	Disable performance analysis
`GetProfilerInfo()`	Get performance analysis info

Interface Introduction

Required Override Interfaces

Important

Each method plugin must implement one of the following core interfaces:

** Method Name**: Only declare in header file

virtual const std::string& GetType() const override;
// Returns plugin's unique type string identifier.
// Automatically implemented by REGISTRATION_PLUGIN macro, no manual implementation needed
// Example: `"method_sift"`, `"method_matches2tracks"`

Algorithm Main Entry: Choose between Build and Run functions, recommend using Run function

virtual DataPtr Build(const DataPtr& material_ptr = nullptr) override;
// Used to implement core algorithm:
// (1) material_ptr is optional input data. If method needs multiple inputs, pack them in `DataPackage` and pass in.
// (2) Return processing result (`DataPtr`), if processing fails or no result, return `nullptr`.

Or

virtual DataPtr Run() override;
// Used to implement core algorithm: Base class's `Build` method will call `Run` and handle input/output checking and performance analysis, etc.
// (1) User needs to set input data types in constructor: required_package_["data_type"] = nullptr;
// (2) Then can use GetRequiredDataPtr<T>("data_type") (recommended) or GetDataPtr<T>(required_package_["data_type"]) in Run function to get input data.

Optional Override Interfaces (for `MethodPreset` and its derived classes)

Set algorithm’s prior information:

virtual void SetPriorInfo(const DataPtr& data_ptr, const std::string& type = "");
// (1) `MethodPreset` sets prior information for algorithms requiring additional guidance information (such as initial poses, weights).
// (2) `data_ptr` is prior information data pointer, `type` is prior information type string.

virtual void ResetPriorInfo();
// Reset prior information (clear all prior information)

Optional Derivation Methods

Interface::Method (base class)
- Provides most basic method plugin interface. Need to handle input checking, configuration loading, etc. yourself.
Interface::MethodPreset (derived from Method)
- Provides preset functional framework to simplify development:
  - Automatic Input Checking: Checks input data types based on required_package_ member variable.
  - Configuration Management: Supports configuring method_options_ through INI files.
  - Prior Information: Supports passing additional information through SetPriorInfo.
  - Core Logic Separation: Implement core algorithm in Run(), Build() handles flow control.
Interface::MethodPresetProfiler (derived from MethodPreset)
- Adds performance analysis functionality on top of MethodPreset.
- Automatically records execution time, memory usage, and can export CSV reports.
- Can control whether to enable analysis through enable_profiling option.
Interface::RobustEstimator<TSample> (derived from MethodPresetProfiler)
- (Functionality to be expanded)

Example

The method_options_ assignments in the example code below are only for demonstrating the existence of configuration items. Actual default values should be provided when calling GetOptionAs...().

CMakeLists.txt:

# Plugin name defined here (single definition point)
add_posdk_plugin(my_method
    PLUGIN_TYPE methods
    SOURCES my_method.cpp
    HEADERS my_method.hpp
)

// my_method.hpp
#include <po_core.hpp>

namespace MyPlugin {
using namespace PoSDK;
using namespace Interface;
using namespace types; // Introduce common types

class MyMethod : public MethodPresetProfiler { // Inherit Profiler for performance analysis
public:
    MyMethod();
    // Only declare, automatically implemented by REGISTRATION_PLUGIN macro
    const std::string& GetType() const override;
    DataPtr Run() override; // Implement core logic

    // Optional: If inheriting MethodPreset, can override GetInputTypes
    // const std::vector<std::string>& GetInputTypes() const override;

    // Optional: Override Copyright() to declare copyright information
    Interface::CopyrightData Copyright() const override;
};
} // namespace MyPlugin

// my_method.cpp
#include "my_method.hpp"

namespace MyPlugin {

MyMethod::MyMethod() {
    // Define required input data types
    // Setting to nullptr indicates this type is required but not yet provided
    required_package_["data_tracks"] = nullptr;
    required_package_["data_global_poses"] = nullptr;

    // ⚠️ Note: The following code only declares config items, NOT effective default values
    // Actual default values should be provided when calling GetOptionAs...()
    method_options_["threshold"] = "0.5";          // Only declares config item
    method_options_["max_iterations"] = "100";     // Only declares config item

    // Load default config file (if exists)
    InitializeDefaultConfigPath();
    // Initialize log directory
    InitializeLogDir();
}

// Don't need to manually implement GetType(), macro automatically generates

DataPtr MyMethod::Run() {
    // 1. Get input data (MethodPreset has handled validation)
    // Recommended: use GetRequiredDataPtr for simplified access
    auto tracks = GetRequiredDataPtr<Tracks>("data_tracks");
    auto poses = GetRequiredDataPtr<GlobalPoses>("data_global_poses");

    // Validate data
    if (!tracks || !poses) {
        std::cerr << "[" << GetType() << "] Error: Missing required input data." << std::endl;
        return nullptr;
    }

    // 2. Get configuration parameters
    // ✅ Correct: Provide default values via function parameters here
    float threshold = GetOptionAsFloat("threshold", 0.5f);      // Default value: 0.5f
    int max_iter = GetOptionAsIndexT("max_iterations", 100);    // Default value: 100

    std::cout << "[" << GetType() << "] Running with threshold=" << threshold
              << ", max_iterations=" << max_iter << std::endl;

    // 3. Implement core algorithm logic...
    // ... process tracks and poses ...

    // 4. Create and return result (e.g., return processed poses)
    // Note: If you don't want to modify input data, deep copy DataPtr first
    // auto result_poses_data = poses->CopyData(); // Assume DataGlobalPoses implements CopyData
    // auto result_poses = GetDataPtr<GlobalPoses>(result_poses_data);
    // ... Modify result_poses ...
    // return result_poses_data;

    // Or create and return new data object
    auto result_data = std::make_shared<DataMap<std::string>>("Processing finished", "data_map_string");
    return result_data;
}

} // namespace MyPlugin

// ✅ Plugin registration - automatically reads plugin name from CMake PLUGIN_NAME
// Plugin type: "my_method" (from CMake)
REGISTRATION_PLUGIN(MyPlugin::MyMethod)

Warning

Parameter Default Value Setting in Constructor

Cannot use method_options_["..."] = "..." in constructor to provide default values. Values set this way will be overwritten when configuration file is loaded.

Correct Approach:

Directly provide default value parameter when calling GetOptionAs...() function
For example: 0.5f in GetOptionAsFloat("threshold", 0.5f) is the default value

Incorrect Approach:

// ❌ Error: Don't set default values like this in constructor
method_options_["threshold"] = "0.5";
method_options_["max_iterations"] = "100";

Method Parameter Configuration

Set Default Values:
- Recommended Method: Use member functions provided by MethodPreset base class for accessing configuration parameters (such as GetOptionAsFloat, GetOptionAsIndexT, etc.) to access config values, and provide default value parameters when calling.
- Example: float threshold = GetOptionAsFloat("threshold", 0.5f); where 0.5f is the default value
Configuration File (.ini):
- Create .ini file with the same name as GetType() return value in configs/methods/ directory (e.g., my_method.ini).
- File format is standard INI format, containing a section with the same name as method type [my_method].
- Define key=value pairs under the section.
- MethodPreset automatically loads this file, values in config file will override default values.
Runtime Settings:
- Can batch set options through SetMethodOptions(const MethodOptions& options).
- Can set options individually through SetMethodOption(const MethodParams& key, const ParamsValue& value).
- Runtime settings have highest priority and will override config file and default values.
Get Configuration Values:
- In Run() or other member functions, directly call member functions provided by MethodPreset base class such as GetOptionAsString("param_key", "default_val"), GetOptionAsIndexT("param_key", 0), GetOptionAsFloat("param_key", 0.0f), GetOptionAsBool("param_key", false), etc. to safely get configuration values. These functions automatically search in method_options_, if not found or type mismatch, return the provided default value.
Parameter Setting Priority: Runtime settings > Configuration file > Default values

Important

Correct Method for Setting Default Values

❌ Incorrect: Use method_options_["param"] = "value" in constructor to set default values

Values set this way will be overwritten when configuration file is loaded
If config file doesn’t have this parameter, the parameter will become empty string or undefined

✅ Correct: Provide default values through function parameters when calling GetOptionAs...()

For example: GetOptionAsFloat("threshold", 0.5f)
When both config file and runtime don’t set this parameter, will use 0.5f as default value

Core Data Types

The core library provides various predefined data types that can be directly used in plugins or as reference (see Core Data Type Detailed Description: Please refer to Appendix A: PoSDK Core Data Types)

MethodPreset Function Details

This section details each operation function of the MethodPreset class.

Data Management Functions

`SetRequiredData()`

Set single required input data to required_package_.

Function Signature:

bool SetRequiredData(const DataPtr &data_ptr);

Parameters:

data_ptr: Data pointer to set

Return Value: Returns true on success, false on failure

Usage Example:

auto tracks_data = FactoryData::Create("data_tracks");
// ... Populate tracks_data ...
method->SetRequiredData(tracks_data);

`GetRequiredPackage()`

Get reference to required input data package.

Function Signature:

const Package& GetRequiredPackage() const;  // const version
Package& GetRequiredPackage();              // non-const version

Return Value: Reference to required_package_

Usage Example:

const Package& pkg = method->GetRequiredPackage();
for (const auto& [key, value] : pkg) {
    std::cout << "Data type: " << key << std::endl;
}

`GetRequiredDataTypes()`

Get list of all required input data types.

Function Signature:

std::vector<std::string> GetRequiredDataTypes() const;

Return Value: String vector of required data types

Usage Example:

auto types = method->GetRequiredDataTypes();
for (const auto& type : types) {
    std::cout << "Required type: " << type << std::endl;
}

`GetRequiredDataPtr<T>()` (Recommended)

Simplified data access function, directly get typed data pointer from required_package_.

Function Signature:

template <typename T>
std::shared_ptr<T> GetRequiredDataPtr(const std::string &data_name) const;

Parameters:

data_name: Key name of data in required_package_

Return Value: Smart pointer to type T, returns nullptr on failure

Usage Example:

// Old way (not recommended)
auto tracks_old = GetDataPtr<Tracks>(required_package_["data_tracks"]);

// New way (recommended)
auto tracks = GetRequiredDataPtr<Tracks>("data_tracks");
auto poses = GetRequiredDataPtr<GlobalPoses>("data_global_poses");

if (!tracks || !poses) {
    LOG_ERROR_ZH << "缺少必要的输入数据";
    LOG_ERROR_EN << "Missing required input data";
    return nullptr;
}

Tip

Why Recommend Using GetRequiredDataPtr?

More concise code, reduces redundancy
Automatically handles lookup and type conversion
Better error messages

`GetOutputPackage()`

Get smart pointer to output data package.

Function Signature:

DataPackagePtr GetOutputPackage() const;

Return Value: Smart pointer to output data package

Usage Example:

auto output_pkg = method->GetOutputPackage();
if (output_pkg) {
    // Access output data...
    auto result = output_pkg->GetData("result_poses");
}

`AddOutputDataPtr()`

Add data to output data package.

Function Signature:

void AddOutputDataPtr(const DataPtr &data_ptr, const std::string &data_name = "");

Parameters:

data_ptr: Data pointer to add
data_name: Data name (optional)

Usage Example:

// Method 1: Specify data name
auto result_poses = FactoryData::Create("data_global_poses");
AddOutputDataPtr(result_poses, "optimized_poses");

// Method 2: Use data type as name
auto result_tracks = FactoryData::Create("data_tracks");
AddOutputDataPtr(result_tracks);  // Automatically uses "data_tracks" as name

// Method 3: Add DataPackage
auto sub_package = FactoryData::Create("data_package");
// ... Populate sub_package ...
AddOutputDataPtr(sub_package, "sub_results");

`GetOutputDataTypes()`

Get list of all data types in output data package.

Function Signature:

std::vector<std::string> GetOutputDataTypes() const;

Return Value: String vector of output data types

Usage Example:

auto output_types = method->GetOutputDataTypes();
for (const auto& type : output_types) {
    std::cout << "Output type: " << type << std::endl;
}

`ClearOutputPackage()`

Clear all data in output data package.

Function Signature:

void ClearOutputPackage();

Usage Example:

// Clear previous output
method->ClearOutputPackage();

// Add new output data
method->AddOutputDataPtr(new_result, "updated_result");

Configuration Management Functions

`LoadMethodOptions()`

Load method options from configuration file.

Function Signature:

void LoadMethodOptions(const std::string &config_file, const std::string &specific_method = "");

Parameters:

config_file: Configuration file path
specific_method: Specific method name (optional)

`SaveMethodOptions()`

Save method options to configuration file.

Function Signature:

void SaveMethodOptions(const std::string &config_file);

`GetMethodOptions()`

Get method options dictionary.

Function Signature:

const MethodOptions& GetMethodOptions() const;

`SetMethodOptions()`

Batch set method options.

Function Signature:

void SetMethodOptions(const MethodOptions &options);

`SetMethodOption()`

Set single method option.

Function Signature:

void SetMethodOption(const MethodParams &option_type, const ParamsValue &content);

Parameter Access Functions

`GetOptionAsIndexT()`

Get IndexT type parameter.

Function Signature:

IndexT GetOptionAsIndexT(const MethodParams &key, IndexT default_value = 0) const;

`GetOptionAsInt()`

Get int type parameter.

Function Signature:

int GetOptionAsInt(const MethodParams &key, int default_value = 0) const;

`GetOptionAsFloat()`

Get float type parameter.

Function Signature:

float GetOptionAsFloat(const MethodParams &key, float default_value = 0.0f) const;

`GetOptionAsDouble()`

Get double type parameter.

Function Signature:

double GetOptionAsDouble(const MethodParams &key, double default_value = 0.0) const;

`GetOptionAsBool()`

Get bool type parameter.

Function Signature:

bool GetOptionAsBool(const MethodParams &key, bool default_value = false) const;

`GetOptionAsString()`

Get string type parameter.

Function Signature:

std::string GetOptionAsString(const MethodParams &key, const std::string &default_value = "") const;

`GetOptionAsPath()`

Get path parameter, supports placeholder replacement.

Function Signature:

std::string GetOptionAsPath(const MethodParams &key, const std::string &root_dir = "", const std::string &default_value = "") const;

Supported Placeholders:

{root_dir}: Root directory path
{exe_dir}: Executable file directory
{key_name}: Reference other configuration item values

Usage Example:

// In config file: output_path={root_dir}/results
std::string output = GetOptionAsPath("output_path", "/home/user/project");
// Result: /home/user/project/results

Prior Information and Ground Truth Functions

`SetPriorInfo()`

Set prior information. For details, see Prior Information and Ground Truth Setup.

Function Signature:

void SetPriorInfo(const DataPtr &data_ptr, const std::string& type = "");

`ResetPriorInfo()`

Reset prior information.

Function Signature:

void ResetPriorInfo();

`SetGTData()`

Set ground truth data.

Function Signature:

void SetGTData(DataPtr &gt_data);

`GetGTData()`

Get ground truth data.

Function Signature:

DataPtr GetGTData() const;

Profiling Functions (MethodPresetProfiler)

`EnableProfiling()`

Enable performance analysis. For details, see Performance Analysis System.

`DisableProfiling()`

Disable performance analysis.

`GetProfilerInfo()`

Get performance analysis information.

Method Plugin (Method Plugin)

MethodPreset Common Operation Functions Quick Reference

Data Management | Data Management

Configuration Management | Configuration Management

Parameter Access | Parameter Access

Prior Information & Ground Truth | Prior Information & Ground Truth

Profiling (MethodPresetProfiler) | Profiling

Interface Introduction

Required Override Interfaces

Optional Override Interfaces (for MethodPreset and its derived classes)

Optional Derivation Methods

Example

Method Parameter Configuration

Core Data Types

MethodPreset Function Details

Data Management Functions

SetRequiredData()

GetRequiredPackage()

GetRequiredDataTypes()

GetRequiredDataPtr<T>() (Recommended)

GetOutputPackage()

AddOutputDataPtr()

GetOutputDataTypes()

ClearOutputPackage()

Configuration Management Functions

LoadMethodOptions()

SaveMethodOptions()

GetMethodOptions()

SetMethodOptions()

SetMethodOption()

Parameter Access Functions

GetOptionAsIndexT()

GetOptionAsInt()

GetOptionAsFloat()

GetOptionAsDouble()

GetOptionAsBool()

GetOptionAsString()

GetOptionAsPath()

Prior Information and Ground Truth Functions

SetPriorInfo()

ResetPriorInfo()

SetGTData()

GetGTData()

Profiling Functions (MethodPresetProfiler)

EnableProfiling()

DisableProfiling()

GetProfilerInfo()

Optional Override Interfaces (for `MethodPreset` and its derived classes)

`SetRequiredData()`

`GetRequiredPackage()`

`GetRequiredDataTypes()`

`GetRequiredDataPtr<T>()` (Recommended)

`GetOutputPackage()`

`AddOutputDataPtr()`

`GetOutputDataTypes()`

`ClearOutputPackage()`

`LoadMethodOptions()`

`SaveMethodOptions()`

`GetMethodOptions()`

`SetMethodOptions()`

`SetMethodOption()`

`GetOptionAsIndexT()`

`GetOptionAsInt()`

`GetOptionAsFloat()`

`GetOptionAsDouble()`

`GetOptionAsBool()`

`GetOptionAsString()`

`GetOptionAsPath()`

`SetPriorInfo()`

`ResetPriorInfo()`

`SetGTData()`

`GetGTData()`

`EnableProfiling()`

`DisableProfiling()`

`GetProfilerInfo()`