Basic Plugin Development

This section introduces the fundamentals of PoSDK plugin development, including core interfaces, plugin registration, derivation choices, configuration methods, and detailed descriptions of built-in data and method plugins.

Note

PoSDK currently mainly supports the following plugin development:

DataIO Plugins: For encapsulating various data types
Method Plugins: For implementing specific algorithm logic

Behavior Plugins are temporarily not open for user development.

Quick Start

Tip

Recommended reading order for beginners:

First read Plugin Development Quick Example to understand the basic plugin development workflow
Then check Data Plugin Interface Details and Method Plugin Interface Details to gain deeper understanding of interface design
Finally refer to Built-in Type Reference to learn about available data types and methods

Plugin Registration

All plugins need to use the REGISTRATION_PLUGIN macro for registration at the end of the corresponding .cpp source file.

Important

** Automatic Implementation of GetType() Function**

The REGISTRATION_PLUGIN macro automatically implements the GetType() function:

Only declare const std::string& GetType() const override; in the header file
Do not manually implement GetType() in the source file
The macro automatically generates the implementation

Plugin Registration Method

Usage	Syntax	Plugin Name Source	Applicable Scenarios	Recommendation
Single-param + CMake	`REGISTRATION_PLUGIN(MyClass)`	CMake auto-defined	Any namespace	Highly Recommended

Tip

Recommended Method (Single Source of Truth):

Define plugin name in CMakeLists.txt:

add_posdk_plugin(my_method  # ← Plugin name defined only once here
    PLUGIN_TYPE methods
    SOURCES my_method.cpp
)

Use single-parameter mode in C++ code (auto-read):

REGISTRATION_PLUGIN(MyNamespace::MyMethod)  // ← Automatically uses CMake-defined name

Advantages:

Single Source of Truth: Plugin name only needs to be defined once in CMake
Automatic Consistency: File name, registration name, and CMake target automatically consistent
Error Prevention: No manual synchronization needed, reduces maintenance cost

```{note} 
**Important Notes**:
- `REGISTRATION_PLUGIN` **must** be placed in **source file (.cpp)**, **cannot** be placed in header file (.hpp)
- Ensure registered type string is unique within current plugin directory
- Recommended to use **single-parameter + CMake auto-definition** mode for single source of truth management

Example - Plugin Registration

CMakeLists.txt:

# Plugin name defined here (single definition point)
add_posdk_plugin(opencv_two_view_estimator
    PLUGIN_TYPE methods
    SOURCES opencv_two_view_estimator.cpp
    HEADERS opencv_two_view_estimator.hpp
    LINK_LIBRARIES
        # Note: PoSDK::po_core, PoSDK::pomvg_converter, PoSDK::pomvg_common, and Eigen3::Eigen
        # are automatically linked by add_posdk_plugin function, no need to specify them here.
        # 注意：PoSDK::po_core、PoSDK::pomvg_converter、PoSDK::pomvg_common 和 Eigen3::Eigen
        # 已由 add_posdk_plugin 函数自动链接，无需在此指定。
        ${OpenCV_LIBS}  # Only specify additional libraries not auto-linked
    INCLUDE_DIRS
        ${OpenCV_INCLUDE_DIRS}
)

C++ Header File (opencv_two_view_estimator.hpp):

namespace PluginMethods {
    class OpenCVTwoViewEstimator : public MethodPresetProfiler {
    public:
        // ✨ GetType() is automatically implemented by REGISTRATION_PLUGIN macro
        const std::string& GetType() const override;
        DataPtr Run() override;
        // ... (other methods) ...
    };
}

C++ Source File (opencv_two_view_estimator.cpp):

#include "opencv_two_view_estimator.hpp"

// ... (Other function implementations for OpenCVTwoViewEstimator class) ...

} // namespace PluginMethods

// ✅ Single-parameter mode - automatically reads from CMake PLUGIN_NAME
// Plugin type: "opencv_two_view_estimator" (from CMake)
// File name: posdk_plugin_opencv_two_view_estimator.{so|dylib|dll}
REGISTRATION_PLUGIN(PluginMethods::OpenCVTwoViewEstimator)

Automatic Consistency:

CMake Target: opencv_two_view_estimator
Plugin file name: posdk_plugin_opencv_two_view_estimator.dylib
Registration type: "opencv_two_view_estimator" (auto-read from CMake)

Plugin Directory Management

PoSDK uses factory pattern to create and manage plugins. The system loads dynamic libraries (.so/.dll/.dylib) as plugins from specific directories. Each plugin type has a corresponding default directory:

Important

Default plugin directory structure (relative to executable or library):

Data plugins: ../plugins/data/
Method plugins: ../plugins/methods/

Plugin Loading Mechanism

PoSDK uses lazy loading mechanism, plugins are only loaded when Create method is called for the first time. Loading process is as follows:

Check if plugin of corresponding type has been loaded
If not loaded, attempt to load all matching dynamic libraries from default plugin directory
When user requests object creation, prioritize creation from built-in factory; if no matching type, attempt to create from plugin

Tip

If you encounter plugin loading issues, please check:

Whether plugin directory exists and has read permissions
Whether plugin files are compatible with current system (Linux .so, Windows .dll, macOS .dylib)
Whether plugin correctly registered the type
Whether all plugin dependency libraries are correctly loaded

Manually Specify Plugin Directory

You can manually specify plugin directory through factory class static method ManagePlugins:

PoSDK::FactoryData::ManagePlugins("/path/to/your/data/plugins");
PoSDK::FactoryMethod::ManagePlugins("/path/to/your/method/plugins");
PoSDK::FactoryBehavior::ManagePlugins("/path/to/your/behavior/plugins");

Get Available Plugin Types

Use the following functions to display available plugin types in command line:

// Only display types provided by plugins
PoSDK::FactoryData::DispPluginTypes();
PoSDK::FactoryMethod::DispPluginTypes();
PoSDK::FactoryBehavior::DispPluginTypes();

Plugin Development Guide

This section provides complete plugin development tutorials and interface specifications.

Plugin Development

Built-in Type Reference

This section provides a list of preset data and method plugins in PoSDK core library along with brief descriptions.

Built-in Types